Options
All
  • Public
  • Public/Protected
  • All
Menu

The Excalibur Engine

The Engine is the main driver for a game. It is responsible for starting/stopping the game, maintaining state, transmitting events, loading resources, and managing the scene.

Hierarchy

Implements

Index

Constructors

  • Creates a new game using the given EngineOptions. By default, if no options are provided, the game will be rendered full screen (taking up all available browser window space). You can customize the game rendering through EngineOptions.

    Example:

    var game = new ex.Engine({
    width: 0, // the width of the canvas
    height: 0, // the height of the canvas
    enableCanvasTransparency: true, // the transparencySection of the canvas
    canvasElementId: '', // the DOM canvas element ID, if you are providing your own
    displayMode: ex.DisplayMode.FullScreen, // the display mode
    pointerScope: ex.Input.PointerScope.Document, // the scope of capturing pointer (mouse/touch) events
    backgroundColor: ex.Color.fromHex('#2185d0') // background color of the engine
    });

    // call game.start, which is a Promise
    game.start().then(function () {
    // ready, set, go!
    });

    Parameters

    Returns Engine

Properties

_originalDisplayMode: DisplayMode
backgroundColor: Color

Sets the background color for the engine.

browser: BrowserEvents

Excalibur browser events abstraction used for wiring to native browser events safely

canvas: HTMLCanvasElement

Direct access to the engine's canvas element

canvasElementId: string

Direct access to the canvas element ID, if an ID exists

clock: Clock

Direct access to the excalibur clock

currentFrameElapsedMs: number = 0

Returns the current frames elapsed milliseconds

currentFrameLagMs: number = 0

Returns the current frame lag when in fixed update mode

currentScene: Scene

The current Scene being drawn and updated on screen

debug: Debug

Access Excalibur debugging functionality.

Useful when you want to debug different aspects of built in engine features like

  • Transform
  • Graphics
  • Colliders
enableCanvasTransparency: boolean = true

Sets the Transparency for the engine.

eventDispatcher: EventDispatcher<any>

Direct access to the game object event dispatcher.

fixedUpdateFps?: number

Optionally configure a fixed update fps, this can be desireable if you need the physics simulation to be very stable. When set the update step and physics will use the same elapsed time for each tick even if the graphical framerate drops. In order for the simulation to be correct, excalibur will run multiple updates in a row (at the configured update elapsed) to catch up, for example there could be X updates and 1 draw each clock step.

NOTE: This does come at a potential perf cost because each catch-up update will need to be run if the fixed rate is greater than the current instantaneous framerate, or perf gain if the fixed rate is less than the current framerate.

By default is unset and updates will use the current instantaneous framerate with 1 update and 1 draw each clock step.

graphicsContext: ExcaliburGraphicsContext

Direct access to the ExcaliburGraphicsContext used for drawing things to the screen

Access engine input like pointer, keyboard, or gamepad

maxFps: number = Number.POSITIVE_INFINITY

Optionally set the maximum fps if not set Excalibur will go as fast as the device allows.

You may want to constrain max fps if your game cannot maintain fps consistently, it can look and feel better to have a 30fps game than one that bounces between 30fps and 60fps

pageScrollPreventionMode: ScrollPreventionMode

The mouse wheel scroll prevention mode

pauseAudioWhenHidden: boolean = true

Indicates whether audio should be paused when the game is no longer visible.

rootScene: Scene

The default Scene of the game, use Engine.goToScene to transition to different scenes.

scenes: {} = {}

Contains all the scenes currently registered with Excalibur

Type declaration

screen: Screen

Screen abstraction

Accessors

  • get canvasHeight(): number
  • The height of the game canvas in pixels, (physical height component of the resolution of the canvas element)

    Returns number

  • get canvasWidth(): number
  • The width of the game canvas in pixels (physical width component of the resolution of the canvas element)

    Returns number

  • get drawHeight(): number
  • Returns the height of the engine's visible drawing surface in pixels including zoom and device pixel ratio.

    Returns number

  • get drawWidth(): number
  • Returns the width of the engine's visible drawing surface in pixels including zoom and device pixel ratio.

    Returns number

  • get halfCanvasHeight(): number
  • Returns half height of the game canvas in pixels (half physical height component)

    Returns number

  • get halfCanvasWidth(): number
  • Returns half width of the game canvas in pixels (half physical width component)

    Returns number

  • get halfDrawHeight(): number
  • Returns half the height of the engine's visible drawing surface in pixels including zoom and device pixel ratio.

    Returns number

  • get halfDrawWidth(): number
  • Returns half the width of the engine's visible drawing surface in pixels including zoom and device pixel ratio.

    Returns number

  • get isDebug(): boolean
  • get isFullscreen(): boolean
  • Indicates whether the engine is set to fullscreen or not

    Returns boolean

  • get isHiDpi(): boolean
  • Returns whether excalibur detects the current screen to be HiDPI

    Returns boolean

  • get isInitialized(): boolean
  • Gets whether the actor is Initialized

    Returns boolean

  • get loadingComplete(): boolean
  • Returns true when loading is totally complete and the player has clicked start

    Returns boolean

  • get pixelRatio(): number
  • Returns the calculated pixel ration for use in rendering

    Returns number

  • get ready(): boolean
  • get snapToPixel(): boolean
  • set snapToPixel(shouldSnapToPixel: boolean): void
  • Hints the graphics context to truncate fractional world space coordinates

    Returns boolean

  • Hints the graphics context to truncate fractional world space coordinates

    Parameters

    • shouldSnapToPixel: boolean

    Returns void

  • get timescale(): number
  • set timescale(value: number): void
  • Gets the current engine timescale factor (default is 1.0 which is 1:1 time)

    Returns number

  • Sets the current engine timescale factor. Useful for creating slow-motion effects or fast-forward effects when using time-based movement.

    Parameters

    • value: number

    Returns void

