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 流程。
• 新建或调整 Vite 生产构建时，按生产构建压缩与发布检查落实 Terser 两轮压缩、标识符缩短、注释移除与生产 Source Map 默认关闭；评估 Phaser Compressor 按需裁剪引擎，并交接实际配置入口、构建命令和验证证据。
• 仅在移动平台档被实际需求触发时用 Capacitor 承载 iOS 与 Android，并将每个已采用插件封装在平台适配层；初始化不得默认安装非必需插件。
• 项目所有已采用 SDK 的初始化由 src/platform/initialize-sdks.ts 单文件统一编排，src/main.ts 调用后 Phaser 首帧不等待初始化批次；设计和实施时读取SDK 统一初始化，在 TDD 明确每个 SDK 的官方真实前置、就绪判据和失败/重试所有权，禁止跨 SDK 建启动屏障或在场景、构造函数、业务服务和导入副作用中分散初始化。
• Android/iOS 原生平台功能优先使用现有插件，按下述原生平台插件选型执行，避免重复实现原生能力。
• 小游戏必须单独验证；可选商业能力须有显式接口和已批准开关。
• 基础模块阶段建立统一音频服务与生命周期适配，按后台暂停与恢复约束实现后台暂停、前台原位置续播；保留手动暂停和静音状态，防止重复恢复、过期音效补播及已销毁实例复活，纳入基础包和 TDD。
• 基础模块实施必须完成基础显示约束：游戏填满实际可用视口；Android 宿主从启动首帧到运行全程无窗口标题栏或 ActionBar，并实现沉浸式全屏及前台/焦点恢复。启动主题、运行主题、窗口配置与视口/安全区适配纳入基础包和 TDD，不延后到场景实现阶段。

原生平台插件选型

• 实现原生平台功能前先检查项目已采用的插件；满足需求时直接复用。需要新增能力时优先评估 Capacitor 官方插件或能力提供方的官方插件，再评估维护活跃、许可适用且满足需求的社区插件；领域 Skill 已指定插件时遵守该领域合同。
• 选型核实插件对项目当前 Capacitor 版本、目标 Android/iOS 版本、所需 API、权限和生命周期行为的支持，并记录依赖版本、维护状态、许可、平台限制和验证方式；只安装当前需求实际使用的插件。
• 插件调用统一封装在平台适配层，通过项目公开接口向业务提供能力；业务和 Scene 不直接调用插件。Web/小游戏适配显式声明支持情况与失败语义，不以空实现伪装原生能力成功。
• 只有现有插件无法满足明确需求时才补充自建原生插件或直接原生实现；在 TDD 和实施包记录已评估插件、具体能力缺口与最小自建范围，避免重复实现插件已经提供的能力。
• 启动主题、Manifest、权限声明等必要宿主配置仍在原生工程维护。沉浸式全屏、系统栏控制和生命周期恢复等运行时能力同样优先使用插件，插件覆盖不了的部分再补最小原生代码；插件优先不降低冷启动首帧和恢复行为的验收要求。

执行与交接

新建游戏项目、实现基础模块或调整目录与模块边界时，先读取游戏项目目录规范，按入口/基础服务分层、场景功能聚合组织代码，明确资源、平台、测试和产物归属，并把实际路径与所有权写入 TDD 和实施包。制作前按产物目录与确认流转及产物存放与证据边界分开临时候选、确认成果、源素材、正式运行资源、人工作业审阅/验证产物和工作流机器记录；根级 evidence/ 不等于机器 evidenceRoot，已冻结引用路径保持原样。

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 并清理监听器；资源生产 1:1 基线与运行时 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/布局和正式可见资产仍在对应场景阶段完成。每个场景在自身阶段完成场景自有玩法、正式视觉、常驻 HUD、清理和联合证据；瞬态弹窗/显示层通过独立 DISPLAY_LAYER Work Item 完成上下文、UI、生命周期与证据，并独立验收，不作为宿主场景完成 V4 的前置。玩法独占规则、状态、碰撞和交互代码；美术可维护纯表现资源配置、布局/表现预制数据与视觉集成调整，但不得改变玩法规则、碰撞语义或状态所有权。为协作集成、触控、安全区、暂停恢复、后台切换和断网定义验证策略。
7. 对组件/资源集和场景路径，在 V1 定义每场景纹理、图集、帧数、动画采样、纹理内存、过绘、Draw Call 和最大纹理预算；在 V3 将预算写入机器清单，V4 只验证。原子资源必须引用已有适用且有效的玩法视觉契约与预算基线，否则升级路径；不得在验收时临时放宽。
8. 在 TDD 按需记录核心、移动平台、数据/API、复杂玩法、高级视觉和商业能力档；每项包含启用原因、拒绝的轻量方案、运行时性能与平台风险、验证命令和所有者。涉及服务时记录契约版本、认证授权、幂等/重试/超时、兼容、迁移/回滚、测试、监控与备份恢复；服务端不在范围时只记录外部依赖、所有者和客户端边界。
9. 在 TDD 定义本地服务身份、默认模式、主机/端口和健康检查。启动开发或预览服务前检查监听进程、命令行、项目根目录与健康状态；身份一致且健康时直接复用，不得重复启动。
10. 共享基础完成后提供代表性 Vite/Phaser 启动、Boot/首场景、资源和适用插件烟测；关键玩法流完成后提供主目标平台运行烟测；仅最终集成/G3/release 执行完整平台矩阵。不得由局部证据宣称全平台通过，不得自动发起真机验收。
11. F0 完成后提交范围与流程事实；F1 提交规格映射；F2 提交独立架构结论；F3 提交候选 SHA、实际命令证据和未覆盖项。

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