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.
Files changed (55) hide show
  1. package/AGENTS.md +85 -85
  2. package/LICENSE +21 -21
  3. package/README.md +159 -159
  4. package/dist/build/rollup.js.map +1 -1
  5. package/dist/build/vite.js.map +1 -1
  6. package/dist/{chunk-HKT54DDM.js → chunk-DQH3YRGN.js} +3 -3
  7. package/dist/chunk-DQH3YRGN.js.map +1 -0
  8. package/dist/{chunk-35XVAVDB.js → chunk-J34MD3IL.js} +2 -2
  9. package/dist/chunk-J34MD3IL.js.map +1 -0
  10. package/dist/{chunk-U3P3XHA3.js → chunk-LAVHSWBU.js} +2 -2
  11. package/dist/{chunk-U3P3XHA3.js.map → chunk-LAVHSWBU.js.map} +1 -1
  12. package/dist/{chunk-7XOHQFZ6.js → chunk-RYWYBOYO.js} +4 -4
  13. package/dist/chunk-RYWYBOYO.js.map +1 -0
  14. package/dist/{chunk-DDCQIBWW.js → chunk-SXQUZI22.js} +4 -4
  15. package/dist/chunk-SXQUZI22.js.map +1 -0
  16. package/dist/{chunk-V64V4HIZ.js → chunk-TPMMZFHW.js} +22 -6
  17. package/dist/chunk-TPMMZFHW.js.map +1 -0
  18. package/dist/{chunk-FQ2GOIOE.js → chunk-YPG3QUYK.js} +4 -4
  19. package/dist/chunk-YPG3QUYK.js.map +1 -0
  20. package/dist/core/index.js +3 -3
  21. package/dist/index.js +7 -7
  22. package/dist/platforms/browser.js +4 -4
  23. package/dist/platforms/wechat-game.js +5 -5
  24. package/dist/platforms/wechat-miniprogram.js +5 -5
  25. package/dist/polyfills/index.js +1 -1
  26. package/dist/scope.js +1 -1
  27. package/docs/01-design-principles.md +105 -105
  28. package/docs/03-module-map.md +99 -99
  29. package/docs/04-api-reference.md +310 -310
  30. package/docs/05-build-plugin.md +176 -176
  31. package/docs/06-platform-notes.md +6 -3
  32. package/docs/07-integration-guide.md +226 -226
  33. package/docs/08-extension-guide.md +101 -101
  34. package/docs/09-testing-and-release.md +212 -212
  35. package/docs/11-compat-matrix.md +100 -100
  36. package/docs/README.md +41 -41
  37. package/docs/adr/0001-scoped-globals.md +41 -41
  38. package/docs/adr/0002-unified-runtime-lifecycle.md +40 -40
  39. package/docs/adr/0003-ast-rewrite.md +51 -51
  40. package/docs/adr/0004-in-place-patching.md +42 -42
  41. package/docs/adr/0005-webgl2-only.md +44 -44
  42. package/docs/adr/0006-zero-three-dependency.md +43 -43
  43. package/docs/adr/0007-capability-probe-fallback.md +61 -61
  44. package/docs/adr/0008-probe-fallback-boundary.md +56 -56
  45. package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -69
  46. package/docs/adr/0010-native-event-target-boundary.md +82 -82
  47. package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
  48. package/docs/adr/README.md +33 -32
  49. package/package.json +126 -126
  50. package/dist/chunk-35XVAVDB.js.map +0 -1
  51. package/dist/chunk-7XOHQFZ6.js.map +0 -1
  52. package/dist/chunk-DDCQIBWW.js.map +0 -1
  53. package/dist/chunk-FQ2GOIOE.js.map +0 -1
  54. package/dist/chunk-HKT54DDM.js.map +0 -1
  55. package/dist/chunk-V64V4HIZ.js.map +0 -1
