v3-to-v4-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phaser v3 to v4 Migration Guide

Phaser v3 迁移至 v4 指南

This guide covers everything you need to change when upgrading a Phaser v3 project to Phaser v4. It is organized from highest-impact changes to smaller details, so you can work through it top-to-bottom.

Related skills: ../v4-new-features/SKILL.md, ../game-setup-and-config/SKILL.md, ../filters-and-postfx/SKILL.md

本指南涵盖将Phaser v3项目升级至v4所需修改的全部内容，按变更影响从大到小排序，你可以从上到下逐步完成迁移。

相关技能： ../v4-new-features/SKILL.md, ../game-setup-and-config/SKILL.md, ../filters-and-postfx/SKILL.md

1. Renderer: Pipelines to Render Nodes

1. 渲染器：从管线到RenderNode

Phaser v4 contains a brand-new WebGL renderer. The entire rendering pipeline from v3 has been replaced. This is the single biggest change in v4.

What was removed:

The v3

Pipeline

system has been removed entirely. Pipelines frequently held multiple responsibilities (e.g. the Utility pipeline handled various different rendering tasks) and each had to manage WebGL state independently, leading to conflicts where one pipeline could break another's assumptions.

What replaced it:

The new

RenderNode

architecture. Each render node handles a single rendering task, making the system more maintainable. All render nodes have a

run

method, and some have a

batch

method to assemble state from several sources before invoking

run

What this means for you:

If your game only uses the standard Phaser API (Sprites, Text, Tilemaps, etc.), the new renderer should work transparently.
If you wrote custom WebGL pipelines in v3, they will need to be rewritten as render nodes. Use
```
RenderConfig#renderNodes
```
to register custom render nodes at boot.
If you accessed
```
WebGLRenderer
```
internals directly, be aware that many internal properties have been removed or restructured:
- ```
WebGLRenderer.textureIndexes
```
  is removed. Use
```
glTextureUnits.unitIndices
```
  instead.
- ```
WebGLRenderer#genericVertexBuffer
```
  and
```
#genericVertexData
```
  are removed (freeing ~16MB RAM/VRAM).
```
BatchHandler
```
  render nodes now create their own WebGL data buffers.
- ```
WebGLAttribLocationWrapper
```
  is removed.
Do not make direct WebGL
```
gl
```
calls in a Phaser v4 game. This can change the WebGL state without updating the internal
```
WebGLGlobalWrapper
```
, causing unpredictable behavior. If you need direct WebGL access, use an
```
Extern
```
game object, which resets state after it finishes.

Phaser v4搭载了全新的WebGL渲染器，v3的整个渲染管线已被完全替换，这是v4中最大的单一变更。

已移除内容：

v3的

Pipeline

系统已完全移除。管线通常承担多项职责（例如Utility管线处理各类不同渲染任务），且每个管线需独立管理WebGL状态，容易导致冲突，一个管线可能破坏另一个管线的预设条件。

替代方案：

全新的

RenderNode

架构。每个RenderNode仅处理一项渲染任务，让系统更易于维护。所有RenderNode都有

run

方法，部分还具备

batch

方法，可在调用

run

前汇总多个来源的状态。

对你的影响：

若你的游戏仅使用标准Phaser API（Sprite、Text、Tilemap等），新渲染器可无缝工作。
若你在v3中编写了自定义WebGL管线，需将其重写为RenderNode。启动时使用
```
RenderConfig#renderNodes
```
注册自定义RenderNode。
若你直接访问
```
WebGLRenderer
```
内部属性，请注意许多内部属性已被移除或重构：
- ```
WebGLRenderer.textureIndexes
```
  已移除，改用
```
glTextureUnits.unitIndices
```
  。
- ```
WebGLRenderer#genericVertexBuffer
```
  和
```
#genericVertexData
```
  已移除（释放约16MB内存/显存）。BatchHandler类型的RenderNode现在会创建自己的WebGL数据缓冲区。
- ```
WebGLAttribLocationWrapper
```
  已移除。
请勿在Phaser v4游戏中直接调用WebGL的
```
gl
```
方法，这会在未更新内部
```
WebGLGlobalWrapper
```
的情况下修改WebGL状态，导致不可预测的行为。若需直接访问WebGL，请使用
```
Extern
```
游戏对象，它会在执行完毕后重置状态。

2. Canvas Renderer Deprecated

2. Canvas渲染器已被弃用

The Canvas renderer is still available but should be considered deprecated. Canvas rendering does not support any of the WebGL techniques used in v4's advanced rendering features. As WebGL support is effectively baseline today, we recommend WebGL for all new projects.

Canvas retains one advantage: 27 blend modes vs WebGL's 4 native modes (NORMAL, ADD, MULTIPLY, SCREEN). In v4, the new

