Phaser Game Development
Build 2D browser games using Phaser 3's scene-based architecture and physics systems.
STOP: Before Loading Any Spritesheet
Read spritesheets-nineslice.md FIRST.
Spritesheet loading is fragile—a few pixels off causes silent corruption that compounds into broken visuals. The reference file contains the mandatory inspection protocol.
Quick rules (details in reference):
- Measure the asset before writing loader code—never guess frame dimensions
- Character sprites use SQUARE frames: If you calculate frameWidth=56, try 56 for height first
- Different animations have different frame sizes: A run cycle needs wider frames than idle; an attack needs extra width for weapon swing. Measure EACH spritesheet independently
- Check for spacing: Gaps between frames require
spacing: N in loader config
- Verify the math:
imageWidth = (frameWidth × cols) + (spacing × (cols - 1))
Reference Files
Read these BEFORE working on the relevant feature:
| When working on... |
Read first |
| Loading ANY spritesheet |
spritesheets-nineslice.md |
| Nine-slice UI panels |
spritesheets-nineslice.md |
| Config, scenes, objects, input, animations |
core-patterns.md |
| Tiled tilemaps, collision layers |
tilemaps.md |
| Physics tuning, groups, pooling |
arcade-physics.md |
| Performance issues, object pooling |
performance.md |
Architecture Decisions (Make Early)
Before building, decide:
- What scenes does this game need? (Boot, Menu, Game, UI overlay, GameOver)
- What are the core entities and how do they interact?
- What physics model fits? (Arcade for speed, Matter for realism, None for menus)
- What input methods? (keyboard/gamepad/touch)
Physics System Choice
| System |
Use When |
| Arcade |
Platformers, shooters, most 2D games. Fast AABB collisions |
| Matter |
Physics puzzles, ragdolls, realistic collisions. Slower, more accurate |
| None |
Menu scenes, visual novels, card games |
Core Principles
- Scene-first architecture: Organize code around scene lifecycle and transitions
- Composition over inheritance: Build entities from sprite/body/controllers, not deep class trees
- Physics-aware design: Choose collision model early; don't retrofit physics late
- Asset pipeline discipline: Preload everything; reference by keys; keep loading deterministic
- Frame-rate independence: Use
delta for motion and timers; avoid frame counting
Anti-Patterns
| Anti-Pattern |
Problem |
Solution |
Global state on window |
Scene transitions break state |
Use scene data, registries |
Loading in create() |
Assets not ready when referenced |
Load in preload(), use Boot scene |
| Frame counting |
Game speed varies with FPS |
Use delta / 1000 |
| Matter for simple collisions |
Unnecessary complexity |
Arcade handles most 2D games |
| One giant scene |
Hard to extend |
Separate gameplay/UI/menus |
| Magic numbers |
Impossible to balance |
Config objects, constants |
| No object pooling |
GC stutters |
Groups with setActive(false) |
Variation Guidance
Outputs should vary based on:
- Genre (platformer vs top-down vs shmup)
- Target platform (mobile touch, desktop keyboard, gamepad)
- Art style (pixel art scaling vs HD smoothing)
- Performance envelope (many sprites → pooling; few sprites → simpler code)
Remember
Phaser provides powerful primitives—scenes, sprites, physics, input—but architecture is your responsibility.
Think in systems: define the scenes, define the entities, define their interactions—then implement.
Codex can build complete, polished Phaser games. These guidelines illuminate the path—they don't fence it.
1---2name: phaser-gamedev3description: Build 2D browser games with Phaser 3 (JS/TS): scenes, sprites, physics (Arcade/Matter), tilemaps (Tiled), animations, input. Trigger: 'Phaser scene', 'Arcade physics', 'tilemap', 'Phaser 3 game'.4---5
6# Phaser Game Development
7
8Build 2D browser games using Phaser 3's scene-based architecture and physics systems.
9
10---
11
12## STOP: Before Loading Any Spritesheet
13
14**Read [spritesheets-nineslice.md](references/spritesheets-nineslice.md) FIRST.**
15
16Spritesheet loading is fragile—a few pixels off causes silent corruption that compounds into broken visuals. The reference file contains the mandatory inspection protocol.
17
18**Quick rules** (details in reference):
19
201. **Measure the asset** before writing loader code—never guess frame dimensions
212. **Character sprites use SQUARE frames**: If you calculate frameWidth=56, try 56 for height first
223. **Different animations have different frame sizes**: A run cycle needs wider frames than idle; an attack needs extra width for weapon swing. Measure EACH spritesheet independently
234. **Check for spacing**: Gaps between frames require `spacing: N` in loader config
245. **Verify the math**: `imageWidth = (frameWidth × cols) + (spacing × (cols - 1))`
25
26---
27
28## Reference Files
29
30Read these BEFORE working on the relevant feature:
31
32| When working on... | Read first |
33|--------------------|------------|
34| Loading ANY spritesheet | [spritesheets-nineslice.md](references/spritesheets-nineslice.md) |
35| Nine-slice UI panels | [spritesheets-nineslice.md](references/spritesheets-nineslice.md) |
36| Config, scenes, objects, input, animations | [core-patterns.md](references/core-patterns.md) |
37| Tiled tilemaps, collision layers | [tilemaps.md](references/tilemaps.md) |
38| Physics tuning, groups, pooling | [arcade-physics.md](references/arcade-physics.md) |
39| Performance issues, object pooling | [performance.md](references/performance.md) |
40
41---
42
43## Architecture Decisions (Make Early)
44
45**Before building, decide**:
46- What **scenes** does this game need? (Boot, Menu, Game, UI overlay, GameOver)
47- What are the **core entities** and how do they interact?
48- What **physics** model fits? (Arcade for speed, Matter for realism, None for menus)
49- What **input methods**? (keyboard/gamepad/touch)
50
51### Physics System Choice
52
53| System | Use When |
54|--------|----------|
55| **Arcade** | Platformers, shooters, most 2D games. Fast AABB collisions |
56| **Matter** | Physics puzzles, ragdolls, realistic collisions. Slower, more accurate |
57| **None** | Menu scenes, visual novels, card games |
58
59---
60
61## Core Principles
62
631. **Scene-first architecture**: Organize code around scene lifecycle and transitions
642. **Composition over inheritance**: Build entities from sprite/body/controllers, not deep class trees
653. **Physics-aware design**: Choose collision model early; don't retrofit physics late
664. **Asset pipeline discipline**: Preload everything; reference by keys; keep loading deterministic
675. **Frame-rate independence**: Use `delta` for motion and timers; avoid frame counting
68
69---
70
71## Anti-Patterns
72
73| Anti-Pattern | Problem | Solution |
74|--------------|---------|----------|
75| Global state on `window` | Scene transitions break state | Use scene data, registries |
76| Loading in `create()` | Assets not ready when referenced | Load in `preload()`, use Boot scene |
77| Frame counting | Game speed varies with FPS | Use `delta / 1000` |
78| Matter for simple collisions | Unnecessary complexity | Arcade handles most 2D games |
79| One giant scene | Hard to extend | Separate gameplay/UI/menus |
80| Magic numbers | Impossible to balance | Config objects, constants |
81| No object pooling | GC stutters | Groups with `setActive(false)` |
82
83---
84
85## Variation Guidance
86
87Outputs should vary based on:
88- **Genre** (platformer vs top-down vs shmup)
89- **Target platform** (mobile touch, desktop keyboard, gamepad)
90- **Art style** (pixel art scaling vs HD smoothing)
91- **Performance envelope** (many sprites → pooling; few sprites → simpler code)
92
93---
94
95## Remember
96
97Phaser provides powerful primitives—scenes, sprites, physics, input—but **architecture is your responsibility**.
98
99Think in systems: define the scenes, define the entities, define their interactions—then implement.
100
101**Codex can build complete, polished Phaser games. These guidelines illuminate the path—they don't fence it.**
gabrielmoreira