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.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!
});
Optional options: EngineOptionsReadonly _originalSets the background color for the engine.
Excalibur browser events abstraction used for wiring to native browser events safely
Direct access to the engine's canvas element
Direct access to the canvas element ID, if an ID exists
Direct access to the excalibur clock
Returns the current frames elapsed milliseconds
Returns the current frame lag when in fixed update mode
The current [[Scene]] being drawn and updated on screen
Access Excalibur debugging functionality.
Useful when you want to debug different aspects of built in engine features like
Sets the Transparency for the engine.
Listen to and emit events on the Engine
Optional fixedOptionally 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.
Direct access to the ExcaliburGraphicsContext used for drawing things to the screen
Access engine input like pointer, keyboard, or gamepad
Map multiple input sources to specific game actions actions
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
The mouse wheel scroll prevention mode
Indicates whether audio should be paused when the game is no longer visible.
Readonly rootThe default [[Scene]] of the game, use [[Engine.goToScene]] to transition to different scenes.
Readonly scenesContains all the scenes currently registered with Excalibur
Screen abstraction
Readonly versionCurrent Excalibur version string
Useful for plugins or other tools that need to know what features are available
The height of the game canvas in pixels, (physical height component of the resolution of the canvas element)
The width of the game canvas in pixels (physical width component of the resolution of the canvas element)
Indicates the current [[DisplayMode]] of the engine.
Returns the height of the engine's visible drawing surface in pixels including zoom and device pixel ratio.
Returns the width of the engine's visible drawing surface in pixels including zoom and device pixel ratio.
Returns half height of the game canvas in pixels (half physical height component)
Returns half width of the game canvas in pixels (half physical width component)
Returns half the height of the engine's visible drawing surface in pixels including zoom and device pixel ratio.
Returns half the width of the engine's visible drawing surface in pixels including zoom and device pixel ratio.
Indicates whether the engine is set to fullscreen or not
Returns whether excalibur detects the current screen to be HiDPI
Gets whether the actor is Initialized
Returns true when loading is totally complete and the player has clicked start
Returns the calculated pixel ration for use in rendering
Hints the graphics context to truncate fractional world space coordinates
Access [[stats]] that holds frame statistics.
Gets the current engine timescale factor (default is 1.0 which is 1:1 time)
Sets the current engine timescale factor. Useful for creating slow-motion effects or fast-forward effects when using time-based movement.
Internal Internal Adds a [[Scene]] to the engine, think of scenes in Excalibur as you would levels or menus.
The key of the scene, must be unique
The scene to add to the engine
Adds a [[Timer]] to the [[currentScene]].
The timer to add to the [[currentScene]].
Adds a [[TileMap]] to the [[currentScene]], once this is done the TileMap will be drawn and updated.
Adds an actor to the [[currentScene]] of the game. This is synonymous
to calling engine.currentScene.add(actor).
Actors can only be drawn if they are a member of a scene, and only the [[currentScene]] may be drawn or updated.
The actor to add to the [[currentScene]]
Adds a [[ScreenElement]] to the [[currentScene]] of the game, ScreenElements do not participate in collisions, instead the remain in the same place on the screen.
The ScreenElement to add to the [[currentScene]]
Adds a [[Scene]] to the engine, think of scenes in Excalibur as you would levels or menus.
The name of the scene, must be unique
The scene to add to the engine
Optional event: anyReturns a BoundingBox of the top left corner of the screen and the bottom right corner of the screen.
Changes the currently updating and drawing scene to a different, named scene. Calls the [[Scene]] lifecycle events.
The key of the scene to transition to.
Optional data: TDataOptional data to send to the scene's onActivate method
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.
Some [[Loadable]] such as a [[Loader]] collection, [[Sound]], or [[Texture]].
Event signatures
Event signatures
Overridable implementation
Overridable implementation
Overridable implementation
Overridable implementation
Overridable implementation
Removes a scene instance from the engine
The scene to remove
Removes a scene from the engine by key
The scene to remove
Removes a [[Timer]] from the [[currentScene]].
The timer to remove to the [[currentScene]].
Removes a [[TileMap]] from the [[currentScene]], it will no longer be drawn or updated.
Removes an actor from the [[currentScene]] of the game. This is synonymous
to calling engine.currentScene.removeChild(actor).
Actors that are removed from a scene will no longer be drawn or updated.
The actor to remove from the [[currentScene]].
Removes a [[ScreenElement]] to the scene, it will no longer be drawn or updated
The ScreenElement to remove from the [[currentScene]]
Removes a [[Scene]] instance from the engine
The scene to remove
Removes a scene from the engine by key
The scene key to remove
Takes a screen shot of the current viewport and returns it as an HTML Image Element.
in the case of HiDPI return the full scaled backing image, by default false
Starts the internal game loop for Excalibur after loading any provided assets.
Optional loader: LoaderOptional [[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
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.