v4-new-features

Phaser 4 新特性

Phaser 4 中的新功能与特性：Filters（取代 FX/BitmapMask）、RenderNodes（取代 Pipelines）、CaptureFrame、Gradient、Noise 游戏对象、SpriteGPULayer、TilemapGPULayer、Lighting 组件、RenderSteps，以及新的着色模式。

相关技能： ../v3-to-v4-migration/SKILL.md, ../filters-and-postfx/SKILL.md, ../game-object-components/SKILL.md, ../tilemaps/SKILL.md

从 v3 迁移？ 请参阅 v3 到 v4 迁移指南，了解逐步的代码修改、已移除的 API 以及迁移检查清单。

概述：v4 有哪些变化

Phaser 4 是对 WebGL 渲染引擎的全面重构。v3 渲染器让每个子系统独立管理 WebGL 状态，从而导致冲突（例如某些 FX 会破坏 Mask）。v4 通过 RenderNode 图集中管理 WebGL 状态，其中每个节点只负责一项渲染任务。

主要移除项

v3 特性	v4 替代方案
Pipeline	RenderNode（按任务划分的渲染节点）
FX（preFX / postFX）	Filters（filters.internal / filters.external）
BitmapMask	FilterMask（通过 filters 系统）
GeometryMask（WebGL）	FilterMask（Canvas 仍使用 GeometryMask）
派生 FX：Bloom、Circle、Gradient、Shine	Actions（AddEffectBloom、AddEffectShine、AddMaskShape）或 GameObjects
Mesh 和 Plane	已移除（未来计划提供正式 3D 支持）
Point	改用 Vector2

主要新增项

• 新游戏对象：CaptureFrame、Gradient、Noise、NoiseCell2D/3D/4D、NoiseSimplex2D/3D、SpriteGPULayer、Stamp、TilemapGPULayer
• 新组件：Lighting、RenderSteps、RenderNodes
• 新着色模式：MULTIPLY、FILL、ADD、SCREEN、OVERLAY、HARD_LIGHT
• 新 Filters：Blend、Blocky、CombineColorMatrix、GradientMap、ImageLight、Key、Mask、NormalTools、PanoramaBlur、ParallelFilters、Quantize、Sampler、Threshold
• GL 方向：v4 使用标准 GL 方向（纹理的 Y=0 位于底部）

---

Filters 系统（取代 FX 和 BitmapMask）

完整参考：filters-and-postfx.md

Filters 统一了 v3 的 FX 和 Mask 系统。每个 filter 接收输入图像，并通过 shader pass 生成输出图像。Filters 可以应用于任何游戏对象或摄像机——v3 对哪些对象支持 FX 有限制。

// v3 approach (FX):
sprite.preFX.addGlow(0xff00ff, 4);
sprite.postFX.addBlur(0, 2, 2, 1);

// v4 approach (Filters):
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);
sprite.filters.external.addBlur(0, 2, 2, 1);

// v3 approach (BitmapMask):
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskImage);
sprite.setMask(mask);

// v4 approach (FilterMask):
sprite.enableFilters();
sprite.filters.internal.addMask(maskImage);

内部与外部：内部 filters 在摄像机变换之前运行（对象局部空间，开销更低）。外部 filters 在之后运行（屏幕空间，全分辨率）。

---

RenderNodes（取代 Pipelines）

在 v3 中，Pipeline 是一个渲染系统，通常承担多项职责。在 v4 中，每个 RenderNode 通过其 run() 方法处理单一的渲染任务。某些节点还有 batch() 方法，用于在绘制前累积状态。

架构

RenderNodeManager（位于 WebGL 渲染器上）拥有所有渲染节点。游戏对象通过基于角色的映射引用节点。

// RenderNode roles on a game object:
// - 'Submitter': runs other node roles for each element
// - 'Transformer': provides vertex coordinates
// - 'Texturer': handles textures

// GameObjects have default and custom render node maps:
gameObject.defaultRenderNodes  // built-in nodes per role
gameObject.customRenderNodes   // overrides per role
gameObject.renderNodeData      // data keyed by node name

设置自定义 RenderNodes

// Override a specific render role:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');

// Pass data to a render node:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});

// Remove a custom node (falls back to default):
gameObject.setRenderNodeRole('Submitter', null);

内置 RenderNode 类型

批处理器（每次绘制调用累积并绘制多个对象）：

• BatchHandlerQuad -- 标准四边形批处理（Image、Sprite、BitmapText 等）
• BatchHandlerQuadSingle -- 单四边形变体
• BatchHandlerTileSprite -- TileSprite 批处理
• BatchHandlerTriFlat -- 平面三角形批处理（Graphics、Shape）
• BatchHandlerPointLight -- 点光源批处理
• BatchHandlerStrip -- 三角形条带批处理

提交器（按对象类型协调渲染）：

• SubmitterQuad、SubmitterTile、SubmitterTileSprite
• SubmitterSpriteGPULayer、SubmitterTilemapGPULayer

变换器（计算顶点位置）：

• TransformerImage、TransformerStamp、TransformerTile、TransformerTileSprite

