Phaser 4 con Vite y TypeScript desde cero

Phaser 4 ya es una versión estable del framework y, si vas a comenzar un proyecto nuevo en 2026, tiene sentido combinarlo con un entorno moderno de desarrollo. En este tutorial vamos a crear una base con Phaser 4, Vite y TypeScript, entender qué hace cada herramienta y dejar una estructura preparada para crecer sin convertir el proyecto en un único archivo enorme.

Phaser 4.2.1 · Vite · TypeScript

Proyecto moderno con Phaser 4, TypeScript, Vite y recarga rápida durante el desarrollo.

★

Qué vamos a conseguir

Al final tendrás un proyecto Phaser ejecutándose con servidor de desarrollo, TypeScript, recarga rápida con Vite y una separación inicial entre escenas, sistemas, assets e interfaz.

Por qué Phaser 4 + Vite + TypeScript

Phaser sigue siendo una de las opciones más directas para crear juegos 2D que corren en el navegador. Phaser 4 conserva gran parte de la filosofía y de la API pública de Phaser 3, pero su renderer fue reescrito y la rama 4 incorpora sistemas gráficos más modernos.

Para un proyecto nuevo utilizaremos tres piezas:

Phaser 4 Motor 2D: escenas, input, sprites, cámaras, audio, animaciones, física y render.

TypeScript Tipado estático, autocompletado y errores detectados antes de ejecutar el juego.

Vite Servidor de desarrollo, módulos ES, HMR y generación del build de producción.

La idea importante es que Vite no sustituye a Phaser. Vite se ocupa del entorno de desarrollo y del empaquetado; Phaser sigue siendo el runtime del juego.

1. Crear el proyecto con la herramienta oficial

Phaser dispone de una herramienta oficial para crear proyectos. Desde una terminal ejecuta:

Terminal Crear proyecto

npm create @phaserjs/game@latest

El asistente te preguntará qué tipo de proyecto deseas crear. Para esta guía selecciona:

1. Web Bundler No necesitamos React, Vue ni otro framework para este ejemplo.
2. Vite Será nuestro servidor de desarrollo y bundler.
3. TypeScript Utilizaremos archivos .ts desde el inicio.
4. Nombre del proyecto Por ejemplo: phaser4-starter.

También puedes indicar directamente la carpeta:

Terminal Nombre de carpeta

npm create @phaserjs/game@latest phaser4-starter

2. Ejecutar el servidor de desarrollo

Entra en la carpeta del proyecto y ejecuta el script de desarrollo que incluye la plantilla:

Terminal Development server

cd phaser4-starter
npm install
npm run dev

Vite levantará un servidor local. La dirección suele parecerse a:

Vite Servidor local

Local: http://localhost:5173/

No abras el index.html directamente con doble clic. Utilizar un servidor local evita problemas con módulos, carga de recursos y políticas del navegador.

Ventaja de Vite

Cuando modificas TypeScript, CSS o partes del proyecto, Vite reconstruye rápidamente el módulo afectado. Esto reduce mucho el ciclo editar → guardar → probar.

3. Una estructura de carpetas que pueda crecer

Para un experimento de veinte líneas cualquier estructura funciona. El problema llega cuando aparecen menús, enemigos, audio, guardado, efectos y varias escenas.

Una estructura inicial razonable puede ser:

Proyecto Arquitectura sugerida

phaser4-starter/
│
├─ public/
│
├─ src/
│  ├─ assets/
│  │  ├─ images/
│  │  └─ audio/
│  │
│  ├─ scenes/
│  │  ├─ BootScene.ts
│  │  └─ MainScene.ts
│  │
│  ├─ systems/
│  │  └─ InputSystem.ts
│  │
│  ├─ ui/
│  │  └─ HUD.ts
│  │
│  └─ main.ts
│
├─ index.html
├─ package.json
├─ tsconfig.json
└─ vite.config.ts

Una estructura sencilla separa escenas, assets, sistemas e interfaz sin complicar demasiado el proyecto.

No es una regla obligatoria. La arquitectura debe crecer con el juego. Lo importante es evitar que MainScene.ts termine controlando absolutamente todo.

4. Crear nuestra primera Scene

Vamos a crear una escena completamente procedural. No necesitaremos imágenes externas: Phaser dibujará los elementos con objetos básicos. Esto permite validar que la instalación funciona antes de añadir assets.

Crea:

Archivo src/scenes/MainScene.ts

import Phaser from "phaser";

export class MainScene extends Phaser.Scene {
  constructor() {
    super("MainScene");
  }

