Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Camera

Cameras

Camera is the base class for all Excalibur cameras. Cameras are used to move around your game and set focus. They are used to determine what is "off screen" and can be used to scale the game.

Cameras are attached to Scenes and can be changed by setting Scene.camera. By default, a Scene is initialized with a Camera that doesn't move and is centered on the screen.

Focus

Cameras have a position (x, y) which means they center around a specific point.

If a camera is following an Actor, it will ensure the Actor is always at the center of the screen. You can use x and y instead if you wish to offset the focal point.

Camera strategies

Cameras can implement a number of strategies to track, follow, or exhibit custom behavior in relation to a target. A common reason to use a strategy is to have the Camera follow an Actor.

In order to user the different built-in strategies, you can access Camera.strategy

Lock the camera exactly to the center of the actor's bounding box

game.currentScene.camera.strategy.lockToActor(actor);

Lock the camera to one axis of the actor, in this case follow the actors x position

game.currentScene.camera.strategy.lockToActorAxis(actor, ex.Axis.X);

Elastically move the camera to an actor in a smooth motion see ElasticToActorStrategy for details

game.currentScene.camera.strategy.elasticToActor(actor, cameraElasticity, cameraFriction);

Keep the actor within a circle around the focus

game.currentScene.camera.strategy.radiusAroundActor(actor, radius);

Keep the camera limited within camera constraints.
Make sure that the camera bounds are at least as large as the viewport size.

let boundingBox = new BoundingBox(leftBorder, topBorder, rightBorder, bottomBorder);
game.currentScene.camera.strategy.limitCameraBounds(boundingBox);

Custom strategies

Custom strategies can be implemented by extending the CameraStrategy interface and added to cameras to build novel behavior with ex.Camera.addStrategy<T>(new MyCameraStrategy<T>()).

As shown below a camera strategy calculates a new camera position (ex.Vector) every frame given a target type, camera, engine, and elapsed delta in milliseconds.

/**
 * Interface that describes a custom camera strategy for tracking targets
 */
export interface CameraStrategy<T> {
  /**
   * Target of the camera strategy that will be passed to the action
   */
  target: T;

  /**
   * Camera strategies perform an action to calculate a new focus returned out of the strategy
   */
  action: (target: T, camera: Camera, engine: Engine, delta: number) => Vector;
}

Camera Shake

To add some fun effects to your game, the shake method will do a random shake. This is great for explosions, damage, and other in-game effects.

Camera Lerp

"Lerp" is short for Linear Interpolation and it enables the camera focus to move smoothly between two points using timing functions. Use move to ease to a specific point using a provided EasingFunction.

Camera Zooming

To adjust the zoom for your game, use zoom which will scale the game accordingly. You can pass a duration to transition between zoom levels.

Known Issues

Actors following a path will wobble when camera is moving
Issue #276

Hierarchy

Implements

Index

Constructors

constructor

Properties

Protected _follow

_follow: Actor

Protected _isShaking

_isShaking: boolean = false

Protected _isZooming

_isZooming: boolean = false

acc

acc: Vector = Vector.Zero

GEt or set the camera's acceleration

az

az: number = 0

Get or set zoom acceleration

dz

dz: number = 0

Get or set rate of change in zoom, defaults to 0

eventDispatcher

eventDispatcher: EventDispatcher

Direct access to the game object event dispatcher.

pos

pos: Vector = Vector.Zero

Get or set the camera's position

rotation

rotation: number = 0

Current rotation of the camera

rx

rx: number = 0

Current angular velocity

strategy

strategy: StrategyContainer = new StrategyContainer(this)

vel

vel: Vector = Vector.Zero

Get or set the camera's velocity

z

z: number = 1

Get or set current zoom of the camera, defaults to 1

Accessors

angularVelocity

  • get angularVelocity(): number
  • set angularVelocity(value: number): void

ax

  • get ax(): number
  • set ax(value: number): void

ay

  • get ay(): number
  • set ay(value: number): void

dx

  • get dx(): number
  • set dx(value: number): void

dy

  • get dy(): number
  • set dy(value: number): void

isInitialized

  • get isInitialized(): boolean

