mini-three-adapter 0.1.7 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +85 -85
- package/LICENSE +21 -21
- package/README.md +159 -159
- package/dist/build/rollup.js.map +1 -1
- package/dist/build/vite.js.map +1 -1
- package/dist/{chunk-HKT54DDM.js → chunk-DQH3YRGN.js} +3 -3
- package/dist/chunk-DQH3YRGN.js.map +1 -0
- package/dist/{chunk-35XVAVDB.js → chunk-J34MD3IL.js} +2 -2
- package/dist/chunk-J34MD3IL.js.map +1 -0
- package/dist/{chunk-U3P3XHA3.js → chunk-LAVHSWBU.js} +2 -2
- package/dist/{chunk-U3P3XHA3.js.map → chunk-LAVHSWBU.js.map} +1 -1
- package/dist/{chunk-7XOHQFZ6.js → chunk-RYWYBOYO.js} +4 -4
- package/dist/chunk-RYWYBOYO.js.map +1 -0
- package/dist/{chunk-DDCQIBWW.js → chunk-SXQUZI22.js} +4 -4
- package/dist/chunk-SXQUZI22.js.map +1 -0
- package/dist/{chunk-V64V4HIZ.js → chunk-TPMMZFHW.js} +22 -6
- package/dist/chunk-TPMMZFHW.js.map +1 -0
- package/dist/{chunk-FQ2GOIOE.js → chunk-YPG3QUYK.js} +4 -4
- package/dist/chunk-YPG3QUYK.js.map +1 -0
- package/dist/core/index.js +3 -3
- package/dist/index.js +7 -7
- package/dist/platforms/browser.js +4 -4
- package/dist/platforms/wechat-game.js +5 -5
- package/dist/platforms/wechat-miniprogram.js +5 -5
- package/dist/polyfills/index.js +1 -1
- package/dist/scope.js +1 -1
- package/docs/01-design-principles.md +105 -105
- package/docs/03-module-map.md +99 -99
- package/docs/04-api-reference.md +310 -310
- package/docs/05-build-plugin.md +176 -176
- package/docs/06-platform-notes.md +6 -3
- package/docs/07-integration-guide.md +226 -226
- package/docs/08-extension-guide.md +101 -101
- package/docs/09-testing-and-release.md +212 -212
- package/docs/11-compat-matrix.md +100 -100
- package/docs/README.md +41 -41
- package/docs/adr/0001-scoped-globals.md +41 -41
- package/docs/adr/0002-unified-runtime-lifecycle.md +40 -40
- package/docs/adr/0003-ast-rewrite.md +51 -51
- package/docs/adr/0004-in-place-patching.md +42 -42
- package/docs/adr/0005-webgl2-only.md +44 -44
- package/docs/adr/0006-zero-three-dependency.md +43 -43
- package/docs/adr/0007-capability-probe-fallback.md +61 -61
- package/docs/adr/0008-probe-fallback-boundary.md +56 -56
- package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -69
- package/docs/adr/0010-native-event-target-boundary.md +82 -82
- package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
- package/docs/adr/README.md +33 -32
- package/package.json +126 -126
- package/dist/chunk-35XVAVDB.js.map +0 -1
- package/dist/chunk-7XOHQFZ6.js.map +0 -1
- package/dist/chunk-DDCQIBWW.js.map +0 -1
- package/dist/chunk-FQ2GOIOE.js.map +0 -1
- package/dist/chunk-HKT54DDM.js.map +0 -1
- package/dist/chunk-V64V4HIZ.js.map +0 -1
package/docs/11-compat-matrix.md
CHANGED
|
@@ -1,100 +1,100 @@
|
|
|
1
|
-
# 11 · 兼容矩阵
|
|
2
|
-
|
|
3
|
-
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
-
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
-
|
|
6
|
-
## 11.1 three.js 版本
|
|
7
|
-
|
|
8
|
-
| three 版本 | 状态 | 说明 |
|
|
9
|
-
| --- | --- | --- |
|
|
10
|
-
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
-
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
-
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
-
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
-
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
-
|
|
16
|
-
### 每次 three 升级需要复核的点
|
|
17
|
-
|
|
18
|
-
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
-
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
-
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
-
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
-
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
-
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
-
|
|
25
|
-
## 11.2 微信基础库 / 平台
|
|
26
|
-
|
|
27
|
-
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
-
| --- | --- | --- | --- |
|
|
29
|
-
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
-
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
-
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ | 离屏画布首选来源;**API 完全不存在时不做回退**,退回版本推断([ADR-0008](./adr/0008-probe-fallback-boundary.md)) |
|
|
32
|
-
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
-
| 回退探测与上屏画布的身份冲突 | — | ✅ | `probeContext` 接收 `reservedCanvases`(本次画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`),`createCanvas()` 返回其中任一对象即放弃、不 `getContext`(含宿主显式传 `canvas` 的窄口子) |
|
|
34
|
-
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
35
|
-
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
36
|
-
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
37
|
-
| `.wasm.br` Brotli | — | 🟡 | `assets.brotli: true` |
|
|
38
|
-
| Worker(分包) | 2.0.10 | 🟡 | 需 `wx.preDownloadSubpackage({packageType:'workers'})`;并发上限 1 |
|
|
39
|
-
| 分包加载 | 2.1.0 | 🟡 | `game.json` 建议由 manifest 生成 |
|
|
40
|
-
| iOS 高性能 / 高性能+ | 需后台开通 | 🟡 | `game.json` 的 `iOSHighPerformance` / `iOSHighPerformance+`;官方建议 WebGL2 场景开启高性能+ |
|
|
41
|
-
| `wx.triggerGC` | — | ✅ | 影响 image 创建路径判定 |
|
|
42
|
-
|
|
43
|
-
## 11.3 平台支持
|
|
44
|
-
|
|
45
|
-
| 平台 | 入口 | 状态 | 备注 |
|
|
46
|
-
| --- | --- | --- | --- |
|
|
47
|
-
| 微信小游戏 | `mini-three-adapter/wechat-game` | ✅ 单元级 | 自动订阅 `wx.onTouch*`;完整示例 |
|
|
48
|
-
| 微信小程序(`<canvas type="webgl2">`) | `mini-three-adapter/wechat-miniprogram` | 🟡 | 需 WXML 转发 `bindtouch*`;`selectorCtx` 传组件实例 |
|
|
49
|
-
| 浏览器 / H5 双端 | `mini-three-adapter/browser` | ✅ 单元级 | `globalThis` 不被覆盖;canvas 的原生事件目标与 DOM 成员同样保留(ADR-0010,`nativeEventTarget`) |
|
|
50
|
-
| 其他小程序 / 小游戏平台 | 自定义 `PlatformBinding` | 🟡 框架就绪 | 按 [`docs/08`](./08-extension-guide.md#81-新增一个平台) 实现 |
|
|
51
|
-
| WebView 套壳 | 不在范围内 | ❌ | 本方案用于非 WebView 原生渲染 |
|
|
52
|
-
|
|
53
|
-
## 11.4 Web / DOM API 覆盖
|
|
54
|
-
|
|
55
|
-
| API | 提供方式 | 状态 |
|
|
56
|
-
| --- | --- | --- |
|
|
57
|
-
| `window` / `self` / `globalThis`(作用域内) | `MiniThreeScope` 自引用 | ✅ |
|
|
58
|
-
| `document.createElement('canvas' \| 'img')` | `createDocument` | ✅ |
|
|
59
|
-
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
60
|
-
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
61
|
-
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
62
|
-
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | `mini-three-blob:` → `data:` | ✅ |
|
|
63
|
-
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
64
|
-
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
65
|
-
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
66
|
-
| `requestAnimationFrame` / `cancelAnimationFrame` | `FrameScheduler` | ✅ |
|
|
67
|
-
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
68
|
-
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
69
|
-
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
70
|
-
| 图片原生事件(`img.onload` / `addEventListener('load')` / `decode()`) |
|
|
71
|
-
| 纹理格式 | PNG / JPEG | ✅ WebP 在部分真机解码失败,见 §11.6 |
|
|
72
|
-
| `FileReader` / `WebSocket` / `AudioContext` | 缺省或透传 | ⚠️ 业务需要时按 `docs/08` 扩展 |
|
|
73
|
-
| `Worker` / `WebAssembly` | 透传宿主全局(`WXWebAssembly`) | 🟡 |
|
|
74
|
-
| `ResizeObserver` | no-op | ⚠️ |
|
|
75
|
-
| 完整 DOM(布局、CSS、事件冒泡树) | 不提供 | ❌ 超出范围 |
|
|
76
|
-
|
|
77
|
-
## 11.5 场景回归记录
|
|
78
|
-
|
|
79
|
-
以 three 官方示例场景为主体建立回归集,用 `examples/` 的三个平台工程逐一接入验证。
|
|
80
|
-
|
|
81
|
-
| 类别 | 覆盖目标 | 状态 | 备注 |
|
|
82
|
-
| --- | --- | --- | --- |
|
|
83
|
-
| `controls_*` | OrbitControls / TrackballControls / TransformControls 的多指交互 | ⬜ 未回归 | 优先验证 pointerId、capture、`pointercancel` |
|
|
84
|
-
| `loader_*` | GLTF / DRACO / KTX2 / OBJ / FBX | ⬜ 未回归 | 需配置 decoder 路径与分包 |
|
|
85
|
-
| `postprocessing_*` | EffectComposer / bloom / SSAO | ⬜ 未回归 | 注意深度缓冲与 render target 尺寸 |
|
|
86
|
-
| `animation_*` / `physics_*` | 骨骼动画 / wasm 物理 | ⬜ 未回归 | 涉及 wasm 资源预下载 |
|
|
87
|
-
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 | 95 个 Vitest 用例覆盖画布、事件、作用域、插件 |
|
|
88
|
-
|
|
89
|
-
每回归一条,在本表追加:`场景 id | three 版本 | 基础库 | 设备 | 结果 | 失败原因 | 新增 polyfill`。
|
|
90
|
-
|
|
91
|
-
## 11.6 已知限制汇总
|
|
92
|
-
|
|
93
|
-
1. 不模拟 WebGPU;`three/webgpu` 项目需改用 WebGL 构建目标。
|
|
94
|
-
2. `createImageBitmap` 恒为 `undefined`,依赖该 API 的库需自带降级。
|
|
95
|
-
3. 不提供完整 DOM;DOM 密集型 UI 库应走 WebView 方案。
|
|
96
|
-
4. 插件默认只改写 `node_modules` 中的三方生态代码;应用代码里直接写 `window` 不会自动改写(可开 `includeUserCode`)。
|
|
97
|
-
5. 对象 URL 是 `mini-three-blob:` + `data:`,不是浏览器 `blob:`;若有库硬编码 `blob:` 前缀判断,需要适配。
|
|
98
|
-
6. Worker 分包、`.wasm.br`、iOS 高性能+ 需业务按 `mini-three-assets.json` 的 `gameJsonSuggestion` 自行配置,插件不直接改 `game.json`。
|
|
99
|
-
7. 纹理请使用 PNG / JPEG。**WebP 在部分真机上无法解码**(`wx.createImage` 直接触发 `error`),这与适配层无关;`mini-three-adapter` 只会在 `wx.getImageInfo` 失败时给出指向格式的告警。
|
|
100
|
-
8. 图片事件桥接依赖宿主投递事件。真正的 `load`/`error` 拿不到时(宿主三种入口全无,或接受了 `onload` 却永不调用),一律在 **2s** 内由 watchdog 给出终态:`complete` 为真则派发 `load`,否则派发 `error`。这意味着 >2s
|
|
1
|
+
# 11 · 兼容矩阵
|
|
2
|
+
|
|
3
|
+
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
+
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
+
|
|
6
|
+
## 11.1 three.js 版本
|
|
7
|
+
|
|
8
|
+
| three 版本 | 状态 | 说明 |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
+
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
+
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
+
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
+
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
+
|
|
16
|
+
### 每次 three 升级需要复核的点
|
|
17
|
+
|
|
18
|
+
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
+
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
+
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
+
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
+
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
+
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
+
|
|
25
|
+
## 11.2 微信基础库 / 平台
|
|
26
|
+
|
|
27
|
+
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
+
| --- | --- | --- | --- |
|
|
29
|
+
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
+
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
+
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ | 离屏画布首选来源;**API 完全不存在时不做回退**,退回版本推断([ADR-0008](./adr/0008-probe-fallback-boundary.md)) |
|
|
32
|
+
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
+
| 回退探测与上屏画布的身份冲突 | — | ✅ | `probeContext` 接收 `reservedCanvases`(本次画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`),`createCanvas()` 返回其中任一对象即放弃、不 `getContext`(含宿主显式传 `canvas` 的窄口子) |
|
|
34
|
+
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
35
|
+
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
36
|
+
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
37
|
+
| `.wasm.br` Brotli | — | 🟡 | `assets.brotli: true` |
|
|
38
|
+
| Worker(分包) | 2.0.10 | 🟡 | 需 `wx.preDownloadSubpackage({packageType:'workers'})`;并发上限 1 |
|
|
39
|
+
| 分包加载 | 2.1.0 | 🟡 | `game.json` 建议由 manifest 生成 |
|
|
40
|
+
| iOS 高性能 / 高性能+ | 需后台开通 | 🟡 | `game.json` 的 `iOSHighPerformance` / `iOSHighPerformance+`;官方建议 WebGL2 场景开启高性能+ |
|
|
41
|
+
| `wx.triggerGC` | — | ✅ | 影响 image 创建路径判定 |
|
|
42
|
+
|
|
43
|
+
## 11.3 平台支持
|
|
44
|
+
|
|
45
|
+
| 平台 | 入口 | 状态 | 备注 |
|
|
46
|
+
| --- | --- | --- | --- |
|
|
47
|
+
| 微信小游戏 | `mini-three-adapter/wechat-game` | ✅ 单元级 | 自动订阅 `wx.onTouch*`;完整示例 |
|
|
48
|
+
| 微信小程序(`<canvas type="webgl2">`) | `mini-three-adapter/wechat-miniprogram` | 🟡 | 需 WXML 转发 `bindtouch*`;`selectorCtx` 传组件实例 |
|
|
49
|
+
| 浏览器 / H5 双端 | `mini-three-adapter/browser` | ✅ 单元级 | `globalThis` 不被覆盖;canvas 的原生事件目标与 DOM 成员同样保留(ADR-0010,`nativeEventTarget`) |
|
|
50
|
+
| 其他小程序 / 小游戏平台 | 自定义 `PlatformBinding` | 🟡 框架就绪 | 按 [`docs/08`](./08-extension-guide.md#81-新增一个平台) 实现 |
|
|
51
|
+
| WebView 套壳 | 不在范围内 | ❌ | 本方案用于非 WebView 原生渲染 |
|
|
52
|
+
|
|
53
|
+
## 11.4 Web / DOM API 覆盖
|
|
54
|
+
|
|
55
|
+
| API | 提供方式 | 状态 |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| `window` / `self` / `globalThis`(作用域内) | `MiniThreeScope` 自引用 | ✅ |
|
|
58
|
+
| `document.createElement('canvas' \| 'img')` | `createDocument` | ✅ |
|
|
59
|
+
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
60
|
+
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
61
|
+
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
62
|
+
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | `mini-three-blob:` → `data:` | ✅ |
|
|
63
|
+
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
64
|
+
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
65
|
+
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
66
|
+
| `requestAnimationFrame` / `cancelAnimationFrame` | `FrameScheduler` | ✅ |
|
|
67
|
+
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
68
|
+
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
69
|
+
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
70
|
+
| 图片原生事件(`img.onload` / `addEventListener('load')` / `decode()`) | 四级桥接:原生 `addEventListener` → `onload` 赋值 → `wx.getImageInfo` 诊断 → 2s watchdog;`onload` getter 非派发期间恒回桥接,覆盖「赋值即存」(模拟器)与「触发时读属性」(真机)两种时序(ADR-0011) | 🟡 单测 21 例覆盖全部宿主形态;真机宿主形态差异大,见 `docs/06` §6.3.1 |
|
|
71
|
+
| 纹理格式 | PNG / JPEG | ✅ WebP 在部分真机解码失败,见 §11.6 |
|
|
72
|
+
| `FileReader` / `WebSocket` / `AudioContext` | 缺省或透传 | ⚠️ 业务需要时按 `docs/08` 扩展 |
|
|
73
|
+
| `Worker` / `WebAssembly` | 透传宿主全局(`WXWebAssembly`) | 🟡 |
|
|
74
|
+
| `ResizeObserver` | no-op | ⚠️ |
|
|
75
|
+
| 完整 DOM(布局、CSS、事件冒泡树) | 不提供 | ❌ 超出范围 |
|
|
76
|
+
|
|
77
|
+
## 11.5 场景回归记录
|
|
78
|
+
|
|
79
|
+
以 three 官方示例场景为主体建立回归集,用 `examples/` 的三个平台工程逐一接入验证。
|
|
80
|
+
|
|
81
|
+
| 类别 | 覆盖目标 | 状态 | 备注 |
|
|
82
|
+
| --- | --- | --- | --- |
|
|
83
|
+
| `controls_*` | OrbitControls / TrackballControls / TransformControls 的多指交互 | ⬜ 未回归 | 优先验证 pointerId、capture、`pointercancel` |
|
|
84
|
+
| `loader_*` | GLTF / DRACO / KTX2 / OBJ / FBX | ⬜ 未回归 | 需配置 decoder 路径与分包 |
|
|
85
|
+
| `postprocessing_*` | EffectComposer / bloom / SSAO | ⬜ 未回归 | 注意深度缓冲与 render target 尺寸 |
|
|
86
|
+
| `animation_*` / `physics_*` | 骨骼动画 / wasm 物理 | ⬜ 未回归 | 涉及 wasm 资源预下载 |
|
|
87
|
+
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 | 95 个 Vitest 用例覆盖画布、事件、作用域、插件 |
|
|
88
|
+
|
|
89
|
+
每回归一条,在本表追加:`场景 id | three 版本 | 基础库 | 设备 | 结果 | 失败原因 | 新增 polyfill`。
|
|
90
|
+
|
|
91
|
+
## 11.6 已知限制汇总
|
|
92
|
+
|
|
93
|
+
1. 不模拟 WebGPU;`three/webgpu` 项目需改用 WebGL 构建目标。
|
|
94
|
+
2. `createImageBitmap` 恒为 `undefined`,依赖该 API 的库需自带降级。
|
|
95
|
+
3. 不提供完整 DOM;DOM 密集型 UI 库应走 WebView 方案。
|
|
96
|
+
4. 插件默认只改写 `node_modules` 中的三方生态代码;应用代码里直接写 `window` 不会自动改写(可开 `includeUserCode`)。
|
|
97
|
+
5. 对象 URL 是 `mini-three-blob:` + `data:`,不是浏览器 `blob:`;若有库硬编码 `blob:` 前缀判断,需要适配。
|
|
98
|
+
6. Worker 分包、`.wasm.br`、iOS 高性能+ 需业务按 `mini-three-assets.json` 的 `gameJsonSuggestion` 自行配置,插件不直接改 `game.json`。
|
|
99
|
+
7. 纹理请使用 PNG / JPEG。**WebP 在部分真机上无法解码**(`wx.createImage` 直接触发 `error`),这与适配层无关;`mini-three-adapter` 只会在 `wx.getImageInfo` 失败时给出指向格式的告警。
|
|
100
|
+
8. 图片事件桥接依赖宿主投递事件。真正的 `load`/`error` 拿不到时(宿主三种入口全无,或接受了 `onload` 却永不调用),一律在 **2s** 内由 watchdog 给出终态:`complete` 为真则派发 `load`,否则派发 `error` 并 `warnOnce('image-events-timeout', …, { path, src })`。这意味着 >2s 才能解码完的网络大图会被判失败,包内纹理不受影响。宿主「触发时读属性」的形态(真机)由访问器桥接保证读到的是函数,不会被遮蔽成 `undefined`(ADR-0011)。
|
package/docs/README.md
CHANGED
|
@@ -1,41 +1,41 @@
|
|
|
1
|
-
# 文档总索引
|
|
2
|
-
|
|
3
|
-
本目录是 `mini-three-adapter` 的**唯一权威文档源**。文档按「人读」与「AI 读」两类组织,全部为纯 Markdown,可直接作为大模型上下文。
|
|
4
|
-
|
|
5
|
-
## 推荐阅读顺序
|
|
6
|
-
|
|
7
|
-
| 顺序 | 文档 | 读者 | 目的 |
|
|
8
|
-
| --- | --- | --- | --- |
|
|
9
|
-
| 0 | [`../AGENTS.md`](../AGENTS.md) | **AI** | 不变量、命令、修改边界、评审清单 |
|
|
10
|
-
| 1 | [`../llms.txt`](../llms.txt) | **AI** | 全仓库文件索引与摘要(llms.txt 标准) |
|
|
11
|
-
| 2 | [01 设计目标与技术约束](./01-design-principles.md) | 人 / AI | 项目定位、环境约束、技术选型、能力边界 |
|
|
12
|
-
| 3 | [02 架构设计](./02-architecture.md) | 人 / AI | 分层、数据流、不变量 |
|
|
13
|
-
| 4 | [03 模块地图](./03-module-map.md) | **AI** | 改哪个文件、会影响谁 |
|
|
14
|
-
| 5 | [04 API 参考](./04-api-reference.md) | 人 / AI | 全部导出与签名 |
|
|
15
|
-
| 6 | [05 构建插件](./05-build-plugin.md) | 人 / AI | 编译期行为 |
|
|
16
|
-
| 7 | [06 平台差异与坑](./06-platform-notes.md) | 人 | 平台能力与已知问题 |
|
|
17
|
-
| 8 | [07 接入与集成指南](./07-integration-guide.md) | 人 | 从零接入现有项目 |
|
|
18
|
-
| 9 | [08 扩展指南](./08-extension-guide.md) | 人 / AI | 新增平台 / polyfill / 资源规则 |
|
|
19
|
-
| 10 | [09 测试与发布](./09-testing-and-release.md) | 人 | 命令与 CI |
|
|
20
|
-
| 11 | [10 AI 协作手册](./10-ai-playbook.md) | **AI** | 提示词模板与迭代工作流 |
|
|
21
|
-
| 12 | [11 兼容矩阵](./11-compat-matrix.md) | 人 / AI | 版本与能力边界 |
|
|
22
|
-
| 13 | [ADR](./adr/README.md) | 人 / AI | 每条关键决策的动机与后果 |
|
|
23
|
-
|
|
24
|
-
## 文档维护约定
|
|
25
|
-
|
|
26
|
-
1. **先读 `AGENTS.md` 的「架构不变量」**,任何改动不得破坏其中任意一条。
|
|
27
|
-
2. **任何行为变更必须同时更新** `docs/03-module-map.md`(若涉及文件职责变化)、`docs/04-api-reference.md`(若涉及导出)、`CHANGELOG.md`,并补一个 `tests/**/*.test.ts` 用例。
|
|
28
|
-
3. 文档编号即阅读顺序;新增文档时按主题插入并在本表、`README.md` 文档表、`llms.txt` 索引中同步登记。
|
|
29
|
-
4. 文档只描述本项目自身的结构与行为,保持自洽;外部规范链接集中放在 `01` 与 `06` 的对应小节。
|
|
30
|
-
|
|
31
|
-
## 文档与代码的对应关系
|
|
32
|
-
|
|
33
|
-
| 想了解 | 先看 |
|
|
34
|
-
| --- | --- |
|
|
35
|
-
| 某个源文件该不该改 | [03 模块地图](./03-module-map.md) |
|
|
36
|
-
| 某个 API 怎么调用 | [04 API 参考](./04-api-reference.md) |
|
|
37
|
-
| 为什么生成 `__m3()` / 资产去哪了 | [05 构建插件](./05-build-plugin.md) |
|
|
38
|
-
| 为什么这样分层 | [02 架构设计](./02-architecture.md) 与 [ADR](./adr/README.md) |
|
|
39
|
-
| 怎么把适配层装进项目 | [07 接入与集成指南](./07-integration-guide.md) |
|
|
40
|
-
| 怎么发布到 npm | [09 测试与发布](./09-testing-and-release.md#95-发布到-npm) |
|
|
41
|
-
| 用 AI 改代码时怎么提问 | [10 AI 协作手册](./10-ai-playbook.md) |
|
|
1
|
+
# 文档总索引
|
|
2
|
+
|
|
3
|
+
本目录是 `mini-three-adapter` 的**唯一权威文档源**。文档按「人读」与「AI 读」两类组织,全部为纯 Markdown,可直接作为大模型上下文。
|
|
4
|
+
|
|
5
|
+
## 推荐阅读顺序
|
|
6
|
+
|
|
7
|
+
| 顺序 | 文档 | 读者 | 目的 |
|
|
8
|
+
| --- | --- | --- | --- |
|
|
9
|
+
| 0 | [`../AGENTS.md`](../AGENTS.md) | **AI** | 不变量、命令、修改边界、评审清单 |
|
|
10
|
+
| 1 | [`../llms.txt`](../llms.txt) | **AI** | 全仓库文件索引与摘要(llms.txt 标准) |
|
|
11
|
+
| 2 | [01 设计目标与技术约束](./01-design-principles.md) | 人 / AI | 项目定位、环境约束、技术选型、能力边界 |
|
|
12
|
+
| 3 | [02 架构设计](./02-architecture.md) | 人 / AI | 分层、数据流、不变量 |
|
|
13
|
+
| 4 | [03 模块地图](./03-module-map.md) | **AI** | 改哪个文件、会影响谁 |
|
|
14
|
+
| 5 | [04 API 参考](./04-api-reference.md) | 人 / AI | 全部导出与签名 |
|
|
15
|
+
| 6 | [05 构建插件](./05-build-plugin.md) | 人 / AI | 编译期行为 |
|
|
16
|
+
| 7 | [06 平台差异与坑](./06-platform-notes.md) | 人 | 平台能力与已知问题 |
|
|
17
|
+
| 8 | [07 接入与集成指南](./07-integration-guide.md) | 人 | 从零接入现有项目 |
|
|
18
|
+
| 9 | [08 扩展指南](./08-extension-guide.md) | 人 / AI | 新增平台 / polyfill / 资源规则 |
|
|
19
|
+
| 10 | [09 测试与发布](./09-testing-and-release.md) | 人 | 命令与 CI |
|
|
20
|
+
| 11 | [10 AI 协作手册](./10-ai-playbook.md) | **AI** | 提示词模板与迭代工作流 |
|
|
21
|
+
| 12 | [11 兼容矩阵](./11-compat-matrix.md) | 人 / AI | 版本与能力边界 |
|
|
22
|
+
| 13 | [ADR](./adr/README.md) | 人 / AI | 每条关键决策的动机与后果 |
|
|
23
|
+
|
|
24
|
+
## 文档维护约定
|
|
25
|
+
|
|
26
|
+
1. **先读 `AGENTS.md` 的「架构不变量」**,任何改动不得破坏其中任意一条。
|
|
27
|
+
2. **任何行为变更必须同时更新** `docs/03-module-map.md`(若涉及文件职责变化)、`docs/04-api-reference.md`(若涉及导出)、`CHANGELOG.md`,并补一个 `tests/**/*.test.ts` 用例。
|
|
28
|
+
3. 文档编号即阅读顺序;新增文档时按主题插入并在本表、`README.md` 文档表、`llms.txt` 索引中同步登记。
|
|
29
|
+
4. 文档只描述本项目自身的结构与行为,保持自洽;外部规范链接集中放在 `01` 与 `06` 的对应小节。
|
|
30
|
+
|
|
31
|
+
## 文档与代码的对应关系
|
|
32
|
+
|
|
33
|
+
| 想了解 | 先看 |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| 某个源文件该不该改 | [03 模块地图](./03-module-map.md) |
|
|
36
|
+
| 某个 API 怎么调用 | [04 API 参考](./04-api-reference.md) |
|
|
37
|
+
| 为什么生成 `__m3()` / 资产去哪了 | [05 构建插件](./05-build-plugin.md) |
|
|
38
|
+
| 为什么这样分层 | [02 架构设计](./02-architecture.md) 与 [ADR](./adr/README.md) |
|
|
39
|
+
| 怎么把适配层装进项目 | [07 接入与集成指南](./07-integration-guide.md) |
|
|
40
|
+
| 怎么发布到 npm | [09 测试与发布](./09-testing-and-release.md#95-发布到-npm) |
|
|
41
|
+
| 用 AI 改代码时怎么提问 | [10 AI 协作手册](./10-ai-playbook.md) |
|
|
@@ -1,41 +1,41 @@
|
|
|
1
|
-
# ADR-0001 · 作用域化的浏览器环境 shim
|
|
2
|
-
|
|
3
|
-
- 状态:Accepted
|
|
4
|
-
- 日期:2026-11-08
|
|
5
|
-
- 影响模块:`src/scope.ts`、`src/core/runtime.ts`、`src/build/scope-rewrite.ts`、`src/build/vite.ts`
|
|
6
|
-
|
|
7
|
-
## 背景
|
|
8
|
-
|
|
9
|
-
小游戏运行时没有 DOM/BOM,three 及其 addons 却会读取 `window`、`document`、`Image`、`URL` 等浏览器全局。要让这些代码工作,就必须有一个地方提供这些对象。
|
|
10
|
-
|
|
11
|
-
如果把 shim 直接挂到 `globalThis`,或者约定一个固定名字的全局容器,会带来几个结构性问题:H5 双端构建会与真实 `window` 冲突;同一进程里无法并存两个独立 runtime;单元测试无法干净还原;全局名靠约定,出错时难以定位。此外,三方模块中的全局引用是在模块求值时发生的,作用域何时可用必须是可以推理的,而不能依赖 import 的隐式副作用。
|
|
12
|
-
|
|
13
|
-
## 决策
|
|
14
|
-
|
|
15
|
-
1. 所有 shim 只存在于一个显式的 `MiniThreeScope` 对象里,`window === self === globalThis === scope`。
|
|
16
|
-
2. `setActiveScope(scope)` 返回 disposer;`getActiveScope()` 供构建插件注入的 `__m3()` 使用,且每次访问都返回**当前**作用域,支持运行时替换。
|
|
17
|
-
3. 三方模块通过构建插件改写为 `__m3().window`;应用代码不受影响。
|
|
18
|
-
4. `installGlobals(scope)` 是**唯一**写 `globalThis` 的地方,必须显式调用、返回精确还原 descriptor 的 disposer,默认关闭。
|
|
19
|
-
5. 未创建 runtime 时 `getActiveScope()` 返回一个占位对象:`typeof x.window` 仍为 `'object'`(满足 three 特性检测),但真正取属性时抛出带指引的错误。
|
|
20
|
-
|
|
21
|
-
## 理由
|
|
22
|
-
|
|
23
|
-
- 可逆性让测试、热更新、多实例、H5 双端都成为可能。
|
|
24
|
-
- 显式生命周期让「作用域何时可用」成为可推理的问题。
|
|
25
|
-
- 惰性读取让作用域可以在不重新构建三方模块的前提下被替换。
|
|
26
|
-
|
|
27
|
-
## 后果
|
|
28
|
-
|
|
29
|
-
- 正面:H5 双端同源、可 `dispose()`、可注入 mock、可观测。
|
|
30
|
-
- 负面:**必须先创建 runtime 再让 three 模块求值**,因此入口必须用动态 `import('./scene.js')`;这是一个需要写进文档与示例的约束(见 `docs/06` §6.2)。
|
|
31
|
-
- 风险:若某个三方库在模块顶层就把 `window.innerWidth` 缓存下来,动态 import 顺序错误会得到占位值——占位作用域会抛明确错误而不是静默返回错误值。
|
|
32
|
-
|
|
33
|
-
## 被否决的备选方案
|
|
34
|
-
|
|
35
|
-
- 直接 `globalThis.window = ...`:简单但不可逆,否决。
|
|
36
|
-
- 每个 runtime 一个 Proxy 拦截全局:性能与兼容性(JSC)风险,且仍要写全局,否决。
|
|
37
|
-
- 让用户在业务代码里手动 `import { scope }`:侵入太大,三方库改不到,否决。
|
|
38
|
-
|
|
39
|
-
## 验证方式
|
|
40
|
-
|
|
41
|
-
`tests/runtime.test.ts`:「populates a scoped environment without polluting globalThis」「installGlobals is reversible」;`tests/scope-rewrite.test.ts`:注入的 import 与 `typeof` 行为。
|
|
1
|
+
# ADR-0001 · 作用域化的浏览器环境 shim
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted
|
|
4
|
+
- 日期:2026-11-08
|
|
5
|
+
- 影响模块:`src/scope.ts`、`src/core/runtime.ts`、`src/build/scope-rewrite.ts`、`src/build/vite.ts`
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
小游戏运行时没有 DOM/BOM,three 及其 addons 却会读取 `window`、`document`、`Image`、`URL` 等浏览器全局。要让这些代码工作,就必须有一个地方提供这些对象。
|
|
10
|
+
|
|
11
|
+
如果把 shim 直接挂到 `globalThis`,或者约定一个固定名字的全局容器,会带来几个结构性问题:H5 双端构建会与真实 `window` 冲突;同一进程里无法并存两个独立 runtime;单元测试无法干净还原;全局名靠约定,出错时难以定位。此外,三方模块中的全局引用是在模块求值时发生的,作用域何时可用必须是可以推理的,而不能依赖 import 的隐式副作用。
|
|
12
|
+
|
|
13
|
+
## 决策
|
|
14
|
+
|
|
15
|
+
1. 所有 shim 只存在于一个显式的 `MiniThreeScope` 对象里,`window === self === globalThis === scope`。
|
|
16
|
+
2. `setActiveScope(scope)` 返回 disposer;`getActiveScope()` 供构建插件注入的 `__m3()` 使用,且每次访问都返回**当前**作用域,支持运行时替换。
|
|
17
|
+
3. 三方模块通过构建插件改写为 `__m3().window`;应用代码不受影响。
|
|
18
|
+
4. `installGlobals(scope)` 是**唯一**写 `globalThis` 的地方,必须显式调用、返回精确还原 descriptor 的 disposer,默认关闭。
|
|
19
|
+
5. 未创建 runtime 时 `getActiveScope()` 返回一个占位对象:`typeof x.window` 仍为 `'object'`(满足 three 特性检测),但真正取属性时抛出带指引的错误。
|
|
20
|
+
|
|
21
|
+
## 理由
|
|
22
|
+
|
|
23
|
+
- 可逆性让测试、热更新、多实例、H5 双端都成为可能。
|
|
24
|
+
- 显式生命周期让「作用域何时可用」成为可推理的问题。
|
|
25
|
+
- 惰性读取让作用域可以在不重新构建三方模块的前提下被替换。
|
|
26
|
+
|
|
27
|
+
## 后果
|
|
28
|
+
|
|
29
|
+
- 正面:H5 双端同源、可 `dispose()`、可注入 mock、可观测。
|
|
30
|
+
- 负面:**必须先创建 runtime 再让 three 模块求值**,因此入口必须用动态 `import('./scene.js')`;这是一个需要写进文档与示例的约束(见 `docs/06` §6.2)。
|
|
31
|
+
- 风险:若某个三方库在模块顶层就把 `window.innerWidth` 缓存下来,动态 import 顺序错误会得到占位值——占位作用域会抛明确错误而不是静默返回错误值。
|
|
32
|
+
|
|
33
|
+
## 被否决的备选方案
|
|
34
|
+
|
|
35
|
+
- 直接 `globalThis.window = ...`:简单但不可逆,否决。
|
|
36
|
+
- 每个 runtime 一个 Proxy 拦截全局:性能与兼容性(JSC)风险,且仍要写全局,否决。
|
|
37
|
+
- 让用户在业务代码里手动 `import { scope }`:侵入太大,三方库改不到,否决。
|
|
38
|
+
|
|
39
|
+
## 验证方式
|
|
40
|
+
|
|
41
|
+
`tests/runtime.test.ts`:「populates a scoped environment without polluting globalThis」「installGlobals is reversible」;`tests/scope-rewrite.test.ts`:注入的 import 与 `typeof` 行为。
|
|
@@ -1,40 +1,40 @@
|
|
|
1
|
-
# ADR-0002 · 单一 `createRuntime()` / `MiniThreeRuntime` 生命周期
|
|
2
|
-
|
|
3
|
-
- 状态:Accepted
|
|
4
|
-
- 日期:2026-11-08
|
|
5
|
-
- 影响模块:`src/core/platform.ts`、`src/core/runtime.ts`、`src/platforms/*`、`src/index.ts`
|
|
6
|
-
|
|
7
|
-
## 背景
|
|
8
|
-
|
|
9
|
-
小游戏与小程序的画布获取方式本质不同:前者可以同步拿到唯一的上屏画布,后者需要异步查询节点。如果按平台分别暴露门面,业务代码就要写两套调用方式,订阅、rAF、全局注入也容易散落在各处,缺少统一的销毁入口。
|
|
10
|
-
|
|
11
|
-
需要一个装配点,把这些差异吸收在内部,对业务只暴露一个对象和一种生命周期。
|
|
12
|
-
|
|
13
|
-
## 决策
|
|
14
|
-
|
|
15
|
-
1. 定义结构化契约 `PlatformBinding`(不是抽象基类),把平台差异收敛为一组字段/方法。
|
|
16
|
-
2. 只有 `createRuntime(platform, options)` 一个装配入口,返回唯一的 `MiniThreeRuntime`。
|
|
17
|
-
3. 三个平台快捷函数(`createWeChatGameRuntime` / `createWeChatMiniProgramRuntime` / `createBrowserRuntime`)只是「构造 binding + 调 createRuntime」的语法糖,全部返回 `Promise<MiniThreeRuntime>`。
|
|
18
|
-
4. 小程序异步查询、小游戏同步画布的差异被 `await binding.getCanvasRect()` 吸收;对外只有 `await runtime.resize()` 一种写法。
|
|
19
|
-
5. 所有订阅、定时器、全局注入登记到 `disposers`,`runtime.dispose()` 逆序执行;`runtime.on('dispose')` 供业务释放 three 资源。
|
|
20
|
-
|
|
21
|
-
## 理由
|
|
22
|
-
|
|
23
|
-
- 用组合(结构化接口)替代继承,平台实现不必继承基类、不必暴露内部装配状态。
|
|
24
|
-
- 单一生命周期使「有没有泄漏」变成可测试命题,也让 AI 迭代时只有一个心智模型。
|
|
25
|
-
- 统一异步 API 消除了按平台分支带来的文档、类型与接入成本。
|
|
26
|
-
|
|
27
|
-
## 后果
|
|
28
|
-
|
|
29
|
-
- 正面:业务代码三端一致;`dispose()` 可验证;新增平台只需实现 `PlatformBinding`。
|
|
30
|
-
- 负面:小游戏本来可以同步启动,现在必须 `await` 一次(代价可忽略,且启动时本来就要读窗口信息)。
|
|
31
|
-
- 风险:平台实现若忘记把某个监听加入 `dispose()`,仍会泄漏——由 `docs/08` 评审清单与测试约束。
|
|
32
|
-
|
|
33
|
-
## 被否决的备选方案
|
|
34
|
-
|
|
35
|
-
- 按平台分别暴露门面再包一层兼容:把复杂度永久留在 API 里,否决。
|
|
36
|
-
- 平台抽象基类 + 条件类型:需要继承、难以组合、类型可读性差,否决。
|
|
37
|
-
|
|
38
|
-
## 验证方式
|
|
39
|
-
|
|
40
|
-
`tests/runtime.test.ts`:「emits resize and dispose events, and fully tears down」断言 `wx.__touch.start` 被清空、`disposed === true`。
|
|
1
|
+
# ADR-0002 · 单一 `createRuntime()` / `MiniThreeRuntime` 生命周期
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted
|
|
4
|
+
- 日期:2026-11-08
|
|
5
|
+
- 影响模块:`src/core/platform.ts`、`src/core/runtime.ts`、`src/platforms/*`、`src/index.ts`
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
小游戏与小程序的画布获取方式本质不同:前者可以同步拿到唯一的上屏画布,后者需要异步查询节点。如果按平台分别暴露门面,业务代码就要写两套调用方式,订阅、rAF、全局注入也容易散落在各处,缺少统一的销毁入口。
|
|
10
|
+
|
|
11
|
+
需要一个装配点,把这些差异吸收在内部,对业务只暴露一个对象和一种生命周期。
|
|
12
|
+
|
|
13
|
+
## 决策
|
|
14
|
+
|
|
15
|
+
1. 定义结构化契约 `PlatformBinding`(不是抽象基类),把平台差异收敛为一组字段/方法。
|
|
16
|
+
2. 只有 `createRuntime(platform, options)` 一个装配入口,返回唯一的 `MiniThreeRuntime`。
|
|
17
|
+
3. 三个平台快捷函数(`createWeChatGameRuntime` / `createWeChatMiniProgramRuntime` / `createBrowserRuntime`)只是「构造 binding + 调 createRuntime」的语法糖,全部返回 `Promise<MiniThreeRuntime>`。
|
|
18
|
+
4. 小程序异步查询、小游戏同步画布的差异被 `await binding.getCanvasRect()` 吸收;对外只有 `await runtime.resize()` 一种写法。
|
|
19
|
+
5. 所有订阅、定时器、全局注入登记到 `disposers`,`runtime.dispose()` 逆序执行;`runtime.on('dispose')` 供业务释放 three 资源。
|
|
20
|
+
|
|
21
|
+
## 理由
|
|
22
|
+
|
|
23
|
+
- 用组合(结构化接口)替代继承,平台实现不必继承基类、不必暴露内部装配状态。
|
|
24
|
+
- 单一生命周期使「有没有泄漏」变成可测试命题,也让 AI 迭代时只有一个心智模型。
|
|
25
|
+
- 统一异步 API 消除了按平台分支带来的文档、类型与接入成本。
|
|
26
|
+
|
|
27
|
+
## 后果
|
|
28
|
+
|
|
29
|
+
- 正面:业务代码三端一致;`dispose()` 可验证;新增平台只需实现 `PlatformBinding`。
|
|
30
|
+
- 负面:小游戏本来可以同步启动,现在必须 `await` 一次(代价可忽略,且启动时本来就要读窗口信息)。
|
|
31
|
+
- 风险:平台实现若忘记把某个监听加入 `dispose()`,仍会泄漏——由 `docs/08` 评审清单与测试约束。
|
|
32
|
+
|
|
33
|
+
## 被否决的备选方案
|
|
34
|
+
|
|
35
|
+
- 按平台分别暴露门面再包一层兼容:把复杂度永久留在 API 里,否决。
|
|
36
|
+
- 平台抽象基类 + 条件类型:需要继承、难以组合、类型可读性差,否决。
|
|
37
|
+
|
|
38
|
+
## 验证方式
|
|
39
|
+
|
|
40
|
+
`tests/runtime.test.ts`:「emits resize and dispose events, and fully tears down」断言 `wx.__touch.start` 被清空、`disposed === true`。
|
|
@@ -1,51 +1,51 @@
|
|
|
1
|
-
# ADR-0003 · 用 Babel AST 作用域分析重写三方模块全局引用
|
|
2
|
-
|
|
3
|
-
- 状态:Accepted
|
|
4
|
-
- 日期:2026-11-08
|
|
5
|
-
- 影响模块:`src/build/scope-rewrite.ts`、`src/build/plugin-core.ts`、`src/build/assets.ts`
|
|
6
|
-
|
|
7
|
-
## 背景
|
|
8
|
-
|
|
9
|
-
「不 fork three」的前提是能在构建期把三方代码里的浏览器全局访问重定向到作用域对象。文本或近似作用域替换在以下场景会误伤:
|
|
10
|
-
|
|
11
|
-
```js
|
|
12
|
-
function f(window) { return window.innerWidth; } // 局部同名
|
|
13
|
-
const o = { window: 1 }; // 对象键
|
|
14
|
-
foo.window; // 成员属性
|
|
15
|
-
if (typeof window !== 'undefined') { ... } // 特性检测
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
随着 three 及其生态(three-stdlib、r3f、tresjs)代码量增长,误伤概率与版本升级成本都很高。改写必须建立在真实的词法作用域信息之上。
|
|
19
|
-
|
|
20
|
-
## 决策
|
|
21
|
-
|
|
22
|
-
1. 用 `@babel/parser`(`sourceType: 'unambiguous'`,启用 TS/JSX 插件)解析每个候选模块。
|
|
23
|
-
2. 用 `@babel/traverse` 的 `ReferencedIdentifier` visitor,只处理**引用位置**的标识符。
|
|
24
|
-
3. 通过 `path.scope.hasBinding(name, true)` 判定是否为自由变量(第二参数屏蔽 Babel 内建全局表,否则 `window` 会被当成 binding 而漏改)。
|
|
25
|
-
4. 排除非计算的对象键、类成员键、成员表达式属性。
|
|
26
|
-
5. 用 `MagicString.overwrite` 精确替换并 `prepend` 一行 `import { getActiveScope as __m3 } from 'mini-three-adapter/scope';`,保留 sourcemap。
|
|
27
|
-
6. `globalThis` 故意不在默认清单(three 用它挂调试钩子)。
|
|
28
|
-
7. 解析失败 → 记录 `parseFailures`、告警、**原样返回**,绝不产出半改写代码。
|
|
29
|
-
|
|
30
|
-
## 理由
|
|
31
|
-
|
|
32
|
-
- 作用域正确性由 Babel 保证,不用自己实现词法作用域。
|
|
33
|
-
- 精确 rewrite + sourcemap 便于调试与 CI 统计(`BuildReport`)。
|
|
34
|
-
- 把「三方代码」与「应用代码」的边界显式化为 `include(id)`,可审计。
|
|
35
|
-
|
|
36
|
-
## 后果
|
|
37
|
-
|
|
38
|
-
- 正面:局部遮蔽、`typeof`、对象键全部正确;支持 TS/JSX;构建报告可观测。
|
|
39
|
-
- 负面:构建期新增 `@babel/parser` / `@babel/traverse` / `magic-string` 三个依赖(**只在 Node 侧,不进小游戏包**);解析有少量构建耗时。
|
|
40
|
-
- 风险:Vite 预打包会把 three 变成一个不透明 blob → `vite.ts` 的 `config()` 显式 `optimizeDeps.exclude`;`.vite/deps/three*` 作为兜底 include。
|
|
41
|
-
- 风险:某模块用了 Babel 不支持的语法 → 跳过并告警,需人工加插件或 `exclude`。
|
|
42
|
-
|
|
43
|
-
## 被否决的备选方案
|
|
44
|
-
|
|
45
|
-
- 正则 / 字符串替换:正确性无法保证,否决。
|
|
46
|
-
- Rollup `attachScopes` + 自定义遍历:能拿到作用域但要自己处理所有节点类型,维护成本高,否决。
|
|
47
|
-
- 运行时 `with` / Proxy 作用域:性能与严格模式限制,否决。
|
|
48
|
-
|
|
49
|
-
## 验证方式
|
|
50
|
-
|
|
51
|
-
`tests/scope-rewrite.test.ts` 8 例:自由变量、局部遮蔽、对象键/成员属性、`typeof`、import/export 不改写、无命中返回 null、自定义访问器、默认清单不含 `globalThis`。
|
|
1
|
+
# ADR-0003 · 用 Babel AST 作用域分析重写三方模块全局引用
|
|
2
|
+
|
|
3
|
+
- 状态:Accepted
|
|
4
|
+
- 日期:2026-11-08
|
|
5
|
+
- 影响模块:`src/build/scope-rewrite.ts`、`src/build/plugin-core.ts`、`src/build/assets.ts`
|
|
6
|
+
|
|
7
|
+
## 背景
|
|
8
|
+
|
|
9
|
+
「不 fork three」的前提是能在构建期把三方代码里的浏览器全局访问重定向到作用域对象。文本或近似作用域替换在以下场景会误伤:
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
function f(window) { return window.innerWidth; } // 局部同名
|
|
13
|
+
const o = { window: 1 }; // 对象键
|
|
14
|
+
foo.window; // 成员属性
|
|
15
|
+
if (typeof window !== 'undefined') { ... } // 特性检测
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
随着 three 及其生态(three-stdlib、r3f、tresjs)代码量增长,误伤概率与版本升级成本都很高。改写必须建立在真实的词法作用域信息之上。
|
|
19
|
+
|
|
20
|
+
## 决策
|
|
21
|
+
|
|
22
|
+
1. 用 `@babel/parser`(`sourceType: 'unambiguous'`,启用 TS/JSX 插件)解析每个候选模块。
|
|
23
|
+
2. 用 `@babel/traverse` 的 `ReferencedIdentifier` visitor,只处理**引用位置**的标识符。
|
|
24
|
+
3. 通过 `path.scope.hasBinding(name, true)` 判定是否为自由变量(第二参数屏蔽 Babel 内建全局表,否则 `window` 会被当成 binding 而漏改)。
|
|
25
|
+
4. 排除非计算的对象键、类成员键、成员表达式属性。
|
|
26
|
+
5. 用 `MagicString.overwrite` 精确替换并 `prepend` 一行 `import { getActiveScope as __m3 } from 'mini-three-adapter/scope';`,保留 sourcemap。
|
|
27
|
+
6. `globalThis` 故意不在默认清单(three 用它挂调试钩子)。
|
|
28
|
+
7. 解析失败 → 记录 `parseFailures`、告警、**原样返回**,绝不产出半改写代码。
|
|
29
|
+
|
|
30
|
+
## 理由
|
|
31
|
+
|
|
32
|
+
- 作用域正确性由 Babel 保证,不用自己实现词法作用域。
|
|
33
|
+
- 精确 rewrite + sourcemap 便于调试与 CI 统计(`BuildReport`)。
|
|
34
|
+
- 把「三方代码」与「应用代码」的边界显式化为 `include(id)`,可审计。
|
|
35
|
+
|
|
36
|
+
## 后果
|
|
37
|
+
|
|
38
|
+
- 正面:局部遮蔽、`typeof`、对象键全部正确;支持 TS/JSX;构建报告可观测。
|
|
39
|
+
- 负面:构建期新增 `@babel/parser` / `@babel/traverse` / `magic-string` 三个依赖(**只在 Node 侧,不进小游戏包**);解析有少量构建耗时。
|
|
40
|
+
- 风险:Vite 预打包会把 three 变成一个不透明 blob → `vite.ts` 的 `config()` 显式 `optimizeDeps.exclude`;`.vite/deps/three*` 作为兜底 include。
|
|
41
|
+
- 风险:某模块用了 Babel 不支持的语法 → 跳过并告警,需人工加插件或 `exclude`。
|
|
42
|
+
|
|
43
|
+
## 被否决的备选方案
|
|
44
|
+
|
|
45
|
+
- 正则 / 字符串替换:正确性无法保证,否决。
|
|
46
|
+
- Rollup `attachScopes` + 自定义遍历:能拿到作用域但要自己处理所有节点类型,维护成本高,否决。
|
|
47
|
+
- 运行时 `with` / Proxy 作用域:性能与严格模式限制,否决。
|
|
48
|
+
|
|
49
|
+
## 验证方式
|
|
50
|
+
|
|
51
|
+
`tests/scope-rewrite.test.ts` 8 例:自由变量、局部遮蔽、对象键/成员属性、`typeof`、import/export 不改写、无命中返回 null、自定义访问器、默认清单不含 `globalThis`。
|