loading-assets

name	loading-assets
description	Use this skill when loading assets in Phaser 4. Covers the Loader plugin, loading images, spritesheets, atlases, audio, JSON, tilemaps, bitmap fonts, and tracking load progress. Triggers on: preload, this.load, asset loading, spritesheet, atlas, load progress.

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.

preload() {
    // Set base URL (prepended to all relative paths)
    this.load.setBaseURL('https://cdn.example.com/');

    // Set path (prepended after baseURL, before filename)
    this.load.setPath('assets/images/');

    // Set key prefix (prepended to the cache key, not the URL)
    this.load.setPrefix('LEVEL1.');

    // Loads from: https://cdn.example.com/assets/images/hero.png
    // Cached with key: LEVEL1.hero
    this.load.image('hero', 'hero.png');

    // Absolute URLs bypass the path/baseURL
    this.load.image('cloud', 'https://other-server.com/cloud.png');
}

These can also be set in the game config:

const config = {
    loader: {
        baseURL: 'https://cdn.example.com/',
        path: 'assets/',
        prefix: '',
        maxParallelDownloads: 32,
        crossOrigin: 'anonymous',
        responseType: '',
        async: true,
        timeout: 0,
        maxRetries: 2,
        imageLoadType: 'XHR' // or 'HTMLImageElement'
    }
};

Global Caches

Assets are stored in global game-level caches, not per-Scene. An image loaded in one Scene is available in every other Scene. Textures go into game.textures (the Texture Manager). Other data goes into game.cache sub-caches (e.g., game.cache.json, game.cache.audio, game.cache.xml).

Load Events

The Loader emits events throughout the loading lifecycle. Use these for progress bars and loading screens.

preload() {
    this.load.on('progress', (value) => {
        // value is 0 to 1
        console.log(`Loading: ${Math.round(value * 100)}%`);
    });

    this.load.on('complete', () => {
        console.log('All assets loaded');
    });

    this.load.on('loaderror', (file) => {
        console.warn('Failed to load:', file.key);
    });

    this.load.image('bg', 'assets/bg.png');
}

Common Patterns

Loading Images and Sprite Sheets

preload() {
    // Single image
    this.load.image('star', 'assets/star.png');

    // Image with normal map (pass URL array: [texture, normalMap])
    this.load.image('brick', ['assets/brick.png', 'assets/brick_n.png']);

    // Sprite sheet (fixed frame sizes)
    this.load.spritesheet('explosion', 'assets/explosion.png', {
        frameWidth: 64,
        frameHeight: 64,
        startFrame: 0,
        endFrame: 23,
        margin: 0,
        spacing: 0
    });

    // SVG (optionally rasterize at a specific size)
    this.load.svg('logo', 'assets/logo.svg', { width: 400, height: 400 });
}

Loading Audio

preload() {
    // Single file
    this.load.audio('bgm', 'assets/music.mp3');

    // Multiple formats for cross-browser support
    this.load.audio('bgm', ['assets/music.ogg', 'assets/music.mp3']);

    // Audio sprite (JSON defines named regions within a single audio file)
    this.load.audioSprite('sfx', 'assets/sfx.json', [
        'assets/sfx.ogg',
        'assets/sfx.mp3'
    ]);
}

Loading JSON and Tilemaps

preload() {
    // JSON data (stored in this.cache.json)
    this.load.json('levelData', 'assets/level1.json');

    // JSON with a dataKey to extract a sub-object
    this.load.json('enemies', 'assets/data.json', 'enemies');

    // Tiled tilemap (JSON format exported from Tiled)
    this.load.tilemapTiledJSON('map', 'assets/map.json');

    // CSV tilemap
    this.load.tilemapCSV('csvmap', 'assets/level.csv');

    // Impact tilemap
    this.load.tilemapImpact('impactmap', 'assets/level.js');
}

create() {
    const data = this.cache.json.get('levelData');
    const map = this.make.tilemap({ key: 'map' });
}

Loading Atlases

preload() {
    // JSON atlas (e.g., TexturePacker JSON Hash/Array)
    this.load.atlas('sprites', 'assets/sprites.png', 'assets/sprites.json');

    // XML atlas (e.g., Starling/Sparrow format)
    this.load.atlasXML('ui', 'assets/ui.png', 'assets/ui.xml');

    // Multi-atlas (atlas split across multiple textures)
    this.load.multiatlas('world', 'assets/world.json', 'assets/');

    // Unity texture atlas format
    this.load.unityAtlas('chars', 'assets/chars.png', 'assets/chars.txt');

    // Aseprite atlas
    this.load.aseprite('knight', 'assets/knight.png', 'assets/knight.json');
}

