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!
});Sets the background color for the engine.
Direct access to the engine's canvas element
Direct access to the canvas element ID, if an ID exists
Direct access to the engine's 2D rendering context
The current Scene being drawn and updated on screen
Access Excalibur debugging functionality.
Sets the Transparency for the engine.
Direct access to the game object event dispatcher.
Access engine input like pointer, keyboard, or gamepad
Indicates whether the engine should draw with debug information
The mouse wheel scroll prevention mode
Indicates whether audio should be paused when the game is no longer visible.
Indicates the current position of the engine. Valid only when DisplayMode is DisplayMode.Position
Gets or sets the list of post processors to apply at the end of drawing a frame (such as ColorBlindCorrector)
The default Scene of the game, use Engine.goToScene to transition to different scenes.
Contains 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 the calculated pixel ration for use in rendering
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.
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
Removes an actor from the currentScene of the game. This is synonymous
to calling engine.currentScene.remove(actor).
Actors that are removed from a scene will no longer be drawn or updated.
The actor to remove from the currentScene.
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 TileMap to the currentScene, once this is done the TileMap will be drawn and updated.
Adds a Timer to the currentScene.
The timer to add to the currentScene.
Emits a new event
Name of the event to emit
Data associated with this event
Return the current smoothing status of the canvas
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.
Returns the Engine's Running status, Useful for checking whether engine is running or paused.
The action to take when a fatal exception is thrown
Plays a sprite animation on the screen at the specified x and y
(in game coordinates, not screen pixels). These animations play
independent of actors, and will be cleaned up internally as soon
as they are complete. Note animations that loop will never be
cleaned up.
Animation to play
x game coordinate to play the animation
y game coordinate to play the animation
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 TileMap from the currentScene, it will no longer be drawn or updated.
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.
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.
Set smoothing to true or false
Stops Excalibur's main loop, useful for pausing the game.
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.
Excalibur uses the HTML5 Canvas API for drawing your game to the screen. The canvas is available to all
drawfunctions for raw manipulation, but Excalibur is meant to simplify or completely remove the need to use the canvas directly.Creating a Game
To create a new game, create a new instance of Engine and pass in the configuration (EngineOptions). Excalibur only supports a single instance of a game at a time, so it is safe to use globally. You can then call start which starts the game and optionally accepts a Loader which you can use to pre-load assets.
Look at the Screen abstraction to specify custom resolutions and viewport for your game.
var game = new ex.Engine({ width: 800, // the width of the canvas height: 600, // the height 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 }); // call game.start, which is a Promise game.start().then(function() { // ready, set, go! });The Main Loop
The Excalibur engine uses a simple main loop. The engine updates and renders the "scene graph" which is the scenes and the tree of actors within that scene. Only one Scene can be active at a time. The engine does not update/draw any other scene, which means any actors will not be updated/drawn if they are part of a deactivated scene.
Scene Graph
Engine |_ Scene 1 (activated) |_ Actor 1 |_ Child Actor 1 |_ Actor 2 |_ Scene 2 (deactivated) |_ Scene 3 (deactivated)The engine splits the game into two primary responsibilities: updating and drawing. This is to keep your game smart about splitting duties so that you aren't drawing when doing logic or performing logic as you draw.
Update Loop
The first operation run is the Update loop. Actor and Scene both implement an overridable/extendable
updatemethod. Use it to perform any logic-based operations in your game for a particular class.Draw Loop
The next step is the Draw loop. A Scene loops through its child actors and draws each one. You can override the
drawmethod on an actor to customize its drawing. You should not perform any logic in a draw call, it should only relate to drawing.Working with Scenes
The engine automatically creates a "root" Scene. You can use this for whatever you want. You can manipulate scenes using add, remove, and goToScene. You can overwrite or remove the
rootscene if you want. There always has to be at least one scene and only one scene can be active at any one time.Learn more about the scene lifecycle.
Adding a scene
var game = new ex.Engine(); // create a new level var level1 = new ex.Scene(); // add level 1 to the game game.add('level1', level1); // in response to user input, go to level 1 game.goToScene('level1'); // go back to main menu game.goToScene('root');Accessing the current scene
To add actors and other entities to the current Scene, you can use add. Alternatively, you can use Engine.currentScene to directly access the current scene.
Managing the Viewport
Excalibur supports multiple display modes for a game. Pass in a
displayModeoption when creating a game to customize the viewport.The canvasWidth and canvasHeight are still used to represent the native width and height of the canvas, but you can leave them at 0 or
undefinedto ignore them. If width and height are not specified, the game won't be scaled and native resolution will be the physical screen width/height.If you use DisplayMode.Container, the canvas will automatically resize to fit inside of it's parent DOM element. This allows you maximum control over the game viewport, e.g. in case you want to provide HTML UI on top or as part of your game.
You can use DisplayMode.Position to specify where the game window will be displayed on screen. if this DisplayMode is selected, then a position option must be provided to the Engine constructor. The position option can be a String or an AbsolutePosition. The first word in a String must be the desired vertical alignment of the window. The second (optional) word is the desired horizontal alignment.
Valid String examples: "top left", "top", "bottom", "middle", "middle center", "bottom right" Valid AbsolutePosition examples: {top: 5, right: 10%}, {bottom: 49em, left: 10px}, {left: 10, bottom: 40}
Extending the Engine
For complex games, any entity that inherits Class can be extended to override built-in functionality. This is recommended for actors and scenes, especially. You can customize the options or provide more for your game by extending Engine.
TypeScript
class Game extends ex.Engine { constructor() { super({ width: 800, height: 600, displayMode: DisplayMode.FullScreen }); } public start() { // add custom scenes this.add('mainmenu', new MainMenu()); return super.start(myLoader).then(() => { this.goToScene('mainmenu'); // custom start-up }); } } var game = new Game(); game.start();Javascript
var Game = ex.Engine.extend({ constructor: function () { Engine.call(this, { width: 800, height: 600, displayMode: DisplayMode.FullScreen }); } start: function() { // add custom scenes this.add("mainmenu", new MainMenu()); var _this = this; return Engine.prototype.start.call(this, myLoader).then(function() { _this.goToScene("mainmenu"); // custom start-up }); } }); var game = new Game(); game.start();