game-object-components

Name: game-object-components
Author: phaserjs

github.com/phaserjs开发40.6k816 次安装10 周前更新

代码仓库

关于 game-object-components

Phaser 4 游戏对象组件参考指南，面向需要调整游戏对象渲染与变换行为的开发者。介绍通过混入共享功能，以及各组件的主要属性和方法。

主要功能

01配置透明度与混合模式
02调整深度、翻转和原点
03获取边界并控制尺寸
04设置纹理、裁剪与色调
05控制滚动因子和可见性

适用场景

01调整游戏对象的绘制顺序
02让 HUD 固定于摄像机或实现视差
03裁剪纹理并设置对象色调

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/phaserjs/phaser --skill game-object-components

安装后在 Claude Code 中输入/game-object-components确认已加载。

附带文件references/REFERENCE.md

详细介绍

Phaser 4 -- 游戏对象组件参考

为所有游戏对象提供共享行为的组件混入：Alpha、BlendMode、Depth、Flip、GetBounds、Lighting、Mask、Origin、ScrollFactor、Size、Texture、TextureCrop、Tint、Transform、Visible、PathFollower、RenderNodes、RenderSteps、Filters、FilterList。

快速开始

// Every Game Object gets its component methods via mixins.
// Just call them directly on any game object:
const sprite = this.add.sprite(400, 300, 'hero');

sprite.setAlpha(0.5);                          // Alpha
sprite.setBlendMode(Phaser.BlendModes.ADD);    // BlendMode
sprite.setDepth(10);                           // Depth
sprite.setFlip(true, false);                   // Flip
sprite.setOrigin(0, 0);                        // Origin
sprite.setScrollFactor(0);                     // ScrollFactor (HUD)
sprite.setDisplaySize(64, 64);                 // Size
sprite.setTexture('hero', 'walk-1');           // Texture
sprite.setTint(0xff0000);                      // Tint
sprite.setPosition(100, 200);                  // Transform
sprite.setVisible(false);                      // Visible
sprite.setScale(2);                            // Transform
sprite.setAngle(45);                           // Transform

// Per-corner alpha (WebGL only)
sprite.setAlpha(1, 0.5, 0.5, 1);

// Crop a texture region
sprite.setCrop(0, 0, 32, 32);

// Enable WebGL filters (post-processing)
sprite.enableFilters();
sprite.filters.internal.addBlur(1, 2, 2, 1);

// Lighting (WebGL only, v4 feature)
sprite.setLighting(true);

核心概念

混入系统

Phaser 使用 Phaser.Class 配合 Mixins 数组，从可复用的组件对象组合出游戏对象。每个组件都是一个普通的 JS 对象，其属性和方法会被复制到类原型上。这并非原型继承——而是在类定义时进行属性复制。

// How Phaser defines Sprite internally:
var Sprite = new Class({
    Extends: GameObject,
    Mixins: [
        Components.Alpha,
        Components.BlendMode,
        Components.Depth,
        Components.Flip,
        Components.GetBounds,
        Components.Lighting,
        Components.Mask,
        Components.Origin,
        Components.RenderNodes,
        Components.ScrollFactor,
        Components.Size,
        Components.TextureCrop,
        Components.Tint,
        Components.Transform,
        Components.Visible,
        SpriteRender
    ],
    initialize: function Sprite (scene, x, y, texture, frame) { /* ... */ }
});

关键规则

组件在类创建时混入，而不是按实例混入。
大多数 setter 方法返回 this 以支持链式调用：sprite.setAlpha(0.5).setDepth(10).setPosition(100, 200)。
许多属性在内部使用 getter/setter（例如 alpha、depth、visible、scale、rotation）。将 alpha = 0 或 scale = 0 会清除渲染标志，从而跳过渲染。
renderFlags 是一个位掩码：位 0 = 可见，位 1 = alpha，位 2 = 缩放，位 3 = 纹理。所有位都必须置位，对象才会渲染。
Alpha 与 AlphaSingle：Alpha 支持逐角 alpha（WebGL），AlphaSingle 仅支持单一全局 alpha。Container 使用 AlphaSingle。
Texture 与 TextureCrop：TextureCrop 在 Texture 基础上扩展了 setCrop() 支持。Sprite 和 Image 使用 TextureCrop；某些对象使用普通的 Texture。
Filters 和 RenderSteps 是 v4 独有的、仅限 WebGL 的后处理系统。