create() {
    this.add.sprite(400, 300, 'sprites', 'walk_01');
}

Loading Bitmap Fonts

preload() {
    // Requires both a texture and XML/JSON font data file
    this.load.bitmapFont('pixels', 'assets/font.png', 'assets/font.xml');
}

create() {
    this.add.bitmapText(100, 100, 'pixels', 'Hello World', 32);
}

Loading Video

preload() {
    // Load a video file. Third arg: noAudio flag (default false)
    this.load.video('intro', 'assets/intro.mp4');

    // Load without audio track
    this.load.video('bg_loop', 'assets/loop.mp4', true);
}

Loading Web Fonts

preload() {
    // Load a font file (ttf, otf, woff, woff2)
    this.load.font('myFont', 'assets/myfont.ttf', 'truetype');

    // With optional font face descriptors
    this.load.font('boldFont', 'assets/bold.woff2', 'woff2', {
        weight: 'bold',
        style: 'normal'
    });
}

Loading a Pack File

A pack file is a JSON file that describes multiple assets to load at once. Useful for organizing asset manifests.

preload() {
    this.load.pack('pack1', 'assets/pack.json');
}

Pack file format:

{
    "section1": {
        "baseURL": "assets/",
        "files": [
            { "type": "image", "key": "bg", "url": "bg.png" },
            { "type": "atlas", "key": "chars", "textureURL": "chars.png", "atlasURL": "chars.json" }
        ]
    }
}

Loading with a Progress Bar

preload() {
    const progressBar = this.add.graphics();
    const progressBox = this.add.graphics();
    progressBox.fillStyle(0x222222, 0.8);
    progressBox.fillRect(240, 270, 320, 50);

    this.load.on('progress', (value) => {
        progressBar.clear();
        progressBar.fillStyle(0xffffff, 1);
        progressBar.fillRect(250, 280, 300 * value, 30);
    });

    this.load.on('complete', () => {
        progressBar.destroy();
        progressBox.destroy();
    });

    // Queue your assets
    this.load.image('sky', 'assets/sky.png');
    // ... more assets
}

All File Types Reference

All this.load methods accept positional arguments or a single config object. They also accept an array of config objects to batch-load multiple files of the same type. See references/REFERENCE.md for the complete parameter table.

Textures: image, spritesheet, atlas, atlasXML, multiatlas, unityAtlas, aseprite, svg, htmlTexture, texture (compressed) Audio/Video: audio, audioSprite, video Data: json, xml, text, binary, html, css, glsl Fonts: bitmapFont, font Tilemaps: tilemapTiledJSON, tilemapCSV, tilemapImpact Other: animation, pack, script, scripts, plugin, scenePlugin, sceneFile

Events

All events are emitted on the Loader instance (this.load).

Event String	Callback Signature	Description
'addfile'	(key, type, loader, file)	A file was added to the load queue
'start'	(loader)	Loader has started. Progress is zero
'load'	(file)	A single file finished loading (before processing/caching)
'fileprogress'	(file, percentComplete)	Per-file download progress (0-1). Only fires if browser provides lengthComputable
'progress'	(value)	Overall load progress updated (0-1)
'postprocess'	(loader)	All files loaded and processed, before internal cleanup
'filecomplete'	(key, type, data)	Any file finished loading and processing
'filecomplete-{type}-{key}'	(key, type, data)	Specific file finished (e.g., 'filecomplete-image-hero')
'loaderror'	(file)	A file failed to load
'complete'	(loader, totalComplete, totalFailed)	All files in the queue are done

Event Lifecycle Order

1. 'start' - Loader begins
2. 'fileprogress' - Per-file progress (repeats per file, if available)
3. 'load' - Each file finishes downloading
4. 'filecomplete-{type}-{key}' - Specific file processed and cached
5. 'filecomplete' - Generic per-file completion
6. 'progress' - Overall progress updated
7. 'postprocess' - All files done, before cleanup
8. 'complete' - Everything finished

Gotchas and Common Mistakes

Keys must be unique within their type. Loading a second image with the same key as an existing one will log a warning and skip it. Remove the old texture from the Texture Manager first if you need to replace it.

