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!
});
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.
Direct access to the game object event dispatcher.
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
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
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 Timer to the currentScene.
The timer to add to the currentScene.
Returns 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.
Alias for removeEventListener. If only the eventName is specified
it will remove all handlers registered for that specific event. If the eventName
and the handler instance are specified only that handler will be removed.
Name of the event to listen for
Optional handler: ((event: ExcaliburGraphicsContext2DCanvas) => void)Event handler for the thrown event
Optional handler: ((event: Events.InitializeEvent<Engine>) => void)Optional handler: ((event: Events.VisibleEvent) => void)Optional handler: ((event: Events.HiddenEvent) => void)Optional handler: ((event: Events.GameStartEvent) => void)Optional handler: ((event: Events.GameStopEvent) => void)Optional handler: ((event: Events.PreUpdateEvent<Engine>) => void)Optional handler: ((event: Events.PostUpdateEvent<Engine>) => void)Optional handler: ((event: Events.PreFrameEvent) => void)Optional handler: ((event: Events.PostFrameEvent) => void)Optional handler: ((event: Events.PreDrawEvent) => void)Optional handler: ((event: Events.PostDrawEvent) => void)Event signatures
Event signatures
Overridable implementation
Overridable implementation
Once listens to an event one time, then unsubscribes from that event
The name of the event to subscribe to once
The handler of the event that will be auto unsubscribed
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 Timer from the currentScene.
The timer to remove to the currentScene.
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
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.