phaser-best-practices

构建 Phaser 游戏

何时使用此技能

当用户希望执行以下操作时，使用此技能：

• 创建新的 Phaser 3 游戏或原型
• 添加或重构场景、实体、UI、物理、瓦片地图、输入、音频或摄像机
• 调试 Phaser 特有的问题，例如场景重启、像素艺术模糊、碰撞器错误、资源加载问题或动画问题
• 改进 Phaser 项目的架构、可维护性或运行时性能

除非用户明确希望将 Phaser 风格的模式应用到其他引擎，否则不要将此技能用于非 Phaser 引擎。

操作方式

1. 判断请求类型

编写代码前，先对任务分类：

• 新项目：脚手架、文件夹布局、游戏配置、首批场景
• 功能开发：添加玩法、UI、音频、过渡效果、瓦片地图、敌人、拾取物
• 修复错误：定位场景生命周期、资源、物理、输入、摄像机或渲染故障
• 优化：分析性能瓶颈、对象池、剔除、节流、资源策略
• 美术 / 资源工作流：精灵表尺寸测量、动画设置、九宫格 / 三宫格 UI、瓦片地图集成

2. 先检查，再决定

如果仓库已存在，在提出结构调整前先检查：

• package.json、打包工具配置、tsconfig/jsconfig
• Phaser 版本，以及代码库使用 JS 还是 TS
• 游戏启动代码、场景列表、物理配置、缩放配置
• 资源文件夹和命名约定
• 当前的状态共享方式（场景数据、注册表、服务、全局变量）
• 项目属于像素艺术、高清美术、桌面优先、移动端优先，还是混合输入

优先适配现有代码库，而不是用样板代码替换它。

3. 默认技术选择

除非任务明显需要其他方案，否则采用以下默认选择：

• 新项目优先采用官方的 Vite + TypeScript 风格配置
• 平台游戏、射击游戏、俯视角动作游戏、简单拾取物和轻量级碰撞逻辑，优先使用 Arcade Physics
• 只有当游戏需要由旋转驱动的碰撞、复合刚体、约束、堆叠稳定性或更真实的模拟时，才使用 Matter Physics
• 先围绕 场景 组织代码，再在场景内组织实体 / 系统
• 输入由场景管理；实体应读取输入状态，而不是自行注册监听器
• 多个精灵共享相同动画数据时，使用 全局动画
• 启动必需的资源应预先加载；在有助于缩短启动时间时，再加载关卡专用资源
• 纹理布局支持时，使用内置的 NineSlice / ThreeSlice 制作可缩放 UI 美术资源；只有透明填充或不连续的美术内容导致内置切片不适用时，才改用自定义合成
• 大多数游戏使用 FIT 缩放；类似编辑器或 UI 占比高的布局使用 RESIZE；只有在手动控制画布尺寸时才使用 NONE
• 像素艺术启用 pixelArt 模式，尽可能采用整数倍缩放，并避免摄像机亚像素移动

4. 输出要求

对于新游戏，提供：

• 推荐的文件夹结构
• 游戏配置
• 场景列表及职责
• 可运行的入门代码
• 说明每项架构选择为何适合所请求的游戏类型

对于功能开发或错误修复，提供：

• 精简且有针对性的修改
• 根本原因说明
• 补丁
• 用户可立即执行的验证步骤

对于架构建议，提供：

• 能解决当前问题的最精简结构
• 一条推荐方案，而不是多个权重相同的选项
• 在选择较重要时明确说明权衡（例如 Arcade 与 Matter 的比较）

不可妥协的实现规则

• 除非用户要求迁移，否则遵循项目现有的 JS 或 TS 选择
• 将场景键、资源键、碰撞类别和平衡常量集中管理
• 让 update() 专注于编排；将详细逻辑放入实体或系统中
• 添加监听器、计时器、补间动画或长期持有的引用时，注册场景关闭／销毁时的清理逻辑
• 除非性能分析证明无害，否则不要在频繁执行的 update() 循环中创建新对象
• 不要默认让所有对象都可交互或启用物理效果
• 不要假定精灵表的帧尺寸；应检查并验证
• 如果 Arcade 已能简洁地解决问题，不要建议用户改用 Matter
• 不要仅仅因为方便，就在一个 Boot 场景中预加载整个游戏

