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

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

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