Loading resources

--- 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 ``js 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(). `js 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: `js 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. `js 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: `js 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. `js 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 `js 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 ``js preload() { // Single file this.load.audio('bgm', 'assets/music.mp3'); // Multiple formats for cross-browser support this.load.audio('bgm', ['