pelican-engine 0.0.0-stage → 0.3.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,268 @@
+# 总体架构与实现边界
+
+状态：研发设计提案，尚未实现。产品要求以 [DECISIONS.md](DECISIONS.md) 为准；本文中的接口名、包名、目录与数据结构为拟定设计，M0 原型后通过 ADR 固化。版本与依赖选择依据见 [RESEARCH.md](RESEARCH.md)。
+
+## 1. 总体结构
+
+```text
+外部 AI 编码工具（读取文件 / 执行终端 / 检查画面）
+    ├─ 引擎研发：实现、验证、维护 pelican
+    └─ 游戏开发：仅使用公开 SDK 编写游戏
+                      │
+               TypeScript 游戏项目
+         ┌────────────┼──────────────┐
+      声明定义      玩法系统代码     材质/后处理/计算图
+         └────────────┼──────────────┘
+                 pelican 编译器
+      类型/规则检查 → 多类 IR → 依赖/变体分析
+          → 资源构建 / JS 构建 / 管线准备计划
+                      │
+            版本化清单 + 代码 + 资源分块
+                      │
+                 pelican 运行时
+        ECS / 调度 / 资源 / 事件 / 状态 / 诊断
+          ├─ 渲染：光栅 / 混合光追 / 路径追踪
+          ├─ 刚体 / 布料 / 绳索 / 软体 / 流体
+          ├─ 动画 / 世界 / NPC / UI / 音频 / 玩法
+          └─ 内部 Three.js WebGPU / WASM / Web APIs
+                      │
+                  浏览器游戏
+```
+
+外部 AI 不参与每帧运算；开发控制协议是可移除的工具通道。游戏行为由编译后的普通程序、状态机和数值算法执行。
+
+## 2. 公开 SDK 的表达能力
+
+### 2.1 统一概念
+
+| 概念 | 拟定职责 | 关键规则 |
+| --- | --- | --- |
+| Project / Game | 项目、启动场景、能力与构建配置 | 合理默认值，推导优先，不重复手写依赖清单 |
+| Component | 字段类型、默认值、版本、序列化策略 | 有稳定类型 ID；动态状态不混入资源定义 |
+| System | 阶段、查询、读写集合、执行函数 | 明确顺序和资源权限；有诊断与性能归属 |
+| Entity / Prefab | 实例句柄、可组合定义、覆盖与继承规则 | 实体身份不是内部对象引用；继承冲突可定位 |
+| Scene / World / Chunk | 内容、空间和流送组织 | 稳定内容 ID 与运行实体身份分离 |
+| Asset | 类型化引用、变体、加载和释放 | 不暴露底层纹理/缓冲；共享所有权明确 |
+| Material / Effect / Compute | 受控图与参数接口 | 编译为引擎 IR，不泄露 TSL/WGSL/设备对象 |
+| State / Event / Command | 状态、通知和延迟操作 | 约定顺序、生命周期、消费与错误行为 |
+| Test / Probe | 输入、状态断言、测量与画面捕获 | 开发测试接口不成为生产游戏必要依赖 |
+
+游戏侧可自由新增组件、规则和系统。限制底层访问是为了让资源、调度、编译和诊断保持一致，不限制游戏题材或玩法类型。当前唯一公开入口为 `pelican-engine`；仓库工具解析同一 SDK 源定义，npm 分发该定义生成的 JavaScript 与类型声明，不提供另一套包装 API。两渠道共用 CLI、AI 游戏开发指引和结构化协议。
+
+### 2.2 三类程序分别处理
+
+1. **内容声明**：组件 Schema、预制体、场景、资源、状态机、时间轴等转换为可验证的数据定义。静态字面量和可分析组合优先；确需生成的内容通过显式、确定的构建任务产生。
+2. **玩法逻辑**：受约束 TypeScript 正常编译为 JavaScript；保留函数与模块语义，通过公开查询、命令和服务执行。不尝试全程序证明，也不把任意函数塞进 JSON。
+3. **图形计算**：通过引擎提供的类型化节点/表达式构造图，编译为材质、后处理或计算 IR，再由内部适配层生成 TSL/着色器。循环、缓冲访问、资源读写等有明确可校验规则。
+
+三类代码不共用模糊的“所有内容都可静态编译”承诺。需要 IO 的构建任务与内容定义分开；不在扫描项目时随意执行任意游戏模块的副作用。
+
+### 2.3 自定义能力的边界
+
+- 通用 TS 的计算和控制流可以用于玩法系统；需要时间、随机、输入、资源、存储等时通过引擎服务取得。
+- 游戏内扩展只能组合公开能力；不提供 `getThreeObject()`、`getGPUDevice()`、任意原生 shader 注入等逃逸接口。
+- 建议检查公开包导入、内部路径引用、DOM/图形对象误用及生命周期违规；这些属于开发规则检查，不承诺安全沙箱。
+- 高性能批处理通过公开的类型化视图/查询/命令接口提供，既避免每帧对象分配，也不把内部内存布局变成永久 API。
+- 扩展点必须有资源声明、生命周期、能力要求、序列化和诊断约定。不能只给一个回调而让使用者自建完整子系统。
+- 新扩展需求做成能力缺口报告，由引擎侧决定演进；游戏开发任务不暗改引擎。
+
+### 2.4 建议统一的基础约定
+
+以下为 M0 需要验证并固化的候选，尚不是已实现 API：
+
+- 单位采用米、秒、千克和弧度；2D 明确世界单位与显示像素映射，不隐式混用。
+- 世界右手系、Y 向上；相机前向、纹理坐标、2D 屏幕坐标和外部模型转换规则在接口参考中单独说明。
+- 颜色输入标记色彩空间，光照运算使用统一线性工作空间；不能让不同渲染模式自行解释同一颜色。
+- 数值、向量、矩阵、四元数提供统一类型和零额外分配的批量操作，游戏不依赖 Three.js 数学类。
+- 同步调用、异步任务、事件和资源释放分别使用一致返回规范；错误可分类，避免同类方法有时抛异常、有时返回 undefined、有时仅打印日志。
+- 可序列化数据与函数、资源句柄、临时查询视图区分；瞬时视图有有效期，不允许跨结构修改后继续持有。
+- 公开服务默认配置应可解释，任何自动优化可在报告中追溯；默认值不是隐藏规则。
+
+## 3. 编译器与内容构建
+
+### 3.1 流水线
+
+| 步骤 | 输入与处理 | 输出和错误定位 |
+| --- | --- | --- |
+| 发现项目 | 项目清单、本地引擎路径、版本/入口 | 项目上下文；不依赖 cwd、Git 或固定盘符 |
+| 类型与规则检查 | TS 程序、公开接口索引、导入关系 | 类型结果、规则诊断、源码位置 |
+| 提取声明 | 定义调用、Schema、引用与显式生成任务 | 定义 IR；不支持的表达形式明确报错 |
+| 建立链接 | 类型/内容/资源/系统依赖和动态引用集合 | 稳定 ID、依赖图、未解析引用报告 |
+| 语义检查 | 系统循环依赖、组件字段、材质类型、资源访问 | 有原因的错误，不依赖运行时偶然发现 |
+| 构建内容 | 资产转换、场景分块、几何/纹理变体 | 内容寻址资源、来源与工具版本记录 |
+| 编译图形 | 材质/计算图、后处理、模式支持矩阵 | 后端中间结果、参数布局、管线准备清单 |
+| 构建程序 | 玩法逻辑、运行时模块与服务引用 | JS 分块、source map、模块可达性报告 |
+| 打包验证 | 分包、路径、许可与加载清单 | 可部署 `dist/`、可解释报告、版本清单 |
+
+浏览器相关的最终 GPU 管线创建仍发生在实际设备。构建期只能准备代码/描述和预热计划，不能承诺离线生成跨所有 GPU 可复用的机器码。
+
+### 3.2 IR 和单一事实来源
+
+建议内部区分：`DefinitionIR`、`SystemIR`、`MaterialIR`、`ComputeIR`、`SceneIR`、`AssetGraph`、`BuildManifest`。各 IR 有版本、来源位置、依赖和稳定 ID。一个声明更改可以追踪到受影响的产物和诊断。
+
+公开组件/资源/命令定义采用同一元数据源派生类型、Schema、接口参考和索引。复杂 API 可保留手写解释，但签名和示例必须自动验证。具体生成方案通过 M0 验证，不同时维护三份手工 API 真相。
+
+### 3.3 缓存与可重复构建
+
+缓存键包含输入内容、引擎版本、编译器版本、目标能力、选项和转换工具版本；不能仅依赖文件修改时间。输出清单排序稳定，记录必要来源，构建时间戳不污染内容哈希。
+
+动态资产用公开声明指定可选集合或外部 provider；禁止依赖分析失败后默默漏包。无法确定的内容可在报告中明确标记为外部依赖，不强制所有内容静态内置。
+
+### 3.4 增量与热更新
+
+变更传播沿依赖图进行。玩法代码、定义、Schema、材质和资源分别有热更策略。运行时保存状态与新定义默认值不能混合套用；Schema 变化须迁移或重载。更新过程先准备新资源，再在安全提交点切换，失败保留上一可用版本或明确重启。
+
+热更新报告记录输入版本、受影响对象、状态处理、重启情况及失败原因。正式验证始终从冷启动复跑。
+
+## 4. 运行时核心
+
+### 4.1 世界和身份
+
+采用 ECS 为主的统一世界状态。内部内核可封装成熟 ECS 或有限自研，由查询、结构变化、快照等原型决定，公开 SDK 不依赖该选择。
+
+实体句柄包含失效检测信息；持久化内容 ID、跨流送引用与运行时句柄分开。命令缓冲处理创建、销毁、组件结构变化，规定同帧可见性。资源句柄另行管理，不能把实体存活等同于 GPU 资源存活。
+
+### 4.2 调度与时钟
+
+定义固定模拟阶段、展示阶段和异步工作队列。初步阶段：输入采样 → 游戏前置逻辑 → 动画意图/根运动 → 物理与约束 → 后置逻辑/事件 → 导航和世界提交 → 展示姿态 → 渲染。
+
+这只是待验证顺序，IK、物理骨骼、GPU 求解和动画事件需明确分阶段处理，不能用单一回调承担全部前后依赖。各系统声明读写集合、前后约束与执行频率。声明权限有助于诊断，不代表任意 JS 函数可自动多线程化。
+
+控制随机源、模拟 tick 和输入时间；异步资产、音频和外部事件以可记录提交事件接入。渲染插值不改变模拟权威状态。
+
+### 4.3 CPU、Worker、WASM 与 GPU
+
+- CPU：玩法、调度、权威状态、资源/任务管理。
+- Worker/WASM：有证据收益的刚体、导航、资产处理等模块。
+- GPU compute：图形计算，以及适合的粒子、形变和模拟；不是强制所有物理上 GPU。
+- 通过明确数据所有权和交换边界协作，避免主线程逐帧全量读回 GPU。
+- SharedArrayBuffer/多线程路径若需要服务器额外响应头，必须报告部署要求；默认静态 `dist/` 仍应提供不依赖这类头的正常执行路径，不能暗中破坏 D38。
+
+### 4.4 生命周期与诊断
+
+资源采用显式所有权/作用域、共享引用和延迟释放。卸载、热更、设备丢失与失败重试必须经过统一路径。开发态追踪实体、系统、资源及 GPU 分配的归属，生产态保留必要错误和能力报告。
+
+GPU 内存和计时数据并非所有平台都可准确取得。报告区分实测、估算和不可用；不把缺少指标写为零成本。
+
+## 5. 渲染架构
+
+### 5.1 公共表示与后端
+
+引擎维护私有渲染场景数据库：几何/实例、材质 IR、灯光、相机、形变结果、可见性和变更标记。ECS 是游戏权威状态，渲染数据库是派生状态，不让游戏直接操作内部 Three.js 场景树。
+
+Three.js WebGPU/TSL 作为内部基础；光追加速结构、路径积分、降噪及与动态模拟的同步很可能需要独立实现或深度适配。不得因为选了 Three.js 就宣称这些已被包含。
+
+当前按 D44/D45 使用 WebGPURenderer 的内置 WebGL2 回退，不手动创建 WebGPUBackend，也不因缺少 navigator.gpu 提前失败。初始化后显式记录实际后端，公开只返回普通能力数据；不降低作者画质配置。WebGL2 上 compute/光追/降噪明确不可用，模式配置与恢复先校验再提交，不静默替换。主里程碑仍检查真实 WebGPU 硬件证据，回退独立验证。
+
+### 5.2 三种模式
+
+| 模式 | 正式职责 | 共同接口 |
+| --- | --- | --- |
+| 光栅 | 物理材质、光照、阴影、环境、透明、后处理和稳定性 | 场景/材质/灯光/相机/质量配置 |
+| 混合真实光追 | 光栅主可见性结合真实场景射线的阴影/反射/间接光 | 加速结构、采样、降噪、调试视图 |
+| 全路径追踪 | 动态交互下的多次反弹、发光/透明等材质与累积处理 | 采样预算、反弹、重投影、历史管理 |
+
+模式差异通过支持矩阵公开。自定义材质需定义各模式可执行语义；无法转换的节点在检查时指出，不静默替换为别的效果。屏幕空间反射可作为另一效果，但不能标成真实场景光追。
+
+### 5.3 动态场景关键链路
+
+区分刚性实例变换、蒙皮/Morph、布料/软体形变、流体表面、拓扑变化、地形编辑和流送增删。各类变更标明是否需要 refit、rebuild 或替代表示，并处理包围盒、法线、运动信息和历史失效。
+
+光追结构必须支持几何/实例更新和安全切换。降噪依赖的深度、法线、运动信息与模拟/动画一致。对象显隐、传送、相机切换、材质与灯光变化都需要明确的历史重置策略。
+
+M0 实测动态结构更新、形变、采样降噪和呈现的时间与内存成本。WebGPU compute 软件遍历不等于使用显卡 RT 单元；不将实验特性作为基础运行条件。
+
+### 5.4 质量与性能
+
+质量配置显式列出分辨率、采样、阴影、反弹、降噪、LOD 等。可以由游戏选择自适应策略，但基准测试固定配置并报告实际效果，禁止静默降级。
+
+1080p60 是核心目标；为各模式建立具体负载和质量测试。不能在没有硬件实测时承诺所有模式、任意场景都 60 FPS。高质量资产、材质正确性和画面稳定性独立于帧率评估。
+
+## 6. 物理、形变与耦合
+
+### 6.1 模块组织
+
+2D/3D 刚体、角色、关节和车辆与布料、绳索、软体、流体分别实现或封装专用求解器；通过统一时间、单位、材质、碰撞过滤、句柄和事件语义接入。2D 与 3D 默认是不同物理世界，2.5D 可采用受约束 3D 或 2D，由游戏配置，不宣称两者自动相互碰撞。
+
+GPU 物理选择不能只看单模块速度，还要计入 CPU↔GPU 交换、快照和渲染更新。候选算法需以真实交互和稳定性选择，而非在文档中直接锁定尚未验证的实现。
+
+### 6.2 明确交互，不用演示代替系统
+
+刚体与布料/绳索/软体/流体至少要有代表性的双向作用验证。高级模拟之间的具体耦合契约和组合范围在 M0 明确，最终写入公开支持矩阵；不能暗示所有精度、所有组合无限支持。
+
+力/冲量交换、接触数据所有权、约束求解顺序、子步与延迟必须记录。禁止用“碰到了会动”的单向动画代替要求的交互模拟。
+
+### 6.3 可保存与可调试
+
+定义检查点能恢复哪些状态、哪些需重建；GPU 粒子或网格状态的导出、恢复与耗时单独测量。调试接口能查询约束、接触、能量/稳定性代理指标和求解耗时，避免只观察画面猜测。
+
+## 7. 世界、资源和内容一致性
+
+场景分块、实体持久状态、资产分包和空间导航使用不同索引，不把它们绑成同一文件。资源内容寻址、加载优先级、取消、预取和驻留预算由资源管理器协调。
+
+世界修改采用事务式提交：生成几何 → 物理/导航/渲染准备 → 校验 → 安全切换 → 持久状态记录。对不能同一 tick 完成的更新，提供明确的 pending/ready 状态与可配置交互行为，不留下“看得见但碰不到”的隐性窗口。
+
+大范围坐标采用世界分区/局部原点等候选方案；渲染、物理、音频、导航和存档必须共用坐标转换契约。程序化生成保存种子、生成器版本及用户修改，不只保存最终截图。
+
+## 8. 动画、NPC、UI、音频和玩法
+
+- **动画**：姿态、根运动、IK/重定向、物理骨骼与形变分阶段处理；过场可分支、跳过、恢复，并正确交接控制权。
+- **NPC**：感知、记忆、决策与移动规划分离；支持地面、飞行、水中，动态世界修改触发局部更新；每个行为可查询原因与失败状态。
+- **UI**：统一代码接口，覆盖屏幕和世界 UI；内部 DOM/canvas 混合或其他路线先验证 IME、文本、焦点、手柄、捕获和性能。底层 DOM 实现不等于给游戏直接开放 DOM。
+- **音频**：独立音频时间与模拟/过场建立映射；空间/混响/混音/互动音乐可查询。必须处理浏览器用户手势要求：游戏提供开始交互，自动测试用真实自动化输入触发，不承诺无手势强行有声。
+- **玩法**：引擎通用机制与可复制游戏模板分层。背包等模块可以组合、替换规则，示例只使用公开 API。
+- **平台服务**：提供必要的输入、用户设置、本地保存、异步资源/provider 和可选 HTTP 能力；不要求构建后端或运行时 AI 服务，不将整个单机能力与远程服务绑定。
+
+## 9. 状态、回放、存档和迁移
+
+划分权威状态、可重建派生状态、外部资源、瞬时显示状态。保存格式引用稳定类型/资源 ID，记录版本、随机源、模拟时间和必要事件。
+
+玩家存档、开发检查点、输入回放分别定义用途和兼容规则：存档注重长期恢复，检查点可保存更详细状态，回放依赖版本与受控事件。GPU 物理和音频等不保证跨机器逐位相同；明确容差与不确定因素。
+
+设备丢失时决定哪些可重建、哪些需从检查点恢复，无法恢复时给出诊断而非继续在坏状态运行。版本迁移以拷贝、验证、提交方式进行，支持无 Git 恢复。
+
+## 10. 拟定目录与项目形态
+
+以下是未来目录，不代表目前已经创建。
+
+```text
+pelican/
+  AGENTS.md / README.md / LICENSE
+  engine.manifest.json       # 名称、版本、公开入口和协议版本
+  tools/                     # Windows 启动、环境检查和 CLI 源码
+  packages/
+    schema/ compiler/ sdk/ runtime/ assets/
+    renderer/ physics/ animation/ world/ navigation/
+    ui/ audio/ gameplay/ diagnostics/ testkit/
+  templates/                 # 可复制修改的游戏模板
+  examples/                  # 只调用公开 API 的最小可运行例子
+  games/                     # 默认游戏工作区
+  tests/                     # 单元、契约、集成、画面、性能、AI 使用测试
+  experiments/               # M0 原型，不能作为正式运行时隐式依赖
+  docs/                      # 需求、架构、API、ADR、任务与操作指引
+  evidence/                  # 可审查证据索引，小型基线与报告
+  .pelican/                 # 本地可再生缓存，不是唯一证据存储
+```
+
+外部游戏目录包含自己的项目清单、内容、源码、测试与构建配置；明确记录本地引擎位置和版本。工具解析外部路径，不依赖全局 npm link 或导入内部文件。目录搬移后允许重新定位本地引擎，不把机器绝对路径写进发布产物。
+
+npm 项目通过常规本地依赖安装 `pelican-engine`，只锁定精确版本，无需本地引擎源码路径。依赖准备完成后，可离线创建、检查、开发、构建与运行；编译包、API 索引、运行时版本和校验清单需一致。npm 暂存产物位于 `.pelican/npm/`，与静态游戏 `dist/` 隔离；许可和 AI 文档随包交付，证据、示例资产和源码映射不随包交付。
+
+未来 `dist/` 至少包括入口 HTML、代码、资产/分块、版本化加载清单和所需第三方声明；开发控制通道默认剔除。使用相对基址或可配置基址，测试根路径和子路径部署；必要的 MIME、HTTPS/安全上下文、跨域等条件由发布检查报告解释，不绑定服务器厂商。
+
+## 11. 初步技术取舍
+
+| 范围 | 候选方法 | 当前决策状态 |
+| --- | --- | --- |
+| 工作区/依赖 | 固定 Node 版本、单一包管理器和锁文件、仓库命令入口 | M0 选择具体版本；不要求全局安装包管理器 |
+| TS/构建 | TypeScript 类型系统与编译 API，现代打包器处理程序与开发服务 | M0 验证提取、增量和 source map，避免无谓自研打包器 |
+| ECS | 封装成熟库或有限自研，公开 API 隔离实现 | 依据结构变更、查询、快照测量决定 |
+| 渲染 | Three.js WebGPU/TSL + 自有场景/材质/计算 IR | 产品基础已定，具体版本及内部适配待验证 |
+| 光追/PT | WebGPU compute、加速结构和降噪，候选现有项目仅供评估 | 高风险原型，不把 WebGL 实现当 WebGPU 成果 |
+| 模拟 | 刚体可用 WASM 库；高级模拟与耦合独立评估 | 不宣称单库覆盖全部需求 |
+| 内容 | glTF/纹理压缩、网格优化、字体/音频等处理器适配 | 先建立来源和版本记录，再按能力引入 |
+| 自动测试 | 浏览器自动化 + 引擎测试协议 + 截图/状态/性能证据 | 验证真实 GPU 路径，不盲信 headless 指标 |
+
+## 12. 不建设的内容
+
+不建设可视化编辑器、运行时模型/智能体、资产生成服务平台、防篡改系统、必需的云控制台或 AI 编排产品。多人联机不进入本次首发。上述边界用于集中实现已确认的完整能力，不限制未来游戏作者的创作和资产选择。

