mini-three-adapter 0.1.6 → 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.d.ts +2 -2
- package/dist/build/rollup.js.map +1 -1
- package/dist/build/vite.d.ts +2 -2
- package/dist/build/vite.js.map +1 -1
- package/dist/{chunk-MSP7V7KM.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-LCJNTN6F.js → chunk-LAVHSWBU.js} +8 -5
- package/dist/chunk-LAVHSWBU.js.map +1 -0
- package/dist/{chunk-WYUHMKUM.js → chunk-RYWYBOYO.js} +43 -4
- package/dist/chunk-RYWYBOYO.js.map +1 -0
- package/dist/{chunk-6Y4MKIJL.js → chunk-SXQUZI22.js} +4 -4
- package/dist/chunk-SXQUZI22.js.map +1 -0
- package/dist/{chunk-TDVL2OAV.js → chunk-TPMMZFHW.js} +123 -58
- package/dist/chunk-TPMMZFHW.js.map +1 -0
- package/dist/{chunk-L4QZ5SP6.js → chunk-YPG3QUYK.js} +4 -4
- package/dist/chunk-YPG3QUYK.js.map +1 -0
- package/dist/core/index.d.ts +9 -3
- package/dist/core/index.js +3 -3
- package/dist/index.d.ts +2 -2
- package/dist/index.js +7 -7
- package/dist/platforms/browser.d.ts +2 -2
- package/dist/platforms/browser.js +4 -4
- package/dist/platforms/wechat-game.d.ts +2 -2
- package/dist/platforms/wechat-game.js +5 -5
- package/dist/platforms/wechat-miniprogram.d.ts +2 -2
- package/dist/platforms/wechat-miniprogram.js +5 -5
- package/dist/{plugin-core-BuqW9C-L.d.ts → plugin-core-CBOr1cyv.d.ts} +15 -4
- package/dist/polyfills/index.d.ts +1 -1
- package/dist/polyfills/index.js +1 -1
- package/dist/{runtime-BrHExTjl.d.ts → runtime-C8_xIlDM.d.ts} +29 -1
- package/dist/scope.d.ts +1 -1
- package/dist/scope.js +1 -1
- package/dist/{types-X_5SJh4y.d.ts → types-DOoJ7noL.d.ts} +13 -1
- package/docs/01-design-principles.md +105 -105
- package/docs/03-module-map.md +99 -99
- package/docs/04-api-reference.md +310 -304
- package/docs/05-build-plugin.md +176 -176
- package/docs/06-platform-notes.md +8 -4
- package/docs/07-integration-guide.md +226 -225
- package/docs/08-extension-guide.md +101 -101
- package/docs/09-testing-and-release.md +212 -211
- 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 -0
- package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
- package/docs/adr/README.md +33 -31
- package/package.json +126 -125
- package/dist/chunk-35XVAVDB.js.map +0 -1
- package/dist/chunk-6Y4MKIJL.js.map +0 -1
- package/dist/chunk-L4QZ5SP6.js.map +0 -1
- package/dist/chunk-LCJNTN6F.js.map +0 -1
- package/dist/chunk-MSP7V7KM.js.map +0 -1
- package/dist/chunk-TDVL2OAV.js.map +0 -1
- package/dist/chunk-WYUHMKUM.js.map +0 -1
package/docs/05-build-plugin.md
CHANGED
|
@@ -1,176 +1,176 @@
|
|
|
1
|
-
# 05 · 构建插件原理与配置
|
|
2
|
-
|
|
3
|
-
> 插件是「不 fork three」这一路线成立的关键。它只在 **Node 构建期**运行,产物不会进入小游戏运行时。
|
|
4
|
-
|
|
5
|
-
## 5.1 为什么必须改写三方模块
|
|
6
|
-
|
|
7
|
-
微信小游戏没有 `window` / `document` / `Image` / `URL` 等全局([官方 Adapter 文档](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html))。three 及其 addons 会直接引用这些自由变量。两种办法:
|
|
8
|
-
|
|
9
|
-
1. 把这些 shim 挂到 `globalThis`(官方 `weapp-adapter` 路线)→ 简单但不可逆、H5 双端冲突。
|
|
10
|
-
2. 在编译期把三方模块中的**自由引用**改成 `__m3().window` → 运行时由 `MiniThreeScope` 提供。
|
|
11
|
-
|
|
12
|
-
本项目选 2,并额外用 AST 作用域分析保证精确。
|
|
13
|
-
|
|
14
|
-
## 5.2 改写流程(`src/build/scope-rewrite.ts`)
|
|
15
|
-
|
|
16
|
-
```mermaid
|
|
17
|
-
flowchart TD
|
|
18
|
-
A["transform(code, id)"] --> B{"include(id)?"}
|
|
19
|
-
B -->|否| Z["返回 null"]
|
|
20
|
-
B -->|是| C["@babel/parser<br/>sourceType: unambiguous<br/>TS/JSX 插件"]
|
|
21
|
-
C --> D["traverse: ReferencedIdentifier"]
|
|
22
|
-
D --> E{"name ∈ DEFAULT_GLOBAL_NAMES?"}
|
|
23
|
-
E -->|否| D
|
|
24
|
-
E -->|是| F{"简写属性 { X }?"}
|
|
25
|
-
F -->|是| H1["展开:X: (__m3().X)"]
|
|
26
|
-
F -->|否| F2{"非计算属性键 / 成员属性?"}
|
|
27
|
-
F2 -->|是| D
|
|
28
|
-
F2 -->|否| G{"path.scope.hasBinding(name, true)?"}
|
|
29
|
-
G -->|是(局部/import/参数)| D
|
|
30
|
-
G -->|否(真正的自由全局)| G2{"typeof 的操作数?"}
|
|
31
|
-
G2 -->|是| H2["(__m3Has() ? __m3().X : undefined)"]
|
|
32
|
-
G2 -->|否| G3{"new 的 callee 成员链根?"}
|
|
33
|
-
G3 -->|是| H3["(__m3().X),由外层 new 结合"]
|
|
34
|
-
G3 -->|否| H4["name → __m3().name"]
|
|
35
|
-
H1 --> I["prepend:<br/>import { getActiveScope as __m3 } from 'mini-three-adapter/scope'<br/>(用到 typeof 守卫时追加 hasActiveScope as __m3Has)"]
|
|
36
|
-
H2 --> I
|
|
37
|
-
H3 --> I
|
|
38
|
-
H4 --> I
|
|
39
|
-
I --> J["返回 { code, map }"]
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
关键正确性保证:
|
|
43
|
-
|
|
44
|
-
| 场景 | 处理 |
|
|
45
|
-
| --- | --- |
|
|
46
|
-
| `function f(window) { return window.x }` | `hasBinding` 命中 → **不改写** |
|
|
47
|
-
| `const o = { window: 1 }` | 非计算属性键 → 不改写 |
|
|
48
|
-
| `foo.window` | 成员属性 → 不改写 |
|
|
49
|
-
| `import { window as w } from 'x'` | import 绑定 → 不改写 |
|
|
50
|
-
| `new TextDecoder()` | 改写成 `new (__m3().TextDecoder)()`。**括号不能省**:`new __m3().TextDecoder()` 会被解析成 `(new __m3()).TextDecoder()`,于是 scope 对象被当成构造函数、类被普通调用,报 `Class constructor ... cannot be invoked without 'new'` |
|
|
51
|
-
| `new OffscreenCanvas(1, 1).getContext('2d')` | 只给链根加括号 → `new (__m3().OffscreenCanvas)(1, 1).getContext('2d')`,语义不变 |
|
|
52
|
-
| `const o = { TextDecoder }` | 展开成 `{ TextDecoder: (__m3().TextDecoder) }`。简写属性的 key 与 value 是两个**区间相同**的独立节点,原地替换会产出 `{ __m3().TextDecoder }` 这种**语法错误**,因此必须展开 |
|
|
53
|
-
| `typeof window !== 'undefined'` | 改写成 `typeof __m3().window !== 'undefined'`,结果 `'object'`,three 走浏览器分支(正是我们想要的) |
|
|
54
|
-
| `typeof document !== 'undefined'` | 改写成 `typeof (__m3Has() ? __m3().document : undefined)`:runtime 未创建时得到 `'undefined'` 而不是抛错;runtime 存在时照常返回真实对象 |
|
|
55
|
-
| `URL.createObjectURL(blob)` | `URL` 与 `Blob` 都改写 |
|
|
56
|
-
| 解析失败 | 记录 `parseFailures` + `ctx.warn`,**原样返回**,绝不产出半改写代码 |
|
|
57
|
-
|
|
58
|
-
> 为什么只有 `new` 需要括号:`typeof`、`in`、`delete`、`?.`、`instanceof` 右侧等位置,`__m3().X` 的优先级都足够高;唯一优先级倒挂的是 `new`。
|
|
59
|
-
|
|
60
|
-
> 为什么 `typeof` 要单独守卫:`typeof` 是本应永不抛错的运算符,而 `emptyScope` 只对 `document` / `navigator` / `screen` / `location` / `history` 返回 `undefined`,其余键(`TextDecoder`、`HTMLCanvasElement`、`Blob` …)仍然抛可读错误。不加守卫时,库顶层的 `typeof TextDecoder !== 'undefined'` 会在 runtime 创建之前直接崩掉,而报错指向适配层,极易误判为「初始化顺序写错」。守卫只加在 `window/self/globalThis` 之外的名字上,因为这三个在 `emptyScope` 里恒指向自身。
|
|
61
|
-
|
|
62
|
-
> 守卫的边界:它只覆盖 `typeof X` 这种**直接操作数**。`typeof window.document` 的操作数是成员表达式,插件唯一能改的是 `window`,因此那条路径靠 `emptyScope` 把 `document` 读作 `undefined` 来兜住(见 [ADR-0009](./adr/0009-placeholder-scope-environment-globals.md))。
|
|
63
|
-
|
|
64
|
-
`globalThis` **故意不在**默认清单里:three 会用它挂调试钩子(`__THREE_DEVTOOLS__` 等),改写会破坏这些逻辑。
|
|
65
|
-
|
|
66
|
-
`forceUndef: ['createImageBitmap']`:这些名字同样被改写,但作用域里恒为 `undefined`,于是 three 的 `typeof createImageBitmap !== 'undefined'` 判定为假,自动走非 Blob 分支。宿主环境提供了该 API 却没有原生 `Blob` 实现时,这个开关可以让 three 绕开不可用的代码路径。
|
|
67
|
-
|
|
68
|
-
## 5.3 默认 include 规则
|
|
69
|
-
|
|
70
|
-
命中以下路径(Vite/Rollup 的 `id` 会被规范化为 `/`):
|
|
71
|
-
|
|
72
|
-
```
|
|
73
|
-
/node_modules/three/...
|
|
74
|
-
/node_modules/three@<version>/...
|
|
75
|
-
/node_modules/three-stdlib/...
|
|
76
|
-
/node_modules/@react-three/...
|
|
77
|
-
/node_modules/@tresjs/...
|
|
78
|
-
/node_modules/.vite/deps/three* # Vite 预打包产物兜底
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
应用代码默认**不改写**。若确实需要,设 `includeUserCode: true`(会跳过 `mini-three-adapter` 自身)。
|
|
82
|
-
`vite.ts` 的 `config()` 额外设置 `optimizeDeps.exclude`,避免 Vite 把 three 预打包成一个不透明显式的 blob。
|
|
83
|
-
|
|
84
|
-
## 5.4 WebGPU 策略
|
|
85
|
-
|
|
86
|
-
微信小游戏没有 WebGPU,而 three r180+ 主推 `three/webgpu`。插件检测到 `from 'three/webgpu'` 时:
|
|
87
|
-
|
|
88
|
-
| `webgpu` | 行为 |
|
|
89
|
-
| --- | --- |
|
|
90
|
-
| `'warn'`(默认) | 构建告警,记入 `report.webgpuWarnings` |
|
|
91
|
-
| `'error'` | 直接失败,强制改用 `WebGLRenderer` |
|
|
92
|
-
| `'rewrite'` | 把 `three/webgpu` → `three`、`WebGPURenderer` → `WebGLRenderer`(**仅适用于未使用 TSL/NodeMaterial 的简单场景**) |
|
|
93
|
-
| `'ignore'` | 不处理 |
|
|
94
|
-
|
|
95
|
-
> `'rewrite'` 是有损的:`MeshStandardNodeMaterial`、TSL、`PostProcessing` 没有 WebGLRenderer 等价物,不能靠重命名解决。复杂 WebGPU 项目应改用 WebGL 构建目标。
|
|
96
|
-
|
|
97
|
-
## 5.5 资源收集(`src/build/assets.ts`)
|
|
98
|
-
|
|
99
|
-
```mermaid
|
|
100
|
-
flowchart LR
|
|
101
|
-
A["扫描模块内字符串字面量<br/>*.wasm / *.wasm.br / *.bin / *.js"] --> B["按关键字过滤<br/>draco/ktx2/basis/meshopt/rhino3dm/zstd/ammo/worker/decoder/transcoder/lottie/sdf"]
|
|
102
|
-
B --> C["在 roots 中按 basename 索引查找"]
|
|
103
|
-
C --> D["collectAssets(): entries + files + missing"]
|
|
104
|
-
D --> E["generateBundle(): emitFile 每个资源"]
|
|
105
|
-
D --> F["emitFile('mini-three-assets.json')"]
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
默认搜索目录:`node_modules/three/examples/jsm/libs`、`node_modules/three/examples/jsm`、`node_modules/three-stdlib`、`public`、`static`,以及用户 `roots`。
|
|
109
|
-
|
|
110
|
-
`mini-three-assets.json` 内容:
|
|
111
|
-
|
|
112
|
-
```json
|
|
113
|
-
{
|
|
114
|
-
"generatedBy": "mini-three-adapter",
|
|
115
|
-
"outputDir": "assets/three",
|
|
116
|
-
"entries": [{ "reference": "draco_decoder_gltf.wasm", "source": "...", "destination": "assets/three/draco_decoder_gltf.wasm", "kind": "wasm" }],
|
|
117
|
-
"gameJsonSuggestion": {
|
|
118
|
-
"workers": { "path": "assets/three", "isSubpackage": true },
|
|
119
|
-
"subpackages": [{ "name": "three-assets", "root": "assets/three/" }]
|
|
120
|
-
},
|
|
121
|
-
"decoderPaths": { "draco": "assets/three/" },
|
|
122
|
-
"build": { "modulesScanned": 12, "rewrites": 87, "missingAssets": [] }
|
|
123
|
-
}
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
约定与限制:
|
|
127
|
-
|
|
128
|
-
- 微信 Worker 配置只支持**一个目录**,所以 worker 与 wasm 统一输出到同一个 `outputDir`。
|
|
129
|
-
- `brotli: true` 时若存在 `xxx.wasm.br` 会一并拷贝;`WXWebAssembly.instantiate` 支持 `.wasm.br`([官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html))。
|
|
130
|
-
- Worker 分包需先 `wx.preDownloadSubpackage({ packageType: 'workers' })` 再 `wx.createWorker()`,且**并发最多 1 个 Worker**。
|
|
131
|
-
- 找不到资源时只告警并记入 `missingAssets`,不阻断构建——decoder 可能由业务自行放置。
|
|
132
|
-
|
|
133
|
-
运行时设置 decoder 路径示例:
|
|
134
|
-
|
|
135
|
-
```ts
|
|
136
|
-
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
|
|
137
|
-
const draco = new DRACOLoader();
|
|
138
|
-
draco.setDecoderPath('assets/three/'); // 与 manifest.decoderPaths.draco 一致
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
## 5.6 Vite / Rollup 差异
|
|
142
|
-
|
|
143
|
-
| | Vite | Rollup |
|
|
144
|
-
| --- | --- | --- |
|
|
145
|
-
| 入口 | `mini-three-adapter/vite`(default export `miniThree`) | `mini-three-adapter/rollup`(named `miniThree`) |
|
|
146
|
-
| 额外 hook | `config()` 设置 `optimizeDeps.exclude` | 无 |
|
|
147
|
-
| `enforce` | `'pre'` | `'pre'` |
|
|
148
|
-
| 资源输出 | `generateBundle` 内 `emitFile` | 同 |
|
|
149
|
-
| 高级 API | 通过 `/rollup` 子路径获取 | 直接导出 |
|
|
150
|
-
|
|
151
|
-
## 5.7 调试构建问题
|
|
152
|
-
|
|
153
|
-
```ts
|
|
154
|
-
const plugin = miniThree({ debug: true, report: true });
|
|
155
|
-
// 构建后(在 CI 或插件宿主中)
|
|
156
|
-
console.log(plugin.api.report());
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
| 现象 | 查哪里 |
|
|
160
|
-
| --- | --- |
|
|
161
|
-
| three 里仍出现裸 `window` | `report.modulesScanned` 是否为 0 → 调整 `include`;检查 Vite 是否预打包 |
|
|
162
|
-
| 局部变量被误改 | `report.globalsSeen`;补 `tests/scope-rewrite.test.ts` 用例 |
|
|
163
|
-
| 解析报错 | `report.parseFailures`,考虑给 `rewrite` 加语法插件或 `exclude` 该模块 |
|
|
164
|
-
| worker/wasm 没进包 | `report.assetReferences` / `missingAssets`;补 `roots` |
|
|
165
|
-
| 包体过大 | 参照 `gameJsonSuggestion` 分包;`manualChunks` 见 [`examples/wechat-minigame/vite.config.ts`](../examples/wechat-minigame/vite.config.ts) |
|
|
166
|
-
|
|
167
|
-
### 按报错文案反查
|
|
168
|
-
|
|
169
|
-
| 报错 | 含义 | 处理 |
|
|
170
|
-
| --- | --- | --- |
|
|
171
|
-
| `Class constructor xxx cannot be invoked without 'new'`(栈顶常是 `GLTFLoader.js:444`) | 改写产物把 `new TextDecoder()` 变成了 `(new __m3()).TextDecoder()` | 升级到含本修复的版本;宿主侧临时补丁见下 |
|
|
172
|
-
| `SyntaxError: Unexpected token '.'`,指向 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
|
|
173
|
-
| `Scoped global "document" was read before a runtime was created` | 真的在 runtime 之前读了 `document`(不是 `typeof`);`document` 本身已不再抛错,这个文案现在只会出现在 `TextDecoder` / `HTMLCanvasElement` 这类真实 API 上 | 按 [`docs/07`](./07-integration-guide.md#74-入口改造最关键的一步) 调整入口顺序 |
|
|
174
|
-
| `new __m3().X` 残留 | 适配层版本过旧 | 检查 `dist` 里的重写器版本,清理缓存后重建 |
|
|
175
|
-
|
|
176
|
-
临时规避(仅用于旧版本):在适配层插件**之后**(`enforce: 'post'`)跑一段产物级正则,把 `new __m3().X()` 改成 `new (__m3().X)()`。它依赖访问器名与「空参数」两个特征,适配层改了默认 `accessor` 就会静默失效,因此修复到位后应当删除。
|
|
1
|
+
# 05 · 构建插件原理与配置
|
|
2
|
+
|
|
3
|
+
> 插件是「不 fork three」这一路线成立的关键。它只在 **Node 构建期**运行,产物不会进入小游戏运行时。
|
|
4
|
+
|
|
5
|
+
## 5.1 为什么必须改写三方模块
|
|
6
|
+
|
|
7
|
+
微信小游戏没有 `window` / `document` / `Image` / `URL` 等全局([官方 Adapter 文档](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html))。three 及其 addons 会直接引用这些自由变量。两种办法:
|
|
8
|
+
|
|
9
|
+
1. 把这些 shim 挂到 `globalThis`(官方 `weapp-adapter` 路线)→ 简单但不可逆、H5 双端冲突。
|
|
10
|
+
2. 在编译期把三方模块中的**自由引用**改成 `__m3().window` → 运行时由 `MiniThreeScope` 提供。
|
|
11
|
+
|
|
12
|
+
本项目选 2,并额外用 AST 作用域分析保证精确。
|
|
13
|
+
|
|
14
|
+
## 5.2 改写流程(`src/build/scope-rewrite.ts`)
|
|
15
|
+
|
|
16
|
+
```mermaid
|
|
17
|
+
flowchart TD
|
|
18
|
+
A["transform(code, id)"] --> B{"include(id)?"}
|
|
19
|
+
B -->|否| Z["返回 null"]
|
|
20
|
+
B -->|是| C["@babel/parser<br/>sourceType: unambiguous<br/>TS/JSX 插件"]
|
|
21
|
+
C --> D["traverse: ReferencedIdentifier"]
|
|
22
|
+
D --> E{"name ∈ DEFAULT_GLOBAL_NAMES?"}
|
|
23
|
+
E -->|否| D
|
|
24
|
+
E -->|是| F{"简写属性 { X }?"}
|
|
25
|
+
F -->|是| H1["展开:X: (__m3().X)"]
|
|
26
|
+
F -->|否| F2{"非计算属性键 / 成员属性?"}
|
|
27
|
+
F2 -->|是| D
|
|
28
|
+
F2 -->|否| G{"path.scope.hasBinding(name, true)?"}
|
|
29
|
+
G -->|是(局部/import/参数)| D
|
|
30
|
+
G -->|否(真正的自由全局)| G2{"typeof 的操作数?"}
|
|
31
|
+
G2 -->|是| H2["(__m3Has() ? __m3().X : undefined)"]
|
|
32
|
+
G2 -->|否| G3{"new 的 callee 成员链根?"}
|
|
33
|
+
G3 -->|是| H3["(__m3().X),由外层 new 结合"]
|
|
34
|
+
G3 -->|否| H4["name → __m3().name"]
|
|
35
|
+
H1 --> I["prepend:<br/>import { getActiveScope as __m3 } from 'mini-three-adapter/scope'<br/>(用到 typeof 守卫时追加 hasActiveScope as __m3Has)"]
|
|
36
|
+
H2 --> I
|
|
37
|
+
H3 --> I
|
|
38
|
+
H4 --> I
|
|
39
|
+
I --> J["返回 { code, map }"]
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
关键正确性保证:
|
|
43
|
+
|
|
44
|
+
| 场景 | 处理 |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `function f(window) { return window.x }` | `hasBinding` 命中 → **不改写** |
|
|
47
|
+
| `const o = { window: 1 }` | 非计算属性键 → 不改写 |
|
|
48
|
+
| `foo.window` | 成员属性 → 不改写 |
|
|
49
|
+
| `import { window as w } from 'x'` | import 绑定 → 不改写 |
|
|
50
|
+
| `new TextDecoder()` | 改写成 `new (__m3().TextDecoder)()`。**括号不能省**:`new __m3().TextDecoder()` 会被解析成 `(new __m3()).TextDecoder()`,于是 scope 对象被当成构造函数、类被普通调用,报 `Class constructor ... cannot be invoked without 'new'` |
|
|
51
|
+
| `new OffscreenCanvas(1, 1).getContext('2d')` | 只给链根加括号 → `new (__m3().OffscreenCanvas)(1, 1).getContext('2d')`,语义不变 |
|
|
52
|
+
| `const o = { TextDecoder }` | 展开成 `{ TextDecoder: (__m3().TextDecoder) }`。简写属性的 key 与 value 是两个**区间相同**的独立节点,原地替换会产出 `{ __m3().TextDecoder }` 这种**语法错误**,因此必须展开 |
|
|
53
|
+
| `typeof window !== 'undefined'` | 改写成 `typeof __m3().window !== 'undefined'`,结果 `'object'`,three 走浏览器分支(正是我们想要的) |
|
|
54
|
+
| `typeof document !== 'undefined'` | 改写成 `typeof (__m3Has() ? __m3().document : undefined)`:runtime 未创建时得到 `'undefined'` 而不是抛错;runtime 存在时照常返回真实对象 |
|
|
55
|
+
| `URL.createObjectURL(blob)` | `URL` 与 `Blob` 都改写 |
|
|
56
|
+
| 解析失败 | 记录 `parseFailures` + `ctx.warn`,**原样返回**,绝不产出半改写代码 |
|
|
57
|
+
|
|
58
|
+
> 为什么只有 `new` 需要括号:`typeof`、`in`、`delete`、`?.`、`instanceof` 右侧等位置,`__m3().X` 的优先级都足够高;唯一优先级倒挂的是 `new`。
|
|
59
|
+
|
|
60
|
+
> 为什么 `typeof` 要单独守卫:`typeof` 是本应永不抛错的运算符,而 `emptyScope` 只对 `document` / `navigator` / `screen` / `location` / `history` 返回 `undefined`,其余键(`TextDecoder`、`HTMLCanvasElement`、`Blob` …)仍然抛可读错误。不加守卫时,库顶层的 `typeof TextDecoder !== 'undefined'` 会在 runtime 创建之前直接崩掉,而报错指向适配层,极易误判为「初始化顺序写错」。守卫只加在 `window/self/globalThis` 之外的名字上,因为这三个在 `emptyScope` 里恒指向自身。
|
|
61
|
+
|
|
62
|
+
> 守卫的边界:它只覆盖 `typeof X` 这种**直接操作数**。`typeof window.document` 的操作数是成员表达式,插件唯一能改的是 `window`,因此那条路径靠 `emptyScope` 把 `document` 读作 `undefined` 来兜住(见 [ADR-0009](./adr/0009-placeholder-scope-environment-globals.md))。
|
|
63
|
+
|
|
64
|
+
`globalThis` **故意不在**默认清单里:three 会用它挂调试钩子(`__THREE_DEVTOOLS__` 等),改写会破坏这些逻辑。
|
|
65
|
+
|
|
66
|
+
`forceUndef: ['createImageBitmap']`:这些名字同样被改写,但作用域里恒为 `undefined`,于是 three 的 `typeof createImageBitmap !== 'undefined'` 判定为假,自动走非 Blob 分支。宿主环境提供了该 API 却没有原生 `Blob` 实现时,这个开关可以让 three 绕开不可用的代码路径。
|
|
67
|
+
|
|
68
|
+
## 5.3 默认 include 规则
|
|
69
|
+
|
|
70
|
+
命中以下路径(Vite/Rollup 的 `id` 会被规范化为 `/`):
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
/node_modules/three/...
|
|
74
|
+
/node_modules/three@<version>/...
|
|
75
|
+
/node_modules/three-stdlib/...
|
|
76
|
+
/node_modules/@react-three/...
|
|
77
|
+
/node_modules/@tresjs/...
|
|
78
|
+
/node_modules/.vite/deps/three* # Vite 预打包产物兜底
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
应用代码默认**不改写**。若确实需要,设 `includeUserCode: true`(会跳过 `mini-three-adapter` 自身)。
|
|
82
|
+
`vite.ts` 的 `config()` 额外设置 `optimizeDeps.exclude`,避免 Vite 把 three 预打包成一个不透明显式的 blob。
|
|
83
|
+
|
|
84
|
+
## 5.4 WebGPU 策略
|
|
85
|
+
|
|
86
|
+
微信小游戏没有 WebGPU,而 three r180+ 主推 `three/webgpu`。插件检测到 `from 'three/webgpu'` 时:
|
|
87
|
+
|
|
88
|
+
| `webgpu` | 行为 |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `'warn'`(默认) | 构建告警,记入 `report.webgpuWarnings` |
|
|
91
|
+
| `'error'` | 直接失败,强制改用 `WebGLRenderer` |
|
|
92
|
+
| `'rewrite'` | 把 `three/webgpu` → `three`、`WebGPURenderer` → `WebGLRenderer`(**仅适用于未使用 TSL/NodeMaterial 的简单场景**) |
|
|
93
|
+
| `'ignore'` | 不处理 |
|
|
94
|
+
|
|
95
|
+
> `'rewrite'` 是有损的:`MeshStandardNodeMaterial`、TSL、`PostProcessing` 没有 WebGLRenderer 等价物,不能靠重命名解决。复杂 WebGPU 项目应改用 WebGL 构建目标。
|
|
96
|
+
|
|
97
|
+
## 5.5 资源收集(`src/build/assets.ts`)
|
|
98
|
+
|
|
99
|
+
```mermaid
|
|
100
|
+
flowchart LR
|
|
101
|
+
A["扫描模块内字符串字面量<br/>*.wasm / *.wasm.br / *.bin / *.js"] --> B["按关键字过滤<br/>draco/ktx2/basis/meshopt/rhino3dm/zstd/ammo/worker/decoder/transcoder/lottie/sdf"]
|
|
102
|
+
B --> C["在 roots 中按 basename 索引查找"]
|
|
103
|
+
C --> D["collectAssets(): entries + files + missing"]
|
|
104
|
+
D --> E["generateBundle(): emitFile 每个资源"]
|
|
105
|
+
D --> F["emitFile('mini-three-assets.json')"]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
默认搜索目录:`node_modules/three/examples/jsm/libs`、`node_modules/three/examples/jsm`、`node_modules/three-stdlib`、`public`、`static`,以及用户 `roots`。
|
|
109
|
+
|
|
110
|
+
`mini-three-assets.json` 内容:
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"generatedBy": "mini-three-adapter",
|
|
115
|
+
"outputDir": "assets/three",
|
|
116
|
+
"entries": [{ "reference": "draco_decoder_gltf.wasm", "source": "...", "destination": "assets/three/draco_decoder_gltf.wasm", "kind": "wasm" }],
|
|
117
|
+
"gameJsonSuggestion": {
|
|
118
|
+
"workers": { "path": "assets/three", "isSubpackage": true },
|
|
119
|
+
"subpackages": [{ "name": "three-assets", "root": "assets/three/" }]
|
|
120
|
+
},
|
|
121
|
+
"decoderPaths": { "draco": "assets/three/" },
|
|
122
|
+
"build": { "modulesScanned": 12, "rewrites": 87, "missingAssets": [] }
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
约定与限制:
|
|
127
|
+
|
|
128
|
+
- 微信 Worker 配置只支持**一个目录**,所以 worker 与 wasm 统一输出到同一个 `outputDir`。
|
|
129
|
+
- `brotli: true` 时若存在 `xxx.wasm.br` 会一并拷贝;`WXWebAssembly.instantiate` 支持 `.wasm.br`([官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html))。
|
|
130
|
+
- Worker 分包需先 `wx.preDownloadSubpackage({ packageType: 'workers' })` 再 `wx.createWorker()`,且**并发最多 1 个 Worker**。
|
|
131
|
+
- 找不到资源时只告警并记入 `missingAssets`,不阻断构建——decoder 可能由业务自行放置。
|
|
132
|
+
|
|
133
|
+
运行时设置 decoder 路径示例:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
|
|
137
|
+
const draco = new DRACOLoader();
|
|
138
|
+
draco.setDecoderPath('assets/three/'); // 与 manifest.decoderPaths.draco 一致
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## 5.6 Vite / Rollup 差异
|
|
142
|
+
|
|
143
|
+
| | Vite | Rollup |
|
|
144
|
+
| --- | --- | --- |
|
|
145
|
+
| 入口 | `mini-three-adapter/vite`(default export `miniThree`) | `mini-three-adapter/rollup`(named `miniThree`) |
|
|
146
|
+
| 额外 hook | `config()` 设置 `optimizeDeps.exclude` | 无 |
|
|
147
|
+
| `enforce` | `'pre'` | `'pre'` |
|
|
148
|
+
| 资源输出 | `generateBundle` 内 `emitFile` | 同 |
|
|
149
|
+
| 高级 API | 通过 `/rollup` 子路径获取 | 直接导出 |
|
|
150
|
+
|
|
151
|
+
## 5.7 调试构建问题
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
const plugin = miniThree({ debug: true, report: true });
|
|
155
|
+
// 构建后(在 CI 或插件宿主中)
|
|
156
|
+
console.log(plugin.api.report());
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
| 现象 | 查哪里 |
|
|
160
|
+
| --- | --- |
|
|
161
|
+
| three 里仍出现裸 `window` | `report.modulesScanned` 是否为 0 → 调整 `include`;检查 Vite 是否预打包 |
|
|
162
|
+
| 局部变量被误改 | `report.globalsSeen`;补 `tests/scope-rewrite.test.ts` 用例 |
|
|
163
|
+
| 解析报错 | `report.parseFailures`,考虑给 `rewrite` 加语法插件或 `exclude` 该模块 |
|
|
164
|
+
| worker/wasm 没进包 | `report.assetReferences` / `missingAssets`;补 `roots` |
|
|
165
|
+
| 包体过大 | 参照 `gameJsonSuggestion` 分包;`manualChunks` 见 [`examples/wechat-minigame/vite.config.ts`](../examples/wechat-minigame/vite.config.ts) |
|
|
166
|
+
|
|
167
|
+
### 按报错文案反查
|
|
168
|
+
|
|
169
|
+
| 报错 | 含义 | 处理 |
|
|
170
|
+
| --- | --- | --- |
|
|
171
|
+
| `Class constructor xxx cannot be invoked without 'new'`(栈顶常是 `GLTFLoader.js:444`) | 改写产物把 `new TextDecoder()` 变成了 `(new __m3()).TextDecoder()` | 升级到含本修复的版本;宿主侧临时补丁见下 |
|
|
172
|
+
| `SyntaxError: Unexpected token '.'`,指向 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
|
|
173
|
+
| `Scoped global "document" was read before a runtime was created` | 真的在 runtime 之前读了 `document`(不是 `typeof`);`document` 本身已不再抛错,这个文案现在只会出现在 `TextDecoder` / `HTMLCanvasElement` 这类真实 API 上 | 按 [`docs/07`](./07-integration-guide.md#74-入口改造最关键的一步) 调整入口顺序 |
|
|
174
|
+
| `new __m3().X` 残留 | 适配层版本过旧 | 检查 `dist` 里的重写器版本,清理缓存后重建 |
|
|
175
|
+
|
|
176
|
+
临时规避(仅用于旧版本):在适配层插件**之后**(`enforce: 'post'`)跑一段产物级正则,把 `new __m3().X()` 改成 `new (__m3().X)()`。它依赖访问器名与「空参数」两个特征,适配层改了默认 `accessor` 就会静默失效,因此修复到位后应当删除。
|
|
@@ -47,10 +47,12 @@ const { startScene } = await import('./scene.js'); // scene.js 里才 import thr
|
|
|
47
47
|
| WebGPU 相关 API 报错 | 小游戏无 WebGPU | 插件 `webgpu` 策略;默认告警 |
|
|
48
48
|
| three 版本升级后控件失效 | r170+ 用 `three/addons/`,`outputColorSpace` 取代 `outputEncoding` | 示例与 `rendererHints` 使用新 API;插件 include 覆盖两种路径 |
|
|
49
49
|
| `img.onload` / `addEventListener('load')` 永不触发,纹理靠超时兜底 | 图片 shim 只建了「合成事件 → 用户回调」这条边,没有「原生 load → 合成事件」;部分宿主的 `onload`/`onerror` 读不到描述符,但支持直接赋值 | `createImageFactory` 在 patch 前抓原生入口,按「原生 `addEventListener` → `onload` 赋值 → `wx.getImageInfo` 诊断 → 2s watchdog」四级兜底;宿主形态写入 `image-native-events` 告警的 payload |
|
|
50
|
+
| 真机纹理全部空白/超时,模拟器正常且**无报错** | 真机宿主在**事件触发时读 `image.onload`** 并调用读到的值;shim 访问器的 getter 只回用户回调登记表,把 Tier-2 写入的桥接函数遮蔽成 `undefined`(three 只用 `addEventListener`,从不赋 `onload`) | getter 非派发期间恒回桥接函数、`dispatchEvent` 行内派发期间回用户回调([ADR-0011](./adr/0011-host-callback-slot-bridging.md));看门狗超时 `warnOnce('image-events-timeout')`,不再静默 |
|
|
50
51
|
| 纹理是 `.webp` 但真机加载失败 | 该设备的图片解码器不支持 WebP | 纹理改用 PNG / JPEG;`wx.getImageInfo` 失败时告警会点名格式与路径 |
|
|
51
52
|
| `canvas.onpointerdown = fn` 之类行内处理器不触发 | 事件方法被绑定到内部对象,`this['on'+type]` 查找落空 | `patchEventTarget` 把宿主对象作为行内处理器宿主传入 |
|
|
52
53
|
| `texture.image` 是个没有 `src` 的空壳,贴图不显示 | 监听器里的 `this` 是内部 `MiniEventTarget`,three `ImageLoader` 把它当成 `<img>` 存进 `Texture.source.data` | `dispatchEvent` 把 `this`、`event.target`、`currentTarget` 全部转发到宿主元素;`event.target` 不再暴露内部监听表 |
|
|
53
54
|
| 预置 `GameGlobal.screencanvas` 的宿主偶发黑屏 | 探测回退拿到的正是上屏画布,`getContext` + `WEBGL_lose_context` 把它废掉 | 无 `createOffscreenCanvas` 时干脆不兜底;兜底时按 `reservedCanvases`(本次使用的画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`)逐个比对身份,命中任一即放弃并退回 `webgl2Source: 'inferred'`(ADR-0008) |
|
|
55
|
+
| H5 上 canvas 收不到 `pointer` / `wheel`,或 `canvas.dispatchEvent(realEvent)` 抛 `Cannot set property target` | 真实 `HTMLCanvasElement` 的事件方法被 `MiniEventTarget` 覆盖,浏览器内部派发绕过了 JS 侧的私有监听表 | 0.1.7 起 `browser` 绑定声明 `nativeEventTarget: true`,事件方法与 DOM 成员不再被覆盖(ADR-0010)。升级前的旧版本只能把监听挂到真实 `document` 上绕开 `runtime.canvas` |
|
|
54
56
|
|
|
55
57
|
深度缓冲补丁(应用层显式启用):
|
|
56
58
|
|
|
@@ -70,7 +72,8 @@ renderer.setAnimationLoop(() => {
|
|
|
70
72
|
| 宿主形态 | 抓取方式 | 结果 |
|
|
71
73
|
| --- | --- | --- |
|
|
72
74
|
| 原生 `addEventListener('load'/'error')` | patch 前 `bind` 保存,patch 后直接调用原生方法 | 最优;`onload` 描述符是否存在都不影响 |
|
|
73
|
-
| `onload` / `onerror`
|
|
75
|
+
| `onload` / `onerror` 可赋值,宿主**赋值时存回调**(模拟器形态) | 在定义 shim 访问器**之前**直接 `img.onload = forward` | 正常出图 |
|
|
76
|
+
| `onload` / `onerror` 可赋值,宿主**事件触发时读属性**(真机形态,0.1.7 空白根因) | 同上 + shim 访问器 getter **非派发期间恒回桥接函数**,宿主读到的永远是函数 | 已修;`finish` 幂等,宿主「既存又读」也不会双发 |
|
|
74
77
|
| 接受赋值但**永远不调用** | 无法从形状上识别 | 由 watchdog 兜底:2s 后按 `complete` 判定,见下 |
|
|
75
78
|
| 只能读描述符、且不可赋值 | — | 走下一级 |
|
|
76
79
|
| 只有 `wx.getImageInfo` | `src` 赋值时调用 `getImageInfo({ src })` | **不出图**:`getImageInfo` 只解码元数据、不填充图片像素,合成 `load` 会让 three 上传空纹理,因此改为派发带 `reason` 的 `error` |
|
|
@@ -80,7 +83,7 @@ renderer.setAnimationLoop(() => {
|
|
|
80
83
|
而这种宿主在 2s 之前与正常加载完全无法区分。到点时:
|
|
81
84
|
|
|
82
85
|
- 宿主 `complete` 为真 → 派发 `load`(浏览器语义下 `complete` 就意味着 `load` 已经发生过),`reason: 'watchdog-complete'`;
|
|
83
|
-
- 否则派发 `error`,`reason: 'image-events-timeout'`,`detail.path`
|
|
86
|
+
- 否则派发 `error`,`reason: 'image-events-timeout'`,`detail.path` 指认是哪一级入口「看起来挂上了」,同时 `warnOnce('image-events-timeout', …, { path, src })`——超时不再只存在于 error detail 里,裸 console 也看得见。
|
|
84
87
|
|
|
85
88
|
真实 `load`/`error` 永远优先:终态只派发一次,闹钟在事件到达时被清掉。
|
|
86
89
|
|
|
@@ -90,8 +93,9 @@ renderer.setAnimationLoop(() => {
|
|
|
90
93
|
要点:
|
|
91
94
|
|
|
92
95
|
- 描述符不是唯一入口:有的宿主 `Object.getOwnPropertyDescriptor(img, 'onload')` 返回 `undefined`,但 `img.onload = fn` 仍然有效并能触发。
|
|
93
|
-
-
|
|
94
|
-
- `
|
|
96
|
+
- 「能赋值」也分两种**消费时序**:模拟器在赋值那一刻把回调存进宿主内部、事件时直接调用存值;真机在事件触发时读 `image.onload` 属性并调用读到的值。shim 的 `onload` / `onerror` getter 因此在非派发期间**永远返回桥接函数**,只有 `dispatchEvent` 行内派发期间返回登记的用户回调——前者保证真机读到的不是 `undefined`(0.1.7 真机空白根因),后者防止行内派发递归回桥接、用户回调双发([ADR-0011](./adr/0011-host-callback-slot-bridging.md))。
|
|
97
|
+
- 「能赋值」还不等于「会触发」:这是 0.1.6 修的边界;不要用 `typeof img.onload === 'function'` 判断宿主是否健康。
|
|
98
|
+
- `patchElement` 在**没有原生事件系统**的宿主上会覆盖 `addEventListener`(小程序 / 小游戏),任何「用原生事件」的方案都必须在它之前保存引用,否则拿到的是 shim。浏览器 canvas 例外:`nativeEventTarget: true` 时事件方法与 DOM 成员一律不动([ADR-0010](./adr/0010-native-event-target-boundary.md))。
|
|
95
99
|
- `src` 同样可能只是可写数据属性。这种情况下 shim 访问器会吞掉写入,`image.ts` 会临时还原宿主属性写一次再装回访问器。
|
|
96
100
|
- `complete` 在 `load` 与 `error` 后都为 `true`,`decode()` 在 `error` 时 reject(与浏览器一致)。
|
|
97
101
|
- 退化路径的告警 payload 带宿主形状(`onload: 'missing' | 'data' | 'data-readonly' | 'accessor'`、`addEventListener`、`getImageInfo`、`ownNames`),可直接贴进 issue。
|