Sprite sheet is not the same as an atlas. Use spritesheet() for fixed-size grids of frames (referenced by index). Use atlas() for packed texture atlases with named frames.

Forgetting this.load.start() outside preload. If you call load methods in create() or later, the Loader does not auto-start. You must call this.load.start() manually.

Path must end with /. If you call this.load.setPath() it will append the slash automatically. If you set this.load.path directly, you must include the trailing slash yourself.

Audio format fallbacks. Always provide multiple audio formats (OGG + MP3 at minimum) for cross-browser support. The Loader picks the first format the browser supports.

Pack files can override baseURL/path/prefix. Each section in a pack file can set its own baseURL, path, and prefix values. These apply only to files within that section and are restored after the section is processed.

File keys include the prefix. If you set this.load.setPrefix('MENU.') and load an image with key 'bg', the actual cache key becomes 'MENU.bg'. You must use that full key when referencing the asset.

The maxRetries property (default: 2) controls how many times the Loader retries a failed file before giving up. This is set per-file at creation time based on this.load.maxRetries. Adjusting it after files are added has no effect on those files.

Image load type. By default images load via XHR (as blobs). Set imageLoadType: 'HTMLImageElement' in the loader config to use <img> tag loading instead, which can help with CORS issues in some environments.

Local file schemes. The Loader recognizes file:// and capacitor:// as local schemes by default (via localSchemes). Files loaded from local schemes skip CORS headers.

Cross-origin. Set crossOrigin: 'anonymous' in the loader config (or via this.load.setCORS('anonymous')) when loading assets from a different domain, especially if those textures will be used with WebGL.

Keys are case-sensitive and scoped per type. 'Player' and 'player' are different keys. An image key 'player' and an audio key 'player' can coexist without conflict.

Duplicate keys are silently ignored. A second this.load.image('bg', ...) call does nothing if 'bg' already exists in the texture cache. Remove the old asset first to replace it.

Scene update() does NOT fire during preload. While assets are loading, update() is paused. However, preupdate, postupdate, and render still fire.

Progress can decrease. If new files are added mid-load (e.g., via filecomplete chaining), the progress value may drop because the total file count increased.

Scene Payload (Load Before Preload)

Load files before preload() runs by defining a pack in the Scene constructor. Useful for loading progress bar assets.

class BootScene extends Phaser.Scene {
    constructor() {
        super({
            key: 'BootScene',
            pack: {
                files: [
                    { type: 'image', key: 'bar', url: 'loaderBar.png' }
                ]
            }
        });
    }
    // 'bar' is already available in preload()
}

Adding Files Mid-Load

Use the per-file completion event to chain dependent loads during an active loading session.

preload() {
    this.load.json('level1', 'level1.json');
    this.load.on('filecomplete-json-level1', (key, type, data) => {
        this.load.image(data.images);
        this.load.spritesheet(data.spritesheets);
    });
}

Inline Pack Manifests

Pack data can be provided inline instead of from a URL.

preload() {
    this.load.pack('manifest', {
        section1: {
            prefix: '',
            path: 'assets/',
            defaultType: 'image',
            files: [
                { type: 'image', key: 'bg', url: 'bg.png' },
                { type: 'spritesheet', key: 'player', url: 'player.png', frameConfig: { frameWidth: 32, frameHeight: 32 } }
            ]
        }
    });
}

Cache System

Loaded assets go into global caches shared across all Scenes. Textures are stored in the Texture Manager (this.textures); other asset types go into typed sub-caches under this.cache.

// Access cached data
const json = this.cache.json.get('levelData');
const text = this.cache.text.get('dialogue');

// Check existence
this.cache.json.exists('levelData'); // or .has('levelData')
this.textures.exists('hero');

// Remove assets to free memory
this.textures.remove('hero');
this.cache.audio.remove('bgm');

// Listen for cross-scene texture additions
this.textures.on('addtexture-mapKey', (texture) => {
    // Another scene loaded 'mapKey' — now available here
});

Cache sub-types: this.cache.text, this.cache.json, this.cache.audio, this.cache.binary, this.cache.shader, this.cache.xml. See references/REFERENCE.md for the full Cache API.

Source File Map

See references/REFERENCE.md for the complete source file map and Cache API reference.

Key files: src/loader/LoaderPlugin.js (main Loader), src/loader/File.js (base File class), src/loader/filetypes/ (all file type loaders), src/loader/events/ (event constants).