phaser-debugger

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phaser 4 Debugger

Phaser 4 调试指南

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

使用此技能基于实际证据而非猜测来诊断和修复Phaser 4问题。

Workflow

工作流程

Collect the exact symptom, error text, stack trace, browser/device context, and reproduction steps when available.
Read the relevant code before editing. For black screens, inspect
```
src/main.ts
```
, scene registration, scene transitions, preload paths, and browser console/network errors.
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.
Make the smallest fix that addresses the root cause.
Verify with
```
npx tsc --noEmit
```
for TypeScript projects and, when practical, a local dev-server smoke test.

收集确切的症状、错误文本、堆栈跟踪、浏览器/设备环境信息，以及可用的复现步骤。
在编辑前阅读相关代码。针对黑屏问题，检查
```
src/main.ts
```
、场景注册、场景切换、预加载路径以及浏览器控制台/网络错误。
按照Phaser生命周期顺序追踪可能的根本原因：配置、预加载、创建、更新、资源键、物理体创建、碰撞、输入、场景启动/停止状态以及渲染层级。
做出能解决根本原因的最小改动。
对TypeScript项目使用
```
npx tsc --noEmit
```
进行验证，在可行的情况下，进行本地开发服务器冒烟测试。

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

资源404错误和纹理键不匹配
场景未注册或使用错误的场景键
在场景初始化前调用
```
this.physics
```
、
```
this.input
```
或
```
this.anims
```
因创建对象时未启用物理系统导致Arcade物理体缺失
使用错误的对象或组注册碰撞器/重叠检测
动画键/帧不匹配
层级/透明度/相机边界导致对象被隐藏
升级到Phaser 4后仍使用Phaser 3 API
每帧内存分配、无限制组以及缺少对象池化
未跟踪计时器事件 —— 使用
```
time.addEvent()
```
但未存储引用，会在场景重启时不断累积
未显式销毁物理组 —— 进化后的武器组和生成阶段组若未执行
```
clear(true,true)
```
+
```
destroy()
```
会导致内存泄漏
无基础值+修饰符的属性修改 —— 两个系统在同一帧修改同一属性会产生竞态条件值
通过字符串相等去重通知 —— 会丢弃合法的快速重复事件（例如200毫秒内拾取两枚硬币）；改用时间窗口去重方式
基于模块级常量设置的覆盖层/面板背景尺寸 —— 在启动时固定大小；应使用
```
this.cameras.main.width/height
```
+ 尺寸变化监听器

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

当游戏冻结或行为异常但无控制台错误时，在查阅

references/agent-guidance.md

中的完整指南前，可先使用以下快速诊断路径。

无报错冻结：

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

然后强制刷新页面。任何之前无报错的故障现在都会被记录。完整检查清单请参阅

references/agent-guidance.md → Silent Freeze

。

生成过程中途停止（无报错）： 对象池插槽泄漏——实体离开相机视野但未回收插槽。在生成调用中添加

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

。如果数值变为0并保持不变，说明有插槽被占用。详细内容请参阅

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

返回0。改用位置增量采样方式。详细内容请参阅

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

如需完整的诊断手册，请阅读

references/agent-guidance.md

。该内容复制自Claude子代理定义，但应作为可移植技能使用；忽略仅Claude相关的字段，如

model

、

color

和

tools

。