EngineOptions <TKnownScenes>
Index
Properties
- antialiasing
- backgroundColor
- canvasElement
- canvasElementId
- configurePerformanceCanvas2DFallback
- displayMode
- enableCanvasContextMenu
- enableCanvasTransparency
- fixedUpdateFps
- fixedUpdateTimestep
- garbageCollection
- grabWindowFocus
- handleContextLost
- handleContextRestored
- height
- maxFps
- physics
- pixelArt
- pixelRatio
- pointerScope
- powerPreference
- resolution
- scenes
- scrollPreventionMode
- snapToPixel
- suppressConsoleBootMessage
- suppressHiDPIScaling
- suppressMinimumBrowserFeatureDetection
- suppressPlayButton
- useDrawSorting
- uvPadding
- viewport
- width
Properties
optionalantialiasing
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.Blendedfalse
- 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
orfalse
unless you understand what you're doing and need to control rendering to a high degree.
optionalbackgroundColor
Optionally set the background color
optionalcanvasElement
Optionally specify the target canvas DOM element directly
optionalcanvasElementId
Optionally specify the target canvas DOM element to render the game in
optionalconfigurePerformanceCanvas2DFallback
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 totrue
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
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.
optionalenableCanvasContextMenu
Optionally enable the right click context menu on the canvas
Default if unset is false
optionalenableCanvasTransparency
Optionally configure the native canvas transparent backdrop
optionalfixedUpdateFps
Optionally configure a fixed update fps, this can be desirable 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.
WARN: fixedUpdateTimestep
takes precedence over fixedUpdateFps
use whichever is most convenient.
optionalfixedUpdateTimestep
Optionally configure a fixed update timestep in milliseconds, this can be desirable 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.
WARN: fixedUpdateTimestep
takes precedence over fixedUpdateFps
use whichever is most convenient.
optionalgarbageCollection
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
orfalse
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
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
Optionally provide a custom handler for the webgl context lost event
Type declaration
Optionally provide a custom handler for the webgl context lost event
Parameters
e: Event
Returns void
optionalhandleContextRestored
Optionally provide a custom handler for the webgl context restored event
Type declaration
Optionally provide a custom handler for the webgl context restored event
Parameters
e: Event
Returns void
optionalheight
Optionally configure the height of the viewport in css pixels
optionalmaxFps
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
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
Quick convenience property to configure Excalibur to use special settings for "pretty" anti-aliased pixel art
- 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
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
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
Optionally hint the graphics context into a specific power profile
Default "high-performance"
optionalresolution
Optionally specify the size the logical pixel resolution, if not specified it will be width x height. See Resolution for common presets.
optionalscenes
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
Scroll prevention method.
optionalsnapToPixel
Optionally snap graphics to nearest pixel, default is false
optionalsuppressConsoleBootMessage
Suppress boot up console message, which contains the "powered by Excalibur message"
optionalsuppressHiDPIScaling
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
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
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
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
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
orfiltering: ImageFiltering.Pixel
- 0.0;pixelArt: true
- 0.25- All else 0.01
optionalviewport
Optionally configure the width & height of the viewport in css pixels.
Use viewport
instead of EngineOptions.width and EngineOptions.height, or vice versa.
optionalwidth
Optionally configure the width of the viewport in css pixels
Defines the available options to configure the Excalibur engine at constructor time.