phaser-debugger

Name: phaser-debugger
Author: Yakoub-ai

63installs0forks

How to install phaser-debugger?

yakoub-ai/phaser4-gamedev/phaser-debugger

$npx -y skills add Yakoub-ai/phaser4-gamedev --skill phaser-debugger

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.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

63installs0forks

View on GitHub

How to install phaser-debugger?

yakoub-ai/phaser4-gamedev/phaser-debugger

$npx -y skills add Yakoub-ai/phaser4-gamedev --skill phaser-debugger

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.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