phaser-analyze

Phaser 4 棕地项目分析

对现有 Phaser 4 项目进行全面分析，评估架构质量、识别性能风险、指出 API 正确性问题，并制定按优先级排列的改进路线图。

分析流程

按顺序完成以下五个阶段。不要跳过任何阶段——每个阶段都建立在前一阶段的基础上。

阶段 1 — 发现

在做出任何判断之前，先收集项目的原始信息。

• 阅读 package.json，检查依赖项和 Phaser 版本
• 使用 glob 列出 src/ 中所有 .ts/.js 文件
• 阅读 main.ts 中的 GameConfig
• 识别所有场景：在 src/ 中使用 grep "extends Phaser.Scene" 搜索
• 绘制场景图：使用 grep 搜索 this.scene.start、this.scene.launch、this.scene.stop
• 识别所有自定义游戏对象：使用 grep "extends Phaser.Physics" 或 grep "extends Phaser.GameObjects" 搜索
• 统计源文件总数和代码行数

阶段 2 — 架构评估

评估代码库的结构质量。

• 场景数量和组织方式 — 场景是否位于 src/scenes/？对于游戏的复杂度而言，场景数量是过多还是过少？
• 状态管理模式 — Registry、全局变量还是模块状态。搜索 window.、模块级 let/var 声明。
• 资源加载策略 — 使用集中式 PreloaderScene，还是在各场景中分散实现 preload() 方法？
• 代码组织 — 项目是否遵循 scenes/、objects/、managers/ 约定？
• 跨场景耦合分析 — 直接引用、事件总线还是 Registry。搜索 this.registry、this.events.emit、this.scene.get。

根据分析结果，将架构评为 A 到 F：

• A — 分离清晰、集中加载、事件驱动通信
• B — 存在少量组织问题，整体结构良好
• C — 存在一些耦合问题，模式不统一，功能正常但结构混乱
• D — 存在严重的结构问题、全局变量和分散加载
• F — 架构无法辨识，所有内容都在一个文件中或彼此严重纠缠

阶段 3 — 性能审计

识别运行时性能风险。

• 对象池： 在组声明中搜索 classType/maxSize。标记未设置 maxSize 的 this.physics.add.group() 物理组——这类组会导致对象泄漏。
• 粒子发射器上限： 搜索未设置 maxParticles 的粒子发射器。没有上限的发射器可能导致帧耗时激增。
• 静态组与动态组： 检查平台、墙壁和其他不可移动物体是否使用 staticGroup()（正确做法），而不是 group()（会浪费物理计算周期）。
• 更新循环开销： 阅读每个场景的 update() 方法。标记其中的复杂逻辑、对象分配（new）或大量遍历。
• 纹理图集使用情况： 统计单独调用 this.load.image() 与调用 this.load.atlas() 的次数。单独加载图片超过 15 次属于风险信号——应将资源打包到图集中。
• 物理体数量： 根据组声明和单独调用 this.physics.add.* 的次数，估算活动物理体的总数。

阶段 4 — API 正确性

检查是否存在已弃用、已移除或误用的 API。

• v3 API 扫描： 搜索已移除的 API——Geom.Point、Math.PI2、Phaser.Structs、Camera3D、Layer3D、FacebookInstant、Create.GenerateTexture、TileSprite.setCrop。
• TypeScript 严格性： 搜索 as any、@ts-ignore、未声明类型的函数参数。这些写法会掩盖真正的错误。
• 资源键一致性： 交叉核对 this.load.* 键与 this.add.*/this.physics.add.* 键。键不匹配会导致静默的纹理缺失错误。
• 场景键注册： 确认所有场景类都出现在 main.ts 的 GameConfig 场景数组中。
• 物理体创建： 标记使用 this.add.sprite() 创建、但预期应具有物理属性的精灵（应使用 this.physics.add.sprite()）。
• DynamicTexture/RenderTexture： 检查绘制操作后是否遗漏 .render() 调用。

阶段 5 — 最佳实践检查

验证项目是否遵循 Phaser 4 最佳实践。

• 生命周期规范： preload() 应只加载资源，create() 应只构建场景，update() 应保持精简（不加载资源、不创建对象）。
• 关闭时清理： 场景应执行清理 — 检查 this.events.off、this.sound.stopAll()、计时器销毁、this.events.on('shutdown', ...)。
• 摄像机边界： 摄像机边界应与世界或瓦片地图边界一致。搜索 this.cameras.main.setBounds，并与世界／地图尺寸进行比较。
• 键盘输入的空值断言： Phaser 4 中 this.input.keyboard 可能为 null。检查是否使用 this.input.keyboard! 或进行了适当的空值保护。
• 物理调试标志： 生产环境中的物理配置应将 debug: true 设为 false。如果存在，请标记出来。
• 控制台语句： 统计 console.log／console.warn／console.error 调用次数。生产环境中应通过 import.meta.env.DEV 控制这些调用，或将其移除。

输出格式

生成一份包含以下部分的结构化报告：

1. 项目摘要 — 文件数、场景数、代码行数、预估复杂度（小／中／大）。
2. 架构评分 — 字母等级（A/B/C/D/F），并说明评分理由。
3. 性能风险 — 按严重程度（严重／高／中／低）排序，并为每项提供具体的修复建议。
4. 代码质量问题 — 尽可能提供 file:line 引用。
5. 改进路线图 — 按影响与工作量优先级排序的重构步骤。
6. 快速改进项 — 3-5 项可立即实施且效果明显的改动。

相关技能

• 使用 /phaser-migrate 修复第 4 阶段发现的任何 Phaser v3 API 问题。
• 使用 /phaser-physics 实现对象池，并修复第 3 阶段发现的物理组问题。
• 使用 phaser-debugger Agent 调查第 3 阶段标记的运行时性能问题。

参考文件

• references/analysis-checklist.md — 包含所有检查项的完整清单、grep 模式、严重程度评级和修复参考。
• references/performance-playbook.md — 面向中端移动设备的九阶段 Phaser 4 性能优化指南：以测量为先的提示、消除每帧分配、注册表节流、音频延迟加载、VFX 对象池、空间网格、图集打包、事件节流、使用真实 delta 跳过 AI 更新。当 FPS 低于目标或游戏过程中内存持续增长时阅读。

自动预扫描

开始手动深入审查前，先运行自动分析脚本：

bash "${CLAUDE_PLUGIN_ROOT}/skills/phaser-analyze/scripts/analyze-project.sh"

这将提供基线指标并标记明显问题。将脚本输出作为起点，然后通过阅读实际源文件完成完整的 5 阶段分析。