完整组件参考

Alpha

提供逐角透明度。被 Sprite、Image、Text 以及大多数可渲染对象使用。

成员	类型	描述
`alpha`	number (get/set)	全局 alpha，0-1。设置此项同时会设置全部四个角。设为 0 会禁用渲染。默认值：`1`
`alphaTopLeft`	number (get/set)	左上角 alpha。仅限 WebGL。
`alphaTopRight`	number (get/set)	右上角 alpha。仅限 WebGL。
`alphaBottomLeft`	number (get/set)	左下角 alpha。仅限 WebGL。
`alphaBottomRight`	number (get/set)	右下角 alpha。仅限 WebGL。
`setAlpha(topLeft?, topRight?, bottomLeft?, bottomRight?)`	method	设置 alpha。一个参数 = 统一设置。四个参数 = 逐角设置（WebGL）。返回 `this`。
`clearAlpha()`	method	将 alpha 重置为 1。返回 `this`。

AlphaSingle

简化的 alpha，不支持逐角设置。被 Container 使用。

成员	类型	描述
`alpha`	number (get/set)	alpha，0-1。默认值：`1`
`setAlpha(value?)`	method	设置 alpha。返回 `this`。
`clearAlpha()`	method	将 alpha 重置为 1。返回 `this`。

BlendMode

控制在渲染过程中像素如何合成。

成员	类型	描述
`blendMode`	number/string (get/set)	当前混合模式。接受 `Phaser.BlendModes` 常量、字符串或整数。
`setBlendMode(value)`	method	设置混合模式。返回 `this`。

WebGL 混合模式：NORMAL、ADD、MULTIPLY、SCREEN、ERASE。Canvas 还支持额外的、取决于浏览器的模式。

Depth

控制渲染顺序（z-index）。depth 越高渲染越靠上。

成员	类型	描述
`depth`	number (get/set)	depth 值。设置它会排队一次深度排序。默认值：`0`
`setDepth(value)`	method	设置 depth。返回 `this`。
`setToTop()`	method	移到显示列表顶部（不改变 depth）。返回 `this`。
`setToBack()`	method	移到显示列表底部。返回 `this`。
`setAbove(gameObject)`	method	在显示列表中移到另一个游戏对象上方。返回 `this`。
`setBelow(gameObject)`	method	在显示列表中移到另一个游戏对象下方。返回 `this`。

Flip

视觉镜像，不影响物理实体。

成员	类型	描述
`flipX`	boolean	水平翻转状态。默认：`false`
`flipY`	boolean	垂直翻转状态。默认：`false`
`setFlipX(value)`	method	设置水平翻转。返回 `this`。
`setFlipY(value)`	method	设置垂直翻转。返回 `this`。
`setFlip(x, y)`	method	设置两个翻转状态。返回 `this`。
`toggleFlipX()`	method	切换水平翻转。返回 `this`。
`toggleFlipY()`	method	切换垂直翻转。返回 `this`。
`resetFlip()`	method	将两者重置为 false。返回 `this`。

GetBounds

无论原点如何，计算位置和边界矩形。

成员	类型	描述
`getCenter(output?, includeParent?)`	method	中心坐标。返回 `Vector2Like`。
`getTopLeft(output?, includeParent?)`	method	左上角坐标。返回 `Vector2Like`。
`getTopCenter(output?, includeParent?)`	method	顶部中心坐标。返回 `Vector2Like`。
`getTopRight(output?, includeParent?)`	method	右上角坐标。返回 `Vector2Like`。
`getLeftCenter(output?, includeParent?)`	method	左侧中心坐标。返回 `Vector2Like`。
`getRightCenter(output?, includeParent?)`	method	右侧中心坐标。返回 `Vector2Like`。
`getBottomLeft(output?, includeParent?)`	method	左下角坐标。返回 `Vector2Like`。
`getBottomCenter(output?, includeParent?)`	method	底部中心坐标。返回 `Vector2Like`。
`getBottomRight(output?, includeParent?)`	method	右下角坐标。返回 `Vector2Like`。
`getBounds(output?)`	method	完整边界矩形。返回 `Rectangle`。

