6f854851f5
- 受控面 v0 六项冻结:getContext2d/onFrame/getInput/getAudioContext/time/random - getInput=归一化事件订阅面(5枚举,host注入桥+_emit测试口,dispose自动清理防泄漏);getAudioContext=lazy单例无工厂返null告警降级 - per-plugin 派生随机流(FNV-1a子种子,序列互不影响同seed复现,向后兼容回退);useContext 守卫(友好错误带插件名) - 向后兼容增量不bump版本;manifest schema 未动;三 lane 按此冻结面开工 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
97 lines
6.7 KiB
Markdown
97 lines
6.7 KiB
Markdown
# game-runtime —— LittleJS 增强发行版（插件协议地基）
|
||
|
||
> **协议版本：`core-protocol-v0`**（见 `src/core/plugin.js` 导出的 `CORE_PROTOCOL_VERSION`）。
|
||
> owner：T1b-α lane-core（Gate0 奠基）。配对 spec：`docs/agent-specs/2026-06-12-T1b-α插件库与参考件-execution.md`（v1.1）/ `…W-T1b-Runner与双层模板-review.md`（v2.1）。
|
||
|
||
平台维护一套「LittleJS 增强发行版」：每个**插件 = 一项引擎能力**（碰撞/粒子/物理/手感/调色/音频…），即插即用、可组合、版本化。
|
||
**插件不含玩法、不含美术成品、不含关卡、不含 UI —— 这四者是 agent 造游戏时的生成域。** 本仓只提供「能力编排 + 受控引擎句柄」，绝不内置任何玩法假设。
|
||
|
||
---
|
||
|
||
## 协议版本声明
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 当前协议版本 | **v0（2026-06-12 冻结，含 Gate0.1 受控面补丁）** |
|
||
| 标识来源 | `src/core/plugin.js` → `export const CORE_PROTOCOL_VERSION = 'core-protocol-v0'`；`schema/plugin-manifest.schema.json` → `$id .../v0` |
|
||
| 冻结状态 | Gate0 评审通过即冻结。Gate0.1 补丁（受控面由 4 扩 6：+getInput/+getAudioContext；random 改 per-plugin 派生流；useContext 守卫）为**向后兼容增量**，随 v0 一并冻结，不 bump 版本号 |
|
||
| 升级规则 | 受控面只增不破坏既有 API；破坏性变更须 bump 版本（v0→v1）并在本表登记 |
|
||
|
||
> **扩展受控面 / 改 manifest 字段 = 改协议**，必须走 Gate0 后的扩展申请，不得 lane 私自加。
|
||
> **受控面 v0 最终成员（冻结口径，6 项）**：`getContext2d` / `onFrame` / `getInput` / `getAudioContext` / `time` / `random`。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
game-runtime/
|
||
├── README.md # 本文件：目录 + 证据约定 + 协议版本声明位
|
||
├── src/
|
||
│ ├── core/ # 协议核心（core-protocol-v0，已冻结对象）
|
||
│ │ ├── plugin.js # Plugin 接口 / PluginRegistry 生命周期 / PluginContext 受控面(6 项) + host-dev 桩(含输入桥)
|
||
│ │ ├── api.d.ts # 手写类型门面（lane 读契约的一等入口，与 plugin.js JSDoc 同步）
|
||
│ │ └── plugin.test.mjs # 核心零依赖单测（31 测，node --test）
|
||
│ └── plugins/
|
||
│ └── _example/ # 空插件样例（五件全，可直接克隆为新插件）
|
||
│ ├── impl.js # ESM 实现（演示受控面用法，无玩法语义）
|
||
│ ├── api.d.ts # 该插件类型门面
|
||
│ ├── manifest.json # 插件机器契约（过 schema 校验）
|
||
│ ├── PLUGIN.md # 给 agent 读的能力文档（PLUGIN-TEMPLATE 活样板）
|
||
│ └── test/example.test.mjs # 该插件零依赖单测（7 测）
|
||
├── schema/
|
||
│ └── plugin-manifest.schema.json # manifest.json 契约（additionalProperties:false）
|
||
├── docs/
|
||
│ └── PLUGIN-TEMPLATE.md # PLUGIN.md 规格模板（六节固定骨架）
|
||
├── scripts/
|
||
│ ├── build.mjs # esbuild 锁参打包（bundle+min+iife+es2019）——⚠️ 仅集成段跑
|
||
│ ├── size.mjs # 增量法字节测量（zlib gz level9）→ SIZES.md ——⚠️ 打包部分仅集成段
|
||
│ ├── validate-manifest.mjs # 零依赖 manifest schema 校验（本机可跑）
|
||
│ └── test.sh # 遍历 core+全插件 node --test（本机可跑）
|
||
└── test/
|
||
└── harness/
|
||
└── browser-evidence.cjs # 浏览器视觉证据 harness（纯计算口径已实现 + CDP 占位，⚠️ 真跑仅集成段）
|
||
```
|
||
|
||
> 下列目录在对应阶段产生，本阶段尚未创建：`src/plugins/<P1..P10>/`（各 lane 插件）、`games/`（参考件）、`host-dev/`（本地挂载页）、`dist/`（集成段构建产物）、`evidence/`（集成段/参考件证据）、`SIZES.md`（集成段 size.mjs 产出）。
|
||
|
||
---
|
||
|
||
## 源码形态与运行纪律
|
||
|
||
- **源码形态**：发行版 = **ESM JS + JSDoc 类型注释**，公开能力面 = **手写 `api.d.ts`**。**零工具链**——lane 阶段 `node --test` 本地直跑，本机零 npm 依赖、不跑 git。
|
||
- **本机可跑**（lane 阶段）：
|
||
- `bash scripts/test.sh` —— 跑 core + 全插件单测；
|
||
- `node scripts/validate-manifest.mjs` —— 校验全部 `manifest.json` 合 schema；
|
||
- `node scripts/size.mjs --selftest` —— gz 量算口径自检。
|
||
- **仅集成段（mini-desktop）跑**（需 esbuild / 真 Chrome）：
|
||
- `node scripts/build.mjs <in> <out>` —— 锁参打包；
|
||
- `node scripts/size.mjs` —— 增量法实测 → `SIZES.md`；
|
||
- `test/harness/browser-evidence.cjs` 的 CDP 真跑（连 Chrome 抓 ImageData/截图）。本机（6c6g）禁启 headless Chrome（OOM 红线）。
|
||
|
||
---
|
||
|
||
## 证据与目录约定（沿 T1 结构）
|
||
|
||
| 阶段 | 证据落点 | 内容 |
|
||
|---|---|---|
|
||
| 每 lane | `<lane>/REPORT.md` | 实现说明 + 边界 + 红线声明 |
|
||
| 每 lane | `<lane>/test/RESULT.txt` | `node --test` 原始输出 |
|
||
| 每插件 | `<plugin>/PLUGIN.md` | 给 agent 读的能力文档（六节，见 `docs/PLUGIN-TEMPLATE.md`） |
|
||
| 集成段 | `SIZES.md` + `evidence/integration/` | 构建日志 / 浏览器证据哈希 + 截图 |
|
||
| 参考件 | `evidence/round-N/` + `LOOP-LOG.md` + `sha256-manifest.txt` | 四件套（输入轨迹/截图+canvas 哈希/probe JSONL/checklist）+ serve 日志 |
|
||
|
||
- **截图路径约定**：`evidence/<bucket>/<name>.png`（集成段 bucket=`integration`，参考件 bucket=`round-N`），由 `browser-evidence.cjs` 的 `screenshotPath()` 统一给出。
|
||
- **哈希族**：全发行版证据用 **FNV-1a 32-bit**（ImageData 哈希与 P10 RuntimeProbe 哈希链同口径）。
|
||
- **字节预算**：每插件 `manifest.json` 声 `gzBudgetBytes`，集成段 `size.mjs` **增量法**实测对照；单件超配额→评审，合计>60K→创始人放行（执行版 §5）。
|
||
|
||
---
|
||
|
||
## 给 lane 开工者的最短路径
|
||
|
||
1. 读 `src/core/api.d.ts`（协议类型契约，一等入口）+ `src/core/plugin.js`（实现与受控面注释）。
|
||
2. 复制 `src/plugins/_example/` 整目录 → 改名为你的插件 → 按 `docs/PLUGIN-TEMPLATE.md` 六节改写 `PLUGIN.md` → 改 `manifest.json`（`node scripts/validate-manifest.mjs` 必须过）。
|
||
3. 实现 `impl.js`：只经 `PluginContext` 4 项受控面拿引擎能力，**绝不直透 littlejsengine 裸对象**。
|
||
4. 写 `test/*.test.mjs`：零依赖 `node:test`，经 `createHostDevContext` 拿受控面 + `tick` 驱动帧（vfx/audio 的渲染/发声证据留集成段 harness）。
|
||
5. `bash scripts/test.sh` 全绿后，产 `REPORT.md` + `test/RESULT.txt`。
|