Blend

filter can recreate all Canvas blend modes in WebGL, though it requires indirection through a

CaptureFrame

DynamicTexture

, or similar.

Canvas渲染器仍可用，但已被标记为弃用。Canvas渲染不支持v4高级渲染功能所使用的任何WebGL技术。如今WebGL支持已成为基础标准，我们建议所有新项目使用WebGL。

Canvas仍有一个优势：支持27种混合模式，而WebGL仅原生支持4种（NORMAL、ADD、MULTIPLY、SCREEN）。在v4中，全新的

Blend

过滤器可在WebGL中还原所有Canvas混合模式，但需通过

CaptureFrame

、

DynamicTexture

等方式间接实现。

3. FX and Masks are now Filters

3. FX与遮罩统一为过滤器

This is one of the most impactful changes for v3 users who relied on the FX or Mask systems.

What changed:

FX (pre and post) and Masks have been unified into a single Filter system. A Filter takes an input image and produces an output image, usually via a single shader. All filters are mutually compatible.

Key differences from v3:

No more preFX/postFX distinction. Filters are divided into internal (affects just the object) and external (affects the object in its rendering context, usually the full screen) lists.
No more object restrictions. In v3, only certain objects supported FX. In v4, filters can be applied to any game object or scene camera, including
```
Extern
```
objects.
BitmapMask
removed. Use the new
```
Mask
```
filter instead.
```
GeometryMask
```
remains available in Canvas only.

Removed derived FX and their replacements:

v3 FX	v4 Replacement
`Bloom`	`Phaser.Actions.AddEffectBloom()`
`Shine`	`Phaser.Actions.AddEffectShine()`
`Circle`	`Phaser.Actions.AddMaskShape()`
`Gradient`	`Gradient` game object

ColorMatrix change:

The

ColorMatrix

filter shifted its color management methods onto a

colorMatrix

property:

// v3
colorMatrix.sepia();

// v4
colorMatrix.colorMatrix.sepia();

Mask migration:

// v3 - BitmapMask
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskObject);
sprite.setMask(mask);

// v4 - Mask filter
sprite.filters.internal.addMask(maskObject);

对于依赖FX或遮罩系统的v3用户而言，这是影响最大的变更之一。

变更内容：

FX（前置与后置）和遮罩已统一为单一的Filter系统。Filter接收输入图像并生成输出图像，通常通过单个着色器实现。所有过滤器彼此兼容。

与v3的主要差异：

不再区分preFX/postFX。过滤器分为内部（仅影响对象本身）和外部（影响对象所在的渲染上下文，通常是全屏）两类。
不再有对象限制。v3中仅部分对象支持FX，v4中过滤器可应用于任何游戏对象或场景相机，包括
```
Extern
```
对象。
BitmapMask
已移除，改用全新的
```
Mask
```
过滤器。
```
GeometryMask
```
仅在Canvas模式下保留。

已移除的衍生FX及替代方案：

v3 FX	v4 替代方案
`Bloom`	`Phaser.Actions.AddEffectBloom()`
`Shine`	`Phaser.Actions.AddEffectShine()`
`Circle`	`Phaser.Actions.AddMaskShape()`
`Gradient`	`Gradient` 游戏对象

ColorMatrix变更：

ColorMatrix

过滤器的颜色管理方法已移至

colorMatrix

属性：

// v3
colorMatrix.sepia();

// v4
colorMatrix.colorMatrix.sepia();

遮罩迁移示例：

// v3 - BitmapMask
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskObject);
sprite.setMask(mask);

// v4 - Mask过滤器
sprite.filters.internal.addMask(maskObject);

4. Tint System

4. 着色系统

The tint system has been overhauled with a new API and additional blend modes.

Removed:

```
tintFill
```
property
```
setTintFill()
```
method

Replacement:

Use the new
```
tintMode
```
property or
```
setTintMode()
```
method to control tint blending.

Phaser.TintModes

enumerates the available modes:

MULTIPLY

FILL

ADD

SCREEN

OVERLAY

HARD_LIGHT

How to convert your code:

// v3
sprite.setTintFill(0xff0000);

// v4
sprite.setTint(0xff0000).setTintMode(Phaser.TintModes.FILL);

Other tint changes:

```
tint
```
and
```
setTint()
```
now purely affect color settings. In v3, calling these would silently deactivate fill mode.
FILL mode now treats partial alpha correctly.
BitmapText tinting now works correctly.

着色系统已全面升级，新增了API和更多混合模式。

已移除内容：

```
tintFill
```
属性
```
setTintFill()
```
方法

替代方案：

使用全新的
```
tintMode
```
属性或
```
setTintMode()
```
方法控制着色混合模式。

