--- id: notque/vexjoy-agent/phaser-gamedev version: "dbf3cad6" license: MIT install: manual updated: 2026-07-25 --- # phaser-gamedev — Phaser Gamedev guides you through building complete 2D games in Phaser 3 using a structured four-phase approach: DESIGN (plan game type and physics), BUILD (implement scenes and assets), ANIMATE (add physics-driven movement and state machines), and POLISH (camera effects, particles, sound, and mobile support). Covers platformers, shooters, RPGs, and puzzle games with TypeScript scaffolds and reference guides for each phase. Publisher: notque · Stars: 412 · Updated: 2026-07-25 Install (manual): `git clone https://github.com/notque/vexjoy-agent` ## SKILL.md # 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 | | `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 | [View on SkillFed](https://skillfed.io/notque/vexjoy-agent/phaser-gamedev) · [View on GitHub](https://github.com/notque/vexjoy-agent)