Methods

  • _postupdate(delta: number): void
  • _preupdate(delta: number): void
  • addScene(key: string, scene: Scene): void
  • Adds a Scene to the engine, think of scenes in Excalibur as you would levels or menus.

    Parameters

    • key: string

      The name of the scene, must be unique

    • scene: Scene

      The scene to add to the engine

    Returns void

  • emit(eventName: string, eventObject: any): void
  • Emits a new event

    Parameters

    • eventName: string

      Name of the event to emit

    • eventObject: any

      Data associated with this event

    Returns void

  • getAntialiasing(): boolean
  • Return the current smoothing status of the canvas

    Returns boolean

  • Returns a BoundingBox of the top left corner of the screen and the bottom right corner of the screen.

    Returns BoundingBox

  • goToScene(key: string): void
  • Changes the currently updating and drawing scene to a different, named scene. Calls the Scene lifecycle events.

    Parameters

    • key: string

      The key of the scene to transition to.

    Returns void

  • isReady(): Promise<void>
  • isRunning(): boolean
  • Returns the Engine's running status, Useful for checking whether engine is running or paused.

    Returns boolean

  • load(loader: Loadable<any>): Promise<void>
  • Another option available to you to load resources into the game. Immediately after calling this the game will pause and the loading screen will appear.

    Parameters

    Returns Promise<void>

  • onFatalException(e: any): void
  • The action to take when a fatal exception is thrown

    Parameters

    • e: any

    Returns void

  • onInitialize(_engine: Engine): void
  • onPostUpdate(_engine: Engine, _delta: number): void
  • onPreUpdate(_engine: Engine, _delta: number): void
  • remove(scene: Scene): void
  • remove(sceneKey: string): void
  • remove(timer: Timer): void
  • remove(tileMap: TileMap): void
  • remove(actor: Actor): void
  • remove(screenElement: ScreenElement): void
  • removeScene(scene: Scene): void
  • removeScene(key: string): void
  • Removes a Scene instance from the engine

    Parameters

    • scene: Scene

      The scene to remove

    Returns void

  • Removes a scene from the engine by key

    Parameters

    • key: string

      The scene key to remove

    Returns void

  • Transforms the current x, y from screen coordinates to world coordinates

    Parameters

    • point: Vector

      Screen coordinate to convert

    Returns Vector

  • screenshot(preserveHiDPIResolution?: boolean): Promise<HTMLImageElement>
  • Takes a screen shot of the current viewport and returns it as an HTML Image Element.

    Parameters

    • preserveHiDPIResolution: boolean = false

      in the case of HiDPI return the full scaled backing image, by default false

    Returns Promise<HTMLImageElement>

  • setAntialiasing(isSmooth: boolean): void
  • If supported by the browser, this will set the antialiasing flag on the canvas. Set this to false if you want a 'jagged' pixel art look to your image resources.

    Parameters

    • isSmooth: boolean

      Set smoothing to true or false

    Returns void

  • showDebug(toggle: boolean): void
  • Enable or disable Excalibur debugging functionality.

    Parameters

    • toggle: boolean

      a value that debug drawing will be changed to

    Returns void

  • start(loader?: Loader): Promise<void>
  • Starts the internal game loop for Excalibur after loading any provided assets.

    Parameters

    • Optional loader: Loader

      Optional Loader to use to load resources. The default loader is Loader, override to provide your own custom loader.

      Note: start() only resolves AFTER the user has clicked the play button

    Returns Promise<void>

  • stop(): void
  • Stops Excalibur's main loop, useful for pausing the game.

    Returns void

  • toggleDebug(): boolean
  • Toggle Excalibur debugging functionality.

    Returns boolean

  • useCanvas2DFallback(): void
  • Switches the engine's graphics context to the 2D Canvas.

    warning

    Some features of Excalibur will not work in this mode.

    Returns void

  • Transforms a world coordinate, to a screen coordinate

    Parameters

    • point: Vector

      World coordinate to convert

    Returns Vector