loading-assets

Loading Assets

The Phaser Loader (this.load) handles fetching all external content: images, audio, JSON, tilemaps, atlases, fonts, scripts, and more. Assets are queued in preload(), loaded in parallel, and placed into global caches accessible by every Scene.

Key source paths: src/loader/LoaderPlugin.js, src/loader/File.js, src/loader/filetypes/, src/loader/events/ Related skills: ../game-setup-and-config/SKILL.md, ../scenes/SKILL.md, ../sprites-and-images/SKILL.md

Quick Start

class GameScene extends Phaser.Scene {
    preload() {
        this.load.image('logo', 'assets/logo.png');
    }

    create() {
        this.add.image(400, 300, 'logo');
    }
}

Assets loaded in preload() are guaranteed to be ready when create() runs. The Loader starts automatically during the preload phase.

Core Concepts

The Preload Pattern

Every Scene can define a preload() method. The Loader automatically starts when preload() completes and waits for all queued files to finish before calling create().

preload() {
    // Queue files - they don't load immediately
    this.load.image('sky', 'assets/sky.png');
    this.load.spritesheet('dude', 'assets/dude.png', { frameWidth: 32, frameHeight: 48 });
    this.load.audio('jump', 'assets/jump.mp3');
}

create() {
    // All assets above are now available
    this.add.image(400, 300, 'sky');
    this.add.sprite(100, 450, 'dude');
    this.sound.play('jump');
}

Loading Outside of Preload

If you call this.load methods outside of preload() (for example, in create() or in response to a user action), you must manually start the Loader:

create() {
    this.load.image('extra', 'assets/extra.png');
    this.load.once('complete', () => {
        this.add.image(400, 300, 'extra');
    });
    this.load.start();
}

URL Resolution: baseURL, path, and prefix

The final URL for a file is resolved as: baseURL + path + filename. These can be set via the game config or at runtime.