设置 includeParent = true 以计入父级 Container 的变换。

Lighting（v4，仅限 WebGL）

使用 Phaser 4 光照系统启用基于光照的渲染。

成员	类型	描述
`lighting`	boolean	是否使用光照。默认：`false`
`selfShadow`	object	`{ enabled, penumbra, diffuseFlatThreshold }`。自阴影设置。
`setLighting(enable)`	method	启用/禁用光照。返回 `this`。
`setSelfShadow(enabled?, penumbra?, diffuseFlatThreshold?)`	method	配置自阴影。将 `enabled` 传递为 `null` 以使用游戏配置的默认值。返回 `this`。

Mask（v4 中仅限 Canvas）

用于 Canvas 渲染器的几何遮罩。在 WebGL 中，请改用 Filters.addMask()。

成员	类型	描述
`mask`	GeometryMask	当前遮罩，或 null。
`setMask(mask)`	method	应用一个 GeometryMask。仅限 Canvas。在 WebGL 中会记录警告。返回 `this`。
`clearMask(destroyMask?)`	method	移除遮罩。传递 `true` 以同时销毁它。返回 `this`。
`createGeometryMask(graphics?)`	method	从 Graphics/Shape 对象创建一个 GeometryMask。返回 `GeometryMask`。

Origin

控制位置、旋转和缩放的锚点。归一化为 0-1。

成员	类型	描述
`originX`	number	水平原点。默认：`0.5`（中心）
`originY`	number	垂直原点。默认：`0.5`（中心）
`displayOriginX`	number（get/set）	以像素为单位的原点。设置时会重新计算 `originX`。
`displayOriginY`	number（get/set）	以像素为单位的原点。设置时会重新计算 `originY`。
`setOrigin(x?, y?)`	method	设置原点（归一化）。`y` 默认为 `x`。默认：`0.5`。返回 `this`。
`setOriginFromFrame()`	method	从纹理 Frame 的轴心设置原点。返回 `this`。
`setDisplayOrigin(x?, y?)`	method	以像素为单位设置原点。返回 `this`。
`updateDisplayOrigin()`	method	重新计算显示原点缓存。返回 `this`。

ScrollFactor

控制相机滚动如何影响对象的渲染位置。

成员	类型	描述
`scrollFactorX`	number	水平滚动因子。默认：`1`
`scrollFactorY`	number	垂直滚动因子。默认：`1`
`setScrollFactor(x, y?)`	method	设置滚动因子。`y` 默认为 `x`。返回 `this`。

关键值：0 = 固定于相机（HUD 元素），1 = 随相机移动，0.5 = 视差半速。

Size

管理原生尺寸和显示尺寸。

成员	类型	描述
`width`	number	原生（未缩放）宽度。
`height`	number	原生（未缩放）高度。
`displayWidth`	number (get/set)	缩放后的宽度。设置时会调整 `scaleX`。
`displayHeight`	number (get/set)	缩放后的高度。设置时会调整 `scaleY`。
`setSize(width, height)`	method	设置原生尺寸。不影响渲染尺寸。返回 `this`。
`setDisplaySize(width, height)`	method	设置渲染尺寸（调整缩放）。返回 `this`。
`setSizeToFrame(frame?)`	method	根据纹理 Frame 设置尺寸。返回 `this`。

Texture

获取并设置用于渲染的纹理和帧。

成员	类型	描述
`texture`	Phaser.Textures.Texture	当前 Texture。
`frame`	Phaser.Textures.Frame	当前 Frame。
`setTexture(key, frame?, updateSize?, updateOrigin?)`	method	通过 key 设置纹理。返回 `this`。
`setFrame(frame, updateSize?, updateOrigin?)`	method	通过名称、索引或 Frame 实例设置帧。默认更新尺寸和原点。返回 `this`。

TextureCrop

