用途
本技能介绍 Phaser 4 中加载(Loading)资产的方法。Phaser Loader(this.load)负责获取所有外部内容,包括图片、音频、JSON、瓦片地图、图集、字体、脚本等。资产在 preload() 中排队,并行加载,并存入全局缓存,供每个 Scene 访问。
关键源码路径:src/loader/LoaderPlugin.js、src/loader/File.js、src/loader/filetypes/、src/loader/events/。
相关技能:../game-setup-and-config/SKILL.md、../scenes/SKILL.md、../sprites-and-images/SKILL.md。
主要能力
- 加载各类资产:图片、精灵表、图集(JSON、XML、多图集、Unity、Aseprite)、音频、音频精灵、视频、JSON、XML、文本、二进制、HTML、CSS、GLSL、位图字体、Web 字体、瓦片地图(Tiled JSON、CSV、Impact)、动画、脚本、插件等。
- 通过 preload() 模式自动加载,或手动调用 this.load.start()。
- URL 解析:baseURL + path + filename,可通过配置或运行时设置。
- 全局缓存:纹理存入 Texture Manager,其他数据存入 game.cache 的子缓存。
- 加载事件:progress、complete、loaderror、filecomplete 等,用于进度条与加载界面。
- 支持包文件(pack)批量描述加载资产,支持内联清单。
- 支持在加载中追加文件(通过 filecomplete 事件链式加载)。
使用方式
基本模式:在 preload() 中排队文件,create() 中即可使用。
class GameScene extends Phaser.Scene {
preload() {
this.load.image('logo', 'assets/logo.png');
}
create() {
this.add.image(400, 300, 'logo');
}
}
在 preload() 之外调用加载方法时,需手动启动:
create() {
this.load.image('extra', 'assets/extra.png');
this.load.once('complete', () => {
this.add.image(400, 300, 'extra');
});
this.load.start();
}
URL 解析可用 setBaseURL、setPath、setPrefix 设置,也可在 game config 的 loader 字段中配置(baseURL、path、prefix、maxParallelDownloads、crossOrigin、responseType、async、timeout、maxRetries、imageLoadType)。
适用场景
适用于 Phaser 4 游戏开发中加载外部资源、构建加载进度界面、从 CDN 或跨域加载资产、使用包文件组织资产清单等场景。
限制与注意事项
- 键(key)在其类型内必须唯一,重复键会被忽略并警告。
- 精灵表与图集不同:spritesheet() 用于固定尺寸网格帧,atlas() 用于带命名帧的打包图集。
- 在 preload 之外调用加载方法必须手动 this.load.start()。
- 直接设置 this.load.path 时需自行包含结尾斜杠。
- 音频建议提供多种格式(至少 OGG + MP3)以兼容浏览器。
- 键包含 prefix,引用资产时须使用完整键。
- maxRetries 默认 2,在文件创建时设定,之后调整无效。
- 图片默认经 XHR 加载,可设 imageLoadType: 'HTMLImageElement' 改用 img 标签。
- 跨域加载需设置 crossOrigin: 'anonymous'。
- 键区分大小写,且按类型作用域。
- preload 期间 update() 不会触发,但 preupdate、postupdate、render 仍会触发。
- 进度值可能因加载中追加文件而下降。
- 完整参数表与 Cache API 见 references/REFERENCE.md。
各分类资产加载方式、事件表、缓存系统、Source File Map 等详细内容请参考原始文档。