SuperAPI AI 工具集

loading-assets

编程与开发

查看项目

更新于 10-15 15:33

技能介绍

用途

本技能介绍 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 等详细内容请参考原始文档。