mcpField
P
phaser-debugger

phaser-debugger

github.com/yakoub-ai开发29199 次安装9 周前更新
代码仓库

关于 phaser-debugger

phaser-debugger 是用于排查和修复 Phaser 4 问题的技能，强调依据错误信息和复现证据分析。它按 Phaser 生命周期追踪根因，并指导进行最小修复与验证。

主要功能

  1. 01基于证据诊断问题
  2. 02按 Phaser 生命周期排查
  3. 03静默故障诊断路径
  4. 04TypeScript 与冒烟测试验证

适用场景

  1. 01排查 Phaser 4 黑屏
  2. 02追踪无控制台错误的卡死
  3. 03查找场景重启后的资源泄漏

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/yakoub-ai/phaser4-gamedev --skill phaser-debugger

安装后在 Claude Code 中输入/phaser-debugger确认已加载。

附带文件references/agent-guidance.md

详细介绍

Phaser 4 调试器

使用此技能，根据证据诊断并修复 Phaser 4 问题，而不是猜测。

工作流程

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

调试检查清单

  • 资源 404 和纹理键不匹配
  • 场景未注册或场景键错误
  • 场景初始化前就使用了 this.physics、this.input 或 this.anims
  • 创建对象时未启用物理，因此缺少 Arcade 物理体
  • Collider/overlap 注册时使用了错误的对象或组
  • 动画键/帧不匹配
  • 深度/透明度/摄像机边界导致对象被遮挡
  • 升级到 Phaser 4 后仍使用 Phaser 3 API
  • 每帧分配对象、组无上限增长，以及缺少对象池
  • 计时器事件未跟踪——未保存引用就调用 time.addEvent()，会导致计时器在场景重启期间不断累积
  • 物理组未显式销毁——进化后的武器组和生成阶段组如果未执行 clear(true,true) 并调用 destroy()，就会泄漏
  • 修改属性时未使用基础值 + 修正值模式——两个系统在同一帧写入同一属性会导致竞争条件，使属性值出错
  • 按字符串相等进行通知去重——会丢弃合法的快速重复事件（例如 200 ms 内拾取两枚金币）；应改用时间窗口去重
  • 覆盖层/面板背景尺寸取自模块级常量——尺寸会固定在启动时的大小；应使用 this.cameras.main.width/height 并添加调整大小监听器

常见的静默故障类别

当游戏冻结或行为异常且没有控制台错误时，先尝试以下快速诊断方法，再查阅完整指南 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 返回 0。改用位置差值采样。请参见 references/agent-guidance.md → Stuck Detection Fails。

完整指南

如需完整的诊断手册，请阅读 references/agent-guidance.md。该文件复制自 Claude 子 Agent 定义，但应作为可移植技能使用；忽略 model、color 和 tools 等仅适用于 Claude 的字段。

评论

支持 Markdown