viewport

x

  • get x(): number
  • set x(value: number): void

y

  • get y(): number
  • set y(value: number): void

Methods

_initialize

  • _initialize(_engine: Engine): void

_postupdate

  • _postupdate(engine: Engine, delta: number): void
  • It is not recommended that internal excalibur methods be overridden, do so at your own risk.

    Internal _preupdate handler for onPostUpdate lifecycle event

    internal

    Parameters

    • engine: Engine
    • delta: number

    Returns void

_preupdate

  • _preupdate(engine: Engine, delta: number): void
  • It is not recommended that internal excalibur methods be overridden, do so at your own risk.

    Internal _preupdate handler for onPreUpdate lifecycle event

    internal

    Parameters

    • engine: Engine
    • delta: number

    Returns void

addStrategy

clearAllStrategies

  • clearAllStrategies(): void

debugDraw

  • debugDraw(ctx: CanvasRenderingContext2D): void

draw

  • draw(ctx: CanvasRenderingContext2D): void
  • Applies the relevant transformations to the game canvas to "move" or apply effects to the Camera

    Parameters

    • ctx: CanvasRenderingContext2D

      Canvas context to apply transformations

    Returns void

emit

  • emit(eventName: string, eventObject: GameEvent<any>): void

getFocus

getZoom

  • getZoom(): number

move

  • This moves the camera focal point to the specified position using specified easing function. Cannot move when following an Actor.

    Parameters

    • pos: Vector

      The target position to move to

    • duration: number

      The duration in milliseconds the move should last

    • Default value easingFn: EasingFunction = EasingFunctions.EaseInOutCubic

    Returns PromiseLike<Vector>

    A Promise that resolves when movement is finished, including if it's interrupted. The Promise value is the Vector of the target position. It will be rejected if a move cannot be made.

off

  • off(eventName: "initialize", handler?: function): void
  • off(eventName: "preupdate", handler?: function): void
  • off(eventName: "postupdate", handler?: function): void
  • off(eventName: string, handler: function): void

on

  • on(eventName: "initialize", handler: function): void
  • on(eventName: "preupdate", handler: function): void
  • on(eventName: "postupdate", handler: function): void

onInitialize

  • onInitialize(_engine: Engine): void
  • Safe to override onPostUpdate lifecycle event handler. Synonymous with .on('preupdate', (evt) =>{...})

    onPostUpdate is called directly after a scene is updated.

    Parameters

    Returns void

onPostUpdate

  • onPostUpdate(_engine: Engine, _delta: number): void
  • Safe to override onPostUpdate lifecycle event handler. Synonymous with .on('preupdate', (evt) =>{...})

    onPostUpdate is called directly after a scene is updated.

    Parameters

    • _engine: Engine
    • _delta: number

    Returns void

onPreUpdate

  • onPreUpdate(_engine: Engine, _delta: number): void
  • Safe to override onPreUpdate lifecycle event handler. Synonymous with .on('preupdate', (evt) =>{...})

    onPreUpdate is called directly before a scene is updated.

    Parameters

    • _engine: Engine
    • _delta: number

    Returns void

once

  • once(eventName: "initialize", handler: function): void
  • once(eventName: "preupdate", handler: function): void
  • once(eventName: "postupdate", handler: function): void
  • once(eventName: string, handler: function): void

removeStrategy

shake

  • shake(magnitudeX: number, magnitudeY: number, duration: number): void
  • Sets the camera to shake at the specified magnitudes for the specified duration

    Parameters

    • magnitudeX: number

      The x magnitude of the shake

    • magnitudeY: number

      The y magnitude of the shake

    • duration: number

      The duration of the shake in milliseconds

    Returns void

update

  • update(_engine: Engine, delta: number): void

zoom

  • Zooms the camera in or out by the specified scale over the specified duration. If no duration is specified, it take effect immediately.

    Parameters

    • scale: number

      The scale of the zoom

    • Default value duration: number = 0

      The duration of the zoom in milliseconds

    • Default value easingFn: EasingFunction = EasingFunctions.EaseInOutCubic

    Returns Promise<boolean>