# Phaser Debugger

> This skill should be used when the user reports a Phaser 4 bug, black screen, missing sprite, failed collision, broken physics, animation issue, crash, console error, performance problem, slow game, save/load issue, mobile runtime issue, or unexpected gameplay behavior.

- Skill: `yakoub-ai/phaser-debugger` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yakoub-ai/phaser-debugger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yakoub-ai/phaser-debugger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yakoub-ai (https://skillmd.com/u/yakoub-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yakoub-ai/phaser-debugger

---


# Phaser 4 Debugger

Use this skill to diagnose and fix Phaser 4 issues from evidence rather than guessing.

## Workflow

1. Collect the exact symptom, error text, stack trace, browser/device context, and reproduction steps when available.
2. Read the relevant code before editing. For black screens, inspect `src/main.ts`, scene registration, scene transitions, preload paths, and browser console/network errors.
3. Trace likely root causes using Phaser lifecycle order: config, preload, create, update, asset keys, physics body creation, collisions, input, scene start/stop state, and rendering depth.
4. Make the smallest fix that addresses the root cause.
5. Verify with `npx tsc --noEmit` for TypeScript projects and, when practical, a local dev-server smoke test.

## Debugging Checklist

- Asset 404s and mismatched texture keys
- Scene not registered or wrong scene key
- `this.physics`, `this.input`, or `this.anims` used before scene initialization
- Arcade body missing because object was created without physics
- Collider/overlap registered with the wrong object or group
- Animation key/frame mismatch
- Depth/alpha/camera bounds hiding an object
- Phaser 3 API usage after upgrading to Phaser 4
- Per-frame allocations, unbounded groups, and missing object pooling
- **Timer events not tracked** — `time.addEvent()` without a stored reference accumulates across scene restarts
- **Physics groups not explicitly destroyed** — evolved weapon groups and spawn-phase groups leak if not `clear(true,true)` + `destroy()`'d
- **Stat mutations without base+modifiers** — two systems writing the same stat in the same frame produce race-condition values
- **Notification dedup by string equality** — drops legitimate rapid repeat events (e.g. two coin pickups in 200 ms); use a time-window dedup instead
- **Overlay/panel backdrops sized from module-level constants** — freeze at boot size; use `this.cameras.main.width/height` + resize listener

## Common Silent Failure Categories

When the game freezes or behaves incorrectly with **no console error**, use these fast diagnostic paths before reaching for the full guide in `references/agent-guidance.md`.

**Silent freeze (no error):**
```typescript
// Add to main.ts BEFORE new Phaser.Game(config)
window.onerror = (msg, _src, _line, _col, err) => {
  console.error('GLOBAL ERROR:', msg, err?.stack);
};
window.onunhandledrejection = (ev) => {
  console.error('UNHANDLED REJECTION:', ev.reason);
};
```
Then hard-refresh. Any previously silent failure will now log. See `references/agent-guidance.md → Silent Freeze` for the full checklist.

**Spawns stop mid-session (no error):**
Pool slot leak — entities leaving the camera view without recycling their slot. Add `console.log('pool free:', pool.getTotalFree())` in your spawn call. If it hits zero and stays there, a slot is being held. See `references/agent-guidance.md → Pool Slot Leak`.

**Forced animation plays one frame then reverts:**
Entity `update()` overwrites forced animation one tick later. Fix with `cinematicMode` flag. See `skills/phaser-animation/references/state-machine-patterns.md`.

**Speed or stat jumps to wrong value intermittently:**
Two systems mutate the same stat on the same frame. Use base+modifiers pattern. See `references/agent-guidance.md → Race Between Two Systems`.

**Stuck entity detection fires incorrectly (false positives or negatives):**
`body.velocity` returns 0 when pushing against a wall. Use position-delta sampling instead. See `references/agent-guidance.md → Stuck Detection Fails`.

## Full Guidance

For the complete diagnostic playbook, read `references/agent-guidance.md`. It is copied from the Claude subagent definition but should be applied as a portable skill; ignore Claude-only fields such as `model`, `color`, and `tools`.