phaser-best-practices

# Building Phaser Games

## When to use this skill

Use this skill when the user wants to:

- create a new Phaser 3 game or prototype
- add or refactor scenes, entities, UI, physics, tilemaps, input, audio, or cameras
- debug Phaser-specific behavior such as scene restarts, blurry pixel art, collider bugs, asset loading problems, or animation issues
- improve architecture, maintainability, or runtime performance in a Phaser project

Do not use this skill for non-Phaser engines unless the user explicitly wants Phaser-style patterns adapted elsewhere.

## How to operate

### 1. Triage the request

Classify the task before writing code:

- **New project**: scaffolding, folder layout, game config, first scenes
- **Feature work**: add gameplay, UI, audio, transitions, tilemaps, enemies, pickups
- **Bug fix**: isolate scene lifecycle, asset, physics, input, camera, or rendering failure
- **Optimization**: profile bottlenecks, pooling, culling, throttling, asset strategy
- **Art / asset pipeline**: spritesheet measurements, animation setup, nine-slice / three-slice UI, tilemap integration

### 2. Inspect first, then decide

When a repository already exists, inspect before proposing structure changes:

- package.json, bundler config, tsconfig/jsconfig
- Phaser version and whether the codebase is JS or TS
- game bootstrap, scene list, physics config, scale config
- asset folders and naming conventions
- current state-sharing approach (scene data, registry, services, globals)
- whether the project is pixel art, HD art, desktop-first, mobile-first, or mixed input

Prefer adapting to the existing codebase over replacing it with boilerplate.

### 3. Default technical choices

Use these defaults unless the task clearly calls for something else:

- Prefer the official **Vite + TypeScript** style setup for new projects
- Prefer **Arcade Physics** for platformers, shooters, top-down action, simple pickups, and lightweight collision logic
- Use **Matter Physics** only when the game needs rotation-driven collisions, compound bodies, constraints, stacking stability, or more realistic simulation
- Organize code around **Scenes first**, then entities / systems inside scenes
- Keep input **scene-owned**; entities should consume input state, not attach their own listeners
- Use **global animations** when multiple sprites share the same animation data
- Preload **startup-critical** assets up front; load level-specific assets later when it improves startup time
- Use built-in **NineSlice / ThreeSlice** for scalable UI art when the texture layout supports it; only fall back to custom compositing when transparent padding or discontinuous art breaks built-in slicing
- Use **FIT** scaling for most games, **RESIZE** for editor-like or UI-heavy layouts, and **NONE** only when manually controlling canvas sizing
- For pixel art, enable **pixelArt** mode, favor integer scaling where possible, and avoid sub-pixel camera movement

### 4. Output expectations

For **new games**, provide:

- the recommended folder structure
- a game config
- scene list and responsibilities
- starter code that runs
- notes on why each architectural choice fits the requested genre

For **feature work or bug fixes**, provide:

- minimal targeted edits
- root cause explanation
- the patch
- validation steps the user can run immediately

For **architecture advice**, provide:

- the smallest structure that solves the current problem
- one recommended path, not a menu of equally-weighted options
- explicit tradeoffs when the choice is important (for example Arcade vs Matter)

## Non-negotiable implementation rules

- Respect the project's existing JS vs TS choice unless the user asks to migrate
- Centralize scene keys, asset keys, collision categories, and balance constants
- Keep `update()` orchestration-focused; push detailed logic into entities or systems
- Register cleanup for scene shutdown / destroy when you attach listeners, timers, tweens, or long-lived references
- Avoid creating new objects inside hot `update()` loops unless profiling proves it is harmless
- Do not make every object interactive or physics-enabled by default
- Do not assume spritesheet frame dimensions; inspect and verify them
- Do not tell the user to use Matter when Arcade already solves the problem cleanly
- Do not preload the entire game into one Boot scene just because it is convenient

## Recommended delivery workflow

### New Phaser project

1. Pick the architecture size:
   - **Small / jam game**: 2-4 scenes, lightweight service modules
   - **Mid-size game**: scenes + entities + systems + constants
   - **Large content-heavy game**: data-driven content, scene services, dedicated state layer
2. Define the base config: renderer, scale mode, physics, pixel-art settings
3. Create startup scenes first: Boot, Menu, Game, UI; add Pause / GameOver only if required
4. Add one vertical slice that proves the core loop works
5. Add reference-driven systems next: audio, saveable state, enemy spawning, tilemaps, UI polish

### Adding or refactoring a feature

1. Locate the owning scene and affected systems
2. Identify the smallest correct insertion point
3. Reuse existing helpers, constants, managers, and pools
4. Add cleanup and validation steps with the change
5. Preserve scene restart safety

### Debugging

1. Reproduce the issue from the code and config
2. Identify whether the fault is:
   - lifecycle / restart
   - asset dimensions or loader config
   - physics body setup or collider order
   - scale / camera / pixel rounding
   - stale listeners, timers, or pooled object state
3. Patch the root cause, not just the symptom
4. Provide a quick repro or verification checklist

## Reference map

Read only the files relevant to the task:

- **Setup / bootstrap / config**: [references/setup-and-build.md](references/setup-and-build.md)
- **Scenes / shared state / architecture**: [references/scenes-state-architecture.md](references/scenes-state-architecture.md)
- **Physics / entities / pooling**: [references/physics-and-entities.md](references/physics-and-entities.md)
- **Assets / animations / UI panels**: [references/assets-animation-ui.md](references/assets-animation-ui.md)
- **Tilemaps / camera / input / audio**: [references/tilemaps-camera-input-audio.md](references/tilemaps-camera-input-audio.md)
- **Performance / debugging / cleanup**: [references/performance-debugging.md](references/performance-debugging.md)
- **Code review / architecture checklist**: [references/review-checklist.md](references/review-checklist.md)

## Concrete examples

### Example: "Create a Phaser top-down shooter"

Use this skill. Default to:

- Vite + TypeScript structure
- Arcade Physics
- Boot, Menu, Game, UI scenes
- scene-owned input mapping
- pooled bullets
- global animations
- camera follow and world bounds
- asset keys / scene keys in constants

Then deliver runnable starter code plus the first playable loop.

### Example: "My pixel art looks blurry on mobile"

Use this skill. Inspect:

- `pixelArt` and `roundPixels` settings
- camera follow rounding
- scale mode and zoom strategy
- CSS around the canvas container
- whether art is being scaled non-integer

Then patch the smallest set of config and camera settings required.

### Example: "Paper UI panels show weird side bars"

Use this skill. Inspect the source texture first. Then:

- try built-in ThreeSlice / NineSlice if the art is a true 3-slice or 9-slice layout
- if frames contain large transparent padding or discontinuous art, use trimmed or composited fallback slices
- document the measured frame sizes, spacing, margins, and any overlap used

## Common traps

Avoid these unless the user explicitly wants them:

- one giant `GameScene` that owns menus, HUD, gameplay, pause, and transitions
- state stored on `window`, random module globals, or ad hoc singleton soup
- entity-owned keyboard listeners
- scene restart bugs caused by forgotten shutdown cleanup
- loading every future asset in the first scene
- manual nine-slice composition when built-in NineSlice already fits the asset
- over-engineering with ECS for tiny games that only need a few entity classes

## Final check before responding

Make sure the answer:

- matches the user's genre, platform, and art style
- uses Phaser 3 APIs, not Phaser 4 RC APIs
- chooses a physics system deliberately
- keeps SKILL.md-level advice concise and moves detail into references
- includes validation steps when code is produced