mini-three-adapter 0.1.3 → 0.1.4

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.
Files changed (43) hide show
  1. package/AGENTS.md +85 -85
  2. package/README.md +159 -159
  3. package/dist/build/rollup.js.map +1 -1
  4. package/dist/build/vite.js.map +1 -1
  5. package/dist/{chunk-OL7NVZZJ.js → chunk-26BRT4GS.js} +21 -12
  6. package/dist/chunk-26BRT4GS.js.map +1 -0
  7. package/dist/{chunk-WZ2HKYC5.js → chunk-2WNTAMJZ.js} +4 -4
  8. package/dist/{chunk-WZ2HKYC5.js.map → chunk-2WNTAMJZ.js.map} +1 -1
  9. package/dist/{chunk-34RWHAW4.js → chunk-35XVAVDB.js} +23 -5
  10. package/dist/chunk-35XVAVDB.js.map +1 -0
  11. package/dist/{chunk-3QUEDYTT.js → chunk-HJIO6AFC.js} +19 -11
  12. package/dist/chunk-HJIO6AFC.js.map +1 -0
  13. package/dist/{chunk-52IMRKOX.js → chunk-NC2FTUEU.js} +3 -3
  14. package/dist/{chunk-52IMRKOX.js.map → chunk-NC2FTUEU.js.map} +1 -1
  15. package/dist/{chunk-J7VBWZRR.js → chunk-XUKHCVAV.js} +11 -3
  16. package/dist/chunk-XUKHCVAV.js.map +1 -0
  17. package/dist/core/index.js +2 -2
  18. package/dist/index.d.ts +1 -1
  19. package/dist/index.js +6 -6
  20. package/dist/platforms/browser.js +3 -3
  21. package/dist/platforms/wechat-game.js +4 -4
  22. package/dist/platforms/wechat-miniprogram.js +4 -4
  23. package/dist/scope.d.ts +8 -1
  24. package/dist/scope.js +1 -1
  25. package/docs/02-architecture.md +4 -4
  26. package/docs/03-module-map.md +99 -99
  27. package/docs/04-api-reference.md +304 -294
  28. package/docs/05-build-plugin.md +4 -2
  29. package/docs/06-platform-notes.md +5 -5
  30. package/docs/07-integration-guide.md +1 -1
  31. package/docs/09-testing-and-release.md +210 -209
  32. package/docs/10-ai-playbook.md +2 -1
  33. package/docs/11-compat-matrix.md +2 -2
  34. package/docs/adr/0007-capability-probe-fallback.md +8 -4
  35. package/docs/adr/0008-probe-fallback-boundary.md +56 -0
  36. package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -0
  37. package/docs/adr/README.md +3 -1
  38. package/llms.txt +4 -1
  39. package/package.json +1 -1
  40. package/dist/chunk-34RWHAW4.js.map +0 -1
  41. package/dist/chunk-3QUEDYTT.js.map +0 -1
  42. package/dist/chunk-J7VBWZRR.js.map +0 -1
  43. package/dist/chunk-OL7NVZZJ.js.map +0 -1