Phaser.TintModes

枚举了可用模式：

MULTIPLY

、

FILL

、

ADD

、

SCREEN

、

OVERLAY

、

HARD_LIGHT

。

代码转换示例：

// v3
sprite.setTintFill(0xff0000);

// v4
sprite.setTint(0xff0000).setTintMode(Phaser.TintModes.FILL);

其他着色变更：

```
tint
```
和
```
setTint()
```
现在仅影响颜色设置。v3中调用这些方法会自动关闭填充模式。
FILL模式现在可正确处理部分透明度。
BitmapText着色现在可正常工作。

5. Camera System

5. 相机系统

The camera matrix system has been rewritten. If you only use standard camera properties (

scrollX

scrollY

zoom

rotation

), your code should work without changes. However, if you access camera matrices directly, you must update your code.

What changed:

v3	v4
`Camera#matrix` = position + rotation + zoom	`Camera#matrix` = rotation + zoom + scroll (no position)
Scroll appended separately	Scroll is part of `Camera#matrix`
No equivalent	`Camera#matrixExternal` = position only
No equivalent	`Camera#matrixCombined` = `matrix` * `matrixExternal`

If you manipulated scroll factors manually:

// v3
spriteMatrix.e -= camera.scrollX * src.scrollFactorX;

// v4
TransformMatrix.copyWithScrollFactorFrom(matrix, scrollX, scrollY, scrollFactorX, scrollFactorY);

Other camera changes:

```
GetCalcMatrix()
```
now takes an additional
```
ignoreCameraPosition
```
parameter.
```
GetCalcMatrixResults
```
now includes a
```
matrixExternal
```
property.

相机矩阵系统已重写。若你仅使用标准相机属性（

scrollX

、

scrollY

、

zoom

、

rotation

），代码无需修改。但如果直接访问相机矩阵，则必须更新代码。

变更内容：

v3	v4
`Camera#matrix` = 位置 + 旋转 + 缩放	`Camera#matrix` = 旋转 + 缩放 + 滚动（无位置）
滚动单独追加	滚动已包含在 `Camera#matrix` 中
无对应项	`Camera#matrixExternal` = 仅位置
无对应项	`Camera#matrixCombined` = `matrix` * `matrixExternal`

若你手动操作滚动因子：

// v3
spriteMatrix.e -= camera.scrollX * src.scrollFactorX;

// v4
TransformMatrix.copyWithScrollFactorFrom(matrix, scrollX, scrollY, scrollFactorX, scrollFactorY);

其他相机变更：

```
GetCalcMatrix()
```
新增
```
ignoreCameraPosition
```
参数。
```
GetCalcMatrixResults
```
新增
```
matrixExternal
```
属性。

6. Texture Coordinates and GL Orientation

6. 纹理坐标与GL方向

Phaser v3 used top-left orientation for textures, which caused mismatches internally (framebuffers drawn upside-down, then flipped). Phaser v4 uses GL orientation throughout, where Y=0 is at the bottom.

Action required:

If you use compressed textures, they must be re-compressed with the Y axis starting at the bottom and increasing upwards. This is usually available as a "flip Y" option in your texture compression software.
Standard image textures (PNG, JPG, etc.) are handled automatically -- no action needed.
If you write custom shaders, note that texture coordinates now use GL conventions where Y=0 is at the bottom of the image.

Phaser v3使用左上角为原点的纹理方向，这会导致内部不匹配（帧缓冲区上下颠倒绘制后再翻转）。Phaser v4全程使用GL方向，即Y=0位于底部。

需执行的操作：

若使用压缩纹理，必须重新压缩，使Y轴从底部开始向上递增。通常纹理压缩软件会提供“翻转Y轴”选项。
标准图像纹理（PNG、JPG等）会自动处理，无需操作。
若编写自定义着色器，请注意纹理坐标现在遵循GL规范，Y=0位于图像底部。

7. DynamicTexture and RenderTexture

7. DynamicTexture与RenderTexture

In v3,

DynamicTexture

allowed you to define batches and perform intricate drawing operations directly. In v4, many of these complex methods have been removed in favor of using the standard rendering system, which handles batching automatically.

Breaking change:

DynamicTexture

and

RenderTexture

must now call

render()

to execute all buffered drawing commands. Previously, draw commands were executed immediately.

New capabilities:

```
DynamicTexture#preserve()
```
keeps the command buffer for reuse after rendering, allowing you to re-render commands that draw changing game objects.
```
DynamicTexture#callback()
```
inserts a callback to run during command buffer execution.
```
DynamicTexture#capture
```
renders game objects more accurately than
```
draw
```
, capturing the current camera view.
```
RenderTexture.renderMode
```
property:
```
"render"
```
(draw like an Image),
```
"redraw"
```
(update texture during render loop without drawing), or
```
"all"
```
(both). The
```
"redraw"
```
mode enables updating textures mid-render-loop for same-frame shader outputs.