扩展 Texture 以支持裁剪。由 Sprite 和 Image 使用。

成员	类型	描述
`texture`	Phaser.Textures.Texture	当前 Texture。
`frame`	Phaser.Textures.Frame	当前 Frame。
`isCropped`	boolean	是否启用裁剪。
`setTexture(key, frame?)`	method	通过 key 设置纹理。返回 `this`。
`setFrame(frame, updateSize?, updateOrigin?)`	method	设置帧。如果已裁剪，还会更新裁剪 UV。返回 `this`。
`setCrop(x?, y?, width?, height?)`	method	设置裁剪矩形。不传参数则清除。第一个参数可接受 `Rectangle`。返回 `this`。

Tint（仅 WebGL）

通过逐角顶点颜色对纹理应用颜色着色。

成员	类型	描述
`tint`	number (get/set)	统一着色颜色（读取 `tintTopLeft`）。默认：`0xffffff`
`tintTopLeft`	number	左上顶点着色。默认：`0xffffff`
`tintTopRight`	number	右上顶点着色。默认：`0xffffff`
`tintBottomLeft`	number	左下顶点着色。默认：`0xffffff`
`tintBottomRight`	number	右下顶点着色。默认：`0xffffff`
`tintMode`	number	着色混合模式。默认：`Phaser.TintModes.MULTIPLY`
`isTinted`	boolean (readonly)	如果设置了任何着色或模式，则为 True。
`setTint(topLeft?, topRight?, bottomLeft?, bottomRight?)`	method	设置着色颜色。一个参数 = 统一着色。返回 `this`。
`setTintMode(mode)`	method	设置着色模式（v4）。模式：`MULTIPLY`、`FILL`、`ADD`、`SCREEN`、`OVERLAY`、`HARD_LIGHT`。返回 `this`。
`clearTint()`	method	重置为白色 + MULTIPLY。返回 `this`。

v4 变更：移除了 setTintFill()。请改用 setTint(color).setTintMode(Phaser.TintModes.FILL)。

Transform

位置、缩放、旋转和坐标变换。

成员	类型	描述
`x`	number	X 位置。默认值：`0`
`y`	number	Y 位置。默认值：`0`
`z`	number	Z 位置（不是渲染顺序；请使用 `depth`）。默认值：`0`
`w`	number	W 位置。默认值：`0`
`scale`	number (get/set)	统一缩放。获取时返回 scaleX 和 scaleY 的平均值。
`scaleX`	number (get/set)	水平缩放。默认值：`1`
`scaleY`	number (get/set)	垂直缩放。默认值：`1`
`angle`	number (get/set)	以度数为单位的旋转（顺时针，0 = 向右）。
`rotation`	number (get/set)	以弧度为单位的旋转。
`setPosition(x?, y?, z?, w?)`	method	设置位置。`y` 默认为 `x`。返回 `this`。
`copyPosition(source)`	method	从类 Vector 对象复制 x/y/z/w。返回 `this`。
`setRandomPosition(x?, y?, width?, height?)`	method	在区域内随机化位置。返回 `this`。
`setRotation(radians?)`	method	以弧度为单位设置旋转。返回 `this`。
`setAngle(degrees?)`	method	以度数为单位设置旋转。返回 `this`。
`setScale(x?, y?)`	method	设置缩放。`y` 默认为 `x`。返回 `this`。
`setX(value?)`	method	设置 x。返回 `this`。
`setY(value?)`	method	设置 y。返回 `this`。
`setZ(value?)`	method	设置 z。返回 `this`。
`setW(value?)`	method	设置 w。返回 `this`。
`getLocalTransformMatrix(tempMatrix?)`	method	获取局部变换矩阵。返回 `TransformMatrix`。
`getWorldTransformMatrix(tempMatrix?, parentMatrix?)`	method	获取包含父级 Container 的世界变换。返回 `TransformMatrix`。
`getLocalPoint(x, y, point?, camera?)`	method	将世界坐标转换为局部空间。返回 `Vector2`。
`getWorldPoint(point?, tempMatrix?, parentMatrix?)`	method	获取考虑父级容器的世界位置。返回 `Vector2`。
`getParentRotation()`	method	所有父级容器旋转的总和，以弧度为单位。