@@ -1,226 +1,226 @@
1
- # 07 · 接入与集成指南
2
-
3
- > 面向「已有一个小游戏 / 小程序项目,现在要接入 3D 场景」的场景。本文给出从安装到真机验收的完整接入顺序,不涉及任何其他库。
4
-
5
- ## 7.1 接入前提
6
-
7
- | 条件 | 说明 |
8
- | --- | --- |
9
- | 构建工具 | Vite 或 Rollup(构建插件需要 hook 到模块转换阶段) |
10
- | three 版本 | `>= 0.163.0`,推荐 `0.187.x` |
11
- | 运行环境 | 微信小游戏基础库支持 `getContext('webgl2')`;小程序使用 `<canvas type="webgl2">` |
12
- | TypeScript | 推荐;`@types/three` 与项目 TS 版本配套 |
13
-
14
- ## 7.2 安装
15
-
16
- ```bash
17
- npm i mini-three-adapter three
18
- npm i -D vite @types/three
19
- ```
20
-
21
- `three` 是 optional peer,不会被打进适配层;业务项目自行决定版本。
22
-
23
- ## 7.3 配置构建插件
24
-
25
- ```ts
26
- // vite.config.ts
27
- import { defineConfig } from 'vite';
28
- import miniThree from 'mini-three-adapter/vite';
29
-
30
- export default defineConfig({
31
- plugins: [
32
- miniThree({
33
- webgpu: 'warn',
34
- assets: { outputDir: 'assets/three', brotli: true },
35
- roots: ['public/decoders'],
36
- }),
37
- ],
38
- build: {
39
- target: 'es2019',
40
- minify: false,
41
- lib: { entry: 'src/main.ts', formats: ['es'], fileName: () => 'game.js' },
42
- rollupOptions: {
43
- output: {
44
- entryFileNames: 'game.js',
45
- chunkFileNames: 'chunks/[name]-[hash].js',
46
- manualChunks(id) {
47
- if (id.includes('/node_modules/three/')) return 'three';
48
- return undefined;
49
- },
50
- },
51
- },
52
- },
53
- });
54
- ```
55
-
56
- 要点:
57
-
58
- - `target: 'es2019'` 让可选链 / 空值合并降级,避免开发者工具语法报错。
59
- - `optimizeDeps.exclude` 由插件的 `config()` 自动设置,确保 AST 重写见到 three 的原始 ESM 模块图。
60
- - `manualChunks` 把 three 拆成独立 chunk,便于放进分包。
61
- - Rollup 项目改用 `import { miniThree } from 'mini-three-adapter/rollup'`。
62
-
63
- ## 7.4 入口改造(**最关键的一步**)
64
-
65
- ESM 静态导入会在模块体执行前求值。three 及其 addons 在模块初始化时会读取作用域对象,因此必须**先创建 runtime,再让场景模块加载**:
66
-
67
- ```ts
68
- // src/main.ts —— 只导入适配层,不在这里导入 three
69
- import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
70
-
71
- async function bootstrap(): Promise<void> {
72
- const runtime = await createWeChatGameRuntime({
73
- pixelRatioCap: 2,
74
- logLevel: 'warn',
75
- });
76
-
77
- console.log(runtime.report());
78
-
79
- const { startScene } = await import('./scene.js'); // scene.js 内才 import three
80
- startScene(runtime);
81
-
82
- runtime.on('dispose', () => console.info('runtime disposed'));
83
- }
84
-
85
- void bootstrap().catch((error: unknown) => console.error('bootstrap failed', error));
86
- ```
87
-
88
- ```ts
89
- // src/scene.ts
90
- import * as THREE from 'three';
91
- import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
92
- import type { MiniThreeRuntime } from 'mini-three-adapter';
93
-
94
- export function startScene(runtime: MiniThreeRuntime): void {
95
- const renderer = new THREE.WebGLRenderer(runtime.rendererHints);
96
- renderer.setPixelRatio(runtime.windowInfo.pixelRatio);
97
- renderer.setSize(runtime.windowInfo.width, runtime.windowInfo.height, false);
98
- renderer.outputColorSpace = THREE.SRGBColorSpace;
99
-
100
- const scene = new THREE.Scene();
101
- const camera = new THREE.PerspectiveCamera(
102
- 60, runtime.windowInfo.width / runtime.windowInfo.height, 0.1, 100,
103
- );
104
- camera.position.z = 3;
105
- scene.add(new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshNormalMaterial()));
106
-
107
- const controls = new OrbitControls(camera, renderer.domElement);
108
- renderer.setAnimationLoop(() => { controls.update(); renderer.render(scene, camera); });
109
-
110
- runtime.on('resize', (info) => {
111
- camera.aspect = info.width / info.height;
112
- camera.updateProjectionMatrix();
113
- renderer.setPixelRatio(info.pixelRatio);
114
- renderer.setSize(info.width, info.height, false);
115
- });
116
- runtime.on('dispose', () => {
117
- renderer.setAnimationLoop(null);
118
- controls.dispose();
119
- renderer.dispose();
120
- });
121
- }
122
- ```
123
-
124
- 若项目结构无法改成动态导入,可在创建 runtime 时打开 `installGlobals: true`,把 shim 显式挂到 `globalThis`;该注入是可逆的,`runtime.dispose()` 会还原。
125
-
126
- ## 7.5 小程序项目的额外接线
127
-
128
- ```ts
129
- // pages/index/index.ts
130
- import { createWeChatMiniProgramRuntime, type MiniThreeRuntime } from 'mini-three-adapter';
131
-
132
- Page({
133
- runtime: null as MiniThreeRuntime | null,
134
-
135
- async onReady(): Promise<void> {
136
- const runtime = await createWeChatMiniProgramRuntime({
137
- selector: '#gl',
138
- selectorCtx: this, // 自定义组件内必须传组件实例
139
- queryDelay: 0,
140
- pixelRatioCap: 2,
141
- });
142
- this.runtime = runtime;
143
- const { startScene } = await import('./scene.js');
144
- startScene(runtime);
145
- },
146
-
147
- onTouch(event: WechatMiniprogram.TouchEvent): void {
148
- this.runtime?.handleTouch(event);
149
- },
150
-
151
- onUnload(): void {
152
- this.runtime?.dispose();
153
- this.runtime = null;
154
- },
155
- });
156
- ```
157
-
158
- ```html
159
- <!-- pages/index/index.wxml -->
160
- <canvas
161
- type="webgl2"
162
- id="gl"
163
- bindtouchstart="onTouch"
164
- bindtouchmove="onTouch"
165
- bindtouchend="onTouch"
166
- bindtouchcancel="onTouch"
167
- bindtap="onTouch"
168
- />
169
- ```
170
-
171
- 小游戏不需要这一步:`watchTouch` 会自动订阅 `wx.onTouch*`。
172
-
173
- ## 7.6 三端接线差异
174
-
175
- | 平台 | runtime 工厂 | 触摸事件 | 画布来源 |
176
- | --- | --- | --- | --- |
177
- | 微信小游戏 | `createWeChatGameRuntime()` | 自动 | 唯一上屏画布,自动获取并缓存 |
178
- | 微信小程序 | `createWeChatMiniProgramRuntime({ selector, selectorCtx })` | WXML 转发到 `handleTouch` | `createSelectorQuery` 异步取节点 |
179
- | 浏览器 / H5 | `createBrowserRuntime({ canvas })` | 浏览器原生 `pointer*` / `wheel`,无需接线 | 真实 DOM canvas(事件目标不被替换,ADR-0010) |
180
-
181
- 三端返回的都是同一个 `MiniThreeRuntime`,因此 `scene.ts` 可以完全复用。
182
-
183
- ## 7.7 分包与资源配置
184
-
185
- 构建后检查产物中的 `mini-three-assets.json`,把其中 `gameJsonSuggestion` 的内容合并到 `game.json`:
186
-
187
- ```json
188
- {
189
- "workers": { "path": "assets/three", "isSubpackage": true },
190
- "subpackages": [{ "name": "three-assets", "root": "assets/three/" }]
191
- }
192
- ```
193
-
194
- - Worker 分包需要先调用 `wx.preDownloadSubpackage({ packageType: 'workers' })`,成功后再 `wx.createWorker()`。
195
- - decoder 路径与 `manifest.decoderPaths` 保持一致,例如 `draco.setDecoderPath('assets/three/')`。
196
- - `assets.brotli: true` 时会一并输出 `.wasm.br`,`WXWebAssembly.instantiate` 支持该后缀。
197
- - `report.missingAssets` 中的条目需要业务把对应文件放进 `roots` 指定目录。
198
-
199
- 完整可运行工程见 [`examples/wechat-minigame/`](../examples/wechat-minigame/vite.config.ts)、[`examples/wechat-miniprogram/`](../examples/wechat-miniprogram/pages/index/index.wxml)、[`examples/h5/`](../examples/h5/index.html)。
200
-
201
- ## 7.8 接入检查清单
202
-
203
- - [ ] 安装 `mini-three-adapter` + `three >= 0.163.0`,配置 `miniThree()` 插件。
204
- - [ ] 入口改为「先 `createXxxRuntime()`,再动态 `import('./scene.js')`」。
205
- - [ ] 渲染器使用 `runtime.rendererHints`、`setAnimationLoop`、`outputColorSpace`。
206
- - [ ] 小程序 WXML 的 `bindtouch*` 转发到 `runtime.handleTouch`。
207
- - [ ] `resize` / `visibilitychange` / `dispose` 事件都已接线并释放 three 资源。
208
- - [ ] `game.json` 配好 worker 目录与分包,检查 `mini-three-assets.json` 的 `missingAssets` 为空。
209
- - [ ] 构建报告 `plugin.api.report()` 中 `parseFailures` 为空、`webgpuWarnings` 已确认。
210
- - [ ] 真机验证 WebGL2 出图、多指触摸、横竖屏切换、前后台恢复。
211
- - [ ] 保存 `runtime.report()` 能力报告,登记到 [`docs/11-compat-matrix.md`](./11-compat-matrix.md)。
212
-
213
- ## 7.9 常见报错对照
214
-
215
- 出现下面的文案时,基本可以按下表直接定位,不必从业务代码查起。
216
-
217
- | 报错 / 现象 | 根因 | 处理 |
218
- | --- | --- | --- |
219
- | `Uncaught TypeError: Class constructor xxx cannot be invoked without 'new'`,栈顶在 `GLTFLoader.js` 的 `new TextDecoder()` 处 | 构建期把 `new TextDecoder()` 改成了 `(new __m3()).TextDecoder()` | 升级适配层;临时规避见 [`docs/05` §5.7](./05-build-plugin.md#57-调试构建问题) |
220
- | `SyntaxError: Unexpected token '.'`,产物里出现 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
221
- | 纹理永远加载不出来、`ImageLoader` 卡满超时;`img.onload` 与 `addEventListener('load')` 都不触发 | 图片 shim 没有把原生 `onload` 桥接到合成事件 | 升级适配层。日志里出现 `image exposes neither onload/onerror slots nor a native addEventListener` 说明宿主三种入口皆无,payload 里的宿主形状可直接贴进 issue;若出现 `wx.getImageInfo could not read` 则先查格式(WebP)与路径 |
222
- | 纹理"加载成功"但画面无变化、法线 / 环境贴图不生效;`texture.image` 没有 `src` 也没有宽高 | 监听器里的 `this` 是内部事件载体,`ImageLoader` 把它当成 `<img>` 存进了 `Texture.source.data` | 升级适配层(0.1.3+)。若业务里自己写过 `image.inlineHost` 取真图,可以删掉 |
223
- | `capabilities.webgl2 === false`,但 `#version 300 es` 能正常渲染 | 能力探测用了离屏画布,离屏与上屏能力不同 | 看 `capabilities.webgl2Source`:`'inferred'` 表示未实测;需要以实测为准时显式传 `capabilities: { webgl2: true }` |
224
- | `Scoped global "xxx" was read before a runtime was created` | 在 `createXxxRuntime()` 之前求值了读 `xxx` 的模块(`document` / `navigator` / `screen` 等环境全局已改为读作 `undefined`,不再抛;能抛的是 `TextDecoder`、`HTMLCanvasElement` 这类真实 API) | 改为动态 `import()`;日志里出现 `Scoped globals were read before this runtime existed` 说明特性检测走了「非浏览器」分支,同样需要调整入口顺序 |
225
- | 触摸事件收不到 | 小程序未转发 `bindtouch*`,或小游戏在 runtime 之后才注册监听 | 见 [`docs/06`](./06-platform-notes.md) 与 §7.5 |
226
- | H5 上 canvas 收不到 `pointer` / `wheel`,`OrbitControls` 拖不动 | 旧版本把 `MiniEventTarget` 打在真实 `HTMLCanvasElement` 上,浏览器内部派发绕过了 JS 侧监听表 | 升级到声明 `nativeEventTarget` 的版本(ADR-0010);旧版本只能把监听挂到真实 `document`。可跑 `npm run verify:h5` 自检 |
1
+ # 07 · 接入与集成指南
2
+
3
+ > 面向「已有一个小游戏 / 小程序项目,现在要接入 3D 场景」的场景。本文给出从安装到真机验收的完整接入顺序,不涉及任何其他库。
4
+
5
+ ## 7.1 接入前提
6
+
7
+ | 条件 | 说明 |
8
+ | --- | --- |
9
+ | 构建工具 | Vite 或 Rollup(构建插件需要 hook 到模块转换阶段) |
10
+ | three 版本 | `>= 0.163.0`,推荐 `0.187.x` |
11
+ | 运行环境 | 微信小游戏基础库支持 `getContext('webgl2')`;小程序使用 `<canvas type="webgl2">` |
12
+ | TypeScript | 推荐;`@types/three` 与项目 TS 版本配套 |
13
+
14
+ ## 7.2 安装
15
+
16
+ ```bash
17
+ npm i mini-three-adapter three
18
+ npm i -D vite @types/three
19
+ ```
20
+
21
+ `three` 是 optional peer,不会被打进适配层;业务项目自行决定版本。
22
+
23
+ ## 7.3 配置构建插件
24
+
25
+ ```ts
26
+ // vite.config.ts
27
+ import { defineConfig } from 'vite';
28
+ import miniThree from 'mini-three-adapter/vite';
29
+
30
+ export default defineConfig({
31
+ plugins: [
32
+ miniThree({
33
+ webgpu: 'warn',
34
+ assets: { outputDir: 'assets/three', brotli: true },
35
+ roots: ['public/decoders'],
36
+ }),
37
+ ],
38
+ build: {
39
+ target: 'es2019',
40
+ minify: false,
41
+ lib: { entry: 'src/main.ts', formats: ['es'], fileName: () => 'game.js' },
42
+ rollupOptions: {
43
+ output: {
44
+ entryFileNames: 'game.js',
45
+ chunkFileNames: 'chunks/[name]-[hash].js',
46
+ manualChunks(id) {
47
+ if (id.includes('/node_modules/three/')) return 'three';
48
+ return undefined;
49
+ },
50
+ },
51
+ },
52
+ },
53
+ });
54
+ ```
55
+
56
+ 要点:
57
+
58
+ - `target: 'es2019'` 让可选链 / 空值合并降级,避免开发者工具语法报错。
59
+ - `optimizeDeps.exclude` 由插件的 `config()` 自动设置,确保 AST 重写见到 three 的原始 ESM 模块图。
60
+ - `manualChunks` 把 three 拆成独立 chunk,便于放进分包。
61
+ - Rollup 项目改用 `import { miniThree } from 'mini-three-adapter/rollup'`。
62
+
63
+ ## 7.4 入口改造(**最关键的一步**)
64
+
65
+ ESM 静态导入会在模块体执行前求值。three 及其 addons 在模块初始化时会读取作用域对象,因此必须**先创建 runtime,再让场景模块加载**:
66
+
67
+ ```ts
68
+ // src/main.ts —— 只导入适配层,不在这里导入 three
69
+ import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
70
+
71
+ async function bootstrap(): Promise<void> {
72
+ const runtime = await createWeChatGameRuntime({
73
+ pixelRatioCap: 2,
74
+ logLevel: 'warn',
75
+ });
76
+
77
+ console.log(runtime.report());
78
+
79
+ const { startScene } = await import('./scene.js'); // scene.js 内才 import three
80
+ startScene(runtime);
81
+
82
+ runtime.on('dispose', () => console.info('runtime disposed'));
83
+ }
84
+
85
+ void bootstrap().catch((error: unknown) => console.error('bootstrap failed', error));
86
+ ```
87
+
88
+ ```ts
89
+ // src/scene.ts
90
+ import * as THREE from 'three';
91
+ import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
92
+ import type { MiniThreeRuntime } from 'mini-three-adapter';
93
+
94
+ export function startScene(runtime: MiniThreeRuntime): void {
95
+ const renderer = new THREE.WebGLRenderer(runtime.rendererHints);
96
+ renderer.setPixelRatio(runtime.windowInfo.pixelRatio);
97
+ renderer.setSize(runtime.windowInfo.width, runtime.windowInfo.height, false);
98
+ renderer.outputColorSpace = THREE.SRGBColorSpace;
99
+
100
+ const scene = new THREE.Scene();
101
+ const camera = new THREE.PerspectiveCamera(
102
+ 60, runtime.windowInfo.width / runtime.windowInfo.height, 0.1, 100,
103
+ );
104
+ camera.position.z = 3;
105
+ scene.add(new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshNormalMaterial()));
106
+
107
+ const controls = new OrbitControls(camera, renderer.domElement);
108
+ renderer.setAnimationLoop(() => { controls.update(); renderer.render(scene, camera); });
109
+
110
+ runtime.on('resize', (info) => {
111
+ camera.aspect = info.width / info.height;
112
+ camera.updateProjectionMatrix();
113
+ renderer.setPixelRatio(info.pixelRatio);
114
+ renderer.setSize(info.width, info.height, false);
115
+ });
116
+ runtime.on('dispose', () => {
117
+ renderer.setAnimationLoop(null);
118
+ controls.dispose();
119
+ renderer.dispose();
120
+ });
121
+ }
122
+ ```
123
+
124
+ 若项目结构无法改成动态导入,可在创建 runtime 时打开 `installGlobals: true`,把 shim 显式挂到 `globalThis`;该注入是可逆的,`runtime.dispose()` 会还原。
125
+
126
+ ## 7.5 小程序项目的额外接线
127
+
128
+ ```ts
129
+ // pages/index/index.ts
130
+ import { createWeChatMiniProgramRuntime, type MiniThreeRuntime } from 'mini-three-adapter';
131
+
132
+ Page({
133
+ runtime: null as MiniThreeRuntime | null,
134
+
135
+ async onReady(): Promise<void> {
136
+ const runtime = await createWeChatMiniProgramRuntime({
137
+ selector: '#gl',
138
+ selectorCtx: this, // 自定义组件内必须传组件实例
139
+ queryDelay: 0,
140
+ pixelRatioCap: 2,
141
+ });
142
+ this.runtime = runtime;
143
+ const { startScene } = await import('./scene.js');
144
+ startScene(runtime);
145
+ },
146
+
147
+ onTouch(event: WechatMiniprogram.TouchEvent): void {
148
+ this.runtime?.handleTouch(event);
149
+ },
150
+
151
+ onUnload(): void {
152
+ this.runtime?.dispose();
153
+ this.runtime = null;
154
+ },
155
+ });
156
+ ```
157
+
158
+ ```html
159
+ <!-- pages/index/index.wxml -->
160
+ <canvas
161
+ type="webgl2"
162
+ id="gl"
163
+ bindtouchstart="onTouch"
164
+ bindtouchmove="onTouch"
165
+ bindtouchend="onTouch"
166
+ bindtouchcancel="onTouch"
167
+ bindtap="onTouch"
168
+ />
169
+ ```
170
+
171
+ 小游戏不需要这一步:`watchTouch` 会自动订阅 `wx.onTouch*`。
172
+
173
+ ## 7.6 三端接线差异
174
+
175
+ | 平台 | runtime 工厂 | 触摸事件 | 画布来源 |
176
+ | --- | --- | --- | --- |
177
+ | 微信小游戏 | `createWeChatGameRuntime()` | 自动 | 唯一上屏画布,自动获取并缓存 |
178
+ | 微信小程序 | `createWeChatMiniProgramRuntime({ selector, selectorCtx })` | WXML 转发到 `handleTouch` | `createSelectorQuery` 异步取节点 |
179
+ | 浏览器 / H5 | `createBrowserRuntime({ canvas })` | 浏览器原生 `pointer*` / `wheel`,无需接线 | 真实 DOM canvas(事件目标不被替换,ADR-0010) |
180
+
181
+ 三端返回的都是同一个 `MiniThreeRuntime`,因此 `scene.ts` 可以完全复用。
182
+
183
+ ## 7.7 分包与资源配置
184
+
185
+ 构建后检查产物中的 `mini-three-assets.json`,把其中 `gameJsonSuggestion` 的内容合并到 `game.json`:
186
+
187
+ ```json
188
+ {
189
+ "workers": { "path": "assets/three", "isSubpackage": true },
190
+ "subpackages": [{ "name": "three-assets", "root": "assets/three/" }]
191
+ }
192
+ ```
193
+
194
+ - Worker 分包需要先调用 `wx.preDownloadSubpackage({ packageType: 'workers' })`,成功后再 `wx.createWorker()`。
195
+ - decoder 路径与 `manifest.decoderPaths` 保持一致,例如 `draco.setDecoderPath('assets/three/')`。
196
+ - `assets.brotli: true` 时会一并输出 `.wasm.br`,`WXWebAssembly.instantiate` 支持该后缀。
197
+ - `report.missingAssets` 中的条目需要业务把对应文件放进 `roots` 指定目录。
198
+
199
+ 完整可运行工程见 [`examples/wechat-minigame/`](../examples/wechat-minigame/vite.config.ts)、[`examples/wechat-miniprogram/`](../examples/wechat-miniprogram/pages/index/index.wxml)、[`examples/h5/`](../examples/h5/index.html)。
200
+
201
+ ## 7.8 接入检查清单
202
+
203
+ - [ ] 安装 `mini-three-adapter` + `three >= 0.163.0`,配置 `miniThree()` 插件。
204
+ - [ ] 入口改为「先 `createXxxRuntime()`,再动态 `import('./scene.js')`」。
205
+ - [ ] 渲染器使用 `runtime.rendererHints`、`setAnimationLoop`、`outputColorSpace`。
206
+ - [ ] 小程序 WXML 的 `bindtouch*` 转发到 `runtime.handleTouch`。
207
+ - [ ] `resize` / `visibilitychange` / `dispose` 事件都已接线并释放 three 资源。
208
+ - [ ] `game.json` 配好 worker 目录与分包,检查 `mini-three-assets.json` 的 `missingAssets` 为空。
209
+ - [ ] 构建报告 `plugin.api.report()` 中 `parseFailures` 为空、`webgpuWarnings` 已确认。
210
+ - [ ] 真机验证 WebGL2 出图、多指触摸、横竖屏切换、前后台恢复。
211
+ - [ ] 保存 `runtime.report()` 能力报告,登记到 [`docs/11-compat-matrix.md`](./11-compat-matrix.md)。
212
+
213
+ ## 7.9 常见报错对照
214
+
215
+ 出现下面的文案时,基本可以按下表直接定位,不必从业务代码查起。
216
+
217
+ | 报错 / 现象 | 根因 | 处理 |
218
+ | --- | --- | --- |
219
+ | `Uncaught TypeError: Class constructor xxx cannot be invoked without 'new'`,栈顶在 `GLTFLoader.js` 的 `new TextDecoder()` 处 | 构建期把 `new TextDecoder()` 改成了 `(new __m3()).TextDecoder()` | 升级适配层;临时规避见 [`docs/05` §5.7](./05-build-plugin.md#57-调试构建问题) |
220
+ | `SyntaxError: Unexpected token '.'`,产物里出现 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
221
+ | 纹理永远加载不出来、`ImageLoader` 卡满超时;`img.onload` 与 `addEventListener('load')` 都不触发 | 图片 shim 没有把原生 `onload` 桥接到合成事件 | 升级适配层。日志里出现 `image exposes neither onload/onerror slots nor a native addEventListener` 说明宿主三种入口皆无,payload 里的宿主形状可直接贴进 issue;若出现 `wx.getImageInfo could not read` 则先查格式(WebP)与路径 |
222
+ | 纹理"加载成功"但画面无变化、法线 / 环境贴图不生效;`texture.image` 没有 `src` 也没有宽高 | 监听器里的 `this` 是内部事件载体,`ImageLoader` 把它当成 `<img>` 存进了 `Texture.source.data` | 升级适配层(0.1.3+)。若业务里自己写过 `image.inlineHost` 取真图,可以删掉 |
223
+ | `capabilities.webgl2 === false`,但 `#version 300 es` 能正常渲染 | 能力探测用了离屏画布,离屏与上屏能力不同 | 看 `capabilities.webgl2Source`:`'inferred'` 表示未实测;需要以实测为准时显式传 `capabilities: { webgl2: true }` |
224
+ | `Scoped global "xxx" was read before a runtime was created` | 在 `createXxxRuntime()` 之前求值了读 `xxx` 的模块(`document` / `navigator` / `screen` 等环境全局已改为读作 `undefined`,不再抛;能抛的是 `TextDecoder`、`HTMLCanvasElement` 这类真实 API) | 改为动态 `import()`;日志里出现 `Scoped globals were read before this runtime existed` 说明特性检测走了「非浏览器」分支,同样需要调整入口顺序 |
225
+ | 触摸事件收不到 | 小程序未转发 `bindtouch*`,或小游戏在 runtime 之后才注册监听 | 见 [`docs/06`](./06-platform-notes.md) 与 §7.5 |
226
+ | H5 上 canvas 收不到 `pointer` / `wheel`,`OrbitControls` 拖不动 | 旧版本把 `MiniEventTarget` 打在真实 `HTMLCanvasElement` 上,浏览器内部派发绕过了 JS 侧监听表 | 升级到声明 `nativeEventTarget` 的版本(ADR-0010);旧版本只能把监听挂到真实 `document`。可跑 `npm run verify:h5` 自检 |