# 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 或两者并存；
- 尚未批准任何公开发布、合作方使用或学生作品商业授权。