游戏引擎 / 系统课时
在 preload 中加载图片和精灵表
在 preload 中加载图片和精灵表
本篇用一张背景图片和一张规则精灵表完成 Phaser 4 场景的资源加载:在 preload() 中声明资源键与帧尺寸,在 create() 中用键创建背景和不同帧的精灵,并检查资源是否真正进入纹理管理器。
学习目标
- 区分
load.image()与load.spritesheet()的用途。 - 使用
frameWidth、frameHeight和纹理键创建游戏对象。 - 根据浏览器网络请求和纹理检查定位加载失败、帧错位。
准备可访问的素材
示例采用 Phaser 4.2.1 + Vite + JavaScript。在安装了受当前 Vite 支持的 Node.js 与 npm 后,使用 macOS、Linux 终端或 Git Bash 执行以下命令。素材来自 Phaser 官方示例使用的公共资源地址;发布自己的游戏时,应换成有使用权的素材。
npm create vite@latest phaser-asset-demo -- --template vanilla
cd phaser-asset-demo
npm install
npm install phaser@4.2.1
mkdir -p public/assets
# 下载一张背景图和一张 32×32 网格精灵表
curl -fL https://cdn.phaserfiles.com/v385/assets/skies/pixelsky.png -o public/assets/pixelsky.png
curl -fL https://cdn.phaserfiles.com/v385/assets/sprites/heartstar32.png -o public/assets/heartstar32.png
test -s public/assets/pixelsky.png && test -s public/assets/heartstar32.png && echo "资源准备完成"预期输出(指最后的文件检查命令;npm 安装日志与下载进度可能不同):
资源准备完成Vite 将 public 中的文件作为静态资源提供服务:public/assets/pixelsky.png 对应运行时的 assets/pixelsky.png。不要在加载 URL 中写上 public/,也不要把图片放到 src 后仍沿用这个路径。
在场景中声明并使用纹理
将 Vite 生成的 src/main.js 整个替换为下面的代码。preload() 只负责把请求加入队列,Phaser 会自动启动加载器;等队列处理完成后才调用 create()。精灵表的 frameWidth 和 frameHeight 使用原图像素,与屏幕显示缩放无关。
import Phaser from 'phaser';
const assetRoot = `${import.meta.env.BASE_URL}assets/`;
class AssetsScene extends Phaser.Scene {
constructor() {
super('AssetsScene');
}
preload() {
// 背景整张作为一帧;精灵表按固定 32×32 像素切分
this.load.image('background', `${assetRoot}pixelsky.png`);
this.load.spritesheet('symbols', `${assetRoot}heartstar32.png`, {
frameWidth: 32,
frameHeight: 32
});
}
create() {
// 创建对象时只使用资源键,不重复发起下载
this.add.image(400, 300, 'background').setDisplaySize(800, 600);
this.add.sprite(330, 300, 'symbols', 0).setScale(3);
this.add.sprite(470, 300, 'symbols', 1).setScale(3);
console.log('纹理检查', this.textures.exists('background'),
this.textures.exists('symbols'));
}
}
new Phaser.Game({
type: Phaser.AUTO,
width: 800,
height: 600,
scene: AssetsScene
});预期结果:在项目根目录运行 npm run dev,打开终端显示的 Local 地址,页面出现 800 × 600 的天空背景,以及同一精灵表的两个不同帧。打开浏览器开发者工具的 Console,应看到:
纹理检查 true truethis.add.image() 适合不需要动画组件的背景;this.add.sprite() 可选择数字帧,并且之后能够接入动画。0、1 指精灵表切出的帧序号,不是两张独立图片。setScale(3) 仅把 32 像素的帧显示为约 96 像素宽,不改变切帧规则。
看懂加载队列与纹理键
preload() 中的两个调用分别进入 Loader 队列:背景图片形成一张完整纹理,精灵表根据固定宽高拆出从 0 开始的数字帧。完成后两者都由 Texture Manager 管理,create() 用资源键读取;图片纹理不应通过 this.cache.json 查找。

load.image() 和 load.spritesheet() 的第一个参数都是自定义资源键,必须与 create() 中的键逐字一致。同一精灵表可以创建多个对象,纹理通常会复用,而不是为每个精灵重新下载文件。更多事件与参数可对照 Phaser Loader 文档。
排查空白画面与错误切帧
- 背景或精灵缺失:打开开发者工具的 Network,检查两个 PNG 请求是否返回
200。若为404,确认图片在public/assets/、拼写一致,以及代码没有把public写进 URL。 - 纹理检查显示
false:检查 Console 是否有加载错误,并核对background、symbols在加载和创建位置完全同名;不要在preload()中刚入队就立即创建对象。 - 两个符号显示错位或挤入相邻图案:检查源文件的单格尺寸是否真是
32 × 32,不要将缩放后的显示尺寸96 × 96填入帧配置。有边距或间隔的图集需正确设置margin、spacing;不规则排布的素材应改用 Texture Atlas。 - 发布到子路径后资源变成 404:本示例使用 Vite 的
import.meta.env.BASE_URL拼接资源路径;若在vite.config.js配置了base,它会随构建前缀变化。部署时仍需确保产物中的assets目录一同发布。
完成检查后,页面应能稳定显示一张背景与来自同一精灵表的两个不同帧。以后增加角色帧,只需保证源图片的网格尺寸、帧号和纹理键一致。