TextureManager#addDynamicTexture

now has a

forceEven

parameter.

v3中

DynamicTexture

允许你直接定义批次并执行复杂的绘制操作。v4中许多复杂方法已被移除，改用标准渲染系统，它会自动处理批处理。

破坏性变更：

DynamicTexture

和

RenderTexture

现在必须调用

render()

才能执行所有缓冲的绘制命令。此前绘制命令会立即执行。

新增功能：

```
DynamicTexture#preserve()
```
会保留命令缓冲区以便渲染后重用，允许重新渲染绘制变化中游戏对象的命令。
```
DynamicTexture#callback()
```
可在命令缓冲区执行期间插入回调函数。
```
DynamicTexture#capture
```
比
```
draw
```
更准确地渲染游戏对象，可捕获当前相机视图。
```
RenderTexture.renderMode
```
属性：
```
"render"
```
（像Image一样绘制）、
```
"redraw"
```
（在渲染循环中更新纹理但不绘制）或
```
"all"
```
（两者兼具）。
```
"redraw"
```
模式允许在渲染循环中更新纹理以实现同帧着色器输出。

TextureManager#addDynamicTexture

新增

forceEven

参数。

8. Shader API

The

Shader

game object has been significantly rewritten. Existing v3 shaders will need to be updated.

What changed:

The construction signature now takes a config object (
```
ShaderQuadConfig
```
) instead of individual parameters.
Shadertoy-style uniforms (resolution, time, etc.) are no longer set automatically. Encode them into your configuration if needed.
Texture coordinates now use GL conventions (Y=0 at bottom).
New
```
Shader#setUniform(name, value)
```
method for setting program uniforms individually.
New
```
Shader#renderImmediate
```
method for rendering outside the regular render loop.

Shader

游戏对象已大幅重写，现有v3着色器需更新。

变更内容：

构造签名现在接收配置对象（
```
ShaderQuadConfig
```
）而非单独参数。
Shadertoy风格的 uniforms（分辨率、时间等）不再自动设置，若需使用需将其编码到配置中。
纹理坐标现在遵循GL规范（Y=0位于底部）。
新增
```
Shader#setUniform(name, value)
```
方法用于单独设置程序uniforms。
新增
```
Shader#renderImmediate
```
方法用于在常规渲染循环外进行渲染。

9. GLSL Loading

9. GLSL加载

The way Phaser loads GLSL code has changed:

GLSL code is no longer classified as "fragment" or "vertex" when loaded. Under the new system it could be either, or both. You load shaders separately and combine them when creating a Shader.
Custom templates have been replaced with
```
#pragma
```
preprocessor directives, which are valid GLSL and compatible with automated syntax checkers. The pragmas are removed before compilation.

Phaser加载GLSL代码的方式已变更：

GLSL代码加载时不再分为“片段”或“顶点”类型。在新系统中它可以是其中一种，或两者兼具。你需单独加载着色器，创建Shader时再将它们组合。
自定义模板已被
```
#pragma
```
预处理指令取代，这些指令是有效的GLSL语法，且兼容自动语法检查器。编译前会移除这些指令。

10. Lighting

10. 光照

Lighting has been simplified and enhanced.

How to convert your code:

// v3 - Pipeline-based lighting
sprite.setPipeline('Light2D');

// v4 - Simple method call
sprite.setLighting(true);

Other lighting changes:

Lighting is available on many game objects: BitmapText, Blitter, Graphics, Shape, Image, Sprite, Particles, SpriteGPULayer, Stamp, Text, TileSprite, Video, TilemapLayer, and TilemapGPULayer.
Objects can now cast self-shadows using a shader that simulates shadows from surface features based on texture brightness. Configurable game-wide or per-object.
Lights now have a
```
z
```
value to set height explicitly, replacing the implicit height based on game resolution from v3.
Note: lighting changes the shader, which breaks render batches.
You can also use the
```
ImageLight
```
filter for image-based lighting, but it is separate from the core lighting system.

光照系统已简化并增强。

代码转换示例：

// v3 - 基于管线的光照
sprite.setPipeline('Light2D');

// v4 - 简单方法调用
sprite.setLighting(true);

其他光照变更：

光照可应用于多种游戏对象：BitmapText、Blitter、Graphics、Shape、Image、Sprite、Particles、SpriteGPULayer、Stamp、Text、TileSprite、Video、TilemapLayer和TilemapGPULayer。
对象现在可投射自阴影，通过着色器根据纹理亮度模拟表面特征产生的阴影。可全局配置或按对象配置。
光源现在有
```
z
```
属性用于显式设置高度，取代v3中基于游戏分辨率的隐式高度。
注意：光照会改变着色器，这会破坏渲染批处理。
你也可使用
```
ImageLight
```
过滤器实现基于图像的光照，但它独立于核心光照系统。