纹理器（管理纹理绑定）：

• TexturerImage、TexturerTileSprite

滤镜（后处理 -- 参见 filters-and-postfx.md）：

• BaseFilter、BaseFilterShader
• FilterBarrel、FilterBlend、FilterBlocky、FilterBlur（Low/Med/High 变体）
• FilterBokeh、FilterColorMatrix、FilterCombineColorMatrix
• FilterDisplacement、FilterGlow、FilterGradientMap、FilterImageLight
• FilterKey、FilterMask、FilterNormalTools、FilterPanoramaBlur
• FilterParallelFilters、FilterPixelate、FilterQuantize
• FilterSampler、FilterShadow、FilterThreshold、FilterVignette、FilterWipe

其他：

• Camera、FillCamera、FillRect、FillPath、FillTri
• DrawLine、StrokePath、ShaderQuad
• ListCompositor、RebindContext、YieldContext
• DynamicTextureHandler

扩展：自定义 RenderNode

// Register a custom node constructor:
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);

// Or add a pre-built node instance:
renderer.renderNodes.addNode('MyNode', myNodeInstance);

---

新游戏对象

CaptureFrame

在显示列表中所在的位置，将当前帧缓冲区内容捕获到纹理。其本身不渲染任何内容。仅支持 WebGL。

// Everything above this in the display list gets captured:
const image1 = this.add.image(400, 300, 'background');

// Enable framebuffer usage on the camera:
this.cameras.main.setForceComposite(true);

// Create the capture point:
const capture = this.add.captureFrame('myCapturedTexture');

// Use the captured texture on another object:
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Add filters to the overlay to distort the captured scene

关键细节：

• 需要 camera.setForceComposite(true) 或帧缓冲区上下文（滤镜、DynamicTexture、带部分 alpha 的相机）
• 在带滤镜的 Container 内部时，仅捕获该 Container 的内容
• 设置 visible = false 可停止捕获
• 组件：BlendMode、Depth、RenderNodes、Visible

源码：src/gameobjects/captureframe/CaptureFrame.js

Gradient

显示 GPU 渲染的颜色渐变。继承自 Shader。支持线性、径向及其他形状模式，可通过包含 ColorBand 对象的可配置 ColorRamp 进行设置。

// Simple linear gradient:
const grad = this.add.gradient(undefined, 100, 100, 200, 200);

// Complex radial gradient with multiple color bands:
const halo = this.add.gradient({
    bands: [
        { start: 0.5, end: 0.6, colorStart: [0.5, 0.5, 1, 0], colorEnd: 0xffffff, colorSpace: 1, interpolation: 4 },
        { start: 0.6, end: 1, colorStart: 0xffffff, colorEnd: [1, 0.5, 0.5, 0], colorSpace: 1, interpolation: 3 }
    ],
    dither: true,
    repeatMode: 1,
    shapeMode: 2,       // radial
    start: { x: 0.5, y: 0.5 },
    shape: { x: 0.5, y: 0.0 }
}, 400, 300, 800, 800);

// Animate:
halo.offset = 0.1 * (1 + Math.sin(time / 1000));

关键细节：

• 配置：GradientQuadConfig，包含 bands、shapeMode、repeatMode、start、shape、dither
• 颜色通过 ColorRamp 及 ColorBand 对象定义（支持 HSV、多种插值模式）
• 在运行时修改 ramp 数据后，调用 gradient.ramp.encode()

源码：src/gameobjects/gradient/Gradient.js

噪声游戏对象

所有噪声类型均继承自 Shader，且仅支持 WebGL。提供六种变体：

类型	工厂方法	描述
Noise	this.add.noise()	白噪声（基于随机哈希）
NoiseCell2D	this.add.noiseCell2D()	2D 细胞/Worley/Voronoi 噪声
NoiseCell3D	this.add.noiseCell3D()	3D 细胞噪声（Z 轴切片用于动画）
NoiseCell4D	this.add.noiseCell4D()	4D 细胞噪声（Z+W 轴切片）
NoiseSimplex2D	this.add.noiseSimplex2D()	2D simplex/梯度噪声（云、火、水）
NoiseSimplex3D	this.add.noiseSimplex3D()	3D simplex 噪声

// Basic white noise:
const noise = this.add.noise({
    noiseOffset: [0, 0],
    noisePower: 1
}, 100, 100, 256, 256);

// Cellular noise with customization:
const cells = this.add.noiseCell2D({
    noiseOffset: [0, 0],
    noiseIterations: 3,
    noiseNormalMap: true    // output as normal map for lighting
}, 200, 200, 256, 256);

// Simplex noise for natural effects:
const simplex = this.add.noiseSimplex2D({
    noiseFlow: 0,           // animate this for evolution
    noiseIterations: 4,
    noiseWarpAmount: 0.5,   // turbulence
    noiseSeed: 42,
    noiseNormalMap: false
}, 300, 300, 256, 256);

各噪声类型的通用属性：

• noiseOffset -- [x, y] 数组，用于滚动图案
• noisePower -- 调整输出级别（值越高，高值被抑制得越多）
• noiseNormalMap -- 输出法线贴图（用于光照集成）
• noiseIterations -- 细节级别（细胞/simplex 类型）

