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