Defines the available options to configure the Excalibur engine at constructor time.


  • EngineOptions


antialiasing?: boolean

Optionally specify antialiasing (smoothing), by default true (smooth pixels)

  • true - useful for high resolution art work you would like smoothed, this also hints excalibur to load images with ImageFiltering.Blended

  • false - useful for pixel art style art work you would like sharp, this also hints excalibur to load images with ImageFiltering.Pixel

backgroundColor?: Color

Optionally set the background color

canvasElement?: HTMLCanvasElement

Optionally specify the target canvas DOM element directly

canvasElementId?: string

Optionally specify the target canvas DOM element to render the game in

configurePerformanceCanvas2DFallback?: {
    allow: boolean;
    showPlayerMessage?: boolean;
    threshold?: {
        fps: number;
        numberOfFrames: number;

Optionally configure how excalibur handles poor performance on a player's browser

Type declaration

  • allow: boolean

    By default true, this will switch the internal graphics context to Canvas2D which can improve performance on non hardware accelerated browsers.

  • Optional showPlayerMessage?: boolean

    By default false, if set to true a dialogue will be presented to the player about their browser and how to potentially address any issues.

  • Optional threshold?: {
        fps: number;
        numberOfFrames: number;

    Default { numberOfFrames: 100, fps: 20 }, optionally configure excalibur to fallback to the 2D Canvas renderer if bad performance is detected.

    In this example of the default if excalibur is running at 20fps or less for 100 frames it will trigger the fallback to the 2D Canvas renderer.

    • fps: number
    • numberOfFrames: number
displayMode?: DisplayMode

The DisplayMode of the game, by default DisplayMode.FitScreen with aspect ratio 4:3 (800x600). Depending on this value, width and height may be ignored.

enableCanvasTransparency?: boolean

Optionally configure the native canvas transparent backdrop

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.

grabWindowFocus?: boolean

Sets the focus of the window, this is needed when hosting excalibur in a cross-origin iframe in order for certain events (like keyboard) to work. For example: or

By default set to true,

height?: number

Optionally configure the height of the viewport in css pixels

maxFps?: number

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

pixelRatio?: number

Optionally upscale the number of pixels in the canvas. Normally only useful if you need a smoother look to your assets, especially Text.

WARNING It is recommended you try using antialiasing: true before adjusting pixel ratio. Pixel ratio will consume more memory and on mobile may break if the internal size of the canvas exceeds 4k pixels in width or height.

Default is based the display's pixel ratio, for example a HiDPI screen might have the value 2;

pointerScope?: PointerScope

Configures the pointer scope. Pointers scoped to the 'Canvas' can only fire events within the canvas viewport; whereas, 'Document' (default) scoped will fire anywhere on the page.

resolution?: ScreenDimension

Optionally specify the size the logical pixel resolution, if not specified it will be width x height. See Resolution for common presets.

scrollPreventionMode?: ScrollPreventionMode

Scroll prevention method.

snapToPixel?: boolean

Optionally snap graphics to nearest pixel, default is false

suppressConsoleBootMessage?: boolean

Suppress boot up console message, which contains the "powered by Excalibur message"

suppressHiDPIScaling?: boolean

Suppress HiDPI auto detection and scaling, it is not recommended users of excalibur switch off this feature. This feature detects and scales the drawing canvas appropriately to accommodate HiDPI screens.

suppressMinimumBrowserFeatureDetection?: boolean

Suppress minimum browser feature detection, it is not recommended users of excalibur switch this off. This feature ensures that the currently running browser meets the minimum requirements for running excalibur. This can be useful if running on non-standard browsers or if there is a bug in excalibur preventing execution.

suppressPlayButton?: boolean

Suppress play button, it is not recommended users of excalibur switch this feature. Some browsers require a user gesture (like a click) for certain browser features to work like web audio.

useDrawSorting?: boolean

Default true, optionally configure excalibur to use optimal draw call sorting, to opt out set this to false.

Excalibur will automatically sort draw calls by z and priority into renderer batches for maximal draw performance, this can disrupt a specific desired painter order.

viewport?: ScreenDimension

Optionally configure the width & height of the viewport in css pixels. Use viewport instead of EngineOptions.width and EngineOptions.height, or vice versa.

width?: number

Optionally configure the width of the viewport in css pixels