phaser-gamedev

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. Verify performance.

Core constraints:

• Remove debug: true from physics config before shipping
• Remove all console.log calls unless the user explicitly requested logging
• Test on a 60 FPS budget — Arcade + 200 active bodies + 50 particles is the practical ceiling on mid-range mobile

Full scaffolds for camera effects, particles (Phaser 3.60+ API), tweens, sound, mobile virtual controls, and final verification steps: references/polish-scaffolds.md.

Gate: Polish checks pass. Performance within budget. Debug config removed. Game is shippable.

---

Error Handling

Common errors and fixes (spritesheet frame mismatches, undefined body access, tilemap collision no-ops, animation failures, mobile slowdowns): references/errors.md.

---

References

| Reference | When to Load | Content |

|-----------|-------------|---------|

| references/core-patterns.md | Always | Scene lifecycle, transitions, input, state machines |

| references/build-scaffolds.md | Phase 2 BUILD | TypeScript entry point, BootScene with progress bar, GameScene skeleton |

| references/animate-scaffolds.md | Phase 3 ANIMATE | Animation definitions, Player state machine, input handling |

| references/polish-scaffolds.md | Phase 4 POLISH | Camera, particles, tweens, sound, mobile controls, verification |

| references/errors.md | Error Handling | Common Phaser error scenarios and fixes |

| references/arcade-physics.md | Arcade physics | Groups, colliders, velocity, physics tuning, pitfalls |

| references/tilemaps.md | Tilemap / Tiled | Layer system, collision, animated tiles, object layers |

| references/spritesheets.md | Sprites / animation | Frame measurement, loading, atlases, nine-slice |

| references/performance.md | Performance concern | Object pooling, GC avoidance, texture atlases, mobile |

| references/game-feel-patterns.md | Polish / juice signal | Screen shake, particle bursts, hit-stop, scale punch, tween chains, sound timing |

| references/tilemaps-and-physics.md | Complex maps / Matter.js | Tiled integration pipeline, Matter.js vs Arcade decision table, collision categories, slopes, object layer spawning |