Cómo migrar de Phaser 3 a Phaser 4

Migrar de Phaser 3 a Phaser 4 es bastante menos traumático de lo que parece si tu juego utiliza principalmente Sprites, Images, Text, Tilemaps, input, física, escenas y tweens. La mayor parte de la API pública se mantuvo muy parecida. Los cambios importantes aparecen cuando el proyecto toca el renderer, pipelines WebGL, FX, masks, tint, iluminación o algunas APIs que fueron eliminadas.

Phaser 3 → Phaser 4.2.1 · Migration Guide 2026

Phaser 4 conserva gran parte del flujo de trabajo de Phaser 3, pero cambia profundamente el renderer y los efectos gráficos.

✓

La buena noticia

Si tu juego usa principalmente objetos estándar de Phaser, la migración suele ser mucho más pequeña que una reescritura completa. El trabajo crece sobre todo cuando hay pipelines WebGL, shaders o integraciones avanzadas con el renderer.

¿Vale la pena migrar a Phaser 4?

Phaser 4 no es simplemente una actualización de versión. El renderer WebGL fue reconstruido y la arquitectura interna cambió bastante, pero el equipo de Phaser intentó mantener la API que utiliza la mayoría de desarrolladores lo más familiar posible.

Esto significa que muchos sistemas habituales continúan funcionando con pocos cambios:

Normalmente cambia poco Sprites, Images, Text, Groups, Scene management, input, audio, tweens y física Arcade/Matter.

Requiere revisión FX, masks, tint, iluminación, DynamicTexture, algunas constantes y estructuras auxiliares.

Requiere más trabajo Custom WebGL pipelines, shaders avanzados y código que accede directamente al renderer.

Antes de tocar código

No hagas la migración directamente sobre tu única copia del proyecto. Crea una rama o un backup y asegúrate de que la versión Phaser 3 funciona correctamente antes de empezar.

1. Crea una rama exclusiva para la migración

GitRama de migración

git checkout -b migrate/phaser-4

Antes de continuar, ejecuta el juego en Phaser 3 y revisa al menos:

• inicio y carga de assets;
• cambio entre escenas;
• input;
• física y colisiones;
• audio;
• efectos visuales;
• guardado;
• game over y reinicio.

2. Haz un inventario de las partes delicadas

Búsquedas útilesVS Code / IDE

setPipeline
PostFX
preFX
postFX
BitmapMask
setTintFill
Phaser.Geom.Point
Phaser.Struct.Set
Phaser.Struct.Map
Math.TAU
DynamicTexture

Si ninguna de esas piezas aparece y el proyecto usa objetos normales, probablemente estás ante una migración relativamente sencilla.

3. Actualiza Phaser

npmActualizar dependencia

npm install phaser@4.2.1

Después inicia el proyecto sin intentar corregir nada por adelantado:

TerminalEjecutar

npm run dev

Los errores que aparezcan ahora se convierten en tu lista real de migración. Es mejor trabajar desde errores concretos que modificar cientos de líneas “por si acaso”.

4. Corrige el import de Phaser si utilizas NPM

Phaser 3

AntesImport habitual

import Phaser from "phaser";

Phaser 4

DespuésWildcard import

import * as Phaser from "phaser";

Si cargas Phaser como variable global mediante CDN, este cambio concreto de import no aplica.

5. El renderer cambió por completo

Phaser 3 utilizaba un sistema basado en WebGL Pipelines. Phaser 4 lo reemplaza por una arquitectura basada en RenderNodes.

Phaser 3

• Pipelines WebGL personalizados.
• Más responsabilidad sobre el estado WebGL.
• Shaders y render custom muy ligados al pipeline.

Phaser 4

• Arquitectura mediante RenderNodes.
• Responsabilidades de render más separadas.
• Modelo más predecible para extensiones gráficas.

Si tu juego solo utiliza Sprite, Image, Text, Tilemap y otros objetos estándar, normalmente no necesitas reescribir nada por este cambio.

Proyecto con custom pipeline

Si escribiste un Pipeline WebGL propio en Phaser 3, trátalo como una subtarea independiente. Esa parte debe migrarse al nuevo sistema de render nodes / filtros, no limitarse a un cambio de nombres.

6. FX y Masks ahora usan el nuevo sistema de Filters

• BitmapMask: fue eliminado y su funcionalidad pasa al nuevo Mask Filter.
• Bloom: ahora puede crearse mediante Phaser.Actions.AddEffectBloom().
• Shine: ahora utiliza Phaser.Actions.AddEffectShine().
• Circle: puede migrarse mediante Phaser.Actions.AddMaskShape().
• Gradient: pasó a ser un Game Object propio.
• preFX / postFX: el modelo anterior fue sustituido por el nuevo sistema de filtros.

La mayor parte del gameplay continúa igual; renderer, pipelines, FX y algunas APIs auxiliares concentran la migración.

7. setTintFill() cambió

Phaser 3

AntesFill tint

player.setTintFill(0xff0000);

Phaser 4

DespuésTint + modo

