Skip to main content

EngineOptions <TKnownScenes>

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

Index

Properties

Properties

optionalantialiasing

antialiasing?: boolean | AntialiasOptions

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 default blending ImageFiltering.Blended
  • false - useful for pixel art style art work you would like sharp, this also hints excalibur to load images with default blending ImageFiltering.Pixel
  • AntialiasOptions Optionally deeply configure the different antialiasing settings, WARNING thar be dragons here. It is recommended you stick to true or false unless you understand what you're doing and need to control rendering to a high degree.

optionalbackgroundColor

backgroundColor?: Color

Optionally set the background color

optionalcanvasElement

canvasElement?: HTMLCanvasElement

Optionally specify the target canvas DOM element directly

optionalcanvasElementId

canvasElementId?: string

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

optionalconfigurePerformanceCanvas2DFallback

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 false, this will switch the internal graphics context to Canvas2D which can improve performance on non hardware accelerated browsers.

  • optionalshowPlayerMessage?: 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.

  • optionalthreshold?: { 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

optionaldisplayMode

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.

optionalenableCanvasTransparency

enableCanvasTransparency?: boolean

Optionally configure the native canvas transparent backdrop

optionalfixedUpdateFps

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.

optionalgarbageCollection

garbageCollection?: boolean | GarbageCollectionOptions

Optionally specify excalibur garbage collection, by default true.

  • true - garbage collection defaults are enabled (default)
  • false - garbage collection is completely disabled (not recommended)
  • GarbageCollectionOptions Optionally deeply configure garbage collection settings, WARNING thar be dragons here. It is recommended you stick to true or false unless you understand what you're doing, it is possible to get into a downward spiral if collection timings are set too low where you are stuck in repeated collection.

optionalgrabWindowFocus

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: itch.io or codesandbox.io

By default set to true,

optionalhandleContextLost

handleContextLost?: (e: Event) => void

Optionally provide a custom handler for the webgl context lost event

Type declaration

    • (e: Event): void

    • Optionally provide a custom handler for the webgl context lost event

      Parameters

      • e: Event

      Returns void

optionalhandleContextRestored

handleContextRestored?: (e: Event) => void

Optionally provide a custom handler for the webgl context restored event

Type declaration

    • (e: Event): void

    • Optionally provide a custom handler for the webgl context restored event

      Parameters

      • e: Event

      Returns void

optionalheight

height?: number

Optionally configure the height of the viewport in css pixels

optionalmaxFps

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

optionalphysics

physics?: boolean | PhysicsConfig

Optionally configure the physics simulation in excalibur

If false, Excalibur will not produce a physics simulation.

Default is configured to use SolverStrategy.Arcade physics simulation

optionalpixelArt

pixelArt?: boolean

Quick convenience property to configure Excalibur to use special settings for "pretty" anti-aliased pixel art

  1. Turns on special shader condition to blend for pixel art and enables various antialiasing settings, notice blending is ON for this special mode.

Equivalent to:

antialiasing: {
 pixelArtSampler: true,
 canvasImageRendering: 'auto',
 filtering: ImageFiltering.Blended,
 webglAntialiasing: true
}

optionalpixelRatio

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 or Pixel Art assets.

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;

optionalpointerScope

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.

optionalpowerPreference

powerPreference?: default | high-performance | low-power

Optionally hint the graphics context into a specific power profile

Default "high-performance"

optionalresolution

resolution?: Resolution

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

optionalscenes

scenes?: SceneMap<TKnownScenes>

Optionally specify scenes with their transitions and loaders to excalibur's scene Director

Scene transitions can can overridden dynamically by the Scene or by the call to .goToScene

optionalscrollPreventionMode

scrollPreventionMode?: ScrollPreventionMode

Scroll prevention method.

optionalsnapToPixel

snapToPixel?: boolean

Optionally snap graphics to nearest pixel, default is false

optionalsuppressConsoleBootMessage

suppressConsoleBootMessage?: boolean

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

optionalsuppressHiDPIScaling

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.

optionalsuppressMinimumBrowserFeatureDetection

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.

optionalsuppressPlayButton

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.

optionaluseDrawSorting

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.

optionaluvPadding

uvPadding?: number

Specify any UV padding you want use in pixels, this brings sampling into the texture if you're using a sprite sheet in one image to prevent sampling bleed.

Defaults:

  • antialiasing: false or filtering: ImageFiltering.Pixel - 0.0;
  • pixelArt: true - 0.25
  • All else 0.01

optionalviewport

viewport?: ViewportDimension

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

optionalwidth

width?: number

Optionally configure the width of the viewport in css pixels