游戏引擎 / 系统课时
从纹理图集提取精灵帧
从纹理图集提取精灵帧
本篇用一张 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 是所截取区域的尺寸。
{
"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 安装提示,按终端指引确认即可。
npm create vite@latest atlas-demo -- --template vanilla
cd atlas-demo
npm install
npm install phaser@4.2.1
npm run dev预期结果(Vite 版本、耗时和端口随环境变化):
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() 引用相同的纹理键,但通过第四个参数选择不同帧。
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):
帧名检查: 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 再刷新,可以验证帧名检查比猜测资源是否成功加载更可靠。