Phaser 4 Debugger

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

references/agent-guidance.md

// 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);
};

references/agent-guidance.md → Silent Freeze

console.log('pool free:', pool.getTotalFree())

references/agent-guidance.md → Pool Slot Leak

update()

cinematicMode

skills/phaser-animation/references/state-machine-patterns.md

references/agent-guidance.md → Race Between Two Systems

body.velocity

references/agent-guidance.md → Stuck Detection Fails

Full Guidance

references/agent-guidance.md

model

color

tools