player
  .setTint(0xff0000)
  .setTintMode(Phaser.TintModes.FILL);

Phaser 4 separa el color del modo y ofrece modos como MULTIPLY, FILL, ADD, SCREEN, OVERLAY y HARD_LIGHT.

8. La iluminación se activa de forma más directa

Phaser 3

AntesLighting pipeline

player.setPipeline("Light2D");

Phaser 4

DespuésLighting component

player.setLighting(true);

Si utilizas normal maps o iluminación personalizada, revisa esa escena completa y no solo una línea.

9. Phaser.Geom.Point desapareció

Phaser 3

AntesPoint

const target = new Phaser.Geom.Point(
  400,
  300
);

Phaser 4

DespuésVector2

const target = new Phaser.Math.Vector2(
  400,
  300
);

10. Math.TAU ahora tiene su valor matemático correcto

En Phaser 3, Math.TAU tenía un valor equivalente a PI / 2. En Phaser 4 representa correctamente una vuelta completa:

Phaser 4Constante

TAU = Math.PI * 2

Si tu código antiguo lo utilizaba esperando PI / 2, cambia a:

Phaser 4Cuarto de vuelta

Phaser.Math.PI_OVER_2

11. Phaser.Struct.Set y Phaser.Struct.Map → JavaScript nativo

Antes

Phaser 3Struct

const enemies = new Phaser.Struct.Set();
const items = new Phaser.Struct.Map();

Después

Phaser 4JavaScript nativo

const enemies = new Set();
const items = new Map();

Si utilizabas métodos específicos de las estructuras de Phaser, revisa sus equivalentes en Set y Map nativos.

12. DynamicTexture requiere render()

Si una textura dinámica aparece vacía después de migrar, revisa si falta ejecutar:

Phaser 4DynamicTexture

dynamicTexture.render();

13. Cámara: lo normal sigue funcionando

Scroll, zoom, rotation y follow suelen continuar sin cambios importantes. Si accedes directamente a matrices internas de cámara, sí debes revisar la implementación.

14. APIs que fueron eliminadas

• antiguos Game Objects Mesh y Plane;
• plugins Camera3D y Layer3D;
• soporte antiguo para IE9;
• plugins Spine incluidos antiguamente en Phaser ya no son el camino recomendado.

i

Mesh2D no es el viejo Mesh

Phaser 4.2 introdujo un nuevo Game Object Mesh2D, pero no debes asumir que sea un reemplazo compatible línea por línea con el Mesh eliminado de Phaser 3.

15. roundPixels cambió de valor por defecto

En Phaser 4 roundPixels es false por defecto. Si tu pixel art dependía de esa opción, haz la intención explícita:

ConfigSi lo necesitas

render: {
  roundPixels: true
}

16. Cuidado con compressed textures

Phaser 4 cambió la orientación interna de texturas para alinearse mejor con WebGL. Si utilizas texturas comprimidas, vuelve a generarlas para la orientación usada por Phaser 4.

17. Checklist de migración

1. Backup / branchParte de una versión Phaser 3 que sabes que funciona.
2. Actualiza la dependenciaInstala Phaser 4 y ejecuta antes de cambiar APIs al azar.
3. Corrige importsSi utilizas NPM, cambia default import por wildcard import.
4. Revisa renderer avanzadoPipelines y shaders personalizados son la parte de mayor riesgo.
5. Migra FX, masks y tintSon cambios localizados pero muy visibles.
6. Revisa APIs pequeñasVector2, TAU, Set, Map y DynamicTexture.
7. Busca elementos eliminadosHazlo antes de invertir horas en la migración.
8. Prueba el juego completoNo basta con que compile y muestre la primera Scene.

18. Qué probar después de que compile

Gameplay

• Input.
• Física.
• Colisiones.
• Tweens.
• Scenes.

Render

• FX.
• Masks.
• Tint.
• Luces.
• Texturas comprimidas.

Plataforma

• Chrome / Chromium.
• Firefox.
• Móvil real.
• Resize.
• Pérdida de foco.

Performance

• FPS.
• Frame time.
• Memoria.
• Carga inicial.
• Errores de consola.

¿Cuánto trabajo puede tomar?

Riesgo bajo Sprites, Text, Tilemaps, Arcade Physics, input, tweens y Scenes estándar.

Riesgo medio FX, masks, tint, DynamicTexture, iluminación y utilidades antiguas.

Riesgo alto Pipelines WebGL, shaders custom, plugins gráficos propios o APIs eliminadas.

La estrategia más práctica es actualizar, ejecutar y dejar que los errores reales te muestren la lista de trabajo.

Si empiezas un proyecto nuevo

Si no estás migrando un juego existente, arranca directamente con Phaser 4 y un entorno moderno.

Phaser 4 con Vite y TypeScript desde cero

Referencias oficiales

Guía oficial de migración Phaser 3 vs Phaser 4 Phaser 4

La clave es no tratar Phaser 4 como un framework completamente diferente. Migra primero lo que realmente rompió, prueba por bloques y deja renderer avanzado, shaders y efectos para una fase controlada.