Build 2D games with Phaser 3 framework. Covers scene lifecycle, sprites, physics (Arcade/Matter), tilemaps, animations, input handling, and game architecture. Trigger: "create phaser game", "add phaser scene", "phaser sprite", "phaser physics", "game development with phaser".

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 writing code, think architecturally. Before building, ask : What scenes does this game need? (Boot, Menu, Game, Pause, GameOver) What entities exist and how do they interact? What state must persist across scenes? What physics model fits? (Arcade for speed, Matter for realism) What input methods will players use? Core principles : 1. Scene First Architecture : Structure games around scenes, not global state 2. Composition Over Inheritance : Build entities from game objects and components 3. Physics Aware Design : Choose physics system before coding collisions 4. Asset Pipeline Discipline : Preload everything, reference by key 5. Frame Rate Independence : Use delta time, not frame counting Game Configuration Every Phaser game starts with a configuration object. Minimal Configuration Full Configuration Pattern Physics System Choice System Use When Arcade Platformers, shooters, most 2D games. Fast, simple AABB collisions Matter Physics puzzles, ragdolls, realistic collisions. Slower, more accurate None Menu scenes, visual novels, card games Scene Architecture Scenes are the fundamental organizational unit. Each scene has a lifecycle. Scene Lifecycle Methods Scene Transitions Recommended Scene Structure Game Objects Everything visible in Phaser is a Game Object. Common Game Objects Sprite Creation Patterns Physics Systems Arcade Physics (Recommended Default) Fast, simple physics for most 2D games. Physics Groups Matter Physics For realistic physics simulations. Input Handling Keyboard Input Pointer/Mouse Input Animations Creating Animations Playing Animations Asset Loading Preload Patterns Boot Scene Pattern Tilemaps (Tiled Integration) Loading and Creating Object Layers Project Structure Recommended Organization ES Module Setup Anti Patterns to Avoid ❌ Global State Soup : Storing game state on window or module globals Why bad : Untrackable bugs, scene transitions break state Better : Use scene data, registries, or dedicated state managers ❌ Loading in Create : Loading assets in create() instead of preload() Why bad : Assets may not be ready when referenced Better : Always load in preload() , use Boot scene for all assets ❌ Frame Dependent Logic : Using frame count instead of delta time Why bad : Game speed varies with frame rate Better : this.speed (delta / 1000) for consistent movement ❌ Physics Overkill : Using Matter for simple platformer collisions Why bad : Performance hit, unnecessary complexity Better : Arcade physics handles 90% of 2D game needs ❌ Monolithic Scenes : One giant scene with all game logic Why bad : Unmaintainable, hard to add features Better : Separate scenes for menus, gameplay, UI overlays ❌ Magic Numbers : Hardcoded values scattered in code Why bad : Impossible to balance, inconsistent Better : Config objects, constants files ❌ Ignoring Object Pooling : Creating/destroying objects every frame Why bad : Memory churn, garbage collection stutters Better : Use groups with setActive(false) / setVisible(false) ❌ Synchronous Asset Access : Assuming assets load instantly Why bad : Race conditions, undefined textures Better : Chain scene starts, use load events ❌ Assuming Spritesheet Frame Dimensions : Using guessed frame sizes without verifying 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 : Stretching a cropped ribbon/banner row that contains internal transparent gaps Why bad : The transparent gutters get stretched, so the UI looks segmented or the fill disappears behind the frame. Better : Slice the asset into caps/center, stretch only the center, and stitch the pieces (with ~1px overlap + smoothing disabled) before rendering at pivot sizes. Variation Guidance IMPORTANT : Game implementations should vary based on: Game Genre : Platformer physics differ from top down shooter physics Target Platform : Mobile needs touch input, desktop can use keyboard Art Style : Pixel art uses nearest neighbor scaling, HD art uses linear Performance Needs : Many sprites → object pooling; few sprites → simple creation Complexity : Simple games can inline; complex games need class hierarchies Avoid converging on : Always using 800x600 resolution Always using Arcade physics Always using the same scene structure Copy pasting boilerplate without adaptation Quick Reference Common Physics Properties Useful Scene Properties Essential Events See Also references/arcade physics.md Deep dive into Arcade physics references/tilemaps.md Advanced tilemap techniques references/performance.md Optimization strategies references/spritesheets nineslice.md Spritesheet loading (spacing/margin), nine slice UI panels, asset inspection Remember Phaser gives you powerful primitives—scenes, sprites, physics, input—but architecture is your responsibility . Think in systems: What scenes do you need? What entities exist? How do they interact? Answer these questions before writing code, and your game will be maintainable as it grows. Claude is capable of building complete, polished Phaser games. These guidelines illuminate the path—they don't fence it.

phaser-gamedev