phaser-init

Phaser 4 Project Initialization

Scaffold a new Phaser 4 (v4.2.1) project with TypeScript and Vite.

Quick Scaffold (Recommended)

Use the official scaffolder for the fastest setup:

npm create @phaserjs/game@latest

This interactive CLI supports React, Vue, Angular, Svelte, Next.js, SolidJS, and plain TypeScript. For beginners: choose TypeScript + Vite when prompted.

After scaffolding, it installs phaser automatically. Run:

cd my-game
npm install
npm run dev

Manual Scaffold

Use this when the user needs a custom setup or wants to understand each piece.

Step 1 — Create Project

mkdir my-game && cd my-game
npm init -y
npm install phaser
npm install -D typescript vite @types/node

Step 2 — Directory Structure

Create this layout:

my-game/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── public/
│   └── assets/
│       ├── images/
│       ├── spritesheets/
│       ├── atlases/
│       ├── audio/
│       └── tilemaps/
└── src/
    ├── main.ts
    └── scenes/
        ├── BootScene.ts
        ├── PreloaderScene.ts
        └── GameScene.ts

Step 3 — Configuration Files

Generate these files exactly as shown in examples/:

• examples/game-config.ts — Complete main.ts with GameConfig
• examples/boot-scene.ts — BootScene starter template
• examples/vite-config.ts — Vite configuration for Phaser 4

Key configuration points:

package.json scripts:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  }
}

tsconfig.json critical fields:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "types": ["vite/client"]
  },
  "include": ["src"]
}

Phaser 4 ships its own types through the exports map in its package.json, so moduleResolution: "bundler" (or "node16"/"nodenext") resolves them from a plain import Phaser from 'phaser' with no extra configuration.

types: ["vite/client"] is separate and is needed: it types import.meta.env, which the mandatory __PHASER_GAME__ instrumentation line uses. Without it npx tsc --noEmit fails with TS2339: Property 'env' does not exist on type 'ImportMeta'.

Do not add typeRoots: ["./node_modules/phaser/types"] with types: ["Phaser"]. That was the Phaser 3 / early-v4-RC recipe. Against Phaser 4.2.1 it fails outright with TS2688: Cannot find type definition file for 'Phaser', because the shipped types are a single types/phaser.d.ts file rather than a Phaser/index.d.ts type-root package. If you inherited that config, delete both fields.

Step 4 — Verify Installation

npm run dev

Expected: browser opens at http://localhost:5173 showing a dark canvas (or whatever background color was set). If it shows a blank page, check the browser console for errors.

What to Do After Scaffolding

1. Replace GameScene.ts with actual game logic (use phaser-coder agent)
2. Add assets to public/assets/
3. Design the full scene flow (use phaser-architect agent)
4. Set arcade: { debug: false } when done debugging

Common Setup Mistakes

• Assets not loading: In Vite, assets must be in public/. Do NOT import them via import. Reference as 'assets/image.png' (relative to server root).
• TypeScript errors on Phaser.*: Import Phaser explicitly (import Phaser from 'phaser';) and use moduleResolution: "bundler". If tsconfig still carries typeRoots/types: ["Phaser"] from a v3-era template, remove them — they break the build on v4. See Step 3.
• phaser not found: Run npm install phaser. Do not use the beta tag — phaser@beta still resolves to 4.0.0-rc.7, which is older than the current stable release.
• Black screen: Check browser console for 404 errors or JS errors.

Additional Resources

Example Files

Working templates in examples/:

• examples/game-config.ts — Complete main.ts with scene registration
• examples/boot-scene.ts — BootScene with minimal asset loading
• examples/vite-config.ts — Vite config for Phaser 4

Reference Files

• references/project-templates.md — Complete file listings for TypeScript+Vite, JavaScript+Vite, and HTML-only setups
• references/template-archetypes.md — Full archetype specs for platformer, top-down RPG, space shooter, and match-3 puzzle games

Template Archetypes

When the user wants a specific type of game rather than a blank scaffold, generate a complete working game from an archetype. The phaser-coder agent uses the archetype specs to produce all files.

Available archetypes (use with /phaser-new [template] or trigger the phaser-coder agent):

Archetype	Command	Core Features
platformer	/phaser-new platformer	Gravity, jump, platforms, enemies, coins, lives system
topdown	/phaser-new topdown	Zero gravity, 8-dir movement, tilemap world, NPC dialog
shooter	/phaser-new shooter	Scrolling BG, bullet pooling, enemy waves, power-ups
puzzle	/phaser-new puzzle	Match-3 grid, tile swapping, cascade matching, score
towerdefense	/phaser-new towerdefense	Grid-based tower placement, enemy waves, economy, projectile pooling
runner	/phaser-new runner	Auto-scrolling, jump/slide, procedural obstacles, parallax, increasing speed
cardgame	/phaser-new cardgame	Memory match cards, flip animations, pair matching, move scoring
fighting	/phaser-new fighting	State machine fighters, 2-player local, hitbox system, round-based
racing	/phaser-new racing	Top-down rotation steering, tilemap track, checkpoints, AI opponents

All archetypes generate with placeholder assets (solid-color rectangles/circles via Graphics.generateTexture()) so the game runs immediately without real art. Replace with real assets when ready.

Archetype specifications: references/template-archetypes.md