推荐的交付工作流

新建 Phaser 项目

1. 选择架构规模：
   • 小型／游戏 Jam 项目：2-4 个场景、轻量服务模块
   • 中型游戏：场景 + 实体 + 系统 + 常量
   • 大型内容丰富型游戏：数据驱动的内容、场景服务、专用状态层
2. 定义基础配置：渲染器、缩放模式、物理、像素艺术设置
3. 先创建启动场景：Boot、Menu、Game、UI；仅在需要时添加 Pause／GameOver
4. 添加一个能验证核心循环正常运行的纵向切片
5. 接着添加有参考资料支持的系统：音频、可保存状态、敌人生成、瓦片地图、UI 润色

添加或重构功能

1. 找到所属场景及受影响的系统
2. 确定最小且正确的插入点
3. 复用现有的辅助工具、常量、管理器和对象池
4. 随更改一起添加清理和验证步骤
5. 确保场景重启安全

调试

1. 根据代码和配置重现问题
2. 判断故障是否与以下因素有关：
   • 生命周期／重启
   • 资源尺寸或加载器配置
   • 物理体设置或碰撞器顺序
   • 缩放／摄像机／像素取整
   • 过期的监听器、计时器或对象池对象状态
3. 修复根本原因，而不只是表面症状
4. 提供快速复现或验证清单

参考资料索引

只阅读与任务相关的文件：

• 设置／引导／配置：references/setup-and-build.md
• 场景／共享状态／架构：references/scenes-state-architecture.md
• 物理／实体／对象池：references/physics-and-entities.md
• 资源／动画／UI 面板：references/assets-animation-ui.md
• 瓦片地图／摄像机／输入／音频：references/tilemaps-camera-input-audio.md
• 性能／调试／清理：references/performance-debugging.md
• 代码审查／架构检查清单：references/review-checklist.md

具体示例

示例：“创建一款 Phaser 俯视角射击游戏”

使用此技能。默认采用：

• Vite + TypeScript 结构
• Arcade Physics
• Boot、Menu、Game、UI 场景
• 由场景管理的输入映射
• 子弹对象池
• 全局动画
• 摄像机跟随和世界边界
• 在常量中定义资源键／场景键

然后交付可运行的起步代码以及第一个可玩的循环。

示例：“我的像素画在手机上看起来模糊”

使用此技能。检查：

• pixelArt 和 roundPixels 设置
• 摄像机跟随取整
• 缩放模式和缩放策略
• 画布容器周围的 CSS
• 美术资源是否经过非整数倍缩放

然后修改所需的最少配置和摄像机设置。

示例：“纸质 UI 面板出现了奇怪的侧边条”

使用此技能。先检查源纹理。然后：

• 如果美术资源确实采用 3 切片或 9 切片布局，尝试使用内置的 ThreeSlice / NineSlice
• 如果帧中包含大量透明留白或美术内容不连续，则使用裁剪或合成的备用切片
• 记录测量得到的帧尺寸、间距、边距以及使用的任何重叠

常见陷阱

除非用户明确要求，否则请避免以下做法：

• 用一个巨大的 GameScene 管理菜单、HUD、游戏玩法、暂停和场景转换
• 将状态存储在 window、随机的模块全局变量或临时拼凑的单例集合中
• 让实体自行管理键盘监听器
• 因遗漏关闭清理而导致的场景重启错误
• 在第一个场景中加载所有未来才会用到的资源
• 当内置 NineSlice 已适用于美术资源时，仍手动组合九宫格切片
• 对只需几个实体类的小型游戏过度设计并引入 ECS

回复前的最终检查

确保答案：

• 符合用户的游戏类型、平台和美术风格
• 使用 Phaser 3 API，而非 Phaser 4 RC API
• 有意选择物理系统
• 保持 SKILL.md 级别的建议简洁，并将细节放入参考资料
• 在生成代码时包含验证步骤