Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Scene

Actors are composed together into groupings called Scenes in Excalibur. The metaphor models the same idea behind real world actors in a scene. Only actors in scenes will be updated and drawn.

Typical usages of a scene include: levels, menus, loading screens, etc.

Adding actors to the scene

For an Actor to be drawn and updated, it needs to be part of the "scene graph". The Engine provides several easy ways to quickly add/remove actors from the current scene.

var game   = new ex.Engine(...);
var player = new ex.Actor();
var enemy  = new ex.Actor();
// add them to the "root" scene
game.add(player);
game.add(enemy);
// start game
game.start();

You can also add actors to a Scene instance specifically.

var game = new ex.Engine();
var level1 = new ex.Scene();
var player = new ex.Actor();
var enemy = new ex.Actor();
// add actors to level1
level1.add(player);
level1.add(enemy);
// add level1 to the game
game.add('level1', level1);
// start the game
game.start();
// after player clicks start game, for example
game.goToScene('level1');

Scene Lifecycle

A scene has a basic lifecycle that dictates how it is initialized, updated, and drawn. Once a scene is added to the engine it will follow this lifecycle.

Scene Lifecycle

Extending scenes

For more complex games, you might want more control over a scene in which case you can extend Scene. This is useful for menus, custom loaders, and levels.

Just use Engine.add to add a new scene to the game. You can then use Engine.goToScene to switch scenes which calls Scene.onActivate for the new scene and Scene.onDeactivate for the old scene. Use Scene.onInitialize to perform any start-up logic, which is called once.

TypeScript

class MainMenu extends ex.Scene {
  // start-up logic, called once
  public onInitialize(engine: ex.Engine) {}
  // each time the scene is entered (Engine.goToScene)
  public onActivate() {}
  // each time the scene is exited (Engine.goToScene)
  public onDeactivate() {}
}
// add to game and activate it
game.add('mainmenu', new MainMenu());
game.goToScene('mainmenu');

Javascript

var MainMenu = ex.Scene.extend({
  // start-up logic, called once
  onInitialize: function(engine) {},
  // each time the scene is activated by Engine.goToScene
  onActivate: function() {},
  // each time the scene is deactivated by Engine.goToScene
  onDeactivate: function() {}
});
game.add('mainmenu', new MainMenu());
game.goToScene('mainmenu');

Scene camera

By default, a Scene is initialized with a BaseCamera which does not move and centers the game world.

Learn more about Cameras and how to modify them to suit your game.

Hierarchy

Implements

Index

Constructors

constructor

Properties

actors

actors: Actor[] = []

The actors in the current scene

camera

camera: BaseCamera

Gets or sets the current camera for the scene

engine

engine: Engine

Access to the Excalibur engine

eventDispatcher

eventDispatcher: EventDispatcher

Direct access to the game object event dispatcher.

groups

groups: object

The Groups in the scene, if any

Type declaration

tileMaps

tileMaps: TileMap[] = []

The TileMaps in the scene, if any

triggers

triggers: Trigger[] = []

The triggers in the current scene

uiActors

uiActors: Actor[] = []

The UIActors in a scene, if any; these are drawn last

Accessors

isInitialized

  • get isInitialized(): boolean
  • Gets whether or not the Scene has been initialized

    Returns boolean

Methods

_activate

  • _activate(oldScene: Scene, newScene: Scene): void
  • It is not recommended that internal excalibur methods be overriden, do so at your own risk.

    Activates the scene with the base behavior, then calls the overridable onActivate implementation.

    internal

    Parameters

    Returns void

Protected _addChild

  • _addChild(actor: Actor): void
  • Adds an actor to the scene, once this is done the actor will be drawn and updated.

    Parameters

    Returns void

_deactivate

  • _deactivate(oldScene: Scene, newScene: Scene): void
  • It is not recommended that internal excalibur methods be overriden, do so at your own risk.

    Deactivates the scene with the base behavior, then calls the overridable onDeactivate implementation.

    internal

    Parameters

    Returns void

_initialize

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

    Initializes the scene before the first update, meant to be called by engine not by users of Excalibur

    internal

    Parameters

    Returns void

_postdraw

  • _postdraw(_ctx: CanvasRenderingContext2D, _delta: number): void
  • It is not recommended that internal excalibur methods be overriden, do so at your own risk.

    Internal _postdraw handler for onPostDraw lifecycle event

    internal

    Parameters

    • _ctx: CanvasRenderingContext2D
    • _delta: number

    Returns 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 onPostUpdate lifecycle event

    internal

    Parameters

    • _engine: Engine
    • delta: number

    Returns void

_predraw

  • _predraw(_ctx: CanvasRenderingContext2D, _delta: number): void
  • It is not recommended that internal excalibur methods be overriden, do so at your own risk.

    Internal _predraw handler for onPreDraw lifecycle event

    internal

    Parameters

    • _ctx: CanvasRenderingContext2D
    • _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 onPreUpdate lifecycle event

    internal

    Parameters

    • _engine: Engine
    • delta: number

    Returns void

Protected _removeChild

  • _removeChild(actor: Actor): void
  • Removes an actor from the scene, it will no longer be drawn or updated.

    Parameters

    Returns void

add

addTileMap

  • addTileMap(tileMap: TileMap): void
  • Adds a TileMap to the scene, once this is done the TileMap will be drawn and updated.

    Parameters

    Returns void

addTimer

addUIActor

  • addUIActor(actor: Actor): void
  • Adds (any) actor to act as a piece of UI, meaning it is always positioned in screen coordinates. UI actors do not participate in collisions.

    todo

    Should this be UIActor only?

    Parameters

    Returns void

cancelTimer

cleanupDrawTree

  • cleanupDrawTree(actor: Actor): void
  • Removes the given actor from the sorted drawing tree

    Parameters

    Returns void