Visible

控制 Game Object 是否渲染。不可见对象仍会运行更新逻辑。

成员	类型	描述
`visible`	boolean (get/set)	可见性状态。默认值：`true`
`setVisible(value)`	method	设置可见性。返回 `this`。

PathFollower

使用内部 tween 管理对 Phaser.Curves.Path 的跟随。

成员	类型	描述
`path`	Phaser.Curves.Path	正在跟随的 Path。
`rotateToPath`	boolean	自动旋转以面向路径方向。默认值：`false`
`pathRotationOffset`	number	当 `rotateToPath` 为 true 时的旋转偏移量（以度数为单位）。
`pathOffset`	Vector2	相对于路径坐标的位置偏移。
`pathVector`	Vector2	路径上的当前点。
`pathDelta`	Vector2	自上次更新以来移动的距离。
`pathTween`	Tween	驱动路径移动的 tween。
`setPath(path, config?)`	method	设置新的 Path。返回 `this`。
`setRotateToPath(value, offset?)`	method	启用自动旋转。返回 `this`。
`isFollowing()`	method	如果正在主动跟随，则返回 `true`。
`startFollow(config?, startAt?)`	method	开始跟随。`config` 可以是 duration（数字）或 PathConfig。返回 `this`。
`pauseFollow()`	method	暂停移动。返回 `this`。
`resumeFollow()`	method	恢复移动。返回 `this`。
`stopFollow()`	method	停止跟随。返回 `this`。

RenderNodes、RenderSteps、Filters、FilterList（v4，仅 WebGL）

有关 RenderNodes、RenderSteps 和 FilterList 的详细信息，请参阅 filters-and-postfx skill 和 references/REFERENCE.md。

要点：在访问 filters 之前，请先在游戏对象上调用 enableFilters()。相机默认带有滤镜。使用 filters.internal 实现对象局部效果，使用 filters.external 实现屏幕空间效果。

有关完整的组件到游戏对象对照表，请参阅 references/REFERENCE.md。

工厂注册与显示列表

自定义游戏对象工厂注册

在工厂上注册自定义游戏对象，以便可以通过 this.add.myObject() 创建它们：

class LaserBeam extends Phaser.GameObjects.Sprite {
    constructor(scene, x, y) {
        super(scene, x, y, 'laser');
    }
}

Phaser.GameObjects.GameObjectFactory.register('laserBeam', function (x, y) {
    const beam = new LaserBeam(this.scene, x, y);
    this.displayList.add(beam);
    return beam;
});

// Now usable in any scene:
const laser = this.add.laserBeam(100, 200);

工厂（this.add）与创建器（this.make）

this.add 创建对象并将其添加到显示列表。this.make 创建对象但不会添加它——这对于屏幕外准备或延迟显示很有用。

// Added to display list immediately
const visible = this.add.sprite(100, 100, 'hero');

// Created but NOT on the display list
const offscreen = this.make.sprite({ key: 'hero', x: 100, y: 100 });

// Add it later when ready
this.add.existing(offscreen);

使用 GetAdvancedValue 实现灵活配置

GetAdvancedValue 从配置对象中解析静态值、随机数组、randInt/Float 范围以及回调：

// Static value
{ speed: 100 }

// Random from array
{ speed: [100, 200, 300] }

// Random integer range
{ speed: { randInt: [50, 150] } }

// Random float range
{ speed: { randFloat: [0.5, 1.5] } }

// Callback
{ speed: function () { return Math.random() * 100; } }

显示列表排序

稍后添加的对象会渲染在较早添加的对象之上。使用以下方式控制排序：

// Depth-based ordering (higher = on top, triggers sort)
sprite.setDepth(10);

// Display list position (no depth change)
sprite.setToTop();
sprite.setToBack();
sprite.setAbove(otherSprite);
sprite.setBelow(otherSprite);

当同时使用 depth 和显示列表位置时，在下一次排序遍历后，depth 优先。

注意事项

