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:

json

{
    "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

```
'start'
```
- Loader begins
```
'fileprogress'
```
- Per-file progress (repeats per file, if available)
```
'load'
```
- Each file finishes downloading
```
'filecomplete-{type}-{key}'
```
- Specific file processed and cached
```
'filecomplete'
```
- Generic per-file completion
```
'progress'
```
- Overall progress updated
```
'postprocess'
```
- All files done, before cleanup
```
'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).

loading-assets

NPX Install

Tags

SKILL.md Content