package/docs/CAPABILITIES.md

@@ -0,0 +1,264 @@
+# pelican 首发能力与验收矩阵
+
+> 文档性质：中文规划与验收规范，不是引擎实现或功能交付声明。  
+> 规划日期：2026-11-04。  
+> 当前状态：M0 原型已通过集成与独立 AI 验收，结果见 `evidence/m0/acceptance.json`；本文 53 项完整首发能力尚未正式逐项验收。以下矩阵保留完整交付要求，原型子集不代表对应 CAP 已完成。  
+> 范围：已确认的能力全部属于首发正式范围。分阶段实现不等于移出首发；M0 用于确定算法、约束、负载和可行性，不自动授权删减需求。
+
+需求依据为 [DECISIONS.md](DECISIONS.md)，实现边界参见 [ARCHITECTURE.md](ARCHITECTURE.md)，研发排期参见 [ROADMAP.md](ROADMAP.md)。本文聚焦验收，不替代需求决策。
+
+## 1. 范围、术语与矩阵规则
+
+### 1.1 产品边界
+
+- pelican 面向外部 AI 编码工具。人提出需求与反馈，引擎研发、游戏开发、验证与维护均由外部 AI 执行。游戏运行时不包含大模型或 AI 智能体；NPC 指普通代码实现的游戏行为。
+- 编译型 TypeScript SDK，无可视化编辑器。场景、资源引用、UI、材质、计算任务和演出均可通过代码定义。游戏内完整 UI 是正式能力。
+- 游戏通过完整公开 API 开发，可定义组件、系统、预制体、材质、后处理和计算任务。公开类型与对象不泄漏 Three.js、TSL、原生 WebGPU 或物理依赖。规范不提供绕过封装的路线，不设计防篡改、账号、授权平台或强制封禁。
+- 图形后端优先 WebGPU，允许 Three.js 内置 WebGL2 光栅回退，不主动降画质；compute/混合/路径追踪/降噪在不支持时明确报错并给可用模式。3D、2D、2.5D、光栅、混合真实光追、全路径追踪均属正式范围，不能用屏幕空间近似代替真实场景光线追踪。主里程碑硬件证据仍限定真实 WebGPU；WebGL2 独立实测。
+- Windows 是开发环境支持范围。玩家端按实际能力运行，不设操作系统、浏览器或版本白名单。测试设备只承担复现与衡量，不是玩家准入条件。
+- GitHub 仓库、ZIP 解压目录、复制目录、外部游戏项目和 npm 安装均是正式入口；共用公开 SDK/CLI/AI 能力，npm 使用不需要引擎源码。不依赖 Git 元数据或固定路径。允许首次联网准备环境；本地依赖与资产齐备后的开发、测试、构建和运行不依赖在线服务。npm 包附许可与版本校验，不含源码映射、证据、示例或游戏资产。
+- 不管理或限制资产创作工具。基础资产应足以形成可玩游戏；高质量成品需要高质量外部资产、生成服务产物或自行生成的内容。引擎必须能处理并呈现这些内容。
+- 首发为单机引擎；多人联机不在本文正式验收范围。发布输出为可部署到 Web 服务器的 `dist/`，不依赖 pelican 在线服务。
+
+### 1.2 编号、阶段与依赖
+
+- `M0-xx`：高风险验证任务；`CAP-xx`：正式能力任务；`INT-xx`：跨模块契约；`ACC-xx`：综合验收场景。
+- 所有条目初始状态均为**未实现**。后续状态只可基于证据更新为实现中、待验收、阻塞或已验收；接口占位、空实现和单张截图均不能标记完成。
+- 表中依赖是开始集成与验收的最小前置条件，不代替完整研发任务图。可先并行做隔离原型，未通过前置条件不得宣称最终集成通过。
+- 里程碑采用研发计划的 M0–M8 编号，见第 11 节。里程碑用于依赖和验收组织，不是多个缩水版本的首发。
+- 风险列表示必须主动验证的失败方式，不表示接受缺陷。风险记录应绑定责任任务、复现材料、处理结论和残余限制。
+- 本文提到的负载、容差、资源预算、帧时间、恢复时间和质量阈值，除已确认的基准目标外均由 M0 产出候选值，再经集成验证锁定；不得用随意填写的数字代替测量。
+
+## 2. 统一完成定义与证据契约
+
+每项正式能力必须同时满足以下条件：
+
+1. **接口可用**：公开类型、运行时校验、生命周期、错误语义、版本行为与可执行示例完整；游戏侧不需要修改引擎或调用内部依赖。
+2. **成功和失败均验证**：覆盖正常、边界、无效输入、缺失资源、取消、销毁、重复运行与相关的设备丢失恢复。不得靠忽略错误通过测试。
+3. **行为有断言**：测试能判定预期状态和事件，画面类能力同时有图像或序列证据；截图只能作为证据之一。
+4. **集成有证据**：满足对应 INT 契约和 ACC 场景；单模块演示不代替跨系统验证。
+5. **成本有记录**：记录启动、稳态、最坏事件、长时间运行及释放后的相关 CPU、GPU、内存、资源、加载和同步成本。指标不可用时标记原因，不用零值冒充。
+6. **可独立复测**：干净环境可按记录重跑；热更新成功不代替冷启动测试；依赖对话记忆或未记录人工操作的步骤不合格。
+7. **外部 AI 可用**：无研发历史上下文的游戏开发 AI 能凭交付内容完成典型任务、理解诊断并修复错误。复杂能力需要代表性任务，不能只检查文档是否存在。
+8. **交付一致**：文档、类型、示例、构建产物和验收记录对应同一版本；未通过项保持未验收，不用实验标记抵扣正式首发范围。
+
+每次验收证据至少记录：任务编号、源码与内容版本/摘要、依赖锁定信息、测试输入、场景种子、运行模式、实际后端、设备与驱动/浏览器信息、执行步骤、预期与实际结果、阈值来源、原始日志及产物路径。根据任务附上状态轨迹、视频/图像序列、音频、性能采样、快照或回放文件。证据保存在对应项目的可追溯位置，不要求全部大文件进入引擎 Git 仓库。
+
+非确定结果需记录重复次数、误差指标、随机源和通过规则；偶发通过不构成验收。证据自身应可关联版本并验证完整性，不能只留一句通过结论。
+
+## 3. M0 高风险验证矩阵
+
+以下任务全部未实现。M0 必须输出可运行原型、原始测量、候选方案比较和可追溯决策，不能仅提交调研文字。
+
+| 编号 | 验证任务与必需输出 | 依赖 | 核心风险 | 必需证据与退出要求 |
+| --- | --- | --- | --- | --- |
+| M0-01 | 最小 TS 定义→校验→中间表示→运行数据链路；覆盖动态引用与错误源映射 | 无 | 把任意 TS 当成可静态分析；执行定义时产生隐藏副作用 | 正反例、依赖图、生成数据、定位结果；明确可编译子集、运行时逻辑边界与缓存失效规则 |
+| M0-02 | 实际 WebGPU 后端、光栅/混合光追/PT 共用场景与材质；相机运动、骨骼、Morph、几何变形 | 无 | 隐性 WebGL 回退；BVH 更新与降噪成本；材质不一致 | 后端初始化与执行证据、动态序列、交叉模式图像、GPU/CPU 时间；确定加速结构、更新与光线执行方案，不假设专用光追硬件可用 |
+| M0-03 | 刚体与布料/绳索/软体/流体的代表性交互及状态导出 | 无 | 多求解器耦合不稳定；CPU/GPU 搬运与回读卡顿 | 受力、碰撞与状态轨迹、稳定性和收敛实验；逐项填写第 8 节的耦合及组合决定 |
+| M0-04 | 外部 AI 从干净目录完成修改、运行、输入驱动、查询、截图、修复与复测 | 无 | 依赖人工点击或特定插件；诊断无定位；暗含对话知识 | 无历史上下文任务记录、失败修复过程、冷启动复测；终端与文件契约可独立使用 |
+| M0-05 | 1080p/60 FPS 高质量档代表负载；三种渲染模式和重模拟分别测量 | M0-02、M0-03 | 均值掩盖卡顿；误把机器配置当玩家门槛 | 锁定测试硬件、软件版本、模式、负载、画质参数及帧时间阈值；不虚构 RT/PT 性能承诺 |
+| M0-06 | 大世界流送、动态世界修改及跨区状态恢复 | M0-01、M0-02、M0-03 | 坐标精度、旧碰撞/旧导航、异步时序竞争 | 连续移动与修改轨迹、同步时序、驻留/释放曲线；确定分块、坐标、脏区与提交策略 |
+| M0-07 | GPU 模拟、音频与流送参与的录放/快照成本验证 | M0-03、M0-06 | GPU 回读停顿；快照体积爆炸；非确定性破坏恢复 | 捕获/恢复时间、字节量、回读等待、回放偏差；确定精确恢复、容差恢复或显式重建的分项契约 |
+| M0-08 | 完整游戏 UI 风险预检；中文输入、手柄焦点及世界空间交互专项原型在 M1/M2 完成 | M0-04 | 文本输入与画面渲染冲突；自动化无法检查 UI | M0 输出风险与验证计划；M1/M2 提交中文组合输入轨迹、布局/命中断言、焦点序列与画面；公开 API 不暴露 DOM |
+
+M0 不允许以删掉动态 PT、把交互模拟改成视觉效果或把自动化步骤交给人完成来退出。不可行或尚无依据的组合必须保持阻塞，列明证据、替代算法与需要确认的取舍；不能静默降低既定目标。
+
+## 4. 公开接口、编译与 AI 使用能力
+
+下表全部未实现，主要在 M1 建立，后续各里程碑持续补齐，M7/M8 完整复验。
+
+| 编号 | 首发能力及验收边界 | 依赖 | 主要风险 | 必需证据 |
+| --- | --- | --- | --- | --- |
+| CAP-01 | 自包含目录识别与 Windows 自动准备；Git/ZIP/复制、本地/外部项目路径均可用 | M0-04 | 路径硬编码、依赖 Git、初始化覆盖游戏 | 含空格与中文路径、无 `.git`、迁移目录、重复初始化、网络失败恢复及离线缓存复用记录 |
+| CAP-02 | 强类型公开 SDK；组件、系统、预制体、资源句柄、生命周期与错误契约 | M0-01 | 类型泄漏、失效句柄、同功能多套相悖用法 | API 类型检查、内部引用诊断、销毁后访问负例、仅公开 API 的示例；检查返回对象也无底层泄漏 |
+| CAP-03 | 编译定义、Schema 校验、源映射、可追溯中间表示 | M0-01、CAP-02 | 错误定位丢失；编译执行不受控副作用 | 有效/无效 TS 定义、循环引用、增量变更、错误位置与稳定错误码；相同输入构建差异解释 |
+| CAP-04 | 模块/资源/材质/计算依赖分析，按需编译、分包与动态引用声明 | CAP-03 | 动态资源漏包、变体数量膨胀 | 包含原因图、体积报告、动态加载验证；未用重模块不启动、不无条件驻留 |
+| CAP-05 | 增量编译与安全热更新；默认值和运行状态策略明确 | CAP-03、CAP-04、CAP-07 | 缓存过期；旧新逻辑混合；旧 GPU 资源泄漏 | 修改逻辑/Schema/资源/材质/UI 的测试；兼容保留、不兼容重启、失败恢复与冷启动对照 |
+| CAP-06 | 统一时间、固定步长、随机源、系统依赖与命令提交 | CAP-02 | 帧率影响玩法；写冲突与结构修改时序不明 | 不同渲染帧率下状态轨迹、依赖循环负例、系统读写诊断；声明读写不等同自动安全并行 |
+| CAP-07 | 实体/资源生命周期与事务性变更；异步任务取消及过期结果处理 | CAP-02、CAP-06 | 悬空引用、重复释放、取消后回写失效实体 | 创建销毁压力、跨帧取消、资源共享引用、失败回滚与驻留恢复曲线 |
+| CAP-08 | 终端与文件标准入口、结构化 Schema 结果、长任务进度/取消/超时 | M0-04、CAP-02 | 只能人工读日志；后台任务失控 | 成功/失败/取消输出样本、退出状态、任务查询与进程清理；不要求插件或专用 AI 平台 |
+| CAP-09 | 运行态实体/资源/系统查询、测试输入、时间控制与画面捕获 | CAP-06、CAP-08 | 查询改变游戏时序；测试绕过真实交互 | 实际输入和内部状态对照、暂停单步、序列捕获；区分测试注入与普通游戏行为 |
+| CAP-10 | 随版本文档、AI 入口指引、可执行示例与错误修复说明 | CAP-02、CAP-08 | 文档与 API 漂移；只能凭研发者记忆使用 | 示例构建和行为测试、接口覆盖报告、独立 AI 使用任务及问题回流记录 |
+
+## 5. 渲染、资产与大世界能力
+
+全部未实现；按 M2 基础光栅与资源、M3 高级渲染、M5 大世界等分工推进，在 M7/M8 综合复验。
+
+| 编号 | 首发能力及验收边界 | 依赖 | 主要风险 | 必需证据 |
+| --- | --- | --- | --- | --- |
+| CAP-11 | WebGPU 优先及 Three.js 内置 WebGL2 回退、能力检测、设备/上下文丢失与失败诊断 | M0-02、CAP-07 | 仅检测 navigator.gpu；隐藏后端；伪装不支持功能或静默降画质 | 真实 WebGPU 为主门禁，WebGL2 独立实测出画面、模式/compute 错误码、资源生命周期及上下文恢复；公开能力数据与状态栏一致 |
+| CAP-12 | 统一 3D/2D/2.5D 场景、相机、精灵/图集、排序与瓦片地图 | CAP-02、CAP-11 | 透明排序、坐标/像素规则冲突 | 混合场景运动序列、正交/透视切换、精灵动画、瓦片碰撞关联与命中测试 |
+| CAP-13 | 高质量光栅：PBR、环境照明、动态灯光/阴影、透明、雾/大气、抗锯齿与后处理 | CAP-11、CAP-12 | 闪烁、阴影不稳定、色彩空间错误 | 材质/照明参考、运动序列、曝光/色调映射/调色检查、透明组合与性能记录 |
+| CAP-14 | 混合真实场景光追：反射、阴影、间接光及与光栅的组合 | M0-02、CAP-13 | 屏幕外缺失；加速结构旧数据；近似效果冒充光追 | 屏幕外遮挡/反射、动态物体、反弹测试；光线与命中诊断；区分真实追踪、近似与降噪 |
+| CAP-15 | 全路径追踪动态游戏：运动相机、运动实体、骨骼/Morph/模拟形变 | M0-02、CAP-14、CAP-30 | 累积污染、拖影、噪声、透明/发光材质偏差 | 连续玩法视频和逐帧状态、变更后历史处理、动态质量指标与成本；静态收敛图不合格 |
+| CAP-16 | 三模式共享场景/材质与显式切换，支持能力表及不支持项诊断 | CAP-13、CAP-14、CAP-15 | 静默换材质、禁效果或切模式 | 同场景三模式对照、切换状态与资源曲线；声明差异及限制，不要求逐像素一致 |
+| CAP-17 | 受控自定义材质、后处理、多通道效果及 GPU 计算 | CAP-03、CAP-11 | 图表达不完整；资源越界；公开底层对象 | 顶点变形/采样/反馈/计算任务、类型与越界负例、依赖和释放；无任意 WGSL/GLSL 注入路线 |
+| CAP-18 | 实例化、批处理、剔除、LOD、管线准备与资源预算诊断 | CAP-04、CAP-13、CAP-17 | 批处理损害剔除；首次使用卡顿 | 稀疏/密集视图、动态实例增删、LOD 连续性、冷/热管线时间和显存估算；不可测指标明确标记 |
+| CAP-19 | 资产检查、转换、压缩、版本/来源记录及可替换引用 | CAP-03、CAP-04、CAP-07 | 质量损失、动画/材质丢失、引用断裂 | 高质量模型/纹理/动画/音频输入输出对照、损坏资产负例、压缩误差和成本；不绑定创作服务 |
+| CAP-20 | 基础资产与程序化内容足以无生成服务启动完整可玩游戏 | CAP-12、CAP-19 | 素材授权不明；基础素材被当成画质上限 | 来源清单、玩法样板、资产替换；高质量外部资产另建质量场景验证 |
+| CAP-21 | 大世界分块、预取、异步加载卸载、驻留与跨区实体/状态 | M0-06、CAP-04、CAP-07、CAP-18 | 穿越卡顿、跨区引用失效、资源泄漏 | 连续往返、快速移动、传送、失败/取消、状态恢复及驻留曲线 |
+| CAP-22 | 大范围坐标精度与原点/局部坐标管理 | M0-06、CAP-21 | 物理/音频/导航/光追使用不同空间 | 远距离移动和原点变化前后轨迹、约束、命中、声源与镜头对照；容差由 M0 锁定 |
+
+## 6. 模拟、世界、动画与行为能力
+
+全部未实现。物理类能力的参数范围、误差、稳定性、碰撞形状与耦合等级由 M0 明确，不能用无限规模、任意材质的隐含承诺代替支持范围。
+
+| 编号 | 首发能力及验收边界 | 依赖 | 主要风险 | 必需证据 |
+| --- | --- | --- | --- | --- |
+| CAP-23 | 2D/3D 刚体、碰撞/触发、材质、连续碰撞检测、射线/形状查询 | M0-03、CAP-06、CAP-07 | 穿透、堆叠失稳、查询与模拟不一致 | 高速/薄物体/堆叠/休眠唤醒/过滤测试，碰撞事件与查询结果；2D、3D 分别验收 |
+| CAP-24 | 角色控制、坡面、台阶、移动平台、跳跃及与环境交互 | CAP-23、CAP-12 | 卡边、穿越平台、帧率依赖、动画位移冲突 | 路线输入回放、接触和落地断言、平台运动轨迹；角色与动力学物体交互测试 |
+| CAP-25 | 关节、弹簧、连接断开与车辆动力学 | CAP-23 | 约束爆炸、质量比失稳、车辆仅视觉移动 | 力/位移轨迹、约束误差、断裂事件、转向制动与不同地面测试；公布支持的约束与车辆模型 |
+| CAP-26 | 布料与绳索真实交互模拟：碰撞、受力、锚点、牵引及撕裂/断开规则 | M0-03、CAP-23、CAP-25 | 穿透、约束误差、拓扑更新成本 | 布料推物/受碰撞、绳索悬挂/拉动物体的双向反应；锚点释放、重建与释放测试；撕裂支持范围在 M0 锁定 |
+| CAP-27 | 软体交互形变、接触、受力、形状/体积约束与状态查询 | M0-03、CAP-23 | 仅顶点动画；体积崩塌；碰撞形状不同步 | 压缩/回弹/碰撞/承重的形变与力轨迹、刚体反应、参数稳定区间与渲染同步 |
+| CAP-28 | 流体交互模拟、容器边界、流动、物体耦合与可观察状态 | M0-03、CAP-23、CAP-17 | 仅水面着色；边界漏液；耦合回读阻塞 | 注入/排出/溢流、容器运动、物体排液与浮力/阻力反应、体积/质量误差；M0 明确液体表示与可承载规模，不默许工业级 CFD 或全部气体模拟 |
+| CAP-29 | 种子驱动的地形/道路/布局/植被生成，建造/吸附/连接/拆除、物件破坏及高度地形/表面材质修改 | M0-06、CAP-19、CAP-21、CAP-23 | 修改后只有画面变化；碎片失控；状态丢失 | 生成复现、放置有效性、连接/拆除、破坏碎片、地形碰撞及脏区更新；修改前后导航/光追/存档对照；不承诺任意体素洞穴或无限拓扑破坏 |
+| CAP-30 | 骨骼动画、混合、分层、遮罩、状态机与事件 | CAP-06、CAP-19 | 状态过渡不连续、事件重复或漏发 | 姿态采样、混合/遮罩和过渡序列、不同时间步事件计数；动画状态可查询 |
+| CAP-31 | IK、重定向、根运动、程序化修正、Morph/表情及预制口型 | CAP-24、CAP-30 | 脚滑、比例不匹配、根运动与碰撞冲突 | 不同骨架映射、接地/持物、受阻位移、表情与口型时间对齐；形变同步到光追，不使用运行时 AI 生成 |
+| CAP-32 | 代码时间轴与可分支过场：动画、相机、音频、字幕、事件、转场 | CAP-30、CAP-31、CAP-37、CAP-40 | 跳过/变速后状态不一致；演出抢占玩法 | 分支、暂停、跳过、变速和中断后的状态断言、音画序列及恢复控制权记录 |
+| CAP-33 | 视野/遮挡、听觉事件、目标记忆、标签与范围感知 | CAP-23、CAP-06 | 把声音播放当感知；遮挡变化不更新 | 可见/遮挡/失忆/多目标测试、查询结果与决策输入轨迹；感知事件和音频播放职责分离 |
+| CAP-34 | 行为树、状态机、效用决策与自定义策略公开接口 | CAP-33、CAP-02 | 调度不透明；行为取消留下资源；运行时 AI 误引入 | 决策原因、节点生命周期、并发/取消/失败恢复；纯代码策略示例和自动断言 |
+| CAP-35 | 地面、飞行、水中规划与跳跃/攀爬等移动连接 | CAP-23、CAP-24、CAP-29 | 用地面导航冒充三维规划；不可达目标死循环 | 三类空间的可达/不可达场景、路径与执行轨迹、连接中断与诊断；M0 确定各自表示和算法 |
+| CAP-36 | 群体避障、队形、更新预算、动态障碍/建造/破坏后的重规划 | CAP-34、CAP-35、CAP-21 | 拥堵、旧路径、重建尖峰、跨区追踪失效 | 狭道/交叉流、门和移动障碍、地形改变、跨区任务；路径有效期和重规划延迟记录 |
+
+### 6.1 物理精度和设备差异
+
+- 固定步长、受控随机源和操作顺序是复现基础，但不承诺所有 GPU/CPU、驱动和浏览器逐位一致。
+- 相同受控环境验证可复现程度；不同运行设备使用 M0 锁定的状态误差、接触误差、约束误差、体积/质量偏差及玩法结果容差。
+- 容差需与物体尺度、时间窗、求解设置和用途关联；不能用放宽整体容差掩盖穿透、非有限值、失控能量或错误玩法结果。
+- CPU 与 GPU 求解、不同子步及异步提交必须记录。双向耦合需测量延迟和稳定性，不能只展示两个物体同时运动。
+- 2D 与 3D 物理各自正式支持；二者共处一个游戏的生命周期与事件必须一致，不自动承诺跨维度接触或统一求解。
+
+## 7. UI、音频、玩法、状态与交付能力
+
+全部未实现。依赖行体现验收所需前置，不规定具体内部库选型。
+
+| 编号 | 首发能力及验收边界 | 依赖 | 主要风险 | 必需证据 |
+| --- | --- | --- | --- | --- |
+| CAP-37 | 代码 UI：自适应布局、主题、列表虚拟化、滚动、弹窗、拖放、屏幕/世界空间 UI | M0-08、CAP-12、CAP-09 | 只能绘制不能操作；命中/遮挡和画面不一致 | 布局树、稳定控件 ID、焦点/可见/命中断言、长列表与世界空间遮挡交互序列；无 UI 编辑器依赖 |
+| CAP-38 | 字体、排版、富文本、可编辑文本、中文输入法及剪贴板接口 | CAP-37 | 组合输入损坏；字体缺字；异步剪贴板失败 | 中文组合/撤销/选择、混排、字体加载失败、复制粘贴与权限失败；按浏览器实际约束报告，不要求用户开实验开关 |
+| CAP-39 | 鼠标/键盘/手柄、焦点、重绑定、提示切换、本地化、字幕与可访问性选项 | CAP-37、CAP-38 | 输入被重复消费；焦点丢失；本地化破布局 | 输入录放、设备切换、失焦/恢复、语言/字号/减少动态效果；可程序化检查并保留真实输入路径 |
+| CAP-40 | 空间声源、距离/方向、遮挡、混响区域与实体运动同步 | CAP-06、CAP-19、CAP-23 | 听起来有声即算完成；区域切换爆音；坐标漂移 | 已知声源测试、空间位置与参数轨迹、遮挡/混响输出音频及能量/响应分析；跨区/原点变化对照 |
+| CAP-41 | 总线/分组、优先级、并发限制、淡变、互动音乐分层/分段/节拍过渡 | CAP-40 | 音乐仅顺序播放；抢占破坏关键音效；点击音 | 总线计量、抢占事件、节拍误差、层切换和淡变波形/音频；游戏状态驱动的自动测试 |
+| CAP-42 | 音效/音乐/预制语音加载、流式播放、暂停恢复及音画同步测试 | CAP-40、CAP-41、CAP-08 | 浏览器自动播放限制、流式断续、时钟漂移 | 自动输入解锁测试、未解锁诊断、网络中断恢复、缓冲与时间戳；可用时离线渲染做信号测试，并以真实浏览器播放复验 |
+| CAP-43 | 属性/修改器、标签、事件、计时器、状态机、实体关系和交互机制 | CAP-02、CAP-06、CAP-07 | 固定规则侵入通用层；事件次序不可预测 | 自定义规则示例、事件顺序、计时暂停/恢复、关系删除与循环处理 |
+| CAP-44 | 物品/背包/装备、技能/效果/战斗、任务/对话/阵营、交易/制作等可组合模块 | CAP-43、CAP-37、CAP-47 | 模块只能适配一种游戏；存档引用断裂 | 替换伤害公式、物品/任务结构等规则的项目；跨模块任务、失败分支和保存恢复断言 |
+| CAP-45 | 可复制修改的玩法模板与不同类型完整参考项目，仅用公开 API | CAP-20、CAP-44、CAP-10 | 示例偷用内部 API；模板被误当不可修改引擎源码 | 复制到游戏侧后的独立构建、变更规则、版本检查；至少覆盖 3D 及 2D/2.5D 用法 |
+| CAP-46 | 输入/必要外部事件录制、时间/随机源控制与回放分歧定位 | M0-07、CAP-06、CAP-09 | 只录输入无法复现异步加载；回放事件重复 | 输入与加载/事件时序、种子、初始状态；同环境重跑及跨设备容差；分歧位置与原因记录 |
+| CAP-47 | 运行快照、玩家存档与恢复；版本化实体/组件/资源引用及跨区状态 | M0-07、CAP-07、CAP-21 | 半写存档、失效引用、恢复顺序错误 | 保存中断、坏数据、资源未就绪、跨区及退出重进；原子提交或可恢复写入证据；快照和存档契约分开 |
+| CAP-48 | 高状态成本捕获策略：GPU 模拟、音频、PT 历史、流送队列 | M0-07、CAP-28、CAP-42、CAP-47 | 回读/序列化停顿；恢复状态与画面不一致 | 分项状态分类、捕获体积/时间/带宽、恢复就绪点和误差；明确重建项，不能声称所有硬件状态原样恢复 |
+| CAP-49 | 引擎/API/内容/存档/回放版本识别、锁定、兼容诊断与显式迁移 | CAP-03、CAP-46、CAP-47 | ZIP 无版本；自动升级破坏游戏；覆盖唯一数据 | 无 Git 版本识别、旧项目迁移前后测试、升级失败回退；无法自动迁移时给外部 AI 明确任务 |
+| CAP-50 | `dist/` 独立静态 Web 构建、子路径/资源地址/分包配置与预览检查 | CAP-04、CAP-19、CAP-49 | 依赖开发服务器、源码路径、在线引擎服务 | 干净目录通过 Web 服务器运行；根路径/子路径、缺失资源、跨源配置、缓存更新和分包检查；不要求双击 HTML 运行 |
+| CAP-51 | 粒子、植被及程序化视觉效果，可用引擎计算/材质接口扩展 | CAP-17、CAP-18、CAP-21 | 只在光栅可见；视觉粒子冒充物理流体 | 生命周期/实例数据/资源释放、风与碰撞等公开参数测试；声明在各渲染模式中的表示，不以特效替代 CAP-28 |
+| CAP-52 | 结构化日志、帧/系统耗时、资源与加载诊断、预算报告 | CAP-08、CAP-09、M0-05 | 观测影响被测对象；只能得到平均 FPS | 采样开销、时间轴、异常峰值与资源曲线、不可用指标原因；故障定位到系统/实体/资源/源代码 |
+| CAP-53 | 无历史上下文外部 AI 从交付目录完成开发、诊断、修复、构建 | CAP-01、CAP-10、CAP-45、CAP-50、CAP-52 | 需要人工补说明；演示项目过度定制 | 干净任务、工具调用与修复记录、最终玩法和 `dist/` 复验；引擎研发 AI 与游戏开发 AI 职责分离 |
+
+### 7.1 状态捕获成本与恢复语义
+
+M0-07、CAP-48 必须给每类状态明确以下分类，并通过恢复后的实际行为验证：
+
+| 状态类别 | 规划中的恢复契约 | 不允许的完成替代 |
+| --- | --- | --- |
+| 游戏逻辑、实体关系、任务与玩家进度 | 精确序列化或显式版本迁移，恢复后符合逻辑断言 | 只恢复位置而丢失任务/引用 |
+| 刚体/布料/绳索/软体/流体 | 确定哪些状态精确保存、哪些由检查点重放或容差重建；记录约束及必要内部状态 | 默默清空流体、重置软体或保留明显错误的接触 |
+| GPU 缓冲与高密度场 | 比较全量/增量捕获、检查点与重建成本；锁定捕获频率和可支持负载 | 无测量地宣称每帧快照无成本 |
+| 音频 | 保存播放意图、轨道/段落、游标/节拍和混音参数；说明流式解码与混响历史的重建策略 | 把没有声音输出的恢复称为音画恢复完成 |
+| PT 累积/降噪历史 | 明确失效、重建或保存策略，验证恢复后动态画面稳定；不强求历史缓冲逐字节恢复 | 逻辑恢复后沿用不匹配的历史导致鬼影 |
+| 流送、导航重建与异步任务 | 恢复有效请求意图、版本和依赖，取消过期结果，明确恢复就绪条件 | 把旧世界的异步结果写入新状态 |
+
+捕获暂停、异步回读、增量日志和重放各有成本，需记录峰值与持续占用。不得把保存“播放意图”冒充保存所有音频 DSP 内部状态，也不得把容差恢复冒充跨设备逐位确定性。
+
+## 8. 跨模块交互矩阵与承诺边界
+
+全部未实现。这里区分两种“交互”：模拟中的双向力学耦合，以及模块之间的状态交换。渲染读取模拟结果不代表渲染反向施力；导航避让水域不代表导航器参与流体求解。
+
+### 8.1 首发必须成立的组合
+
+| 编号 | 组合与依赖 | 首发交互契约 | 主要风险 | 必需证据 |
+| --- | --- | --- | --- | --- |
+| INT-01 | 刚体↔布料；CAP-23/26 | 双向：刚体推动/支撑布料，布料通过接触或约束对动态刚体产生可测反力 | 单向碰撞伪装耦合、质量比失稳 | 交换载荷、运动方向与误差轨迹；固定刚体和动态刚体分别测试 |
+| INT-02 | 刚体↔绳索；CAP-23/25/26 | 双向：绳索牵引/悬挂刚体，刚体运动反馈绳索受力、长度约束与接触 | 视觉线跟随、锚点瞬移 | 拉拽/悬挂/断开、约束误差、端点反力及状态恢复 |
+| INT-03 | 刚体↔软体；CAP-23/27 | 双向：刚体压迫/撞击软体，软体接触与回弹影响刚体运动 | 软体只形变不反馈 | 压缩、回弹、承重的双侧状态与接触力；渲染和碰撞形变一致 |
+| INT-04 | 刚体↔流体；CAP-23/28 | 双向：刚体运动改变液体分布，液体浮力/阻力影响动态刚体 | 预设浮动动画、排液不守恒 | 移动容器、入水/排液、漂浮/下沉、体积误差及双侧轨迹 |
+| INT-05 | 地形/静态场景→各模拟；CAP-23–29 | 四类模拟及刚体接受明确支持的场景碰撞；修改后边界更新。静态物体无受力运动要求 | 不同求解器看见不同场景 | 同一场景边界和修改前后碰撞对照；更新完成点明确 |
+| INT-06 | 角色/载具↔物理；CAP-24–28/31 | 角色/载具能驱动交互；动力学载体遵守双向力学；运动学角色使用显式推力/受阻策略 | 控制器被误当自由刚体、角色无响应穿越 | 推拉、接触、受阻、载具穿越及动画交接；不隐含人体全自由度生物力学 |
+| INT-07 | 模拟/动画→三种渲染；CAP-13–17/26–31 | 骨骼、Morph、布料/绳索/软体/流体的受支持几何表示更新到三模式；加速结构和历史同步 | 画面旧几何、光线命中与可见物体不符 | 同一时间点几何/命中检查与动态序列；流体等表示的模式差异必须列明 |
+| INT-08 | 建造/破坏/地形↔物理/导航/光追；CAP-29/35/36 | 修改经过有版本的提交，各消费者确认生效；查询和重规划使用有效版本，失败可诊断 | 画面新、碰撞旧、导航旧 | 修改事件链、脏区、提交/就绪时间戳和可通行/命中断言 |
+| INT-09 | 流送↔模拟/导航/任务/状态；CAP-21/23/36/44/47 | 卸载有明确冻结/保留/序列化策略；跨区约束和任务不得悬空；恢复后重新建立有效关系 | 缺失约束端点、追踪目标被销毁 | 跨区搬运/追踪/保存和反复往返；边界活动模拟的驻留策略及资源成本 |
+| INT-10 | 根运动/IK/物理↔动画；CAP-24/30/31 | 碰撞反馈动画位移，动画意图通过受控路径驱动角色；控制权和更新次序可查 | 双重积分、脚滑、姿态不同步 | 被阻挡根运动、移动平台 IK、过渡时控制权轨迹 |
+| INT-11 | 行为/导航↔动态世界；CAP-29/33–36 | 世界事件使路径/感知失效并重规划，NPC 行为查询失败原因并执行后备逻辑 | 旧路径重复重试、导航改几何 | 建造封路、拆门、改地形、跨区路径的感知/决策/移动证据 |
+| INT-12 | 输入/UI↔玩法/录放；CAP-37–39/43–46 | 焦点和输入消费规则唯一；录放能重现菜单与玩法切换；UI 可查询游戏状态 | 输入穿透、UI 操作未录制 | 打开菜单/重绑定/手柄操作/中文输入的状态轨迹与回放 |
+| INT-13 | 动画/物理/过场↔音频；CAP-23/30/32/40–42 | 动画/碰撞发出音频事件；音频游标/节拍与过场同步、暂停恢复；明确时钟映射 | 双发脚步、跳过后残留声音 | 事件计数、音频输出、音画偏差、分支/跳过/恢复序列；不要求音波反向参与力学求解 |
+| INT-14 | 快照/存档/回放↔所有有状态模块；CAP-46–49 | 每模块声明权威、派生、瞬时与不可捕获状态；捕获屏障/恢复顺序可验证 | 半帧状态、GPU 回读阻塞、音频重放 | 第 7.1 节分项成本和恢复断言；同时有活动模拟、音频、流送的组合测试 |
+| INT-15 | 热更新↔渲染/模拟/UI/状态；CAP-05/07/17/47 | 按版本替换资源与逻辑，不兼容时明确重启；不会保留旧约束/着色器和失效引用 | 状态混合、泄漏、测试仅热态通过 | 多次更新、失败恢复、驻留曲线及相同变更的冷启动对照 |
+| INT-16 | 原点调整↔物理/渲染/音频/导航；CAP-22 | 同一空间变换贯穿各模块，局部量与世界量转换规则明确 | 约束断裂、声音跳变、路径瞬移 | 调整前后命中、力/轨迹、声源和路径的连续性及容差 |
+
+### 8.2 必须由 M0 明确、不能默认为全部支持的组合
+
+| 编号 | 待决定组合 | M0 必须决定什么 | 首发边界与验证要求 |
+| --- | --- | --- | --- |
+| INT-17 | 布料↔绳索、布料↔软体、绳索↔软体 | 逐对决定接触/附着/自碰撞及是否双向求解；求解次序和子步 | 不由 INT-01–03 推导六种非刚体组合都已承诺；选定支持的逐项做双侧反应测试，其余明确不支持的交互语义 |
+| INT-18 | 布料↔流体、绳索↔流体、软体↔流体 | 逐对决定浮力/阻力/浸润/边界表示的支持等级，双向或单向，以及读回成本 | 不默许完整多相、多尺度统一求解；声明质量/体积误差和负载；核心 INT-04 不能因此取消 |
+| INT-19 | 自碰撞、撕裂、断裂与模拟拓扑变化 | 各模拟的自碰撞范围、网格/粒子表示、重建与持久化策略 | 不由物件破坏推导所有模拟任意切割；受支持拓扑变更须通过快照、渲染和光追更新测试 |
+| INT-20 | 活跃流体/约束跨流送边界、多个求解器同步 | 选择保留邻区、迁移状态、边界条件或受控暂停；定义恢复和守恒误差 | 不能静默销毁边界状态；支持的跨区方式必须实测，不能声称无限世界里无限活跃模拟 |
+| INT-21 | 自定义顶点/计算变形↔物理/导航/光追 | 决定可查询几何、碰撞代理、加速结构输入与同步声明接口 | 装饰性变形可只影响显示但必须显式标记；影响玩法的几何不能只改显示；不能假定任意程序都能自动生成碰撞体 |
+
+以上待决定项的算法、支持表和预算必须落入 ADR 并关联测试；“待决定”不是默认通过，也不能成为取消已确定能力的理由。组合不是所有模块的无限笛卡尔积。确认不支持的非必需组合必须有接口诊断与文档，不应让外部游戏开发 AI 靠猜测发现。
+
+## 9. 画质与性能验收协议
+
+### 9.1 基准与质量分离
+
+已确定的可重复性能基准目标是**主流独显、原生 1920×1080、60 FPS、高质量档**。基准不得依靠动态分辨率或超分辨率达标。具体 GPU/CPU/内存、驱动、浏览器、场景、并发量和通过阈值均尚未锁定，由 M0-05 记录，不能填写假想实测结果。
+
+高画质是独立能力目标，不由 FPS 定义。必须同时验证资产/材质还原、照明、阴影、真实光线效果、动态稳定性、降噪/拖影、细节和透明等。画质参考、误差及序列评估规则同样需要证据来源。
+
+| 测试维度 | 必须固定或记录的条件 | 不允许的替代 |
+| --- | --- | --- |
+| 光栅、混合 RT、全 PT | 分别标记模式、场景负载、分辨率、反弹/采样/降噪、动态实体和几何更新参数 | 默认所有模式同一负载都保证 60 FPS，或用光栅成绩代表 PT |
+| 分辨率与质量 | 输出/内部渲染分辨率、质量配置及运行中变更；基准固定原生分辨率 | 静默降采样、关效果、降模拟密度或切渲染模式 |
+| CPU/GPU 时间 | 模拟、调度、提交、GPU 工作和等待分别测量；记录测量能力和开销 | 把 CPU 提交时间当 GPU 完成时间 |
+| 帧时间 | 分位数、慢帧、连续卡顿、预热与冷启动分开记录；阈值 M0 锁定 | 只报平均 FPS，删除不利样本 |
+| 内容与模拟规模 | 实体、实例、三角形、灯光、模拟粒子/约束、动态几何、流送事件 | 小场景达标即宣称所有游戏达标 |
+| 内存与长期运行 | CPU 内存、GPU 资源估算/可用测量、驻留、释放、重复进出和持续运行 | 只测首帧或忽略累积泄漏 |
+| 实际 GPU 路径 | 后端身份、适配器、提交与执行；软件/无硬件环境单独标注 | headless 或软件路径通过即宣称主流独显性能达标 |
+
+RT/PT 与重模拟分别建立负载档案；达到何种质量和规模的 60 FPS 承诺必须以测量为依据。测试不达标即保持该项未通过并给出优化/算法任务，不暗降质量。更高分辨率、可选动态质量或超分能力不改变此基准。
+
+### 9.2 玩家端行为
+
+启动由 WebGPURenderer 选择 WebGPU 或内置 WebGL2 回退，并检查游戏实际所需特性和限制。成功则运行，失败给错误码、可用模式及修复操作，不静默降画质。不要求命中官方环境白名单，不把测试配置变成最低硬件锁，也不承诺未经测试设备具有相同性能。
+
+## 10. 综合验收场景矩阵
+
+全部未实现。场景数量与资产体量不预填假数字；每个场景必须有固定输入、清晰判据、版本与可复测证据。
+
+| 编号 | 场景与能力依赖 | 必验内容 | 风险与证据要求 |
+| --- | --- | --- | --- |
+| ACC-01 | 单机关卡制第三人称动作冒险；CAP-20/24/30–47 | 移动、相机、战斗、NPC、交互、物品/任务、UI/音频、存档和场景切换形成完整闭环 | 不能仅展示角色走动；用自动试玩、任务断言、失败/恢复路线、连续画面及音频证明 |
+| ACC-02 | 高质量动态三模式场景；CAP-13–18/30/31/51 | 同一资产场景测试光栅/混合 RT/PT，相机移动、骨骼/Morph、模拟几何、屏幕外反射 | 每模式单独记录实际后端、质量设置、序列、命中与性能；单张静态图不通过 |
+| ACC-03 | 交互模拟组合场；CAP-23–28、INT-01–07 | 刚体分别与布料、绳索、软体、流体双向交互，角色或载具触发；三模式呈现 | 双侧轨迹、稳定性、释放、恢复与模拟/渲染成本；非刚体之间按 M0 支持表另测 |
+| ACC-04 | 连续大世界与可变环境；CAP-21/22/29/35/36/47 | 连续移动、建造拆除、破坏、改地形、动态导航、跨区状态与原点调整 | 修改版本链、加载/驻留曲线、旧状态负例、往返存档及视听连续性 |
+| ACC-05 | 2D 与 2.5D 可玩切片；CAP-12/23/37–45 | 精灵/瓦片、碰撞、正交/透视组织、输入/手柄、UI 与存档 | 不能只用 3D 样板证明 2D；玩法断言、排序/命中与完整构建分别验证 |
+| ACC-06 | 演出、交互 UI 与音频；CAP-31/32/37–42 | 中文输入、语言/字号、世界 UI、互动音乐、字幕、分支过场与跳过恢复 | 输入/焦点轨迹、布局断言、音画同步、实际输出音频；不能只查音频 API 返回值 |
+| ACC-07 | 高状态快照、回放与迁移；CAP-46–49 | 活跃四类模拟、跨区加载、音频/过场下捕获恢复，旧版本迁移 | 捕获体积/耗时、GPU 等待、恢复断言、容差轨迹和失败回退；跨 GPU 不要求逐位一致 |
+| ACC-08 | 按需构建、热更与部署；CAP-04/05/49/50 | 不同功能子集、动态引用、热更兼容与重启、根/子路径 `dist/` | 构建原因图、体积与加载报告、冷启动、无开发服务器依赖、无开发控制通道默认暴露 |
+| ACC-09 | 压力、稳定性与故障恢复；CAP-07/11/18/21/52 | 大量实体/资源进出、长运行、加载失败、取消、设备丢失与恢复 | 原始时间轴、泄漏/驻留曲线、错误定位与恢复结果；负载/时长和阈值 M0 锁定 |
+| ACC-10 | 独立外部 AI 使用；CAP-01/10/45/50/53 | 从仓库 URL、ZIP 或本地目录创建不同类型游戏、定位注入缺陷并修复、生成部署产物 | 不依赖研发对话和人工操作；任务过程、修复前后证据和第三方复跑记录；单 AI 也能完成 |
+
+## 11. 里程碑对齐与首发退出条件
+
+里程碑编号与 `ROADMAP.md` 对齐；具体任务排期由研发计划维护，本文只给出验收归属，不重复总体架构或工作流。
+
+| 里程碑 | 本文主要验收归属 | 依赖与退出重点 |
+| --- | --- | --- |
+| M0 高风险原型 | M0-01–07 的原型及 M0-08 UI 风险预检 | 四条主线为编译、动态渲染、交互模拟、外部 AI 闭环；基准/流送/状态成本是关联验证，输出 ADR 与未解决风险 |
+| M1 基础契约、编译与运行 | CAP-01–10、CAP-11 基础、CAP-46–49 状态契约 | 类型、依赖、中间表示、生命周期和自动化链路可执行；状态大规模成本不在此提前宣称完成 |
+| M2 最小完整游戏切片、资源与光栅 | CAP-12/13/18–20/23/24、ACC-01 初始切片 | 用真实游戏检验基础；UI 专项原型 M1/M2 完成，不代表完整 UI 已交付 |
+| M3 高级渲染、光追与 PT | CAP-14–17/51、ACC-02 | 依赖 M0 与基础渲染；可与 M4 并行，动态形变的最终验收依赖模拟/动画集成 |
+| M4 完整模拟耦合 | CAP-25–28、INT-01–06/17–20、ACC-03 | 完成双向交互与状态成本；与 M3 通过明确几何/时间契约集成 |
+| M5 动态世界、导航与动画 | CAP-21/22/29–36、INT-07–11/16/21、ACC-04 | 不需等待 M6 全部完成；涉及音频/过场的最终场景在接口具备后补齐 |
+| M6 2D、UI、音频与玩法广覆盖 | CAP-37–45、ACC-05/06、CAP-12 完整覆盖 | 使用基础编译运行与资源契约；与 M5 按共享接口协作，不构造不必要串行等待 |
+| M7 优化、兼容与发布 | CAP-04/05/18/46–52 完整验收、ACC-07–09 | 跨模块状态、预算、迁移和 `dist/` 实测；复验以前阶段受影响的证据 |
+| M8 独立 AI 全首发验收 | CAP-53、ACC-01–10 全集、全部 INT 必需项 | 全部首发能力证据闭合、干净复测与无历史上下文开发；不能以局部可用或实验性替代完整交付 |
+
+M0 结果见验收记录，M1–M8 尚未完成。首发退出需要：全部 CAP 正式验收；INT 必需组合通过；M0 待决定组合有明确支持表且受支持项有测试；ACC 综合场景通过；硬件/负载/阈值/容差已锁定；残余风险与限制可查询；无隐藏人工步骤。任何删除已确认首发能力或改变需求边界的取舍都需要重新确认，不能通过修改测试范围实现“完成”。