Skip to main content

Cameras

The camera determines which part of the game world is visible on the screen.

Defining cameras​

You can control the camera with the following three functions:

  • Camera defines where the camera is looking.
  • CameraBoundary constrains the camera to stay within a certain area.
  • Viewport lets you define where on the screen the camera's view is drawn.

Each of these functions adds a component to the current entity, which means they only have an effect as long as that entity continues to exist. You can use this to your advantage, for example, if you want to temporarily move the camera for a cutscene, you can spawn a temporary entity for that cutscene, and add a Camera component to it. When the cutscene ends, you despawn that entity, and the camera will revert to its previous state.

Priority​

When there are multiple Camera, CameraBoundary or Viewport components affecting the same camera, the component with the highest priority value takes precedence. If two components have the same priority value, the newest component takes precedence over the older one.

Background color​

You can use the SolidBackground function to set the color of the background for a particular camera. If a camera's has a fully opaque background color, and its viewport completely covers another one, Easel will skip rendering the lower viewport for performance reasons.

For this reason, it is good to use SolidBackground to optimize performance when you have multiple overlapping viewports.

tip

You can also use Vignette to add a vignette effect to a particular camera's viewport. Give the player's main camera a red vignette when they are low on health, for example, or a glowing gold vignette when they have an active power-up.

Multiple cameras​

You can use multiple cameras to create minimaps, heads-up displays, parallax effects, scene transitions, overlay maps and other effects.

The camera parameter​

To use multiple cameras, use the camera parameter that is available on all graphical functions. The camera parameter determines which camera(s) will be affected.

  • For example, ImageSprite takes a camera to determine which camera(s) will see that sprite.
  • Similarly, the Camera function takes a camera parameter to define which camera is being set up.

Entities as cameras​

Pass an Entity into the camera parameter to determine the camera(s). Any Entity can be used as a camera. Depending on your use case you may want to reuse an existing entity, or spawn a new one.

  • Let's say your game has multiple levels. Each level is represented by an entity called level. You could use the level entity as a camera. Then you could do some scene transitions when switching from one level to another. For example, the viewport of the level could fly in from the side of the screen.
  • If you are creating a minimap, you could spawn a globally-accessible entity to represent your minimap camera, for example with pub const Camera:Minimap = Spawn. Then any entity can use the minimap entity in its camera parameter to determine how it should appear on the minimap. See How to: Make a Minimap for an example of how to do this.
  • The World entity represents the main camera and is always available for you to use. If you don't specify a camera parameter, the main camera is used by default.

Multiple cameras at once​

You can pass an array of entities into the camera parameter to render into or modify multiple cameras at once. For example, the following code snippet will render an image sprite into both the main camera and the minimap camera:

ImageSprite(..., camera=[World, Camera:Minimap])

Camera from context​

All graphical functions will take the camera parameter from context. This helps if you want to set the camera once for an entire entity. For example, you could specify use camera=scene at the top of a function to always render everything into the camera called scene.

Camera order​

If the viewports of two cameras overlap, the order parameter of the Viewport function determines which camera is drawn on top. If two viewports have the same order value, the newest viewport is drawn on top of the older one.

Default camera parameters​

If you render something into a camera but have not used the Camera to determine where the camera is looking, it will take its default values from graphics.toml. By default, this means the camera will be centered at the origin @(0,0) with a radius of 50.

If you render something into a camera but have not used the Viewport function to define where on the screen the camera's view is drawn, the camera will take up the entire screen by default.

Hiding a camera​

If you want to temporarily hide a camera, you can give it a zero-sized Viewport. For example, set Viewport(scale=0, camera=Camera:Minimap) to hide the minimap camera completely.

The pointer and cameras​

In Easel, the Pointer position is represented in world coordinates, not screen coordinates. To designate a particular camera as the one that determines the pointer's world position, pass in the pointer=true parameter to Camera.

This is helpful if, you temporarily display a fullscreen overlay camera to allow the player to choose another level for example. The overlay may have a different zoom level to the main camera.

info

The pointer is represented in world coordinates rather than screen coordinates because Easel is designed from the ground up as a multiplayer game engine. This means the pointer is always exactly where the player sees it on their own screen, even if their screen is not perfectly synchronized with everyone else's screen due to latency.