Skip to main content

Loader

Pre-loading assets

The loader provides a mechanism to preload multiple resources at one time. The loader must be passed to the engine in order to trigger the loading progress bar.

The Loader itself implements Loadable so you can load loaders.

Example: Pre-loading resources for a game

// create a loader
var loader = new ex.Loader();

// create a resource dictionary (best practice is to keep a separate file)
var resources = {
  TextureGround: new ex.Texture("/images/textures/ground.png"),
  SoundDeath: new ex.Sound("/sound/death.wav", "/sound/death.mp3")
};

// loop through dictionary and add to loader
for (var loadable in resources) {
  if (resources.hasOwnProperty(loadable)) {
    loader.addResource(resources[loadable]);
  }
}

// start game
game.start(loader).then(function () {
  console.log("Game started!");
});

Customize the Loader

The loader can be customized to show different, text, logo, background color, and button.

const loader = new ex.Loader([playerTexture]);

// The loaders button text can simply modified using this
loader.playButtonText = 'Start the best game ever';

// The logo can be changed by inserting a base64 image string here

loader.logo = 'data:image/png;base64,iVBORw...';
loader.logoWidth = 15;
loader.logoHeight = 14;

// The background color can be changed like so by supplying a valid CSS color string

loader.backgroundColor = 'red'
loader.backgroundColor = '#176BAA'

// To build a completely new button
loader.startButtonFactory = () => {
    let myButton = document.createElement('button');
    myButton.textContent = 'The best button';
    return myButton;
};

engine.start(loader).then(() => {});

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

  • Parameters

    • optionaloptions: LoaderOptions

      Optionally provide options to loader

    Returns Loader

Properties

publicbackgroundColor

backgroundColor: string = '#176BAA'

Gets or sets the background color of the loader as a hex string

publicinheritedcanvas

canvas: Canvas = ...

data

data: Loadable<any>[]

Data associated with a loadable

publicinheritedengine

engine: Engine

publicevents

events: EventEmitter<any> = ...

publicloadingBarColor

loadingBarColor: Color = Color.White

Gets or sets the color of the loading bar, default is Color.White

publicloadingBarPosition

loadingBarPosition: Vector | null

Positions the top left corner of the loading bar If not set, the loader automatically positions the loading bar

publiclogo

logo: string = logoImg

publiclogoHeight

logoHeight: number = 118

publiclogoPosition

logoPosition: Vector | null

Positions the top left corner of the logo image If not set, the loader automatically positions the logo

publiclogoWidth

logoWidth: number = 468

publicplayButtonPosition

playButtonPosition: Vector | null

Positions the top left corner of the play button. If not set, the loader automatically positions the play button

publicplayButtonText

playButtonText: string = 'Play game'

Get/set play button text

publicscreen

screen: Screen

publicsuppressPlayButton

suppressPlayButton: boolean = false

Accessors

publicplayButtonElement

  • get playButtonElement(): HTMLButtonElement | null

  • Returns HTMLButtonElement | null

publicplayButtonRootElement

  • get playButtonRootElement(): HTMLElement | null

  • Returns HTMLElement | null

publicinheritedprogress

  • get progress(): number

  • Returns the progress of the loader as a number between [0, 1] inclusive.

    Returns number

publicinheritedresources

  • get resources(): readonly Loadable<any>[]

  • Returns readonly Loadable<any>[]

Methods

publicinheritedaddResource

  • addResource(loadable: Loadable<any>): void

  • Add a resource to the loader to load

    Parameters

    Returns void

publicinheritedaddResources

  • addResources(loadables: Loadable<any>[]): void

  • Add a list of resources to the loader to load

    Parameters

    • loadables: Loadable<any>[]

      The list of resources to load

    Returns void

publicinheritedareResourcesLoaded

  • areResourcesLoaded(): Promise<void>

  • Returns Promise<void>

publicdispose

  • dispose(): void

  • Clean up generated elements for the loader

    Returns void

publicinheritedemit

  • emit<TEventName>(eventName: TEventName, event: LoaderEvents[TEventName]): void
  • emit(eventName: string, event?: any): void

publichidePlayButton

  • hidePlayButton(): void

  • Returns void

publicinheritedisLoaded

  • isLoaded(): boolean

  • Returns true if the loader has completely loaded all resources

    Returns boolean

publicinheritedload

  • Not meant to be overridden

    Begin loading all of the supplied resources, returning a promise that resolves when loading of all is complete AND the user has interacted with the loading screen

    Returns Promise<Loadable<any>[]>

publicinheritedmarkResourceComplete

  • markResourceComplete(): void

  • Returns void

publicinheritedoff

  • off<TEventName>(eventName: TEventName, handler: Handler<LoaderEvents[TEventName]>): void
  • off(eventName: string, handler: Handler<unknown>): void
  • off(eventName: string): void

publicinheritedon

publiconAfterLoad

  • onAfterLoad(): Promise<void>

  • Overridable lifecycle method, called after loading has completed

    Returns Promise<void>

publiconBeforeLoad

  • onBeforeLoad(): Promise<void>

  • Overridable lifecycle method, called directly before loading starts

    Returns Promise<void>

publicinheritedonce

publiconDraw

  • onDraw(ctx: CanvasRenderingContext2D): void

  • Loader draw function. Draws the default Excalibur loading screen. Override logo, logoWidth, logoHeight and backgroundColor properties to customize the drawing, or just override entire method.

    Parameters

    • ctx: CanvasRenderingContext2D

    Returns void

publiconInitialize

  • onInitialize(engine: Engine): void

  • Called by the engine before loading

    Parameters

    Returns void

inheritedonUpdate

  • onUpdate(engine: Engine, elapsed: number): void

  • Optionally override the onUpdate

    Parameters

    Returns void

publiconUserAction

  • onUserAction(): Promise<void>

  • Return a promise that resolves when the user interacts with the loading screen in some way, usually a click.

    It's important to implement this in order to unlock the audio context in the browser. Browsers automatically prevent audio from playing until the user performs an action.

    Returns Promise<void>

publicshowPlayButton

  • showPlayButton(): Promise<void>

  • Shows the play button and returns a promise that resolves when clicked

    Returns Promise<void>

publicstartButtonFactory

  • startButtonFactory(): HTMLButtonElement

  • Return a html button element for excalibur to use as a play button

    Returns HTMLButtonElement

Page Options