# simulator — 实现分工

这里是独立 Git 仓库，修改前检查本目录状态并保留已有改动。仓库与分发入口见 [README](README.md)、[分发设计](DISTRIBUTION.md)。若位于完整知识工作区中，再读 [父级 AGENTS](../AGENTS.md)、[需求](../docs/demand.md)、[模块地图](../docs/workspace-map.md)；独立检出时这些外部资料可以不存在，不创建替身。

## 读哪里、改哪里

| 职责 | 实现位置与入口 |
|---|---|
| Lua 5.3 VM、script/game/Enum、控件、输入、Tween、require | [client/lua-runtime](client/lua-runtime/README.md)；[架构](client/lua-runtime/docs/architecture.md)、[观察契约](client/lua-runtime/docs/observed-contract.md) |
| 关卡/玩家/角色变量、信号 | [server](server/README.md)；不执行完整官方节点图 |
| Authoring JSON、GIA、布局、试玩编排、日志、回放与断言 | [studio](studio/README.md) 的 `ui/`、`gia/`、`play/`、`log/`、`autotest/` |
| 共用 Controller、工作区边界、持久 Worker、截图和场景渲染 | `studio/host/`、`studio/host-png.js`、`studio/play/pixi-renderer.js`、`studio/play/browser-session.js` |
| Web / DSH 共用编辑器 | [editor-ui](editor-ui/README.md)；宿主注入 React、API 和试玩 URL |
| DSH Host/Tools、Client UI 适配 | [dsh-plugin](dsh-plugin/README.md)；工具流程见 [skill/SKILL.md](skill/SKILL.md) |
| MCP stdio 与工具映射 | [mcp](mcp/README.md)、`mcp/index.js`；复用 `studio/host/controller.js` |
| Web 编辑与只读预览 | [web](web/README.md)、`web/server.js`、`web/lib/session.js`、`web/lib/editor-sessions.js` |
| workspace、DSH 源码安装入口、打包与独立安装验收 | 根 `package.json` 为 DSH 对外清单；`dsh-plugin/package.json` 仅为内部源码包；`pnpm-workspace.yaml`、`scripts/` |
| 编辑器视觉设计（非实现） | `frontend/ui/ui-mockups.md` |

Lua VM 只放在 Runtime，Authoring/GIA 只放在 Studio，接入层复用共享宿主，不另建引擎。未知语义标策略或明确失败，需要真机证据的调查放根 `probes/`。

旧动态原型 `frontend/dsh/`、`studio/dsh-host-kernel.js` 已删除，不恢复；不要安装或调试失败的旧包 `qxqy-dsh-plugin`，使用现行静态包。

## 实现约束

- UI 层级：服务端“客户端控件容器” → 客户端“容器节点” → 子控件。三类存档资产为服务端 UI、客户端模板、Lua 脚本，没有“服务端 Lua”。
- 层序：显式【层级】数值高的在上（Lua sibling 大的在上，First 置底、Last 置顶）；编辑器同级列表第一项在上。内部 children 保持列表顺序，Lua 数值在 scene.js 边界反向映射；不要把编辑器树/GIA wire/运行时索引混成一个方向。主证据见根 knowledge/fact.md“同级绘制与命中”。
- 动态实例化：新实例根默认置顶，模板内静态子列表保持原序；默认顺序在模板脚本启动前就绪。规则来源、边界与回归见 [Runtime 契约](client/lua-runtime/docs/observed-contract.md#默认动态实例层序2026-09-28)。
- 按键监听：创作者预告后续版本同层级上层控件优先接收事件。模拟器 `injectKey` 沿同一显示层序派发；这是待版更规则，不能写成已由旧版真机探针证实。
- `game` 为全局表，函数按官方签名用点号调用；Lua 桥接必须核对参数个数，避免冒号误用在模拟器中静默通过。真机已回传 `GetClientUIRoots()` 零参数报错，见根 [fact.md](../knowledge/fact.md#game-函数误用冒号会在真机多传一个参数)。
- 仅客户端控件/模板允许挂脚本，以 `controlAsset` 区分两棵树同名 ID；模板脚本随实例化运行。11 类控件按 GIA 证据分级，N/U 字段只读，不伪造。
- 图片由 `imageSource + imageId` 共同标识；静态来源 `100001–100006` 用基础图元代理，其他静态白名单还原透明留白，Prefab 白名单直接使用完整图标 PNG。宿主按来源隔离缓存；Lua 用 `SetImage`，编辑器来源可选。未知来源/ID 和加载失败显示缺失框。目录、GIA 边界及刷新见 [素材缓存](studio/docs/image-assets.md)，预览不代表真机素材渲染契约。
- 图片类型 Basic 整图缩放、Stretch 按 m_Border 三/九切片。默认和小尺寸/零中心策略对齐图片编辑器 20659b3；Lua 白名单可写范围与真机条件支持严格区分，详见 [图片类型](studio/docs/image-assets.md#图片类型基础拉伸210)。
- Lua 2D 音效通过 Runtime 实例快照投影到浏览器 Web Audio；音频与图片复用 `studio/host/asset-cache.js` 持久缓存。目录、自动播放、时长与停止策略见 [音频缓存](studio/docs/audio-assets.md)，不得把浏览器音频时钟回灌 Lua。
- 五档画布与 `GetUICanvasSize` 同源，尺寸见根 [fact.md](../knowledge/fact.md)“模拟器画布预设”。原点左下、锚点相对父矩形；手机 16:9（1280×720）完整可见，PC 等比放大/留边。
- 布局只保存 GIA 四平台 `transformByPlatform`，五种画布从平台参数派生显示。读取入口自动迁移旧存档，运行时不恢复画布布局表或回退读取；保存统一为 version 4、资产 `layoutSchemaVersion: 2`。迁移规则见 [Studio README](studio/README.md#json-画布布局与-gia-平台槽)。
- 独立脚本 GIA 与整合包的挂载能力不同；按根本地 [GIA 数据结构](../knowledge/ui/02_UI核心数据结构.md) §5“通用关联槽”/§8 和 `studio/gia/codec.js` 实施，不写未观察字段。排错见 [P11](../knowledge/pitfalls.md)。

## 验证

修改 Git 源码安装入口、根 `prepare` 或 DSH exports 时，另跑 `pnpm test:git-install`；可传入本机 DSH CLI 的 `lib/bin.js` 绝对路径，在临时 profile 中验证真实安装与配置注册。

根目录统一运行 `pnpm install --frozen-lockfile`、`pnpm test`；分发修改另执行 `pnpm pack:release`、`pnpm test:packages`。源码和测试入库，依赖、构建产物与生成的 Skill/预设副本继续忽略，不用 `git add -f`。测试必须自包含，只使用仓库内源码与合成数据，不依赖仓库外的样本文件。真机证据、模拟器策略和测试结果分开记录；在完整知识工作区中遵守 [知识维护规范](../knowledge/AGENTS.md)。