11. TileSprite

TileSprite has been internally rewritten to use a new shader that manually controls texture coordinate wrapping instead of relying on WebGL texture wrapping parameters.

What changed:

```
TileSprite
```
no longer supports texture cropping.
TileSprite now assigns default dimensions to each dimension separately.

New capabilities:

TileSprite now supports texture frames within atlases and spritesheets (v3 could only repeat the entire texture file).
New
```
tileRotation
```
property allows rotating the repeating texture.
Works correctly with compressed textures, non-power-of-two textures, and DynamicTextures (all had issues in v3).

TileSprite已内部重写，使用新的着色器手动控制纹理坐标包裹，而非依赖WebGL纹理包裹参数。

变更内容：

```
TileSprite
```
不再支持纹理裁剪。
TileSprite现在为每个维度单独分配默认尺寸。

新增功能：

TileSprite现在支持图集和精灵表中的纹理帧（v3仅能重复整个纹理文件）。
新增
```
tileRotation
```
属性允许旋转重复的纹理。
可正确处理压缩纹理、非2的幂次纹理和DynamicTexture（这些在v3中都存在问题）。

12. Graphics and Shape

12. Graphics与Shape

```
Graphics
```
has a new
```
pathDetailThreshold
```
property (also available as a game config option) that skips vertices within a certain distance of one another, improving performance on complex curves in small areas.
```
Grid
```
shape has renamed properties: it now uses stroke instead of outline, matching the conventions of other Shape objects. Grid also has new controls for rendering gutters between cells and whether to draw outlines on the outside of the grid or just between cells.
```
Rectangle
```
now supports rounded corners.

```
Graphics
```
新增
```
pathDetailThreshold
```
属性（也可作为游戏配置选项），可跳过彼此距离在特定范围内的顶点，提升小区域复杂曲线的性能。
```
Grid
```
形状的属性已重命名：现在使用stroke而非outline，与其他Shape对象的命名规范一致。Grid还新增了控制单元格之间 gutter 渲染的选项，以及是否在网格外部绘制轮廓还是仅在单元格之间绘制。
```
Rectangle
```
现在支持圆角。

13. Geometry: Point Replaced by Vector2

13. 几何：Point替换为Vector2

The

Geom.Point

class and all related functions have been removed. Use

Vector2

instead.

Quick reference for method replacements:

v3 ( `Point` )	v4 ( `Vector2` / `Math` )
`Point.Ceil`	`Vector2.ceil`
`Point.Floor`	`Vector2.floor`
`Point.Clone`	`Vector2.clone`
`Point.CopyFrom(src, dest)`	`dest.copy(src)`
`Point.Equals`	`Vector2.equals`
`Point.GetCentroid`	`Math.GetCentroid`
`Point.GetMagnitude`	`Vector2.length`
`Point.GetMagnitudeSq`	`Vector2.lengthSq`
`Point.Invert`	`Vector2.invert`
`Point.Negative`	`Vector2.negate`
`Point.SetMagnitude`	`Vector2.setLength`
`Point.Project`	`Vector2.project`
`Point.ProjectUnit`	`Vector2.projectUnit`
`Point.Interpolate`	`Math.LinearXY`
`Point.GetRectangleFromPoints`	`Math.GetVec2Bounds`

All geometry classes now return Vector2 instead of Point:

The following classes and their static helper functions (

getPoint

getPoints

getRandomPoint

CircumferencePoint

Random

, etc.) all return

Vector2

instances:

```
Geom.Circle
```
```
Geom.Ellipse
```
```
Geom.Line
```
```
Geom.Polygon
```
```
Geom.Rectangle
```
```
Geom.Triangle
```

If you have code that checks

instanceof Phaser.Geom.Point

, update it to check for

Phaser.Math.Vector2

Geom.Point

类及所有相关函数已被移除，改用

Vector2

。

方法替换快速参考：

v3 ( `Point` )	v4 ( `Vector2` / `Math` )
`Point.Ceil`	`Vector2.ceil`
`Point.Floor`	`Vector2.floor`
`Point.Clone`	`Vector2.clone`
`Point.CopyFrom(src, dest)`	`dest.copy(src)`
`Point.Equals`	`Vector2.equals`
`Point.GetCentroid`	`Math.GetCentroid`
`Point.GetMagnitude`	`Vector2.length`
`Point.GetMagnitudeSq`	`Vector2.lengthSq`
`Point.Invert`	`Vector2.invert`
`Point.Negative`	`Vector2.negate`
`Point.SetMagnitude`	`Vector2.setLength`
`Point.Project`	`Vector2.project`
`Point.ProjectUnit`	`Vector2.projectUnit`
`Point.Interpolate`	`Math.LinearXY`
`Point.GetRectangleFromPoints`	`Math.GetVec2Bounds`

