/v3-to-v4-migration

name: v3-to-v4-migration
description: "Use this skill when migrating a Phaser 3 project to Phaser 4, or when a user asks about breaking changes, API differences, or how to update their v3 code. Covers renderer changes (pipelines to render nodes), FX/masks to filters, tint system, camera matrix, texture coordinates, DynamicTexture, shaders, lighting, removed game objects, and a full migration checklist. Triggers on: migrate, upgrade, v3 to v4, breaking changes, Phaser 3 to 4, migration guide, update from v3."

Phaser v3 to v4 Migration Guide

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

---

Table of Contents

1. [Renderer: Pipelines to Render Nodes](#1-renderer-pipelines-to-render-nodes) 2. [Canvas Renderer Deprecated](#2-canvas-renderer-deprecated) 3. [FX and Masks are now Filters](#3-fx-and-masks-are-now-filters) 4. [Tint System](#4-tint-system) 5. [Camera System](#5-camera-system) 6. [Texture Coordinates and GL Orientation](#6-texture-coordinates-and-gl-orientation) 7. [DynamicTexture and RenderTexture](#7-dynamictexture-and-rendertexture) 8. [Shader API](#8-shader-api) 9. [GLSL Loading](#9-glsl-loading) 10. [Lighting](#10-lighting) 11. [TileSprite](#11-tilesprite) 12. [Graphics and Shape](#12-graphics-and-shape) 13. [Geometry: Point Replaced by Vector2](#13-geometry-point-replaced-by-vector2) 14. [Math Constants](#14-math-constants) 15. [Data Structures](#15-data-structures) 16. [Round Pixels](#16-round-pixels) 17. [Removed Game Objects](#17-removed-game-objects) 18. [Removed Plugins and Entry Points](#18-removed-plugins-and-entry-points) 19. [Removed Utilities and Polyfills](#19-removed-utilities-and-polyfills) 20. [Spine Plugins](#20-spine-plugins) 21. [Miscellaneous Breaking Changes](#21-miscellaneous-breaking-changes) 22. [Migration Checklist](#migration-checklist)

---

1. Renderer: Pipelines to Render Nodes

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.

---

2. Canvas Renderer Deprecated

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.

---

3. FX and Masks are now Filters

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