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

publiccanvas

canvas: Canvas = ...

data

data: Loadable<any>[]

Data associated with a loadable

publicengine

engine: Engine<any>

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

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

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

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

  • Returns HTMLButtonElement

publicplayButtonRootElement

  • get playButtonRootElement(): HTMLElement

  • Returns HTMLElement

publicprogress

  • get progress(): number

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

    Returns number

publicresources

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

  • Returns readonly Loadable<any>[]

Methods

publicaddResource

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

  • Add a resource to the loader to load

    Parameters

    Returns void

publicaddResources

  • 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

publicareResourcesLoaded

  • areResourcesLoaded(): Promise<void>

  • Returns Promise<void>

publicdispose

  • dispose(): void

  • Clean up generated elements for the loader

    Returns void

publicemit

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

publichidePlayButton

  • hidePlayButton(): void

  • Returns void

publicisLoaded

  • isLoaded(): boolean

  • Returns true if the loader has completely loaded all resources

    Returns boolean

publicload

  • 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>[]>

publicmarkResourceComplete

  • markResourceComplete(): void

  • Returns void

publicoff

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

publicon

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>

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<any>): void

  • Called by the engine before loading

    Parameters

    Returns void

onUpdate

  • onUpdate(engine: Engine<any>, elapsedMilliseconds: number): void

  • Optionally override the onUpdate

    Parameters

    • engine: Engine<any>
    • elapsedMilliseconds: number

    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>

publiconce

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