Phaser 4 is the biggest release in the framework's history, and if you have an existing Phaser 3 project, upgrading is absolutely worth it. A completely rebuilt renderer, a unified filter system, new high-performance game objects, and a significantly improved lighting model are all waiting on the other side. The question is: how much work is the migration?

For most games using the standard Phaser API, less than you might expect. If your game uses sprites, text, tilemaps, and standard Phaser objects, you are probably looking at a few hours of work. If your project has custom WebGL pipelines or shaders, plan for more. Either way, here is a clear picture of what the process looks like from start to finish.

Step 1: Update Phaser and take stock

Start by updating to Phaser 4 and running your game. The errors that appear are your migration to-do list. Before diving into fixes, it is worth scanning that list with this guide open alongside it: most of the work is mechanical and predictable once you know what to look for. A project that only uses the standard API might clear all its errors in an afternoon. A project with custom rendering code will need more time, but the new architecture is cleaner, and the rewrite pays off.

​

Step 2: Deal with the renderer first

The entire WebGL rendering pipeline from v3 has been replaced. This is the biggest change in Phaser 4, but for most developers it is also completely invisible. If your game uses standard Phaser objects like sprites, text, and tilemaps, the new renderer works transparently and you can move straight to the next step.

If you wrote custom WebGL pipelines in v3, those will need to be rewritten as render nodes. The new architecture is cleaner and more predictable than v3 pipelines, so the rewrite is worthwhile. The migration guide has the full details on how render nodes work and how to register them at boot.

​

Step 3: Update your FX and masks to filters

In v3, FX and masks were two separate systems with restrictions on which objects could use them. In Phaser 4 they are unified into a single filter system that works on any game object or camera.

The most common changes you will need to make: Bloom, Shine, and Circle FX have been replaced by Actions you call on a target object. Gradient FX has become a proper Gradient game object. BitmapMask is gone, replaced by the new Mask filter. If your project used any of these, each one has a direct v4 replacement.

Step 4: Update your tint, lighting, and camera code

Three APIs have been cleaned up in ways that will show up as errors in most projects:

  • Tinting: setTintFill() has been removed. You now use setTint() combined with setTintMode() to control how colors blend. The new system gives you more control with six available blend modes.
  • Lighting: Enabling lighting on a sprite in v3 meant assigning a pipeline. In v4 it is a single method call: setLighting(true). If your project sets light heights, those also need updating to use the new explicit z value.
  • Camera: If your game only uses standard camera properties like scroll, zoom, and rotation, nothing changes. If you access camera matrices directly, the matrix system has been restructured and you will need to update those references.

Step 5: Replace the smaller APIs

A handful of smaller APIs have changed that are quick to fix once you know about them:

  • Geom.Point is gone. Every method has a direct replacement in Vector2. It is a straightforward find-and-replace across your codebase.
  • Math.TAU has been corrected. In v3 it was incorrectly set to PI / 2. In v4 it is the correct PI * 2. If you used Math.TAU expecting PI / 2, replace it with the new Math.PI_OVER_2 constant.
  • Native data structures. Phaser.Struct.Set and Phaser.Struct.Map have been replaced with native JavaScript Set and Map. Custom methods are gone, replaced by standard JavaScript equivalents.
  • DynamicTexture now requires render(). Drawing commands are no longer executed immediately. If your textures are coming out blank, this is likely why.

Step 6: Check what has been removed entirely

A few things are gone with no direct replacement: the Mesh and Plane game objects, the Camera3D and Layer3D plugins, and IE9 support. The Spine 3 and Spine 4 plugins bundled with Phaser are also no longer updated, so if you use Spine you should switch to the official plugin from Esoteric Software.

This step is worth doing before you start the migration, not after. If your project depends on any of these, it changes the scope of the work significantly.

​

Step 7: Test, verify, and you are done

Once you have worked through the list above, run your game end to end. Two specific things worth checking before you call it done: roundPixels now defaults to false in v4, so if your game relied on that behavior set it explicitly in your game config. And if you use compressed textures, those need to be re-compressed for the new Y-axis orientation Phaser 4 uses internally.

If everything runs cleanly, you are on Phaser 4. From here, the new features are yours to explore.

Ready to dive into the details?

This guide gives you the full picture of what the migration involves. For the technical details of each change, including before and after code examples and a complete checklist, the official migration guide has everything you need.

​Read the full migration guide in the Phaser docs​