phaser-debugger

Name: phaser-debugger
Author: Yakoub-ai

15stars0forks

How to install phaser-debugger?

yakoub-ai/phaser4-gamedev/phaser-debugger

$curl -o .claude/agents/phaser-debugger.md https://raw.githubusercontent.com/Yakoub-ai/phaser4-gamedev/HEAD/agents/phaser-debugger.md

Installs into the current project.

Summary

Use this agent when the user reports a "Phaser bug", "game not working", "black screen", "sprite not showing", "physics not working", "collision not detected", "animation not playing", "game crashes", "error in console", "performance problems", "slow game", or any Phaser 4 runtim

Files · 1

View on GitHub

agents/phaser-debugger.md

1	# Phaser 4 Debugger
2
3	Use this skill to diagnose and fix Phaser 4 issues from evidence rather than guessing.
4
5	## Workflow
6
7	1. Collect the exact symptom, error text, stack trace, browser/device context, and reproduction steps when available.
8	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.
9	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.
10	4. Make the smallest fix that addresses the root cause.
11	5. Verify with `npx tsc --noEmit` for TypeScript projects and, when practical, a local dev-server smoke test.
12
13	## Debugging Checklist
14
15	- Asset 404s and mismatched texture keys
16	- Scene not registered or wrong scene key
17	- `this.physics`, `this.input`, or `this.anims` used before scene initialization
18	- Arcade body missing because object was created without physics
19	- Collider/overlap registered with the wrong object or group
20	- Animation key/frame mismatch
21	- Depth/alpha/camera bounds hiding an object
22	- Phaser 3 API usage after upgrading to Phaser 4
23	- Per-frame allocations, unbounded groups, and missing object pooling
24	- Timer events not tracked — `time.addEvent()` without a stored reference accumulates across scene restarts
25	- Physics groups not explicitly destroyed — evolved weapon groups and spawn-phase groups leak if not `clear(true,true)` + `destroy()`'d
26	- Stat mutations without base+modifiers — two systems writing the same stat in the same frame produce race-condition values
27	- Notification dedup by string equality — drops legitimate rapid repeat events (e.g. two coin pickups in 200 ms); use a time-window dedup instead
28	- Overlay/panel backdrops sized from module-level constants — freeze at boot size; use `this.cameras.main.width/height` + resize listener
29
30	## Common Silent Failure Categories
31
32	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`.
33
34	Silent freeze (no error):
35	```typescript
36	// Add to main.ts BEFORE new Phaser.Game(config)
37	window.onerror = (msg, _src, _line, _col, err) => {
38	console.error('GLOBAL ERROR:', msg, err?.stack);
39	};
40	window.onunhandledrejection = (ev) => {
41	console.error('UNHANDLED REJECTION:', ev.reason);
42	};
43	```
44	Then hard-refresh. Any previously silent failure will now log. See `references/agent-guidance.md → Silent Freeze` for the full checklist.
45
46	Spawns stop mid-session (no error):
47	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`.
48
49	Forced animation plays one frame then reverts:
50	Entity `update()` overwrites forced animation one tick later. Fix with `cinematicMode` flag. See `skills/phaser-animation/references/state-machine-patterns.md`.
51
52	Speed or stat jumps to wrong value intermittently:
53	Two systems mutate the same stat on the same frame. Use base+modifiers pattern. See `references/agent-guidance.md → Race Between Two Systems`.
54
55	Stuck entity detection fires incorrectly (false positives or negatives):
56	`body.velocity` returns 0 when pushing against a wall. Use position-delta sampling instead. See `references/agent-guidance.md → Stuck Detection Fails`.
57
58	## Full Guidance
59
60	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`.

People who liked this also viewed

6 picks

Type

phaser-debugger

15stars0forks

View on GitHub

How to install phaser-debugger?

yakoub-ai/phaser4-gamedev/phaser-debugger

$curl -o .claude/agents/phaser-debugger.md https://raw.githubusercontent.com/Yakoub-ai/phaser4-gamedev/HEAD/agents/phaser-debugger.md

Installs into the current project.

Summary

Files · 1

View on GitHub

agents/phaser-debugger.md

1	# Phaser 4 Debugger
2
3	Use this skill to diagnose and fix Phaser 4 issues from evidence rather than guessing.
4
5	## Workflow
6
7	1. Collect the exact symptom, error text, stack trace, browser/device context, and reproduction steps when available.
8	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.
9	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.
10	4. Make the smallest fix that addresses the root cause.
11	5. Verify with `npx tsc --noEmit` for TypeScript projects and, when practical, a local dev-server smoke test.
12
13	## Debugging Checklist
14
15	- Asset 404s and mismatched texture keys
16	- Scene not registered or wrong scene key
17	- `this.physics`, `this.input`, or `this.anims` used before scene initialization
18	- Arcade body missing because object was created without physics
19	- Collider/overlap registered with the wrong object or group
20	- Animation key/frame mismatch
21	- Depth/alpha/camera bounds hiding an object
22	- Phaser 3 API usage after upgrading to Phaser 4
23	- Per-frame allocations, unbounded groups, and missing object pooling
24	- Timer events not tracked — `time.addEvent()` without a stored reference accumulates across scene restarts
25	- Physics groups not explicitly destroyed — evolved weapon groups and spawn-phase groups leak if not `clear(true,true)` + `destroy()`'d
26	- Stat mutations without base+modifiers — two systems writing the same stat in the same frame produce race-condition values
27	- Notification dedup by string equality — drops legitimate rapid repeat events (e.g. two coin pickups in 200 ms); use a time-window dedup instead
28	- Overlay/panel backdrops sized from module-level constants — freeze at boot size; use `this.cameras.main.width/height` + resize listener
29
30	## Common Silent Failure Categories
31
32	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`.
33
34	Silent freeze (no error):
35	```typescript
36	// Add to main.ts BEFORE new Phaser.Game(config)
37	window.onerror = (msg, _src, _line, _col, err) => {
38	console.error('GLOBAL ERROR:', msg, err?.stack);
39	};
40	window.onunhandledrejection = (ev) => {
41	console.error('UNHANDLED REJECTION:', ev.reason);
42	};
43	```
44	Then hard-refresh. Any previously silent failure will now log. See `references/agent-guidance.md → Silent Freeze` for the full checklist.
45
46	Spawns stop mid-session (no error):
47	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`.
48
49	Forced animation plays one frame then reverts:
50	Entity `update()` overwrites forced animation one tick later. Fix with `cinematicMode` flag. See `skills/phaser-animation/references/state-machine-patterns.md`.
51
52	Speed or stat jumps to wrong value intermittently:
53	Two systems mutate the same stat on the same frame. Use base+modifiers pattern. See `references/agent-guidance.md → Race Between Two Systems`.
54
55	Stuck entity detection fires incorrectly (false positives or negatives):
56	`body.velocity` returns 0 when pushing against a wall. Use position-delta sampling instead. See `references/agent-guidance.md → Stuck Detection Fails`.
57
58	## Full Guidance
59
60	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`.

People who liked this also viewed

6 picks

Type