所有几何类现在返回Vector2而非Point：

以下类及其静态辅助函数（

getPoint

、

getPoints

、

getRandomPoint

、

CircumferencePoint

、

Random

等）均返回

Vector2

实例：

```
Geom.Circle
```
```
Geom.Ellipse
```
```
Geom.Line
```
```
Geom.Polygon
```
```
Geom.Rectangle
```
```
Geom.Triangle
```

若你的代码中存在

instanceof Phaser.Geom.Point

检查，请更新为检查

Phaser.Math.Vector2

。

14. Math Constants

14. 数学常量

v3	v4	Notes
`Math.TAU` (was PI / 2)	`Math.TAU` (now PI * 2)	Value changed! This is now the correct mathematical tau.
`Math.PI2`	Removed	Use `Math.TAU` instead.
No equivalent	`Math.PI_OVER_2`	New constant for PI / 2 (what v3's `TAU` incorrectly was).

Action required: If you used

Math.TAU

in v3 expecting PI / 2, replace it with

Math.PI_OVER_2

. If you used

Math.PI2

, replace it with

Math.TAU

v3	v4	说明
`Math.TAU` （原等于PI / 2）	`Math.TAU` （现等于PI * 2）	数值已变更！现在为正确的数学tau值。
`Math.PI2`	已移除	改用 `Math.TAU` 。
无对应项	`Math.PI_OVER_2`	新增常量，代表PI / 2（即v3中 `TAU` 的错误值）。

需执行的操作： 若你在v3中使用

Math.TAU

表示PI / 2，请替换为

Math.PI_OVER_2

。若使用

Math.PI2

，请替换为

Math.TAU

。

15. Data Structures

15. 数据结构

Phaser.Struct.Set
has been replaced with a native JavaScript

Set

. Methods like

iterateLocal

are gone. Use standard

Set

methods (

forEach

has

add

delete

, etc.).

Phaser.Struct.Map
has been replaced with a native JavaScript

Map

. Methods like

contains

and

setAll

are gone. Use standard

Map

methods (

has

get

set

delete

, etc.).

Phaser.Struct.Set

**已被原生JavaScript

Set

替代。

iterateLocal

等方法已移除，请使用标准

Set

方法（

forEach

、

has

、

add

、

delete

等）。

Phaser.Struct.Map

**已被原生JavaScript

Map

替代。

contains

和

setAll

等方法已移除，请使用标准

Map

方法（

has

、

get

、

set

、

delete

等）。

16. Round Pixels

16. 像素取整

The

roundPixels

game config option now defaults to

false

(it was

true

in v3). The behavior has also been refined:

```
roundPixels
```
only operates when objects are axis-aligned and unscaled, preventing flicker on transforming objects.
For per-object control, use the new
```
GameObject#vertexRoundMode
```
property:
- ```
"off"
```
  -- Never round.
- ```
"safe"
```
  -- Round only when the transform is position-only (no scale/rotation).
- ```
"safeAuto"
```
  (default) -- Like
```
"safe"
```
  , but only when the camera has
```
roundPixels
```
  enabled.
- ```
"full"
```
  -- Always round (can cause wobble on rotated sprites, PS1-style).
- ```
"fullAuto"
```
  -- Like
```
"full"
```
  , but only when the camera has
```
roundPixels
```
  enabled.
The
```
TransformMatrix#setQuad
```
```
roundPixels
```
parameter has been removed.

游戏配置选项

roundPixels

现在默认值为

false

（v3中默认值为

true

），其行为也已优化：

```
roundPixels
```
仅在对象轴对齐且未缩放时生效，避免变换对象出现闪烁。
若需按对象控制，请使用全新的
```
GameObject#vertexRoundMode
```
属性：
- ```
"off"
```
  -- 从不取整。
- ```
"safe"
```
  -- 仅当变换仅涉及位置（无缩放/旋转）时取整。
- ```
"safeAuto"
```
  （默认） -- 与
```
"safe"
```
  类似，但仅在相机开启
```
roundPixels
```
  时生效。
- ```
"full"
```
  -- 始终取整（旋转精灵可能出现抖动，类似PS1风格）。
- ```
"fullAuto"
```
  -- 与
```
"full"
```
  类似，但仅在相机开启
```
roundPixels
```
  时生效。
```
TransformMatrix#setQuad
```
的
```
roundPixels
```
参数已移除。

17. Removed Game Objects

17. 已移除的游戏对象

Mesh
and
Plane
have been removed. These were limited 3D implementations; proper 3D support is planned for the future.

**
```
Mesh
```
和
```
Plane
```
**已被移除。这些是受限的3D实现；完整的3D支持计划在未来推出。

18. Removed Plugins and Entry Points

18. 已移除的插件与入口

The following have been completely removed:

Camera3D Plugin
Layer3D Plugin
Facebook Plugin detection constants
phaser-ie9.js
entry point (IE9 is no longer supported)

以下内容已完全移除：

Camera3D插件
Layer3D插件
Facebook插件检测常量
**
```
phaser-ie9.js
```
**入口（不再支持IE9）

19. Removed Utilities and Polyfills

19. 已移除的工具与Polyfill

Create.GenerateTexture
and all Create Palettes / the

create

folder have been removed.

TextureManager.generate

is also removed as a result.

Math.SinCosTableGenerator
has been removed.

All legacy polyfills removed:

```
Array.forEach
```
```
Array.isArray
```
```
AudioContextMonkeyPatch
```
```
console
```
```
Math.trunc
```
```
performance.now
```
```
requestAnimationFrame
```
```
Uint32Array
```

Modern browsers provide all of these natively.

Create.GenerateTexture

**及所有Create调色板/

create

文件夹已被移除。

TextureManager.generate

也随之移除。

Math.SinCosTableGenerator

**已被移除。

所有旧版Polyfill已移除：

```
Array.forEach
```
```
Array.isArray
```
```
AudioContextMonkeyPatch
```
```
console
```
```
Math.trunc
```
```
performance.now
```
```
requestAnimationFrame
```
```
Uint32Array
```

现代浏览器已原生支持所有这些功能。

20. Spine Plugins

20. Spine插件

The Spine 3 and Spine 4 plugins bundled with Phaser are no longer updated. Use the official Phaser Spine plugin created by Esoteric Software instead.

Phaser捆绑的Spine 3和Spine 4插件不再更新，请改用Esoteric Software官方推出的Phaser Spine插件。

21. Miscellaneous Breaking Changes

21. 其他破坏性变更

Shader#setTextures()
now replaces the texture array rather than adding to it. If you were calling it multiple times to build up textures, call it once with the full array.
DOMElement
now throws an error if it has no container. Ensure your DOM elements have a parent container.
GameObject#enableLighting
can now be set even if the scene light manager is not enabled. The manager must still be enabled for lights to render, but the flag itself is no longer gated.
Gamepad
Button
class now accepts an
```
isPressed
```
parameter to initialize state correctly across scene transitions.

BatchHandlerConfig#createOwnVertexBuffer
type property has been removed.

WebGLRenderer#genericVertexBuffer
and #genericVertexData
have been removed (freeing ~16MB RAM/VRAM).

**
```
Shader#setTextures()
```
**现在会替换纹理数组而非追加。若你此前多次调用该方法来构建纹理数组，请一次性传入完整数组调用一次。
**
```
DOMElement
```
**现在若没有容器会抛出错误，请确保你的DOM元素有父容器。
**
```
GameObject#enableLighting
```
**现在即使场景光照管理器未启用也可设置。光照仍需管理器启用才能渲染，但该标记本身不再受限制。
Gamepad
Button
类现在接收
```
isPressed
```
参数，以便在场景切换时正确初始化状态。

BatchHandlerConfig#createOwnVertexBuffer

**类型属性已移除。

WebGLRenderer#genericVertexBuffer

和

#genericVertexData

**已移除（释放约16MB内存/显存）。

Migration Checklist

迁移检查清单

Use this checklist to track your migration progress:

Update
```
npm install phaser@4
```
(or equivalent)
Replace any custom WebGL pipelines with render nodes
Replace
```
BitmapMask
```
usage with the
```
Mask
```
filter
Replace removed FX (
```
Bloom
```
,
```
Shine
```
,
```
Circle
```
,
```
Gradient
```
) with their Action/GameObject equivalents
Update
```
ColorMatrix
```
calls (methods moved to
```
.colorMatrix
```
property)

Replace any

setTintFill()

calls with

setTint().setTintMode(Phaser.TintModes.FILL)

Replace
```
Geom.Point
```
usage with
```
Vector2
```
Update
```
Math.TAU
```
usage (now equals PI * 2, not PI / 2)
Replace
```
Math.PI2
```
with
```
Math.TAU
```
Replace
```
Phaser.Struct.Set
```
with native
```
Set
```
Replace
```
Phaser.Struct.Map
```
with native
```
Map
```
Add
```
render()
```
calls to
```
DynamicTexture
```
/
```
RenderTexture
```
usage
Re-compress any compressed textures for new Y-axis orientation
Update any direct
```
Camera#matrix
```
access to use the new matrix system
Update
```
Shader
```
game objects to use new
```
ShaderQuadConfig
```
constructor
Update GLSL loading code (no fragment/vertex classification,
```
#pragma
```
directives)

Replace

sprite.setPipeline('Light2D')

with

sprite.setLighting(true)

Update light height code to use new
```
z
```
property
Remove any
```
TileSprite
```
texture cropping code
Update
```
Grid
```
shape code (
```
outline
```
properties renamed to
```
stroke
```
)
Remove any
```
Mesh
```
or
```
Plane
```
usage
Replace any Phaser-bundled Spine plugin usage with the official Esoteric Software plugin

Remove any reliance on

Create.GenerateTexture

TextureManager.generate

Test
```
roundPixels
```
behavior (now defaults to
```
false
```
)
Remove any usage of removed polyfills, plugins, or entry points
Verify custom shader texture coordinates (Y=0 is now at bottom)

使用此清单跟踪你的迁移进度：

更新依赖：
```
npm install phaser@4
```
（或对应包管理命令）
将所有自定义WebGL管线替换为RenderNode
将
```
BitmapMask
```
用法替换为
```
Mask
```
过滤器
将已移除的FX（
```
Bloom
```
、
```
Shine
```
、
```
Circle
```
、
```
Gradient
```
）替换为对应的Action/游戏对象
更新
```
ColorMatrix
```
调用（方法已移至
```
.colorMatrix
```
属性）

将所有

setTintFill()

调用替换为

setTint().setTintMode(Phaser.TintModes.FILL)

将
```
Geom.Point
```
用法替换为
```
Vector2
```
更新
```
Math.TAU
```
用法（现在等于PI * 2，而非PI / 2）
将
```
Math.PI2
```
替换为
```
Math.TAU
```
将
```
Phaser.Struct.Set
```
替换为原生
```
Set
```
将
```
Phaser.Struct.Map
```
替换为原生
```
Map
```
在
```
DynamicTexture
```
/
```
RenderTexture
```
用法中添加
```
render()
```
调用
重新压缩所有压缩纹理以适配新的Y轴方向
更新所有直接访问
```
Camera#matrix
```
的代码以适配新矩阵系统
更新
```
Shader
```
游戏对象以使用新的
```
ShaderQuadConfig
```
构造函数
更新GLSL加载代码（不再区分片段/顶点，使用
```
#pragma
```
指令）

将

sprite.setPipeline('Light2D')

替换为

sprite.setLighting(true)

更新光源高度代码以使用新的
```
z
```
属性
移除所有
```
TileSprite
```
纹理裁剪代码
更新
```
Grid
```
形状代码（
```
outline
```
属性已重命名为
```
stroke
```
）
移除所有
```
Mesh
```
或
```
Plane
```
用法
将所有Phaser捆绑的Spine插件用法替换为Esoteric Software官方插件

移除所有对

Create.GenerateTexture

或

TextureManager.generate

的依赖

测试
```
roundPixels
```
行为（现在默认值为
```
false
```
）
移除所有对已移除Polyfill、插件或入口的用法
验证自定义着色器的纹理坐标（Y=0现在位于底部）

v3-to-v4-migration

Original

Translation

Phaser v3 to v4 Migration Guide

Phaser v3 迁移至 v4 指南

Table of Contents

目录

1. Renderer: Pipelines to Render Nodes

1. 渲染器：从管线到RenderNode

2. Canvas Renderer Deprecated

2. Canvas渲染器已被弃用

3. FX and Masks are now Filters

3. FX与遮罩统一为过滤器

4. Tint System

4. 着色系统

5. Camera System

5. 相机系统

6. Texture Coordinates and GL Orientation

6. 纹理坐标与GL方向

7. DynamicTexture and RenderTexture

7. DynamicTexture与RenderTexture

8. Shader API

8. Shader API

9. GLSL Loading

9. GLSL加载

10. Lighting

10. 光照

11. TileSprite

11. TileSprite

12. Graphics and Shape

12. Graphics与Shape

13. Geometry: Point Replaced by Vector2

13. 几何：Point替换为Vector2

14. Math Constants

14. 数学常量

15. Data Structures

15. 数据结构

16. Round Pixels

16. 像素取整

17. Removed Game Objects

17. 已移除的游戏对象

18. Removed Plugins and Entry Points

18. 已移除的插件与入口

19. Removed Utilities and Polyfills

19. 已移除的工具与Polyfill

20. Spine Plugins

20. Spine插件

21. Miscellaneous Breaking Changes

21. 其他破坏性变更

Migration Checklist

迁移检查清单