contains

  • contains(actor: Actor): boolean
  • Checks whether an actor is contained in this scene or not

    Parameters

    Returns boolean

createGroup

  • createGroup(name: string): Group
  • Creates and adds a Group to the scene with a name

    Parameters

    • name: string

    Returns Group

debugDraw

  • debugDraw(ctx: CanvasRenderingContext2D): void
  • Draws all the actors' debug information in the Scene. Called by the Engine.

    Parameters

    • ctx: CanvasRenderingContext2D

      The current rendering context

    Returns void

draw

  • draw(ctx: CanvasRenderingContext2D, delta: number): void
  • Draws all the actors in the Scene. Called by the Engine.

    Parameters

    • ctx: CanvasRenderingContext2D

      The current rendering context

    • delta: number

      The number of milliseconds since the last draw

    Returns void

emit

  • emit(eventName: string, eventObject?: GameEvent<any>): void
  • Emits a new event

    Parameters

    • eventName: string

      Name of the event to emit

    • Optional eventObject: GameEvent<any>

      Data associated with this event

    Returns void

getGroup

  • getGroup(name: string): Group

isActorInDrawTree

  • isActorInDrawTree(actor: Actor): boolean
  • Checks if an actor is in this scene's sorted draw tree

    Parameters

    Returns boolean

isCurrentScene

  • isCurrentScene(): boolean

isTimerActive

  • isTimerActive(timer: Timer): boolean
  • Tests whether a Timer is active in the scene

    Parameters

    Returns boolean

off

  • off(eventName: Events.initialize, handler?: function): void
  • off(eventName: Events.activate, handler?: function): void
  • off(eventName: Events.deactivate, handler?: function): void
  • off(eventName: Events.preupdate, handler?: function): void
  • off(eventName: Events.postupdate, handler?: function): void
  • off(eventName: Events.predraw, handler?: function): void
  • off(eventName: Events.postdraw, handler?: function): void
  • off(eventName: Events.predebugdraw, handler?: function): void
  • off(eventName: Events.postdebugdraw, handler?: function): void
  • off(eventName: string, handler?: function): void

on

  • on(eventName: Events.initialize, handler: function): void
  • on(eventName: Events.activate, handler: function): void
  • on(eventName: Events.deactivate, handler: function): void
  • on(eventName: Events.preupdate, handler: function): void
  • on(eventName: Events.postupdate, handler: function): void
  • on(eventName: Events.predraw, handler: function): void
  • on(eventName: Events.postdraw, handler: function): void
  • on(eventName: Events.predebugdraw, handler: function): void
  • on(eventName: Events.postdebugdraw, handler: function): void
  • on(eventName: string, handler: function): void

onActivate

  • onActivate(_oldScene: Scene, _newScene: Scene): void
  • This is called when the scene is made active and started. It is meant to be overriden, this is where you should setup any DOM UI or event handlers needed for the scene.

    Parameters

    Returns void

onDeactivate

  • onDeactivate(_oldScene: Scene, _newScene: Scene): void
  • This is called when the scene is made transitioned away from and stopped. It is meant to be overriden, this is where you should cleanup any DOM UI or event handlers needed for the scene.

    Parameters

    Returns void

onInitialize

  • onInitialize(_engine: Engine): void
  • This is called before the first update of the Scene. Initializes scene members like the camera. This method is meant to be overridden. This is where initialization of child actors should take place.

    Parameters

    Returns void

onPostDraw

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

    onPostDraw is called directly after a scene is drawn.

    Parameters

    • _ctx: CanvasRenderingContext2D
    • _delta: number

    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

onPreDraw

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

    onPreDraw is called directly before a scene is drawn.

    Parameters

    • _ctx: CanvasRenderingContext2D
    • _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: Events.initialize, handler: function): void
  • once(eventName: Events.activate, handler: function): void
  • once(eventName: Events.deactivate, handler: function): void
  • once(eventName: Events.preupdate, handler: function): void
  • once(eventName: Events.postupdate, handler: function): void
  • once(eventName: Events.predraw, handler: function): void
  • once(eventName: Events.postdraw, handler: function): void
  • once(eventName: Events.predebugdraw, handler: function): void
  • once(eventName: Events.postdebugdraw, handler: function): void
  • once(eventName: string, handler: function): void

remove

  • Removes a Timer from the current scene, it will no longer be updated.

    Parameters

    • timer: Timer

      The timer to remove to the current scene.

    Returns void

  • Removes a TileMap from the scene, it will no longer be drawn or updated.

    Parameters

    Returns void

  • Removes an actor from the scene, it will no longer be drawn or updated.

    Parameters

    • actor: Actor

      The actor to remove from the current scene.

    Returns void

  • Removes a UIActor to the scene, it will no longer be drawn or updated

    Parameters

    • uiActor: UIActor

      The UIActor to remove from the current scene

    Returns void

removeGroup

  • removeGroup(name: string): void
  • removeGroup(group: Group): void

removeTileMap

  • removeTileMap(tileMap: TileMap): void
  • Removes a TileMap from the scene, it will no longer be drawn or updated.

    Parameters

    Returns void

removeTimer

removeUIActor

  • removeUIActor(actor: Actor): void
  • Removes an actor as a piece of UI

    Parameters

    Returns void

update

  • update(engine: Engine, delta: number): void
  • Updates all the actors and timers in the scene. Called by the Engine.

    Parameters

    • engine: Engine

      Reference to the current Engine

    • delta: number

      The number of milliseconds since the last update

    Returns void

updateDrawTree

  • updateDrawTree(actor: Actor): void
  • Updates the given actor's position in the sorted drawing tree

    Parameters

    Returns void

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