游戏引擎 / 系统课时

从纹理图集提取精灵帧

从纹理图集提取精灵帧

本篇用一张 128×64 的 PNG 图集和一份 JSON 帧描述,在 Phaser 4.2.1 中显示两个独立精灵。完成后你会用纹理键和帧名定位图像区域,检查加载结果,并判断什么时候应该用图集替代逐张图片。

学习目标

  • 说清图集 PNG、帧描述 JSON、纹理键与帧名之间的关系。
  • 用 load.atlas() 加载资源,并通过帧名创建 Sprite。
  • 用帧名检查和网络请求记录定位资源错误,比较两种资源组织方式。

图集如何定位每个精灵

图集是一张共享的大纹理,JSON 记录每个小图在大图里的矩形坐标。以宽 128、高 64 的透明 PNG 为例:左半画一个红色角色方块,右半画一个黄色道具圆形,每个区域均为 64×64 像素。图集里不需要为每个对象单独创建 PNG 文件。

把图片保存到 public/assets/items.png,并在同目录新建 items.json。以下是 Phaser 能识别的 TexturePacker JSON Hash 帧描述;frame 的 x/y 从图集左上角起算,w/h 是所截取区域的尺寸。

json
{
  "frames": {
    "hero-idle": {
      "frame": { "x": 0, "y": 0, "w": 64, "h": 64 },
      "rotated": false,
      "trimmed": false,
      "spriteSourceSize": { "x": 0, "y": 0, "w": 64, "h": 64 },
      "sourceSize": { "w": 64, "h": 64 }
    },
    "coin": {
      "frame": { "x": 64, "y": 0, "w": 64, "h": 64 },
      "rotated": false,
      "trimmed": false,
      "spriteSourceSize": { "x": 0, "y": 0, "w": 64, "h": 64 },
      "sourceSize": { "w": 64, "h": 64 }
    }
  },
  "meta": {
    "image": "items.png",
    "size": { "w": 128, "h": 64 },
    "scale": "1"
  }
}

hero-idle 和 coin 是程序要传入的帧名;items 则是稍后注册的纹理键,它不要求与文件名相同。这里两帧未裁边、未旋转,所以原始尺寸与图集截取尺寸一致;美术工具启用 Trim 或 Rotate 后,应保留其导出的裁切与旋转字段,不要手改坐标。

纹理图集、描述文件与精灵帧的映射关系

建立可运行的测试项目

使用 Node.js 20.19+ 或 22.12+,从空目录创建 Vite 原生 JavaScript 项目并安装 Phaser 4.2.1。命令最后启动本地开发服务器;首次执行可能出现 Vite 安装提示,按终端指引确认即可。

bash
npm create vite@latest atlas-demo -- --template vanilla
cd atlas-demo
npm install
npm install phaser@4.2.1
npm run dev

预期结果(Vite 版本、耗时和端口随环境变化):

text
Local: http://localhost:<PORT>/

Vite 将 public 目录中的资源映射到站点根路径,因此 public/assets/items.png 在代码里写成 /assets/items.png,JSON 同理。图片尺寸和上述两条矩形区域必须匹配;若只是改了 JSON 而 PNG 没按坐标绘制,程序能加载但会截到错误画面。

加载图集并按帧名创建精灵

将 Vite 项目的 src/main.js 全部替换为以下代码。preload() 将 PNG 与 JSON 一起排入 Loader,资源加载结束后才会执行 create();两次 add.sprite() 引用相同的纹理键,但通过第四个参数选择不同帧。

js
import Phaser from 'phaser';

class AtlasScene extends Phaser.Scene {
  constructor() {
    super('AtlasScene');
  }

  preload() {
    // 一个 key 绑定图集图片和帧坐标文件
    this.load.atlas('items', '/assets/items.png', '/assets/items.json');
  }

  create() {
    // 创建两个对象,不会为每个帧重新下载一张图片
    this.add.sprite(96, 120, 'items', 'hero-idle');
    this.add.sprite(224, 120, 'items', 'coin');

    const names = this.textures.get('items').getFrameNames();
    console.log('帧名检查:', ['hero-idle', 'coin'].every(name => names.includes(name)));
  }
}

new Phaser.Game({
  type: Phaser.AUTO,
  parent: 'app',
  width: 320,
  height: 240,
  backgroundColor: '#f1f5f9',
  scene: AtlasScene
});

预期输出(浏览器开发者工具 Console):

text
帧名检查: true

页面应出现 320×240 画布:左侧显示红色方块,右侧显示黄色圆形。刷新页面后仍能显示,且在 DevTools 的 Network 面板只看到一次 items.png 与一次 items.json 的加载请求;如果浏览器缓存命中,状态码或传输量可能不同。

选图集还是逐张图片

维度 逐张 load.image() load.atlas() 图集
资源文件 两个 PNG 一个 PNG 加一个 JSON
游戏对象引用 ('hero-idle')、('coin') 各用一个纹理键 都用 'items',再选 'hero-idle'、'coin' 帧
更新方式 替换单张图片较直接 重新打包时需要同步替换 PNG 与 JSON
适用场景 少量独立大图、背景 大量小图、角色帧、图标

图集通常有助于减少纹理切换、提高批处理机会,但不能保证所有对象只产生一次绘制调用;不同渲染状态和对象顺序仍可能拆分批次。图集特别大时还要考虑设备纹理尺寸限制和未使用区域占用的显存。

发现空白或错图时,先在 Network 检查两个文件是否返回成功,再查看 this.textures.get('items').getFrameNames() 是否包含完全一致的帧名(含大小写与扩展名),最后核对 JSON 的矩形是否落在 PNG 尺寸内。把 coin 改成不存在的 coins 再刷新,可以验证帧名检查比猜测资源是否成功加载更可靠。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

从纹理图集提取精灵帧

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通