Skip to main content

Scene <TActivationData>

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.

Scenes go through the following lifecycle

  1. onPreLoad - called once
  2. onInitialize - called once
  3. onActivate - called the first frame the scene is current
  4. onPreUpdate - called every update
  5. onPostUpdate - called every update
  6. onPreDraw - called every draw
  7. onPostDraw - called every draw
  8. onDeactivate - called teh first frame thescene is no longer current

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

  • new Scene<TActivationData>(): Scene<TActivationData>

  • Type parameters

    • TActivationData = unknown

    Returns Scene<TActivationData>

Properties

publicoptionalbackgroundColor

backgroundColor?: Color

Scene specific background color

publiccamera

camera: Camera = ...

Gets or sets the current camera for the scene

publicengine

engine: Engine<any>

Access to the Excalibur engine

publicevents

events: EventEmitter<SceneEvents> = ...

publicinput

input: InputHost

Access scene specific input, handlers on this only fire when this scene is active.

publicphysics

physics: PhysicsWorld = ...

The Excalibur physics world for the scene. Used to interact with colliders included in the scene.

Can be used to perform scene ray casts, track colliders, broadphase, and narrowphase.

publicworld

world: World = ...

The ECS world for the scene

Accessors

publicactors

  • get actors(): readonly Actor[]

  • The actors in the current scene

    Returns readonly Actor[]

publicentities

  • get entities(): readonly Entity<any>[]

  • The entities in the current scene

    Returns readonly Entity<any>[]

publicisInitialized

  • get isInitialized(): boolean

  • Gets whether or not the Scene has been initialized

    Returns boolean

publictileMaps

publictimers

  • get timers(): readonly Timer[]

publictriggers

  • The triggers in the current scene

    Returns readonly Trigger[]

Methods

publicadd

  • Adds a Timer to the current Scene.

    Parameters

    • timer: Timer

      The timer to add to the current Scene.

    Returns void

publicaddTimer

  • Adds a Timer to the scene

    Parameters

    • timer: Timer

      The timer to add

    Returns Timer

publiccancelTimer

  • Cancels a Timer, removing it from the scene nicely

    Parameters

    • timer: Timer

      The timer to cancel

    Returns Timer

publicclear

  • clear(deferred?: boolean): void

  • Removes all entities and timers from the scene, optionally indicate whether deferred should or shouldn't be used.

    By default entities use deferred removal

    Parameters

    • deferred: boolean = true

    Returns void

publiccontains

  • contains(actor: Actor): boolean

  • Checks whether an actor is contained in this scene or not

    Parameters

    Returns boolean

publicdebugDraw

  • Draws all the actors' debug information in the Scene. Called by the Engine.

    Parameters

    Returns void

publicdraw

  • Draws all the actors in the Scene. Called by the Engine.

    Parameters

    Returns void

publicemit

  • emit<TEventName>(eventName: TEventName, event: SceneEvents[TEventName]): void
  • emit(eventName: string, event?: any): void

publicisCurrentScene

  • isCurrentScene(): boolean

  • Returns boolean

publicisTimerActive

  • isTimerActive(timer: Timer): boolean

  • Tests whether a Timer is active in the scene

    Parameters

    Returns boolean

publicoff

  • off<TEventName>(eventName: TEventName, handler: Handler<SceneEvents[TEventName]>): void
  • off(eventName: string, handler: Handler<unknown>): void
  • off(eventName: string): void

publicon

publiconActivate

  • This is called when the scene is made active and started. It is meant to be overridden, this is where you should setup any DOM UI or event handlers needed for the scene.

    Parameters

    Returns void

publiconDeactivate

  • This is called when the scene is made transitioned away from and stopped. It is meant to be overridden, this is where you should cleanup any DOM UI or event handlers needed for the scene.

    Parameters

    Returns any

    Either data to pass to the next scene activation context as previousSceneData or nothing

publiconInitialize

  • onInitialize(engine: Engine<any>): 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

publiconPostDraw

  • Safe to override onPostDraw lifecycle event handler. Synonymous with .on('preupdate', (evt) =>{...})

    onPostDraw is called directly after a scene is drawn.

    Parameters

    Returns void

publiconPostUpdate

  • onPostUpdate(engine: Engine<any>, elapsed: 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<any>

      reference to the engine

    • elapsed: number

      Number of milliseconds elapsed since the last draw.

    Returns void

publiconPreDraw

  • Safe to override onPreDraw lifecycle event handler. Synonymous with .on('preupdate', (evt) =>{...})

    onPreDraw is called directly before a scene is drawn.

    Parameters

    Returns void

publiconPreLoad

  • Event hook to provide Scenes a way of loading scene specific resources.

    This is called before the Scene.onInitialize during scene transition. It will only ever fire once for a scene.

    Parameters

    Returns void

publiconPreUpdate

  • onPreUpdate(engine: Engine<any>, elapsed: 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<any>

      reference to the engine

    • elapsed: number

      Number of milliseconds elapsed since the last draw.

    Returns void

publiconTransition

  • Event hook fired directly before transition, either "in" or "out" of the scene

    This overrides the Engine scene definition. However transitions specified in goToScene take highest precedence

    // Overrides all
Engine.goToScene('scene', { destinationIn: ..., sourceOut: ... });

    This can be used to configure custom transitions for a scene dynamically

    Parameters

    • direction: in | out

    Returns Transition

publiconce

publicremove

  • 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

publicremoveTimer

  • Removes a Timer from the scene.

    @warning

    Can be dangerous, use cancelTimer instead

    Parameters

    • timer: Timer

      The timer to remove

    Returns Timer

publictransfer

  • Removes a Timer from it's current scene and adds it to this scene.

    Useful if you want to have an object be present in only 1 scene at a time.

    Parameters

    • timer: Timer

      The Timer to transfer to the current scene

    Returns void

publicupdate

  • update(engine: Engine<any>, elapsed: number): void

  • Updates all the actors and timers in the scene. Called by the Engine.

    Parameters

    • engine: Engine<any>

      Reference to the current Engine

    • elapsed: number

      The number of milliseconds since the last update

    Returns void

Page Options