phaser-gamedev

Phaser Game Development

Build fast, polished 2D browser games using Phaser 3’s scene-based architecture and physics systems.

Philosophy: Games as Living Systems

Games are not static UIs—they are dynamic systems where entities interact, state evolves, and player input drives everything.

Before building, ask:

• What scenes does this game need? (Boot, Menu, Game, Pause, GameOver, UI overlay)
• What are the core entities and how do they interact?
• What state must persist across scenes (and what must not)?
• What physics model fits? (Arcade for speed, Matter for realism)
• What input methods will players use? (keyboard/gamepad/touch)

Core principles:

1. Scene-first architecture: Organize code around scene lifecycle and transitions.
2. Composition over inheritance: Build entities from sprite/body/controllers, not deep class trees.
3. Physics-aware design: Choose collision model early; don’t retrofit physics late.
4. Asset pipeline discipline: Preload everything; reference by keys; keep loading deterministic.
5. Frame-rate independence: Use delta for motion and timers; avoid frame counting.

Workflow: Build the Spine First

• Define the minimal playable loop (movement + win/lose + restart) before content/polish.
• Decide scene graph and transitions (including UI overlay scene if needed).
• Choose physics system early:
  • Arcade for most games (platformers/top-down/shooters).
  • Matter for realistic collision/constraints/ragdolls.
  • None for non-physics scenes (menus, VN, card games).
• Implement a reliable asset-loading path (Boot scene), then scale out content.
• Add debug toggles/profiling early so performance doesn’t become a late surprise.

Use References (Progressive Disclosure)

• references/core-patterns.md: config, scene lifecycle, objects, input, animations, asset loading, project structure.
• references/arcade-physics.md: Arcade physics deep dive (including pooling patterns).
• references/tilemaps.md: Tiled tilemap workflows, collision setup, object layers.
• references/performance.md: optimization strategies (pooling, batching, culling, camera, texture atlases).
• references/spritesheets-nineslice.md: spritesheet loading (spacing/margin), nine-slice UI panels, asset inspection protocol.

Anti-Patterns to Avoid

❌ Global state soup: Storing game state on window or module globals
Why bad: scene transitions become fragile; debugging becomes chaotic
Better: scene data, registries, or a dedicated state manager

❌ Loading in create(): Loading assets in create() instead of preload()
Why bad: assets may not be ready when referenced
Better: load in preload(); use a Boot scene for all assets

❌ Frame-dependent logic: Using frame count instead of delta
Why bad: game speed varies with frame rate
Better: scale by (delta / 1000) for consistent movement/timers

❌ Physics overkill: Using Matter for simple platformer collisions
Why bad: unnecessary complexity + perf cost
Better: Arcade covers most 2D collision needs

❌ Monolithic scenes: One giant scene with all game logic
Why bad: hard to extend; UI/menus/pause become hacks
Better: separate gameplay vs UI overlay vs menus

❌ Magic numbers everywhere: Hardcoded tuning values scattered in code
Why bad: balancing becomes painful; changes cause regressions
Better: config objects/constants and centralized tuning

❌ No pooling for spammy objects: Creating/destroying bullets/particles constantly Why bad: GC spikes → stutters Better: object pooling with groups + setActive(false) / setVisible(false)

❌ Assuming spritesheet frame dimensions: Using guessed frame sizes without verifying source asset Why bad: wrong dimensions cause silent frame corruption; off-by-pixels compounds into broken visuals Better: open asset file, measure frames, calculate with spacing/margin, verify math adds up

❌ Ignoring spritesheet spacing: Not specifying spacing for gapped spritesheets Why bad: frames shift progressively; later frames read wrong pixel regions Better: check source asset for gaps between frames; use spacing: N in loader config

❌ Hardcoding nine-slice colors: Using single background color for all UI panel variants Why bad: transparent frame edges reveal wrong color for different asset color schemes Better: per-asset background color config; sample from center frame (frame 4)

❌ Nine-slice with padded frames: Treating the full frame as the slice region when the art is centered/padded inside each tile Why bad: edge tiles contribute interior fill, showing up as opaque “side bars” inside the panel Better: trim tiles to their effective content bounds (alpha bbox) and composite/cache a texture; add ~1px overlap + disable smoothing to avoid seams

❌ Scaling discontinuous UI art: Scaling a cropped banner/ribbon row that contains internal transparent gaps Why bad: the transparent gutters scale too, making the UI look “broken” or segmented Better: slice into left/center/right (or similar), stretch only the center, and stitch into a cached texture at the target size

Variation Guidance

Outputs should vary based on:

• Genre (platformer vs top-down vs shmup changes physics/input/camera)
• Target platform (mobile touch, desktop keyboard, gamepad support)
• Art style (pixel art scaling vs HD smoothing; atlas usage)
• Performance envelope (many sprites → pooling/culling; few sprites → simpler code)
• Team size / complexity (prototype vs production architecture)

Avoid converging on:

• One “default” resolution and scale mode
• Always defaulting to Arcade (or always defaulting to Matter)
• Copy-pasting boilerplate without adapting to the game’s needs

Remember

Phaser gives 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 is capable of building complete, polished Phaser games. These guidelines illuminate the path—they don't fence it.