Skip to main content

Cameras

Cameras determine what part of the world is visible on the screen. It is possible to have multiple cameras in a game, each with its own position, zoom level, and viewport on the screen. See Learn > Graphics > Cameras to learn more about how to use cameras in Easel.

Camera​

this.Camera<Id = auto>([body], radius?=, freeRadius?, maxScreenSizePx?, stencil?, acquireRate?, panningRate?, transitionRate?, priority?, [audience?, owner?, camera?])
delete this.Camera<Id>

Determines the target position of the camera for a given audience.

  • this (Entity): Determines the lifespan of the camera. When this despawns, the camera will be deleted.

  • Id: An optional discriminator to allow for multiple Cameras on the same entity.

Position:

  • body (Entity or Vector): Determines the position. If body is an Entity, the camera will track the position of the entity's Body. If body is a Vector, the camera will be fixed at that position. Defaults to this.

Zoom:

  • radius (Number or Vector): Controls the zoom level of the camera. The camera will zoom in or out to ensure this radius is visible. Provide a Number to set both the horizontal and vertical radius to the same value. Provide a Vector to separately define a different horizontal and vertical radius. Defaults to 50.

  • freeRadius (Number): When the camera is within this distance of the body it will stop moving, allowing body to freely move around within this radius without affecting the camera. Defaults to 0.

Transition:

  • acquireRate (Number): When the camera is acquiring its target for the first time, this parameter controls the rate at which the camera finds its target position, where 1 is instant and 0 is never. A value of 0.25 means the camera will move 25% of the way to its target position each frame. Once the camera has acquired its target, it then switches to using panningRate. Defaults to transitionRate.

  • panningRate (Number): After the camera has acquired its target already, this parameter controls the rate at which the camera finds its target position, where 1 is instant and 0 is never. A value of 0.25 means the camera will move 25% of the way to its target position each frame. Defaults to transitionRate.

  • transitionRate (Number): Sets both acquireRate and panningRate with one parameter, if they are not otherwise specified. Defaults to 1 (instant).

Stencil:

  • stencil (Boolean): If true, the camera will only render inside the areas defined by any stencil components such as PolygonStencil. If false, the camera will render everything, ignoring any stencils. If nullish, will default to true if any stencil components are present for the camera, or false otherwise.

Viewer:

  • camera (Entity or Array of Entities): Determines which camera(s) will have its target position set. Defaults to World (the main camera).

  • audience (Entity, Symbol or Flag): If provided, sets the camera position only for the specified audience. Defaults to the value of owner. See Audience.

  • owner (Entity): The player or team who owns the camera. Only used to interpret the audience parameter.

  • priority (Number): Only the Camera with the highest priority will be used. Must be an integer between -128 and 127. Defaults to 0.

  • maxScreenSizePx (Number): If specified, the camera will only be used when the screen width or height is less than or equal to this value, in pixels.

Deprecated parameters:

  • aspectRatio: This parameter has now been moved to Viewport. It will still be accepted here for legacy reasons, but may be removed in a future update.

CameraBoundary​

this.CameraBoundary<Id = auto>(left?=, right?, top?, bottom?, priority?, [audience?, owner?, camera?])
delete this.CameraBoundary<Id>

Limits the viewable area of the camera for a given audience. The camera's position will be clamped to only show areas within the specified boundaries. If the camera's radius is too big, the camera will also be forced to zoom in order to fit within the boundaries.

  • this (Entity): Determines the lifespan of the camera. When this despawns, the camera will be deleted.

  • Id: An optional discriminator to allow for multiple CameraBoundarys on the same entity.

  • left (Number): If supplied, the leftmost boundary of the camera.

  • right (Number): If supplied, the rightmost boundary of the camera.

  • top (Number): If supplied, the topmost boundary of the camera.

  • bottom (Number): If supplied, the bottommost boundary of the camera.

  • audience (Entity, Symbol or Flag): If provided, sets the camera boundaries only for the specified audience. Defaults to the value of owner. See Audience.

  • owner (Entity): The player or team who owns the camera. Only used to interpret the audience parameter.

  • priority (Number): Only the CameraBoundary with the highest priority will be used. Must be an integer between -128 and 127. Defaults to 0.

  • camera (Entity or Array of Entities): Determines which camera(s) will have its boundaries set. Defaults to World (the main camera).

Subcamera​

camera.Subcamera(parent?, radiusMultiplier?=, stencil?)

Makes camera a subcamera of a parent camera. A subcamera's position and zoom is locked relative to its parent camera. If the parent camera moves or zooms, the subcamera will follow. This can be used to create parallax effects.

  • camera (Entity): Determines which camera to make into a subcamera.

  • parent (Entity): Determines the parent camera from which to take the position and radius. Defaults to World (the main camera).

  • radiusMultiplier (Number): The subcamera's radius will be the parent camera's radius multiplied this value. Defaults to 1.

  • stencil (Boolean): If true, the camera will only render inside the areas defined by any stencil components such as PolygonStencil. If false, the camera will render everything, ignoring any stencils. If nullish, will default to true if any stencil components are present for the camera, or false otherwise.

Example:

pub const Camera:Main = World

pub const Camera:Background = Spawn camera {
    Subcamera(Camera:Main, radiusMultiplier=2)
    Viewport(order=-1) // Place behind the main camera
}

Viewport​

this.Viewport<Id = auto>(order?=, scale?, aspectRatio?, width?, height?, anchor?, offset?, pointer?, priority?, [audience?, owner?, camera?])
delete this.Viewport<Id>

Determines where on the screen the camera's view will be rendered.

  • this (Entity): Determines the lifespan of the viewport. When this despawns, the viewport will be deleted.

  • Id: An optional discriminator to allow for multiple Viewports on the same entity.

Position:

  • anchor (Vector): Sets the anchor point of the viewport on the screen. A value of @(0,0) places the viewport in the middle of the screen. A value of @(-1,-1) places the viewport in the top-left corner, while a value of @(1,1) places it in the bottom-right corner. You will only notice the effect of this parameter when the viewport is smaller than the screen.

  • offset (Vector): An additional offset to apply to the viewport's position on the screen, in em units.

Size:

  • width (Number): Sets the width of the viewport in em units. Defaults to the full width of the screen.

  • height (Number): Sets the height of the viewport in em units. Defaults to the full height of the screen.

  • aspectRatio (Number): The desired aspect ratio (width divided by height) of the viewport. The viewport will be sized to be as large as possible within the specified width and height while maintaining this aspect ratio. Defaults to the aspect ratio of the screen.

  • scale (Number): The size of the viewport will be scaled by this factor. A value of 0.5 would halve both the width and height of the viewport. Defaults to 1.0.

Z-order:

  • order (Number): Viewports with a higher order number will be rendered on top of viewports with a lower number. Must be an integer in the range -128 to 127. Defaults to 0.

Pointer:

  • pointer (Boolean): If true, the position of the Pointer will be transformed from screen space to world space using this viewport's camera. If multiple Viewports have pointer set to true, the one with the highest order will take precedence (i.e. the one on top). If no Viewports have pointer set to true, the main camera (World) will be used. Defaults to false.

Viewer:

  • audience (Entity, Symbol or Flag): If provided, sets the viewport only for the specified audience. Defaults to the value of owner. See Audience.

  • owner (Entity): The player or team who owns the viewport. Only used to interpret the audience parameter.

  • priority (Number): Only the Viewport with the highest priority will be used for each camera. Must be an integer between -128 and 127. Defaults to 0.

  • camera (Entity or Array of Entities): The camera(s) to set the viewport for. Defaults to World (the main camera).