# Phaser4 Game Architecture

> Phaser 4 移动端 2D 游戏的技术架构角色。需要划分或评审模块职责、公开契约、状态所有权和依赖方向，或建立 TypeScript、Vite、Capacitor、场景、资源、存档、平台适配和可复现构建的技术基线时使用。

- Skill: `weberwang/phaser4-game-architecture` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add weberwang/phaser4-game-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/weberwang/phaser4-game-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: weberwang (https://skillmd.com/u/weberwang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/weberwang/phaser4-game-architecture

---


# Phaser 4 技术架构

## 全局控制接入

控制面边界：可提议、可审查、可在当前用户任务的 Work Item 范围内修改，且必须回到 `$phaser4-game-workflow-control` 审计和状态迁移；仅涉及外部写入、付费、真机、破坏性或外部删除、发布副作用的 A4-A6 操作请求批准。

本领域可提议、审查，并在当前用户任务、Implementation Package、A 等级和路径范围内修改；任何结果必须回到 [`phaser4-game-workflow-control`](../phaser4-game-workflow-control/SKILL.md) 风险门。任务内方案和路径变化同步更新计划即可继续；首次模块或边界变化先关闭事实，只有实质架构取舍才停止并 grilling。

建立可维护、可测试、可构建的边界，并显式处理小游戏、iOS、Google Play 的差异。

## 输入与边界

读取全局 Work Item、模块审计、依赖能力档、服务边界和项目权威工件。按 F0 范围与流程、F1 规格一致性、F2 架构质量、F3 工程验证、F4 集成/发布决策提交结果，不自行改变全局状态。

- 用 Phaser 4、TypeScript、Vite 实现 Web 核心；新项目优先采用官方当前的 create-phaser-game 流程。
- 仅在移动平台档被实际需求触发时用 Capacitor 承载 iOS 与 Android，并将每个已采用插件封装在平台适配层；初始化不得默认安装非必需插件。
- 小游戏必须单独验证；可选商业能力须有显式接口和已批准开关。

## 执行与交接

1. 在实现前划分并审计模块，记录职责与非目标、公开输入/输出、状态所有权、生命周期、允许/禁止依赖、失败边界、测试和实现顺序；首次模块先完成模块门与 grilling，再按 F0-F4 写入 TDD。全局阶段、视觉硬门和场景前置以[控制模型](../phaser4-game-workflow-control/references/control-model.md)、[状态、阶段与停止门](../phaser4-game-workflow-control/references/state-gates.md)及对应 Schema 为准；本领域只补充模块边界。
2. 在 TDD 标注 foundation-only 的 `SHARED`/`MODULE` 范围、场景 `SCENE`/`DISPLAY_LAYER` 归属和跨场景 `INTEGRATION` 依赖。基础包只提供稳定契约，不实现具体场景玩法、UI/布局、正式可见资产消费或 Boot→正式可见 Scene 接入；模块可按互斥所有权并行，共享契约/入口保持串行。场景只通过公开服务、状态仓库或消息契约协作，不得直接访问其他 Scene 的内部状态。
3. 任务内新增模块、拆分职责或调整实现方案时同步更新计划与所有权，定向验证受影响部分。只有目标、对外行为或用户需要决定的实质设计取舍发生变化时才创建 Change Request 并请求决定；只有带副作用的 A4-A6 操作进入 F4 批准门。
4. 为装饰性屏幕空间满幅背景建立唯一适配器，覆盖创建、唤醒、恢复、方向与画布尺寸变化；具体缩放、焦点和裁切规则由项目契约定义。世界空间关卡、Tilemap、碰撞或玩法环境必须使用独立对象、地图和层级数据，不得套用装饰背景适配器或扁平化。
5. 涉及 UI 时使用 [`phaser4-game-ui-layout`](../phaser4-game-ui-layout/SKILL.md) 定义唯一的逻辑坐标与布局入口，把视口、安全区、方向、内容尺寸、状态和运行时有效 DPR（动态封顶 1.5）作为显式参数；在 TDD 记录父级坐标空间、参照物、双方停靠点、距离、尺寸策略、横纵布局组、断点、滚动轴所有权、遮挡回退和精度阈值。布局重算从合同值开始并保持幂等，资源 origin、布局锚点和动画偏移相互分离，禁止在多个生命周期回调散布无参照语义的屏幕坐标。合同验证器属于 F3 工程验证，固定值或绝对定位完整有据时触发布局专项 F2。
6. 分离核心规则、表现、平台和第三方服务。公共代码和公共正式资源必须被至少两个已确认场景稳定复用，或属于运行必需；禁止无边界 `common`/`utils` 和公共素材库。foundation-only 阶段的 `SHARED` 只提供最小启动、公开契约和 Boot/Preload 生命周期，`MODULE` 只提供场景无关数据/状态/输入/平台/资源基础设施与测试支撑；具体场景业务、UI/布局和正式可见资产仍在对应场景阶段完成。每个场景在自身阶段一并完成玩法、正式视觉、全部 UI/弹窗显示层、清理和联合证据。玩法独占规则、状态、碰撞和交互代码；美术可维护纯表现资源配置、布局/表现预制数据与视觉集成调整，但不得改变玩法规则、碰撞语义或状态所有权。为协作集成、触控、安全区、暂停恢复、后台切换和断网定义验证策略。
7. 对组件/资源集和场景路径，在 V1 定义每场景纹理、图集、帧数、动画采样、纹理内存、过绘、Draw Call 和最大纹理预算；在 V3 将预算写入机器清单，V4 只验证。原子资源必须引用已有适用且有效的玩法视觉契约与预算基线，否则升级路径；不得在验收时临时放宽。
8. 在 TDD 按需记录核心、移动平台、数据/API、复杂玩法、高级视觉和商业能力档；每项包含启用原因、拒绝的轻量方案、运行时性能与平台风险、验证命令和所有者。涉及服务时记录契约版本、认证授权、幂等/重试/超时、兼容、迁移/回滚、测试、监控与备份恢复；服务端不在范围时只记录外部依赖、所有者和客户端边界。
9. 在 TDD 定义本地服务身份、默认模式、主机/端口和健康检查。启动开发或预览服务前检查监听进程、命令行、项目根目录与健康状态；身份一致且健康时直接复用，不得重复启动。
10. 共享基础完成后提供代表性 Vite/Phaser 启动、Boot/首场景、资源和适用插件烟测；关键玩法流完成后提供主目标平台运行烟测；仅最终集成/G3/release 执行完整平台矩阵。不得由局部证据宣称全平台通过，不得自动发起真机验收。
11. F0 完成后提交范围与流程事实；F1 提交规格映射；F2 提交独立架构结论；F3 提交候选 SHA、实际命令证据和未覆盖项。

交给玩法开发模块入口、数据流和测试入口；交给测试提供构建命令、版本和日志定位方式。新增或修改的类、函数、实体定义均添加解释设计边界的简体中文注释。