ADR-0002：Web 原生 3D 世界壳 + Canvas 2D 作品运行时
- 状态：已被 ADR-0003 的引擎对照闸门部分取代；其余背景仍有效
- 日期：2026-07-31
背景
Inception Space 必须直接在网页运行，包含可行走的科幻博物馆、传送门、多面体 房间、简单桌椅/画板等 3D 物品，同时复用儿童友好的 Live Painting 编辑与动画。 世界还需要嵌入常规 DOM 编辑器、授权流程、AI 计划审批和截图反馈。
决定
Pilot 使用以下组合：
- TypeScript + Vite 作为应用和编辑器底座；
- Three.js 负责 WebGL 3D 世界；
- 现有 Canvas 2D Live Painting 作为独立 artwork runtime；
CanvasTexture将动态作品贴到 Three.js 平面、画框和画架；- 简单 3D 资产统一为 GLB/glTF，另支持受限的参数化 primitives；
- 不在 Pilot 引入完整物理引擎，静态环境先使用 capsule/AABB/简化 mesh 碰撞；
- p5.js 可作为课程中的 sketch/创意编程模式，不作为世界引擎。
理由
相比 Godot
Godot 很适合独立游戏和桌面式场景编辑，但 Web 导出需要 WebAssembly/WebGL 2， Godot 4 的 C# 项目仍不能导出 Web；多线程 Web 导出还需要 cross-origin isolation。 更重要的是，本项目的儿童编辑器、Canvas Live Painting、授权和 AI 审批都是 Web 原生界面，把它们与 Godot Web 构建双向桥接会形成两个运行时。
相比 Unity
Unity 的 3D 工具和资产生态最强，当前 Unity 6 也支持部分移动浏览器；但 Web 构建 通过 WebAssembly/WebGL 运行，与 DOM/Canvas 编辑器通信需要额外 JavaScript 插件 边界。对于低多边形静态博物馆，这个体量和双语言工作流没有带来对应收益。
相比 p5.js
p5.WebGL 适合教学和单件作品，但缺少本产品需要的完整场景/资产工程层。使用它构建 世界会迫使团队重新实现 glTF 管线、场景生命周期、裁剪、拾取和碰撞约定。
为什么选择 Three.js 而不是立即使用更完整的 Web 引擎
世界几何和互动刻意保持简单，现有代码已经是无框架 TypeScript/Vite。Three.js 能够直接接收 HTML Canvas 作为纹理，并允许对纹理更新、draw call、材质和资源释放 做细粒度控制。若技术切片显示相机、碰撞、序列化或工具链成本过高，Babylon.js 是 第一备选，而不是转向桌面引擎。
风险
- Three.js 不提供完整游戏编辑器，需要自行实现领域化房间编辑器；
- 多张动态 CanvasTexture 可能造成 GPU 上传卡顿；
- 自制碰撞和对象序列化容易逐渐变成隐形引擎；
- 低端移动设备的内存、纹理和 shader 编译必须真机验证。
性能与退出条件
技术切片包含一条走廊、一个房间、20 个静态物品和四件同时可见的 512px Live Painting，并在 Chromebook、iPad Safari 和桌面浏览器验证。
保留 Three.js 的条件：
- 移动端稳定达到 30fps；
- 动态纹理更新没有周期性长帧；
- 首次进入和传送门切换可被明确预算；
- 房间 manifest 能稳定往返序列化；
- 编辑器和 3D runtime 可共享同一套 artwork/permission schema。
若主要失败来自场景工具、碰撞或资源生命周期，而不是 CanvasTexture 本身，则做同场景 Babylon.js 对照切片。只有 Web 原生方案共同失败时，才重新评估 Godot 或 Unity。
非决定
- 尚未选择正式域名、托管数据库、对象存储或 AI 提供商；
- 尚未决定是否需要 WebGPU；Pilot 必须有 WebGL 2 路径；
- 尚未决定高阶 3D 课程使用 Blockbench、Blender 或两者并存；
- 尚未批准任何公开发布、合作方使用或学生作品商业授权。