本技能介绍在 Phaser 4 中创建和操作 Sprite(精灵)与 Image(图像)游戏对象,涉及工厂方法、纹理/帧选择、组件混入系统以及常见的视觉效果操作(位置、缩放、旋转、着色、翻转、透明度、原点、深度)。
用途
用于在 Phaser 4 场景中创建静态图像或支持动画的精灵,并对它们进行定位、缩放、旋转、着色、翻转、透明度调整、原点设置和渲染深度排序等操作。
核心概念
Sprite 与 Image 都继承自 GameObject,并共享同一套组件混入。唯一区别是 Sprite 包含 AnimationState 实例(sprite.anims)以及动画便捷方法(play、stop、chain 等)。Image 不支持动画,不会每帧调用 preUpdate,也不加入 Scene 的 updateList,因此 API 更小、开销更低。
选型原则: 不需要逐帧动画的对象使用 Image;仅在需要 Animation 组件时使用 Sprite。
组件混入系统
Phaser 通过将组件对象混入原型来构建游戏对象类。Sprite 与 Image 共享相同的 Mixins 数组,包含 Alpha、BlendMode、Depth、Flip、GetBounds、Lighting、Mask、Origin、RenderNodes、ScrollFactor、Size、TextureCrop、Tint、Transform、Visible 以及各自的渲染组件(SpriteRender / ImageRender)。基础 GameObject 类本身混入 Filters 和 RenderSteps。例如 setAlpha() 来自 Components.Alpha,而非 Sprite 类本身,组件的源文件是该方法的权威参考。
纹理与帧
两者都使用 TextureCrop 组件,提供 texture、frame、setTexture(key, frame)、setFrame(frame, updateSize, updateOrigin)、setCrop(x, y, width, height) 和 isCropped。texture 参数接受字符串键或 Texture 实例;frame 接受字符串名称或数字索引,省略时使用基础帧。
sprite.setTexture('enemies', 'goblin-walk-1');
sprite.setFrame('goblin-walk-2');
sprite.setFrame('small-frame', false, false);
sprite.setCrop(10, 10, 50, 50);
sprite.setCrop();
常见操作
创建与定位: Transform 组件提供 x、y、z、w 属性,以及 setPosition(x, y, z, w)、setRandomPosition、copyPosition。Size 组件提供 width、height、displayWidth、displayHeight 及 setSize、setDisplaySize、setSizeToFrame。
缩放与旋转: scale、scaleX、scaleY 及 setScale(x, y);rotation(弧度)、angle(角度)及 setRotation、setAngle。
着色与透明度: Tint 组件(仅 WebGL)提供 tint、tintTopLeft 等四角属性、tintMode、isTinted,以及 setTint、setTintMode、clearTint。Phaser 4 已移除 setTintFill(),改用 setTint(color).setTintMode(Phaser.TintModes.FILL)。Alpha 组件提供 alpha 及四角 alpha 属性和 setAlpha、clearAlpha。alpha 设为 0 会清除渲染标记,对象不再绘制。
翻转: flipX、flipY 属性,以及 setFlipX、setFlipY、setFlip、toggleFlipX、toggleFlipY、resetFlip。翻转仅影响渲染,不影响物理体或命中区域,且不改变 scale 值。
原点与深度: originX、originY(归一化 0-1,默认 0.5)及 displayOriginX/Y,方法有 setOrigin、setDisplayOrigin、setOriginFromFrame、updateDisplayOrigin。depth 默认 0,越大越靠前,方法有 setDepth、setToTop、setToBack、setAbove、setBelow;后者改变显示列表位置而不修改 depth 值。
销毁: destroy() 会从显示列表和更新列表移除并清理;ignoreDestroy 可阻止销毁;isDestroyed 表示是否已销毁。Sprite 的 destroy() 还会调用 anims.destroy()。
附加组件
- Visible: visible 属性、setVisible;不可见对象跳过渲染但仍更新。
- ScrollFactor: scrollFactorX/Y(默认 1),setScrollFactor,0 表示固定于相机。
- BlendMode: blendMode(默认 NORMAL),setBlendMode 支持 ADD、MULTIPLY、SCREEN、ERASE 等。注意切换混合模式会打断 WebGL 批处理,建议按混合模式分组对象以减少绘制调用。
工厂方法
this.add.sprite(x, y, texture, frame);
参数:x(number,必填)、y(number,必填)、texture(string 或 Texture,必填)、frame(string 或 number,可选)。返回 Phaser.GameObjects.Sprite。内部执行 this.displayList.add(new Sprite(this.scene, x, y, texture, frame)),构造函数依次调用 setTexture、setPosition、setSizeToFrame、setOriginFromFrame、initRenderNodes。
this.add.image(x, y, texture, frame);
参数与返回值结构相同,返回 Phaser.GameObjects.Image,内部执行 this.displayList.add(new Image(this.scene, x, y, texture, frame)),初始化序列与 Sprite 一致。
专用游戏对象
NineSlice: 角固定、边与中心可拉伸的 UI 面板,适合按钮、面板和对话框。
const panel = this.add.nineslice(400, 300, 'panel', null, 300, 200, 20, 20, 20, 20);
panel.setSize(500, 400);
TileSprite: 用重复纹理填充区域,v4 支持图集帧和新属性 tileRotation。
const bg = this.add.tileSprite(400, 300, 800, 600, 'grass');
bg.tilePositionX += 0.5;
bg.tilePositionY += 0.25;
bg.tileRotation = 0.1;
Blitter: 面向大量静态或半静态精灵的高性能批渲染,其子对象(Bobs)没有旋转、缩放或物理,但渲染显著更快。
const blitter = this.add.blitter(0, 0, 'particles');
for (let i = 0; i < 1000; i++) {
const bob = blitter.create(
Phaser.Math.Between(0, 800),
Phaser.Math.Between(0, 600),
'particle_01'
);
bob.setAlpha(Math.random());
}
Video: 作为游戏对象的视频播放,支持位置、缩放和滤镜。
this.load.video('intro', 'intro.mp4');
const video = this.add.video(400, 300, 'intro');
video.play();
关键源码路径
src/gameobjects/sprite/、src/gameobjects/image/、src/gameobjects/GameObject.js、src/gameobjects/components/。相关技能:loading-assets、animations、physics-arcade、game-object-components。
限制
Tint 组件和逐角 Alpha 仅适用于 WebGL。Blitter 子对象不支持旋转、缩放与物理。翻转不影响物理体和命中区域。更多详细配置选项、API 参考表与源码文件映射,请见参考指南(本资料未提供具体内容)。