/phaser-gamedev

name: phaser-gamedev
description: "Phaser 3 2D game dev: scenes, physics, tilemaps, sprites, polish."
agent: typescript-frontend-engineer
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
routing:
  triggers:
    - phaser
    - 2d game
    - platformer
    - arcade physics
    - tilemap
    - sprite sheet
    - side scroller
  pairs_with:
    - typescript-frontend-engineer
    - game-pipeline
  complexity: Medium
  category: game-development

Phaser Gamedev Skill

Overview

This skill builds complete Phaser 3 2D games using a **Phased Construction** pattern: DESIGN (plan game type, physics, scenes) → BUILD (scene lifecycle, sprites, tilemaps) → ANIMATE (physics, animation state machines, input) → POLISH (camera effects, particles, tweens, sound, mobile). Targets Phaser 3.60+ throughout.

**Scope**: Platformers, arcade shooters, top-down RPGs, puzzle games, and side-scrollers — anything 2D in Phaser 3. Use `threejs-builder` for 3D games, native mobile games, and non-Phaser canvas work.

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | `references/core-patterns.md` | `core-patterns.md` | Always | | `references/build-scaffolds.md` | `build-scaffolds.md` | Phase 2 BUILD | | `references/animate-scaffolds.md` | `animate-scaffolds.md` | Phase 3 ANIMATE | | `references/polish-scaffolds.md` | `polish-scaffolds.md` | Phase 4 POLISH | | `references/errors.md` | `errors.md` | Error Handling | | `references/arcade-physics.md` | `arcade-physics.md` | Arcade physics | | `references/tilemaps.md` | `tilemaps.md` | Tilemap / Tiled | | `references/spritesheets.md` | `spritesheets.md` | Sprites / animation | | `references/performance.md` | `performance.md` | Performance concern | | Frame rate must reach a target number | `hill-climb` skill | Measured baseline, profile, accept/revert loop on p1-low FPS | | `references/game-feel-patterns.md` | `game-feel-patterns.md` | Polish / juice signal | | `references/tilemaps-and-physics.md` | `tilemaps-and-physics.md` | Complex maps / Matter.js |

Instructions

Phase 1: DESIGN

**Goal**: Understand what to build, select the physics system, and plan the scene graph before writing any code.

**Core constraints**:

• **Read repository CLAUDE.md before building** — local standards override defaults here
• **Select physics system before any other decision** — Arcade (fast AABB), Matter.js (complex shapes), or no physics cannot be mixed per scene without deliberate design
• **Plan scenes upfront** — Boot → Preload → Game → UI is the standard flow; diverge only when the game requires it

**Step 1: Identify the game type**

From the user's request, determine: game genre (platformer, shooter, RPG, puzzle, side-scroller), primary physics need, number of scenes, tilemap or procedural world, spritesheet or texture atlas.

**Step 2: Select the physics system**

| Physics | Use When | When Not to Use | |---------|----------|------------| | Arcade | Platformers, shooters, simple AABB | Rotating bodies, non-rectangular shapes | | Matter.js | Physics puzzles, destructible terrain | Performance-critical (100+ bodies) | | None | Puzzles, card games, UI-only | Any meaningful collision detection |

**Step 3: Document the scene plan and load references**

Write a short markdown scene plan covering: Boot, Game, UI, Physics choice, World, Sprites (measured frame dimensions).

Load these references based on the plan:

• Always: `references/core-patterns.md` (scene lifecycle, transitions, input)
• If tilemap: `references/tilemaps.md`
• If sprites/animation: `references/spritesheets.md`
• If Arcade physics: `references/arcade-physics.md`
• If performance concern or many moving objects: `references/performance.md`
• If polish / game feel / juice signal ("screen shake", "particles", "game feel", "hit feedback", "satisfying"): `references/game-feel-patterns.md`
• If Matter.js, slopes, object layers, complex collision, or enemy spawning from Tiled: `references/tilemaps-and-physics.md`

**Gate**: Scene plan documented. Physics system selected. References loaded. Proceed only when gate passes.

---

Phase 2: BUILD

**Goal**: Implement the scene lifecycle skeleton, load assets, place sprites, wire up tilemaps.

**Core constraints**:

• **MEASURE spritesheet frames before loading** — wrong `frameWidth`/`frameHeight` is the #1 Phaser bug; open the PNG, count pixels per frame before writing `this.load.spritesheet()`
• **Preload all assets in `preload()`** — never load assets in `create()` or `update()`
• **Use a Boot scene for asset loading** — shows a progress bar, keeps Game scene clean

Full TypeScript scaffolds (entry point, BootScene with progress bar, GameScene skeleton): `references/build-scaffolds.md`.

**Gate**: Boot and Game scenes compile. Assets load without console errors. Scene transitions work. Proceed only when gate passes.

---

Phase 3: ANIMATE

**Goal**: Add physics-driven movement, animation state machines, and player input.

**Core constraints**:

• **Never allocate objects in `update()`** — no `new Phaser.Math.Vector2()`, no `this.physics.add.sprite()`, no array creation per frame; allocate in `create()`, reuse in `update()`
• **Use `delta` for frame-rate-independent movement** — `velocity = speed * (delta / 1000)` ensures consistent feel at any FPS
• **State machine over boolean flags** — `'idle' | 'walk' | 'jump' | 'attack' | 'dead'` prevents impossible states like `isJumping && isAttacking`

Animation definitions (`anims.create`), the Player state machine, and input handling scaffolds: `references/animate-scaffolds.md`. Collision groups, overlap callbacks, and physics tuning: `references/arcade-physics.md`.

**Gate**: Player moves. Animations transition correctly. State machine has no impossible state combinations. No per-frame allocations. Proceed only when gate passes.

---

Phase 4: POLISH

**Goal**: Add camera work, particles, tweens, sound, and mobile controls. V