phaser4-game-architecture

Phaser 4 技术架构

全局控制接入

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

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

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

输入与边界

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

• 用 Phaser 4、TypeScript、Vite 实现 Web 核心；新项目优先采用官方当前的 create-phaser-game 流程。
• 仅在移动平台档被实际需求触发时用 Capacitor 承载 iOS 与 Android，并将每个已采用插件封装在平台适配层；初始化不得默认安装非必需插件。
• 小游戏必须单独验证；可选商业能力须有显式接口和已批准开关。
• 基础模块阶段建立统一音频服务与生命周期适配，按后台暂停与恢复约束实现后台暂停、前台原位置续播；保留手动暂停和静音状态，防止重复恢复、过期音效补播及已销毁实例复活，纳入基础包和 TDD。
• 基础模块实施必须完成基础显示约束：游戏填满实际可用视口；Android 宿主从启动首帧到运行全程无窗口标题栏或 ActionBar，并实现沉浸式全屏及前台/焦点恢复。启动主题、运行主题、窗口配置与视口/安全区适配纳入基础包和 TDD，不延后到场景实现阶段。

执行与交接

新建游戏项目、实现基础模块或调整目录与模块边界时，先读取游戏项目目录规范，按入口/基础服务分层、场景功能聚合组织代码，明确资源、平台、测试和产物归属，并把实际路径与所有权写入 TDD 和实施包。

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

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