  create() {
    this.cameras.main.setBackgroundColor("#071522");

    this.add
      .text(32, 28, "Phaser 4 + TypeScript", {
        fontFamily: "Arial",
        fontSize: "28px",
        color: "#ffffff"
      });

    // Jugador
    this.add.rectangle(
      190,
      300,
      48,
      64,
      0x22d3ee
    );

    // Enemigos
    const enemyPositions = [
      [470, 150],
      [600, 220],
      [520, 360],
      [700, 285]
    ];

    enemyPositions.forEach(([x, y]) => {
      this.add.rectangle(
        x,
        y,
        42,
        42,
        0xff8a1f
      );
    });

    this.add
      .text(32, 420, "El proyecto está funcionando.", {
        fontFamily: "Arial",
        fontSize: "20px",
        color: "#94a3b8"
      });
  }
}

5. Crear la configuración principal

Ahora abre src/main.ts. La configuración indica a Phaser cómo crear el juego y qué escena debe arrancar primero.

TypeScript src/main.ts

import Phaser from "phaser";
import { MainScene } from "./scenes/MainScene";

const config: Phaser.Types.Core.GameConfig = {
  type: Phaser.AUTO,

  width: 960,
  height: 540,

  backgroundColor: "#071522",

  parent: "game-container",

  scene: [
    MainScene
  ]
};

new Phaser.Game(config);

Phaser.AUTO permite que Phaser seleccione el renderer apropiado. El tamaño 960 × 540 es nuestra resolución lógica inicial; más adelante veremos cómo convertirla en un layout responsive.

6. El contenedor HTML

El valor:

Config parent

parent: "game-container"

indica que Phaser insertará su canvas dentro de un elemento HTML con ese identificador.

En index.html asegúrate de tener:

HTML index.html

<div id="game-container"></div>

7. ¿Dónde entran preload, create y update?

El ciclo clásico de una Scene continúa siendo uno de los conceptos fundamentales de Phaser:

preload()

• Carga imágenes.
• Carga audio.
• Carga atlas y JSON.
• Se ejecuta antes de crear la escena.

create()

• Crea objetos.
• Configura input.
• Construye el mundo.
• Se ejecuta una vez.

update()

• Se ejecuta durante el game loop.
• Actualiza gameplay.
• Lee input continuo.
• No debe llenarse de trabajo innecesario.

Systems

• Extraen lógica reutilizable.
• Reducen escenas gigantes.
• Facilitan test y mantenimiento.
• No hace falta crearlos demasiado pronto.

8. Añadir assets después de validar el proyecto

Una vez que el canvas aparece y el servidor funciona, entonces sí conviene comenzar a cargar sprites. Por ejemplo:

TypeScript preload()

preload() {
  this.load.image(
    "player",
    "assets/images/player.png"
  );
}

Y dentro de create():

TypeScript create()

create() {
  this.add.image(
    480,
    270,
    "player"
  );
}

Separar primero el problema de instalación del problema de los assets hace que depurar sea mucho más fácil. Si el canvas procedural funciona y una imagen no aparece después, ya sabes que el problema está en la ruta o en la carga del asset, no en Phaser o Vite.

9. Crear el build para producción

Durante el desarrollo utilizamos:

Terminal Desarrollo

npm run dev

Cuando quieras publicar el juego:

Terminal Producción

npm run build

Vite generará la versión optimizada para producción, normalmente dentro de dist/. Esa es la carpeta que después podrás desplegar en un servidor, GitHub Pages, itch.io o un portal compatible con juegos HTML5.

10. Errores comunes al empezar

No copies configuraciones antiguas sin comprobar la versión

Muchos tutoriales de Phaser que todavía aparecen en Google fueron escritos para Phaser 2 o versiones tempranas de Phaser 3. El concepto puede seguir siendo válido, pero imports, renderer, plugins y tooling pueden haber cambiado.

• Abrir index.html directamente: usa siempre el servidor de Vite durante desarrollo.
• Rutas incorrectas: revisa dónde viven realmente los assets.
• Una Scene gigante: extrae sistemas cuando la lógica empiece a crecer.
• Instalar muchas librerías desde el inicio: primero consigue un game loop funcionando.
• Ignorar TypeScript: evita abusar de any; el tipado es parte de la ventaja.

Qué tenemos hasta ahora

Con muy poco código ya tenemos una base moderna:

• Phaser 4 ejecutándose como motor del juego.
• TypeScript para escribir código con tipos.
• Vite como servidor y sistema de build.
• Una Scene independiente.
• Una estructura preparada para assets, sistemas y UI.
• Un build de producción listo para desplegar.

Siguiente tutorial

El siguiente paso será hacer que este canvas se adapte correctamente a móviles y escritorio sin deformar el juego. Ahí veremos resolución lógica, resize, relación de aspecto y HUD responsive.

Referencias oficiales

Phaser 4 Create Phaser Game

Este tutorial utiliza el flujo actual de Phaser 4 y está pensado como punto de partida para los próximos ejemplos del blog.