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