package/AGENTS.md CHANGED
@@ -1,85 +1,85 @@
1
- # AGENTS.md · AI 协作约束
2
-
3
- > 本文件是**给 AI 编码助手的第一入口**。任何自动修改前先读完本文,再按 [`docs/10-ai-playbook.md`](./docs/10-ai-playbook.md#101-上下文装载顺序每次会话先做) 装载最小上下文。
4
-
5
- ## 项目一句话
6
-
7
- `mini-three-adapter` 是一个 TypeScript 编写、ESM、零全局污染的 **微信小游戏 / 小程序 Three.js 适配层**:构建期用 AST 把三方模块的浏览器全局引用重定向到作用域对象,运行期用 `PlatformBinding` 把 `wx` 的原始 canvas 就地补成一个可 `dispose()` 的 `MiniThreeRuntime`。
8
-
9
- ## 必读文件顺序
10
-
11
- 1. `AGENTS.md`(本文)
12
- 2. `llms.txt`
13
- 3. `docs/03-module-map.md`(**改哪个文件**)
14
- 4. `docs/02-architecture.md` 的「架构不变量」
15
- 5. 相关 `docs/adr/*.md`
16
- 6. `docs/10-ai-playbook.md`(提示词模板与反模式)
17
-
18
- 只需读取目标文件及其直接依赖,不要一次性加载整个 `src/`。
19
-
20
- ## 命令
21
-
22
- ```bash
23
- npm run typecheck # tsc --noEmit, strict + noUncheckedIndexedAccess
24
- npm test # vitest run(单 fork,63 例)
25
- npm run build # tsup → dist/*.js + *.d.ts
26
- npm run check # 以上全部
27
- ```
28
-
29
- Windows 临时目录权限问题:`TMP="$PWD/.tmp/vitest" TEMP="$PWD/.tmp/vitest" npm test`。
30
-
31
- ## 架构不变量(**不得破坏**)
32
-
33
- 1. **只有一个上屏画布**:`wx.createCanvas()` 只在 `getScreenCanvas()` 调用一次并缓存,之后的调用只会得到离屏画布。能力探测优先用 `wx.createOffscreenCanvas()`;仅在上屏画布**已解析之后**、且调用方显式 opt-in 时,才可按 [ADR-0007](./docs/adr/0007-capability-probe-fallback.md) 回退到第二次 `createCanvas()`。
34
- 2. **对象身份不变**:canvas / image 永远是 `wx` 返回的那个对象。禁止 `new Proxy` 包装、`Object.setPrototypeOf`、返回克隆体。用 `Object.defineProperty` + `Symbol.hasInstance` 注册表。
35
- 3. **默认零全局污染**:只有 `installGlobals()` 写 `globalThis`,必须显式调用、必须可逆;三方代码只能经 `getActiveScope()` 拿 shim。
36
- 4. **`three` 零运行时依赖**:`src/` 不得 `import 'three'`;它是 optional peer + external。
37
- 5. **平台无关核心**:`core/` 不得 import `platforms/*`;差异全部收敛到 `PlatformBinding`。
38
- 6. **构建 / 运行隔离**:`build/*` 不 import `core/*`/`platforms/*`;`node:fs` 只在 `build/` 出现。
39
- 7. **单一生命周期**:所有订阅、定时器、全局注入登记到 `disposers`,`dispose()` 后无残留。
40
- 8. **WebGL2 优先**:`document.createElement('canvas')` 默认 webgl2;无 WebGL2 必须明确告警,不静默降级。
41
- 9. **改写只针对自由变量**:AST 重写必须走 `path.scope.hasBinding(name, true)`;禁止字符串/正则全局替换。
42
- 10. **破坏性行为必须显式**:全局注入、WebGPU rewrite、深度缓冲补丁等一律 opt-in。
43
-
44
- 若某改动必须违反其中一条:先写 `docs/adr/NNNN-*.md` 说明动机,再改代码。
45
-
46
- ## 代码约定
47
-
48
- - 严格 TypeScript;`verbatimModuleSyntax`,类型用 `import type`。
49
- - 只用 ASCII 直引号写语法;注释与文档用中文。
50
- - 运行时目标 `es2019`(避免 `?.` / `??` 造成开发者工具语法错误)。
51
- - 每个公开导出都要有 JSDoc 或类型注解,并同步 `docs/04-api-reference.md`。
52
- - 新 polyfill 放 `src/polyfills/`,自包含、不依赖 `core/`。
53
- - 新平台放 `src/platforms/`,实现 `PlatformBinding`,提供可注入 mock 宿主。
54
- - 日志一律用 `Diagnostics`(`warnOnce` 避免每帧刷屏),不要直接 `console.log`。
55
- - 不改写 three 源码语义,不在运行时猴补丁 `WebGLRenderer`。
56
-
57
- ## 修改后必做(Definition of Done)
58
-
59
- - [ ] 新增/更新 `tests/**/*.test.ts`(先写失败用例再修)
60
- - [ ] `npm run check` 全绿
61
- - [ ] `docs/03-module-map.md`(职责变化)、`docs/04-api-reference.md`(导出变化)、`docs/11-compat-matrix.md`(能力变化)
62
- - [ ] `CHANGELOG.md`
63
- - [ ] 触及不变量时新增/更新 ADR
64
- - [ ] 若是平台相关,补/改 `examples/`
65
-
66
- ## 目录边界
67
-
68
- | 目录 | 权限 |
69
- | --- | --- |
70
- | `src/`、`tests/`、`examples/`、`docs/` | 可修改 |
71
- | `dist/`、`node_modules/`、`.tmp/` | 生成物,不手改 |
72
- | `.workbuddy/` | 项目数据,禁止删除 |
73
-
74
- ## 常见反模式(直接拒绝)
75
-
76
- - 「在 `globalThis` 上补个 `window` 就好了」→ 用 `MiniThreeScope`
77
- - 「正则把 `window` 全替换」→ 用 Babel 作用域分析
78
- - 「包一层 Proxy / 改原型」→ 就地 `defineProperty`
79
- - 「探测时先调 `wx.createCanvas()`」→ 用 `createOffscreenCanvas`(`allowCanvasFallback` 只在 `getScreenCanvas()` 之后才有意义)
80
- - 「把 three 打进适配层」→ 保持 external peer
81
- - 「猴补丁 `WebGLRenderer.render` 清深度」→ 应用层显式 `renderer.clearDepth()`
82
-
83
- ## 需要人类决策时
84
-
85
- 以下情况**先问再做**:改变公开 API 签名、改变默认行为、新增运行时依赖、放宽架构不变量、删除项目文档、发布版本、修改许可。
1
+ # AGENTS.md · AI 协作约束
2
+
3
+ > 本文件是**给 AI 编码助手的第一入口**。任何自动修改前先读完本文,再按 [`docs/10-ai-playbook.md`](./docs/10-ai-playbook.md#101-上下文装载顺序每次会话先做) 装载最小上下文。
4
+
5
+ ## 项目一句话
6
+
7
+ `mini-three-adapter` 是一个 TypeScript 编写、ESM、零全局污染的 **微信小游戏 / 小程序 Three.js 适配层**:构建期用 AST 把三方模块的浏览器全局引用重定向到作用域对象,运行期用 `PlatformBinding` 把 `wx` 的原始 canvas 就地补成一个可 `dispose()` 的 `MiniThreeRuntime`。
8
+
9
+ ## 必读文件顺序
10
+
11
+ 1. `AGENTS.md`(本文)
12
+ 2. `llms.txt`
13
+ 3. `docs/03-module-map.md`(**改哪个文件**)
14
+ 4. `docs/02-architecture.md` 的「架构不变量」
15
+ 5. 相关 `docs/adr/*.md`
16
+ 6. `docs/10-ai-playbook.md`(提示词模板与反模式)
17
+
18
+ 只需读取目标文件及其直接依赖,不要一次性加载整个 `src/`。
19
+
20
+ ## 命令
21
+
22
+ ```bash
23
+ npm run typecheck # tsc --noEmit, strict + noUncheckedIndexedAccess
24
+ npm test # vitest run(单 fork,71 例)
25
+ npm run build # tsup → dist/*.js + *.d.ts
26
+ npm run check # 以上全部
27
+ ```
28
+
29
+ Windows 临时目录权限问题:`TMP="$PWD/.tmp/vitest" TEMP="$PWD/.tmp/vitest" npm test`。
30
+
31
+ ## 架构不变量(**不得破坏**)
32
+
33
+ 1. **只有一个上屏画布**:`wx.createCanvas()` 只在 `getScreenCanvas()` 调用一次并缓存,之后的调用只会得到离屏画布。能力探测优先用 `wx.createOffscreenCanvas()`;仅在上屏画布**已解析之后**、离屏 API **存在**、且调用方显式 opt-in 时,才可按 [ADR-0007](./docs/adr/0007-capability-probe-fallback.md)/[ADR-0008](./docs/adr/0008-probe-fallback-boundary.md) 回退到第二次 `createCanvas()`,并对候选上屏画布集合逐个比对身份。
34
+ 2. **对象身份不变**:canvas / image 永远是 `wx` 返回的那个对象。禁止 `new Proxy` 包装、`Object.setPrototypeOf`、返回克隆体。用 `Object.defineProperty` + `Symbol.hasInstance` 注册表。
35
+ 3. **默认零全局污染**:只有 `installGlobals()` 写 `globalThis`,必须显式调用、必须可逆;三方代码只能经 `getActiveScope()` 拿 shim。
36
+ 4. **`three` 零运行时依赖**:`src/` 不得 `import 'three'`;它是 optional peer + external。
37
+ 5. **平台无关核心**:`core/` 不得 import `platforms/*`;差异全部收敛到 `PlatformBinding`。
38
+ 6. **构建 / 运行隔离**:`build/*` 不 import `core/*`/`platforms/*`;`node:fs` 只在 `build/` 出现。
39
+ 7. **单一生命周期**:所有订阅、定时器、全局注入登记到 `disposers`,`dispose()` 后无残留。
40
+ 8. **WebGL2 优先**:`document.createElement('canvas')` 默认 webgl2;无 WebGL2 必须明确告警,不静默降级。
41
+ 9. **改写只针对自由变量**:AST 重写必须走 `path.scope.hasBinding(name, true)`;禁止字符串/正则全局替换。
42
+ 10. **破坏性行为必须显式**:全局注入、WebGPU rewrite、深度缓冲补丁等一律 opt-in。
43
+
44
+ 若某改动必须违反其中一条:先写 `docs/adr/NNNN-*.md` 说明动机,再改代码。
45
+
46
+ ## 代码约定
47
+
48
+ - 严格 TypeScript;`verbatimModuleSyntax`,类型用 `import type`。
49
+ - 只用 ASCII 直引号写语法;注释与文档用中文。
50
+ - 运行时目标 `es2019`(避免 `?.` / `??` 造成开发者工具语法错误)。
51
+ - 每个公开导出都要有 JSDoc 或类型注解,并同步 `docs/04-api-reference.md`。
52
+ - 新 polyfill 放 `src/polyfills/`,自包含、不依赖 `core/`。
53
+ - 新平台放 `src/platforms/`,实现 `PlatformBinding`,提供可注入 mock 宿主。
54
+ - 日志一律用 `Diagnostics`(`warnOnce` 避免每帧刷屏),不要直接 `console.log`。
55
+ - 不改写 three 源码语义,不在运行时猴补丁 `WebGLRenderer`。
56
+
57
+ ## 修改后必做(Definition of Done)
58
+
59
+ - [ ] 新增/更新 `tests/**/*.test.ts`(先写失败用例再修)
60
+ - [ ] `npm run check` 全绿
61
+ - [ ] `docs/03-module-map.md`(职责变化)、`docs/04-api-reference.md`(导出变化)、`docs/11-compat-matrix.md`(能力变化)
62
+ - [ ] `CHANGELOG.md`
63
+ - [ ] 触及不变量时新增/更新 ADR
64
+ - [ ] 若是平台相关,补/改 `examples/`
65
+
66
+ ## 目录边界
67
+
68
+ | 目录 | 权限 |
69
+ | --- | --- |
70
+ | `src/`、`tests/`、`examples/`、`docs/` | 可修改 |
71
+ | `dist/`、`node_modules/`、`.tmp/` | 生成物,不手改 |
72
+ | `.workbuddy/` | 项目数据,禁止删除 |
73
+
74
+ ## 常见反模式(直接拒绝)
75
+
76
+ - 「在 `globalThis` 上补个 `window` 就好了」→ 用 `MiniThreeScope`
77
+ - 「正则把 `window` 全替换」→ 用 Babel 作用域分析
78
+ - 「包一层 Proxy / 改原型」→ 就地 `defineProperty`
79
+ - 「探测时先调 `wx.createCanvas()`」→ 用 `createOffscreenCanvas`(`allowCanvasFallback` 只在 `getScreenCanvas()` 之后才有意义)
80
+ - 「把 three 打进适配层」→ 保持 external peer
81
+ - 「猴补丁 `WebGLRenderer.render` 清深度」→ 应用层显式 `renderer.clearDepth()`
82
+
83
+ ## 需要人类决策时
84
+
85
+ 以下情况**先问再做**:改变公开 API 签名、改变默认行为、新增运行时依赖、放宽架构不变量、删除项目文档、发布版本、修改许可。
package/README.md CHANGED
@@ -1,159 +1,159 @@
1
- # mini-three-adapter
2
-
3
- > 面向微信小游戏 / 小程序的 Three.js 适配层。TypeScript 优先、ESM、零全局污染、可释放、可测试。
4
-
5
- 让标准 three.js 场景代码运行在非 WebView 的原生渲染环境里:业务侧照常写 `new THREE.WebGLRenderer({ canvas })`、`three/addons/*` 的控制器与加载器,适配层负责补齐宿主缺失的浏览器环境、桥接触摸事件、管理画布与资源。
6
-
7
- ---
8
-
9
- ## 设计要点
10
-
11
- - **作用域化 shim**:所有 `window` / `document` / `Image` 等兼容对象集中在一个显式、可替换、可卸载的 `MiniThreeScope` 中,默认不写 `globalThis`。
12
- - **构建期精确重定向**:用 `@babel/parser` + 作用域绑定分析,把三方模块中的自由全局引用改写成 `__m3().window`,局部同名变量、对象键、`typeof` 检测不受影响。
13
- - **就地画布补丁**:在宿主返回的原始 canvas 对象上定义属性,配合 `Symbol.hasInstance` 注册表满足 `instanceof` 判定,保持对象身份不变。
14
- - **统一生命周期**:`createRuntime()` 装配出唯一的 `MiniThreeRuntime`,订阅、定时器、全局注入统一登记,`dispose()` 后无残留。
15
- - **三端同源**:小游戏 / 小程序 / 浏览器各自实现 `PlatformBinding`,对外 API 完全一致。
16
- - **WebGL2 主线**:适配 three ≥ r163,能力探测不占用唯一的上屏画布。
17
- - **可观测**:分级日志、一次性告警、`runtime.report()` 能力报告、`plugin.api.report()` 构建报告。
18
-
19
- 架构全貌见 [`docs/02-architecture.md`](./docs/02-architecture.md),设计约束见 [`docs/01-design-principles.md`](./docs/01-design-principles.md)。
20
-
21
- ---
22
-
23
- ## 快速开始
24
-
25
- ### 安装
26
-
27
- ```bash
28
- npm i mini-three-adapter three
29
- npm i -D vite @types/three
30
- ```
31
-
32
- 需要 `three >= 0.163.0`(WebGL2)与 Node.js >= 18。
33
-
34
- ### 1) 配置构建插件
35
-
36
- ```ts
37
- // vite.config.ts
38
- import { defineConfig } from 'vite';
39
- import miniThree from 'mini-three-adapter/vite';
40
-
41
- export default defineConfig({
42
- plugins: [miniThree({ assets: { outputDir: 'assets/three' } })],
43
- build: { target: 'es2019' },
44
- });
45
- ```
46
-
47
- ### 2) 创建 runtime(**必须先于 three 的求值**)
48
-
49
- ```ts
50
- // src/main.ts
51
- import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
52
-
53
- const runtime = await createWeChatGameRuntime({ pixelRatioCap: 2 });
54
- const { startScene } = await import('./scene.js'); // 动态导入 three
55
- startScene(runtime);
56
- ```
57
-
58
- ```ts
59
- // src/scene.ts
60
- import * as THREE from 'three';
61
- import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
62
- import type { MiniThreeRuntime } from 'mini-three-adapter';
63
-
64
- export function startScene(runtime: MiniThreeRuntime) {
65
- const renderer = new THREE.WebGLRenderer(runtime.rendererHints);
66
- renderer.setPixelRatio(runtime.windowInfo.pixelRatio);
67
- renderer.setSize(runtime.windowInfo.width, runtime.windowInfo.height, false);
68
- renderer.outputColorSpace = THREE.SRGBColorSpace;
69
-
70
- const scene = new THREE.Scene();
71
- const camera = new THREE.PerspectiveCamera(60, runtime.windowInfo.width / runtime.windowInfo.height, 0.1, 100);
72
- camera.position.z = 3;
73
- scene.add(new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshNormalMaterial()));
74
-
75
- const controls = new OrbitControls(camera, renderer.domElement); // 触摸自动接入
76
- renderer.setAnimationLoop(() => { controls.update(); renderer.render(scene, camera); });
77
-
78
- runtime.on('resize', (info) => {
79
- camera.aspect = info.width / info.height;
80
- camera.updateProjectionMatrix();
81
- renderer.setSize(info.width, info.height, false);
82
- });
83
- runtime.on('dispose', () => { renderer.setAnimationLoop(null); controls.dispose(); renderer.dispose(); });
84
- }
85
- ```
86
-
87
- 小程序换成 `createWeChatMiniProgramRuntime({ selector: '#gl', selectorCtx: this })`,并在 WXML 上把 `bindtouch*` 事件转发给 `runtime.handleTouch(e)`。完整接入步骤见 [`docs/07-integration-guide.md`](./docs/07-integration-guide.md),可运行示例见 [`examples/`](./examples/README.md)。
88
-
89
- ---
90
-
91
- ## 架构速览
92
-
93
- ```
94
- ┌──────────────────── 构建期 ────────────────────┐
95
- three / addons │ @babel/parser + scope analysis │
96
- ──────────────►│ window.x ──► __m3().window.x │──► bundle
97
- │ worker/wasm 收集 + manifest + game.json 建议 │
98
- └────────────────────────────────────────────────┘
99
-
100
- ┌──────────────────── 运行期 ────────────────────┐
101
- PlatformBinding│ raw canvas / metrics / image / touch / raf │
102
- ──────────────►│ createRuntime() │
103
- │ ├─ patchCanvas (in-place, Symbol.hasInstance) │
104
- │ ├─ MiniThreeScope (window/document/polyfills) │
105
- │ ├─ PointerBridge (touch → pointer/mouse) │
106
- │ ├─ FrameScheduler (delta / fpsCap / fps) │
107
- │ └─ WindowInfoStore (DPR cap / resize) │
108
- └──────────────────► MiniThreeRuntime (disposable) │
109
- ```
110
-
111
- 详见 [`docs/02-architecture.md`](./docs/02-architecture.md) 与 [`docs/03-module-map.md`](./docs/03-module-map.md)。
112
-
113
- ---
114
-
115
- ## 关键能力
116
-
117
- - **零全局污染**:默认只向 `getActiveScope()` 提供 shim;`installGlobals()` 是显式且可逆的逃生舱。
118
- - **WebGL2 优先**:适配 three ≥ r163(已移除 WebGL1 支持),能力探测不占用上屏 canvas。
119
- - **统一事件桥**:多点触控、pointerId 跟踪、pointer capture、`pointercancel`、`typeof window` 特性检测全部可用。
120
- - **资源管线**:`Blob`/`URL.createObjectURL` → `data:` URI,`fetch`/`XHR` → `wx.request`,`TextEncoder/Decoder`、`atob/btoa`、`AbortController`。
121
- - **构建期资产收集**:DRACO / KTX2 / meshopt / rhino3dm 的 wasm 与 worker 自动拷贝,输出 `mini-three-assets.json` 与 `game.json` 建议,支持 `.wasm.br`。
122
- - **可观测**:分级日志、`warnOnce`、`runtime.report()` 能力报告、构建报告 `plugin.api.report()`。
123
- - **AI 友好**:[`AGENTS.md`](./AGENTS.md)、[`llms.txt`](./llms.txt)、[`docs/10-ai-playbook.md`](./docs/10-ai-playbook.md)、逐条 ADR。
124
-
125
- ---
126
-
127
- ## 文档
128
-
129
- | 文档 | 内容 |
130
- | --- | --- |
131
- | [docs/README.md](./docs/README.md) | 文档总索引与推荐阅读顺序 |
132
- | [01 设计目标与技术约束](./docs/01-design-principles.md) | 项目定位、环境约束、技术选型、能力边界 |
133
- | [02 架构设计](./docs/02-architecture.md) | 分层、数据流、不变量 |
134
- | [03 模块地图](./docs/03-module-map.md) | 每个源文件职责 / 依赖 / 修改入口(AI 专用) |
135
- | [04 API 参考](./docs/04-api-reference.md) | 全部导出与类型 |
136
- | [05 构建插件](./docs/05-build-plugin.md) | AST 重写、资产收集、配置 |
137
- | [06 平台差异与坑](./docs/06-platform-notes.md) | 平台能力、已知问题、诊断 |
138
- | [07 接入与集成指南](./docs/07-integration-guide.md) | 从零接入现有项目、分包、检查清单 |
139
- | [08 扩展指南](./docs/08-extension-guide.md) | 新平台 / 新 polyfill / 新资源规则 |
140
- | [09 测试与发布](./docs/09-testing-and-release.md) | 命令、CI、发布流程 |
141
- | [10 AI 协作手册](./docs/10-ai-playbook.md) | 提示词模板与迭代工作流 |
142
- | [11 兼容矩阵](./docs/11-compat-matrix.md) | three / 基础库 / 平台 |
143
- | [ADR](./docs/adr/README.md) | 关键设计决策记录 |
144
-
145
- ---
146
-
147
- ## 开发
148
-
149
- ```bash
150
- npm install
151
- npm run typecheck # tsc --noEmit
152
- npm test # vitest run (63 tests)
153
- npm run build # tsup: dist/*.js + dist/*.d.ts
154
- npm run check # 以上三项
155
- ```
156
-
157
- ## 许可
158
-
159
- MIT。
1
+ # mini-three-adapter
2
+
3
+ > 面向微信小游戏 / 小程序的 Three.js 适配层。TypeScript 优先、ESM、零全局污染、可释放、可测试。
4
+
5
+ 让标准 three.js 场景代码运行在非 WebView 的原生渲染环境里:业务侧照常写 `new THREE.WebGLRenderer({ canvas })`、`three/addons/*` 的控制器与加载器,适配层负责补齐宿主缺失的浏览器环境、桥接触摸事件、管理画布与资源。
6
+
7
+ ---
8
+
9
+ ## 设计要点
10
+
11
+ - **作用域化 shim**:所有 `window` / `document` / `Image` 等兼容对象集中在一个显式、可替换、可卸载的 `MiniThreeScope` 中,默认不写 `globalThis`。
12
+ - **构建期精确重定向**:用 `@babel/parser` + 作用域绑定分析,把三方模块中的自由全局引用改写成 `__m3().window`,局部同名变量、对象键、`typeof` 检测不受影响。
13
+ - **就地画布补丁**:在宿主返回的原始 canvas 对象上定义属性,配合 `Symbol.hasInstance` 注册表满足 `instanceof` 判定,保持对象身份不变。
14
+ - **统一生命周期**:`createRuntime()` 装配出唯一的 `MiniThreeRuntime`,订阅、定时器、全局注入统一登记,`dispose()` 后无残留。
15
+ - **三端同源**:小游戏 / 小程序 / 浏览器各自实现 `PlatformBinding`,对外 API 完全一致。
16
+ - **WebGL2 主线**:适配 three ≥ r163,能力探测不占用唯一的上屏画布。
17
+ - **可观测**:分级日志、一次性告警、`runtime.report()` 能力报告、`plugin.api.report()` 构建报告。
18
+
19
+ 架构全貌见 [`docs/02-architecture.md`](./docs/02-architecture.md),设计约束见 [`docs/01-design-principles.md`](./docs/01-design-principles.md)。
20
+
21
+ ---
22
+
23
+ ## 快速开始
24
+
25
+ ### 安装
26
+
27
+ ```bash
28
+ npm i mini-three-adapter three
29
+ npm i -D vite @types/three
30
+ ```
31
+
32
+ 需要 `three >= 0.163.0`(WebGL2)与 Node.js >= 18。
33
+
34
+ ### 1) 配置构建插件
35
+
36
+ ```ts
37
+ // vite.config.ts
38
+ import { defineConfig } from 'vite';
39
+ import miniThree from 'mini-three-adapter/vite';
40
+
41
+ export default defineConfig({
42
+ plugins: [miniThree({ assets: { outputDir: 'assets/three' } })],
43
+ build: { target: 'es2019' },
44
+ });
45
+ ```
46
+
47
+ ### 2) 创建 runtime(**必须先于 three 的求值**)
48
+
49
+ ```ts
50
+ // src/main.ts
51
+ import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
52
+
53
+ const runtime = await createWeChatGameRuntime({ pixelRatioCap: 2 });
54
+ const { startScene } = await import('./scene.js'); // 动态导入 three
55
+ startScene(runtime);
56
+ ```
57
+
58
+ ```ts
59
+ // src/scene.ts
60
+ import * as THREE from 'three';
61
+ import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
62
+ import type { MiniThreeRuntime } from 'mini-three-adapter';
63
+
64
+ export function startScene(runtime: MiniThreeRuntime) {
65
+ const renderer = new THREE.WebGLRenderer(runtime.rendererHints);
66
+ renderer.setPixelRatio(runtime.windowInfo.pixelRatio);
67
+ renderer.setSize(runtime.windowInfo.width, runtime.windowInfo.height, false);
68
+ renderer.outputColorSpace = THREE.SRGBColorSpace;
69
+
70
+ const scene = new THREE.Scene();
71
+ const camera = new THREE.PerspectiveCamera(60, runtime.windowInfo.width / runtime.windowInfo.height, 0.1, 100);
72
+ camera.position.z = 3;
73
+ scene.add(new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshNormalMaterial()));
74
+
75
+ const controls = new OrbitControls(camera, renderer.domElement); // 触摸自动接入
76
+ renderer.setAnimationLoop(() => { controls.update(); renderer.render(scene, camera); });
77
+
78
+ runtime.on('resize', (info) => {
79
+ camera.aspect = info.width / info.height;
80
+ camera.updateProjectionMatrix();
81
+ renderer.setSize(info.width, info.height, false);
82
+ });
83
+ runtime.on('dispose', () => { renderer.setAnimationLoop(null); controls.dispose(); renderer.dispose(); });
84
+ }
85
+ ```
86
+
87
+ 小程序换成 `createWeChatMiniProgramRuntime({ selector: '#gl', selectorCtx: this })`,并在 WXML 上把 `bindtouch*` 事件转发给 `runtime.handleTouch(e)`。完整接入步骤见 [`docs/07-integration-guide.md`](./docs/07-integration-guide.md),可运行示例见 [`examples/`](./examples/README.md)。
88
+
89
+ ---
90
+
91
+ ## 架构速览
92
+
93
+ ```
94
+ ┌──────────────────── 构建期 ────────────────────┐
95
+ three / addons │ @babel/parser + scope analysis │
96
+ ──────────────►│ window.x ──► __m3().window.x │──► bundle
97
+ │ worker/wasm 收集 + manifest + game.json 建议 │
98
+ └────────────────────────────────────────────────┘
99
+
100
+ ┌──────────────────── 运行期 ────────────────────┐
101
+ PlatformBinding│ raw canvas / metrics / image / touch / raf │
102
+ ──────────────►│ createRuntime() │
103
+ │ ├─ patchCanvas (in-place, Symbol.hasInstance) │
104
+ │ ├─ MiniThreeScope (window/document/polyfills) │
105
+ │ ├─ PointerBridge (touch → pointer/mouse) │
106
+ │ ├─ FrameScheduler (delta / fpsCap / fps) │
107
+ │ └─ WindowInfoStore (DPR cap / resize) │
108
+ └──────────────────► MiniThreeRuntime (disposable) │
109
+ ```
110
+
111
+ 详见 [`docs/02-architecture.md`](./docs/02-architecture.md) 与 [`docs/03-module-map.md`](./docs/03-module-map.md)。
112
+
113
+ ---
114
+
115
+ ## 关键能力
116
+
117
+ - **零全局污染**:默认只向 `getActiveScope()` 提供 shim;`installGlobals()` 是显式且可逆的逃生舱。
118
+ - **WebGL2 优先**:适配 three ≥ r163(已移除 WebGL1 支持),能力探测不占用上屏 canvas。
119
+ - **统一事件桥**:多点触控、pointerId 跟踪、pointer capture、`pointercancel`、`typeof window` 特性检测全部可用。
120
+ - **资源管线**:`Blob`/`URL.createObjectURL` → `data:` URI,`fetch`/`XHR` → `wx.request`,`TextEncoder/Decoder`、`atob/btoa`、`AbortController`。
121
+ - **构建期资产收集**:DRACO / KTX2 / meshopt / rhino3dm 的 wasm 与 worker 自动拷贝,输出 `mini-three-assets.json` 与 `game.json` 建议,支持 `.wasm.br`。
122
+ - **可观测**:分级日志、`warnOnce`、`runtime.report()` 能力报告、构建报告 `plugin.api.report()`。
123
+ - **AI 友好**:[`AGENTS.md`](./AGENTS.md)、[`llms.txt`](./llms.txt)、[`docs/10-ai-playbook.md`](./docs/10-ai-playbook.md)、逐条 ADR。
124
+
125
+ ---
126
+
127
+ ## 文档
128
+
129
+ | 文档 | 内容 |
130
+ | --- | --- |
131
+ | [docs/README.md](./docs/README.md) | 文档总索引与推荐阅读顺序 |
132
+ | [01 设计目标与技术约束](./docs/01-design-principles.md) | 项目定位、环境约束、技术选型、能力边界 |
133
+ | [02 架构设计](./docs/02-architecture.md) | 分层、数据流、不变量 |
134
+ | [03 模块地图](./docs/03-module-map.md) | 每个源文件职责 / 依赖 / 修改入口(AI 专用) |
135
+ | [04 API 参考](./docs/04-api-reference.md) | 全部导出与类型 |
136
+ | [05 构建插件](./docs/05-build-plugin.md) | AST 重写、资产收集、配置 |
137
+ | [06 平台差异与坑](./docs/06-platform-notes.md) | 平台能力、已知问题、诊断 |
138
+ | [07 接入与集成指南](./docs/07-integration-guide.md) | 从零接入现有项目、分包、检查清单 |
139
+ | [08 扩展指南](./docs/08-extension-guide.md) | 新平台 / 新 polyfill / 新资源规则 |
140
+ | [09 测试与发布](./docs/09-testing-and-release.md) | 命令、CI、发布流程 |
141
+ | [10 AI 协作手册](./docs/10-ai-playbook.md) | 提示词模板与迭代工作流 |
142
+ | [11 兼容矩阵](./docs/11-compat-matrix.md) | three / 基础库 / 平台 |
143
+ | [ADR](./docs/adr/README.md) | 关键设计决策记录 |
144
+
145
+ ---
146
+
147
+ ## 开发
148
+
149
+ ```bash
150
+ npm install
151
+ npm run typecheck # tsc --noEmit
152
+ npm test # vitest run (71 tests)
153
+ npm run build # tsup: dist/*.js + dist/*.d.ts
154
+ npm run check # 以上三项
155
+ ```
156
+
157
+ ## 许可
158
+
159
+ MIT。