alpha=0 会完全阻止渲染：将 alpha 设置为 0 会清除一个渲染标志位。该对象完全不会被绘制，而不仅仅是透明。scale = 0 和 visible = false 也是如此。
翻转不影响物理：翻转仅影响渲染。物理刚体保持不变。在碰撞代码中要考虑到这一点。
ScrollFactor 与物理：物理碰撞使用世界位置。滚动因子不为 1 会偏移纹理渲染的位置，但不会偏移刚体的位置。对于滚动因子为 0 的 HUD 元素，避免添加物理刚体。
depth 与显示列表顺序：setDepth() 会排队一次排序，是主要的 z 轴排序工具。setToTop()、setAbove() 等会重新排列显示列表，而不会改变 depth。如果同时混用两者，在下一次排序后 depth 优先。
v4 中 Mask 组件仅适用于 Canvas：对于 WebGL 遮罩，请使用 enableFilters()，然后使用 filters.internal.addMask()。setMask() 方法在 WebGL 中会记录一条警告。
v4 中已移除 setTintFill：请改用 setTint(color).setTintMode(Phaser.TintModes.FILL)。
v4 中的着色模式：着色模式现在与着色颜色分离。可用模式：MULTIPLY（默认）、FILL、ADD、SCREEN、OVERLAY、HARD_LIGHT。
displayWidth/displayHeight 会调整缩放：设置 displayWidth 或 displayHeight 会修改 scaleX/scaleY。它不会改变 width/height。
setSize 与 setDisplaySize：setSize() 更改内部尺寸（用于帧、物理）。setDisplaySize() 通过调整缩放来更改渲染尺寸。
原点默认为 0.5：所有游戏对象默认以中心为原点。使用 setOrigin(0, 0) 实现左上角定位。Text 和 BitmapText 则默认以左上角定位。
Transform.z 不是 depth：Transform 上的 z 属性供自定义使用。渲染顺序由 depth（Depth 组件）或显示列表位置控制。
滤镜开销较大：每个激活滤镜的对象都需要额外的绘制调用。使用 renderFilters = false 可临时禁用。内部滤镜比外部滤镜开销更低。

源文件映射

文件	说明
`src/gameobjects/components/index.js`	组件注册表，导出所有组件
`src/gameobjects/components/Alpha.js`	逐角 alpha 混入
`src/gameobjects/components/AlphaSingle.js`	单值 alpha 混入
`src/gameobjects/components/BlendMode.js`	混合模式混入
`src/gameobjects/components/Depth.js`	深度/z 顺序混入
`src/gameobjects/components/Flip.js`	视觉翻转混入
`src/gameobjects/components/GetBounds.js`	边界计算混入
`src/gameobjects/components/Lighting.js`	v4 光照混入
`src/gameobjects/components/Mask.js`	Canvas 几何遮罩混入
`src/gameobjects/components/Origin.js`	原点/锚点混入
`src/gameobjects/components/ScrollFactor.js`	相机滚动因子混入
`src/gameobjects/components/Size.js`	尺寸混入
`src/gameobjects/components/Texture.js`	纹理/帧分配混入
`src/gameobjects/components/TextureCrop.js`	支持裁剪的纹理混入
`src/gameobjects/components/Tint.js`	顶点颜色着色混入
`src/gameobjects/components/Transform.js`	位置/缩放/旋转混入
`src/gameobjects/components/Visible.js`	可见性混入
`src/gameobjects/components/PathFollower.js`	路径跟随混入
`src/gameobjects/components/RenderNodes.js`	v4 WebGL 渲染节点混入
`src/gameobjects/components/RenderSteps.js`	v4 WebGL 渲染步骤混入
`src/gameobjects/components/Filters.js`	v4 WebGL 滤镜系统混入
`src/gameobjects/components/FilterList.js`	v4 滤镜列表类（添加效果）
`src/gameobjects/components/TransformMatrix.js`	2D 变换矩阵工具

相关技能：sprites-and-images.md、custom-game-objects.md

支持 Markdown

登录后评论

基本信息

作者: phaserjs
仓库: phaserjs/phaser
分类: 开发
安装次数: 816
GitHub Stars: 40,588

报告问题