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);

Custom strategies

Custom strategies can be implemented by extending the ICameraStrategy 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

ax

ax: number = 0

ay

ay: number = 0

az

az: number = 0

dx

dx: number = 0

dy

dy: number = 0

dz

dz: number = 0

eventDispatcher

eventDispatcher: EventDispatcher

Direct access to the game object event dispatcher.

rotation

rotation: number = 0

rx

rx: number = 0

strategy

strategy: StrategyContainer = new StrategyContainer(this)

z

z: number = 1

Accessors

isInitialized

  • get isInitialized(): boolean

pos

vel

viewport

x

  • get x(): number
  • set x(value: number): void
  • Get the camera's x position

    Returns number

  • Set the camera's x position (cannot be set when following an Actor or when moving)

    Parameters

    • value: number

    Returns void

y

  • get y(): number
  • set y(value: number): void
  • Get the camera's y position

    Returns number

  • Set the camera's y position (cannot be set when following an Actor or when moving)

    Parameters

    • value: number

    Returns void

Methods

_initialize

  • _initialize(_engine: Engine): void

_postupdate

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

    Internal preupdate handler for <a href="camera_.camera.html#onpostupdate">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 overriden, do so at your own risk.

    Internal preupdate handler for <a href="camera_.camera.html#onpreupdate">onPreUpdate lifecycle event

    internal

    Parameters

    • engine: Engine
    • delta: number

    Returns void

addStrategy

clearAllStrategies

  • clearAllStrategies(): void
  • Clears all camera strategies from the camera

    Returns void

debugDraw

  • debugDraw(ctx: CanvasRenderingContext2D): void
  • Parameters

    • ctx: CanvasRenderingContext2D

    Returns 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
  • Emits a new event

    Parameters

    • eventName: string

      Name of the event to emit

    • eventObject: GameEvent<any>

      Data associated with this event

    Returns void

getFocus

  • Returns the focal point of the camera, a new point giving the x and y position of the camera

    Returns Vector

getZoom

  • getZoom(): number
  • Gets the current zoom scale

    Returns 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>

Static extend

  • extend(methods: any): any
  • You may wish to extend native Excalibur functionality in vanilla Javascript. Any method on a class inheriting Class may be extended to support additional functionality. In the example below we create a new type called MyActor.

    var MyActor = Actor.extend({
    
       constructor: function() {
          this.newprop = 'something';
          Actor.apply(this, arguments);
       },
    
       update: function(engine, delta) {
          // Implement custom update
          // Call super constructor update
          Actor.prototype.update.call(this, engine, delta);
    
          console.log("Something cool!");
       }
    });
    
    var myActor = new MyActor(100, 100, 100, 100, Color.Azure);

    In TypeScript, you only need to use the extends syntax, you do not need to use this method of extension.

    Parameters

    • methods: any

      A JSON object contain any methods/properties you want to extend

    Returns any