数学等价物：Phaser.Math.Hash()、Phaser.Math.HashCell()、Phaser.Math.HashSimplex()

源码：src/gameobjects/noise/

SpriteGPULayer

通过将数据存储在静态 GPU 缓冲区中，在单次绘制调用中渲染极大量四边形（最多可达数百万个）。速度比单个精灵快最多 100 倍。仅限 WebGL。

const layer = this.add.spriteGPULayer(texture, size); // size = max number of members

// Add members (do this all at once, not incrementally):
const member = { x: 100, y: 200, frame: 'tree', scaleX: 1, scaleY: 1, alpha: 1 };
layer.addMember(member);

// Reuse the member object for efficiency with millions of entries:
member.x = 300;
member.y = 400;
member.frame = 'bush';
layer.addMember(member);

// Enable lighting on the layer:
layer.setLighting(true);

关键细节：

• 仅支持单纹理（不支持多图集），每层单张图像
• 成员支持在创建时定义的类补间动画（淡入淡出、弹跳、波动、颜色偏移）
• 更新缓冲区内容开销很大——一次填充，之后保持不变
• 像素画建议使用 2 的幂纹理，以避免接缝
• 通过将 scaleX/scaleY/alpha 设为 0 来在视觉上“移除”成员（避免重建缓冲区）
• 组件：Alpha、BlendMode、Depth、ElapseTimer、Lighting、Mask、RenderNodes、TextureCrop、Visible

源码：src/gameobjects/spritegpulayer/SpriteGPULayer.js

---

新组件

完整组件参考：game-object-components.md

Lighting 组件

取代 v3 中分配光照管线的做法。仅限 WebGL。

// v3 approach:
sprite.setPipeline('Light2D');

// v4 approach:
sprite.setLighting(true);

// Self-shadowing (simulates surface shadows from texture brightness):
sprite.setSelfShadow(true, 0.5, 1/3);
// Args: enabled, penumbra (lower = sharper), diffuseFlatThreshold (0-1)

// Use game-wide default for self-shadow:
sprite.setSelfShadow(null);  // reads from config.render.selfShadow

支持对象：BitmapText、Blitter、Graphics、Shape、Image、Sprite、Particles、SpriteGPULayer、Stamp、Text、TileSprite、Video、TilemapLayer、TilemapGPULayer。

批处理注意事项：光照会改变着色器，从而打断批处理。为获得最佳性能，请将受光照影响的对象归为一组，未受光照影响的对象归为另一组。

源码：src/gameobjects/components/Lighting.js

RenderSteps 组件

允许向游戏对象的渲染流程中注入自定义逻辑。仅限 WebGL。Filters 系统内部使用 RenderSteps。

// Add a custom render step:
gameObject.addRenderStep(function (renderer, gameObject, drawingContext, parentMatrix, renderStep, displayList, displayListIndex) {
    // Custom rendering logic here
    // Call next step when ready:
    var nextFn = gameObject._renderSteps[renderStep + 1];
    if (nextFn) {
        nextFn(renderer, gameObject, drawingContext, parentMatrix, renderStep + 1, displayList, displayListIndex);
    }
});

关键细节：

• 步骤存储在 _renderSteps 数组中，通过 renderWebGLStep() 执行
• 第一步最先运行，并负责调用后续步骤
• Filters 正是通过这种方式延迟并控制 renderWebGL 流程

源码：src/gameobjects/components/RenderSteps.js

RenderNodes 组件

为游戏对象提供 defaultRenderNodes、customRenderNodes 和 renderNodeData 映射。用法请参见上文的 RenderNodes 部分。

源码：src/gameobjects/components/RenderNodes.js

---

TilemapGPULayer

完整 tilemap 参考：tilemaps.md

高性能的基于 GPU 的 tilemap 渲染。通过专用着色器将整个层渲染为单个四边形。仅限 WebGL。

// Create via Tilemap with the gpu flag:
const map = this.make.tilemap({ key: 'level1' });
const tileset = map.addTilesetImage('tiles', 'tilesImage');
const gpuLayer = map.createLayer('Ground', tileset, 0, 0, true);  // last arg: gpu = true

能力：

• 单个 tileset，仅含单张纹理图像
• 最大 4096x4096 个图块，最多 2^23 个唯一图块 ID
• 支持图块翻转和动画
• 仅限正交 tilemap（不支持等距/六边形）
• 在 LINEAR 模式下实现完美的纹理过滤（无图块接缝）
• 开销按像素计算，而非按图块计算——可见图块很多时也不会有性能损失

限制：

• 不能使用多个 tileset
• 编辑需要手动调用 generateLayerDataTexture() 来更新
• 仅限正交

内部数据：图块数据存储在纹理中（每个图块 4 字节：2 个翻转位、1 个动画位、1 个未使用位、28 位图块索引）。动画数据存储在单独的纹理中。

源码：src/tilemaps/TilemapGPULayer.js

---

有关详细配置选项、API 参考表和源文件映射，请参见参考指南。