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 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() . 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: 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. These can also be set in the game config: 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. Common Patterns Loading Images and Sprite Sheets Loading Audio Loading JSON and Tilemaps Loading Atlases Loading Bitmap Fonts Loading Video Loading Web Fonts Loading a Pack File A pack file is a JSON file that describes multiple assets to load at once. Useful for organizing asset manifests. Pack file format: Loading with a Progress Bar 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. Adding Files Mid Load Use the per file completion event to chain dependent loads during an active loading session. Inline Pack Manifests Pack data can be provided inline instead of from a URL. 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 . 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