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/dist/polyfills/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export { MiniAbortController, MiniAbortSignal, MiniBlob, MiniCustomEvent, MiniDOMException, MiniEvent, MiniEventTarget, MiniMessageEvent, MiniMouseEvent, MiniPointerEvent, MiniProgressEvent, MiniTextDecoder, MiniTextEncoder, MiniURL, MiniURLSearchParams, MiniXMLHttpRequest, OBJECT_URL_PREFIX, atob, base64ToBytes, btoa, bytesToBase64, createFetch, createXMLHttpRequestFactory, patchEventTarget, resolveUrl } from '../chunk-
|
|
1
|
+
export { MiniAbortController, MiniAbortSignal, MiniBlob, MiniCustomEvent, MiniDOMException, MiniEvent, MiniEventTarget, MiniMessageEvent, MiniMouseEvent, MiniPointerEvent, MiniProgressEvent, MiniTextDecoder, MiniTextEncoder, MiniURL, MiniURLSearchParams, MiniXMLHttpRequest, OBJECT_URL_PREFIX, atob, base64ToBytes, btoa, bytesToBase64, createFetch, createXMLHttpRequestFactory, patchEventTarget, resolveUrl } from '../chunk-LAVHSWBU.js';
|
|
2
2
|
import '../chunk-V6TY7KAL.js';
|
|
3
3
|
//# sourceMappingURL=index.js.map
|
|
4
4
|
//# sourceMappingURL=index.js.map
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as Capabilities, R as Rect, D as Disposer, b as ContextType, f as TouchLikeEvent, d as FrameScheduler, W as WindowInfo, e as RuntimeEvents } from './types-
|
|
1
|
+
import { a as Capabilities, R as Rect, D as Disposer, N as NativeEventInit, b as ContextType, f as TouchLikeEvent, d as FrameScheduler, W as WindowInfo, e as RuntimeEvents } from './types-DOoJ7noL.js';
|
|
2
2
|
import { MiniThreeScope, DocumentLike } from './scope.js';
|
|
3
3
|
import { b as WxLike, W as WxCanvas } from './wx-types-BZTQ2jWG.js';
|
|
4
4
|
|
|
@@ -69,6 +69,13 @@ interface PatchElementOptions<T extends object> {
|
|
|
69
69
|
}>;
|
|
70
70
|
/** Called on `setAttribute(name, value)`. */
|
|
71
71
|
onSetAttribute?: (name: string, value: unknown, element: T) => void;
|
|
72
|
+
/**
|
|
73
|
+
* `true` when the object already owns a working event system and real DOM
|
|
74
|
+
* members (browser canvas). In that mode only missing members are defined:
|
|
75
|
+
* `addEventListener` / `style` / `getBoundingClientRect` ... are left to the
|
|
76
|
+
* host. See ADR-0010.
|
|
77
|
+
*/
|
|
78
|
+
nativeEventTarget?: boolean;
|
|
72
79
|
}
|
|
73
80
|
/** Patch DOM-ish properties onto an existing object while keeping identity. */
|
|
74
81
|
declare function patchElement<T extends object>(instance: T, options: PatchElementOptions<T>): PatchedElement<T>;
|
|
@@ -112,6 +119,16 @@ interface PlatformBinding {
|
|
|
112
119
|
readonly rawCanvas: WxCanvas;
|
|
113
120
|
readonly capabilities: Capabilities;
|
|
114
121
|
readonly imageFactory: ImageFactory;
|
|
122
|
+
/**
|
|
123
|
+
* `true` when `rawCanvas` already owns a working event system (browser
|
|
124
|
+
* canvas). The runtime then leaves `addEventListener` / `dispatchEvent` and
|
|
125
|
+
* the native DOM members alone, and dispatches real DOM events instead of
|
|
126
|
+
* `MiniEventTarget` ones. Defaults to `false` (WeChat bare objects).
|
|
127
|
+
* See ADR-0010.
|
|
128
|
+
*/
|
|
129
|
+
readonly nativeEventTarget?: boolean;
|
|
130
|
+
/** Build a real DOM event for `nativeEventTarget` targets. */
|
|
131
|
+
createEvent?(type: string, init: NativeEventInit): unknown;
|
|
115
132
|
/** Current bounding rect of `rawCanvas`; may be async on mini programs. */
|
|
116
133
|
getCanvasRect(): Rect | Promise<Rect>;
|
|
117
134
|
/** Create a secondary canvas without disturbing the on-screen one. */
|
|
@@ -146,6 +163,14 @@ interface PointerBridgeOptions {
|
|
|
146
163
|
/** Also emit legacy mouse* / click events. Default true. */
|
|
147
164
|
emitMouseEvents?: boolean;
|
|
148
165
|
diagnostics?: Diagnostics;
|
|
166
|
+
/**
|
|
167
|
+
* `true` when `targets.element` owns a native event system. The bridge then
|
|
168
|
+
* dispatches real DOM events and never fans out to the `document` / `window`
|
|
169
|
+
* shims: the browser already bubbles the event for us. See ADR-0010.
|
|
170
|
+
*/
|
|
171
|
+
nativeEventTarget?: boolean;
|
|
172
|
+
/** Build a real DOM event instead of a `MiniEvent`. */
|
|
173
|
+
createEvent?: (type: string, init: NativeEventInit) => unknown;
|
|
149
174
|
}
|
|
150
175
|
declare class PointerBridge {
|
|
151
176
|
private readonly options;
|
|
@@ -180,6 +205,7 @@ declare class PointerBridge {
|
|
|
180
205
|
clientY?: number;
|
|
181
206
|
button?: number;
|
|
182
207
|
deltaY?: number;
|
|
208
|
+
deltaMode?: number;
|
|
183
209
|
}): void;
|
|
184
210
|
dispose(): void;
|
|
185
211
|
private track;
|
|
@@ -187,6 +213,8 @@ declare class PointerBridge {
|
|
|
187
213
|
private synthesizePoint;
|
|
188
214
|
private toCoords;
|
|
189
215
|
private emit;
|
|
216
|
+
private makePointer;
|
|
217
|
+
private makeMouse;
|
|
190
218
|
private fanout;
|
|
191
219
|
}
|
|
192
220
|
|
package/dist/scope.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { c as EventTargetLike, P as PatchedCanvas, C as CanvasStyleLike, R as Rect } from './types-
|
|
1
|
+
import { c as EventTargetLike, P as PatchedCanvas, C as CanvasStyleLike, R as Rect } from './types-DOoJ7noL.js';
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* Scoped globals: the central design decision of mini-three-adapter.
|
package/dist/scope.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export { clearEarlyScopeReads, createScope, getActiveScope, getEarlyScopeReads, hasActiveScope, installGlobals, setActiveScope } from './chunk-
|
|
1
|
+
export { clearEarlyScopeReads, createScope, getActiveScope, getEarlyScopeReads, hasActiveScope, installGlobals, setActiveScope } from './chunk-J34MD3IL.js';
|
|
2
2
|
import './chunk-V6TY7KAL.js';
|
|
3
3
|
//# sourceMappingURL=scope.js.map
|
|
4
4
|
//# sourceMappingURL=scope.js.map
|
|
@@ -74,6 +74,18 @@ interface MiniPointerEvent {
|
|
|
74
74
|
stopPropagation(): void;
|
|
75
75
|
}
|
|
76
76
|
type EventListenerLike = (event: unknown) => void;
|
|
77
|
+
/**
|
|
78
|
+
* Fields used when a platform builds a real DOM event for a native event
|
|
79
|
+
* target (browser canvas). Values are forwarded to the host constructor and,
|
|
80
|
+
* when the constructor is missing, defined on a plain `Event` instance.
|
|
81
|
+
*/
|
|
82
|
+
interface NativeEventInit {
|
|
83
|
+
bubbles?: boolean;
|
|
84
|
+
cancelable?: boolean;
|
|
85
|
+
composed?: boolean;
|
|
86
|
+
/** Event-family specific fields: `pointerId`, `clientX`, `button`, `deltaY` ... */
|
|
87
|
+
[key: string]: unknown;
|
|
88
|
+
}
|
|
77
89
|
interface EventTargetLike {
|
|
78
90
|
addEventListener(type: string, listener: EventListenerLike, options?: unknown): void;
|
|
79
91
|
removeEventListener(type: string, listener: EventListenerLike, options?: unknown): void;
|
|
@@ -157,4 +169,4 @@ interface FrameScheduler {
|
|
|
157
169
|
dispose(): void;
|
|
158
170
|
}
|
|
159
171
|
|
|
160
|
-
export type { CanvasStyleLike as C, Disposer as D, EventListenerLike as E, FrameHandle as F, MiniPointerEvent as M, PatchedCanvas as P, Rect as R, TouchEventName as T, WindowInfo as W, Capabilities as a, ContextType as b, EventTargetLike as c, FrameScheduler as d, RuntimeEvents as e, TouchLikeEvent as f, TouchPoint as g };
|
|
172
|
+
export type { CanvasStyleLike as C, Disposer as D, EventListenerLike as E, FrameHandle as F, MiniPointerEvent as M, NativeEventInit as N, PatchedCanvas as P, Rect as R, TouchEventName as T, WindowInfo as W, Capabilities as a, ContextType as b, EventTargetLike as c, FrameScheduler as d, RuntimeEvents as e, TouchLikeEvent as f, TouchPoint as g };
|
|
@@ -1,105 +1,105 @@
|
|
|
1
|
-
# 01 · 设计目标与技术约束
|
|
2
|
-
|
|
3
|
-
> 本文档描述 `mini-three-adapter` 自身的设计目标、运行环境约束、技术选型与能力边界。它是阅读 [02 架构设计](./02-architecture.md) 之前的总纲。
|
|
4
|
-
|
|
5
|
-
## 1.1 项目定位
|
|
6
|
-
|
|
7
|
-
`mini-three-adapter` 让 three.js 运行在微信小游戏 / 小程序的**非 WebView 原生渲染环境**中,目标是让业务侧的场景代码尽可能保持标准 three.js 写法:
|
|
8
|
-
|
|
9
|
-
- 用 `new THREE.WebGLRenderer({ canvas })` 创建渲染器,不改写 three 源码、不引入定制版 three。
|
|
10
|
-
- 用 `three/addons/*` 的控制器、加载器,交互行为与浏览器一致。
|
|
11
|
-
- 同一份场景代码可以在小游戏、小程序和 H5 双端运行。
|
|
12
|
-
- 适配层本身不参与渲染管线、不管理材质与资源生命周期,这些仍归 three 与业务代码。
|
|
13
|
-
|
|
14
|
-
## 1.2 运行环境约束
|
|
15
|
-
|
|
16
|
-
微信小游戏的 JavaScript 运行时在 iOS 是 JavaScriptCore、Android 是 V8,**没有 BOM 与 DOM**:不存在全局 `window`、`document`、`Image`、`URL`、`XMLHttpRequest`、`EventTarget`。基础库只提供 `wx.*` 平台 API 与 `setTimeout` / `requestAnimationFrame` 等基础方法;DOM 兼容层需要由应用自行引入。
|
|
17
|
-
|
|
18
|
-
由此派生出几条硬约束:
|
|
19
|
-
|
|
20
|
-
| 约束 | 对实现的要求 |
|
|
21
|
-
| --- | --- |
|
|
22
|
-
| 只有一个上屏画布:首次 `wx.createCanvas()` 得到上屏画布,后续调用得到的都是离屏画布 | 必须把这一次调用收敛到单一位置并缓存;能力探测只能用 `wx.createOffscreenCanvas()` |
|
|
23
|
-
| 宿主内部按对象身份保存画布校验数据 | 画布补丁必须作用于原对象,不能包装、克隆或改原型 |
|
|
24
|
-
| `Canvas.getContext('webgl2')` 是可用的标准 WebGL2 上下文 | three ≥ r163 仅支持 WebGL2,适配层以 WebGL2 为唯一主线 |
|
|
25
|
-
| Worker 并发上限为 1,且配置只支持一个目录 | worker 与 wasm 必须输出到同一目录,分包 Worker 需先预下载 |
|
|
26
|
-
| 代码包有体积上限(主包 / 分包各 4MB、总包 8MB,以控制台额度为准) | three 本体、decoder、wasm 需要分包;`.wasm.br` 是有效的减包手段 |
|
|
27
|
-
| iOS 高性能模式内存限制更严,高性能+ 建议用于 WebGL2 场景 | 启动阶段就要能报告能力、避免不必要的大对象常驻 |
|
|
28
|
-
|
|
29
|
-
小程序(非小游戏)额外约束:画布节点要通过 `createSelectorQuery().select(...).fields({ node, rect, size })` **异步**取得,触摸事件由 WXML 绑定下发,而不是 `wx.onTouch*`。
|
|
30
|
-
|
|
31
|
-
## 1.3 Three.js 版本约束
|
|
32
|
-
|
|
33
|
-
| 版本 | 关系 |
|
|
34
|
-
| --- | --- |
|
|
35
|
-
| `>= 0.163.0`(r163+) | 目标区间。`WebGLRenderer` 要求 WebGL2 |
|
|
36
|
-
| `0.187.0` | 当前构建与单元测试所依据的版本 |
|
|
37
|
-
| `0.151.0 ~ 0.162.x` | 不保证:未针对 WebGL1 路径做专门适配 |
|
|
38
|
-
| `< 0.151.0` | 不提供保证 |
|
|
39
|
-
| `three/webgpu` + TSL / NodeMaterial | 小游戏环境没有 WebGPU,构建插件默认告警;复杂 WebGPU 项目需使用 WebGL 构建目标 |
|
|
40
|
-
|
|
41
|
-
版本升级时需要复核:导入路径(`three/addons/*`)、`renderer.outputColorSpace`、`renderer.setAnimationLoop()`、以及 three 新增的浏览器全局与 DOM 属性清单。检查项固化在 [`docs/11-compat-matrix.md`](./11-compat-matrix.md)。
|
|
42
|
-
|
|
43
|
-
## 1.4 设计目标
|
|
44
|
-
|
|
45
|
-
1. **不 fork three**:构建期只重定向三方模块对浏览器全局的自由引用,不修改 three 的语义。适配层与 three 版本解耦。
|
|
46
|
-
2. **零全局污染**:所有 shim 存放在显式的 `MiniThreeScope` 中,可被替换、可被卸载;写 `globalThis` 只发生在显式调用且可逆的路径上。
|
|
47
|
-
3. **一套 API 覆盖三端**:`createRuntime()` 返回唯一的 `MiniThreeRuntime`,平台差异收敛在 `PlatformBinding` 内部。
|
|
48
|
-
4. **单一生命周期**:所有订阅、定时器、全局注入统一登记,`dispose()` 之后不留副作用。
|
|
49
|
-
5. **可测试**:平台宿主可注入,核心逻辑能在 Node + Vitest 中完整验证,无需真实设备。
|
|
50
|
-
6. **可观测**:分级日志、一次性告警、能力报告与构建报告,让环境问题在启动/构建阶段就能定位。
|
|
51
|
-
7. **可 tree-shake**:ESM + 子路径导出 + 显式 `sideEffects`,运行时不携带构建工具依赖。
|
|
52
|
-
|
|
53
|
-
## 1.5 技术选型
|
|
54
|
-
|
|
55
|
-
| 领域 | 选型 | 理由 |
|
|
56
|
-
| --- | --- | --- |
|
|
57
|
-
| 语言与模块 | TypeScript strict + ESM | 完整 `.d.ts`,编译期捕获平台类型差异 |
|
|
58
|
-
| 运行时构建目标 | `es2019`(esbuild / tsup) | 降级可选链与空值合并,避免开发者工具语法报错 |
|
|
59
|
-
| 全局重定向 | `@babel/parser` + `@babel/traverse` + `magic-string` | 依赖真实作用域绑定信息,只改写自由变量,保留 sourcemap |
|
|
60
|
-
| 画布兼容 | `Object.defineProperty` + `Symbol.hasInstance` 注册表 | 保持对象身份,满足 three 的 `instanceof` 分支 |
|
|
61
|
-
| 平台抽象 | 结构化接口 `PlatformBinding` | 以组合方式表达平台差异,新增平台只需实现一组字段与方法 |
|
|
62
|
-
| 作用域 | `getActiveScope()` 惰性读取 | 支持运行时替换、多实例与测试注入 |
|
|
63
|
-
| 网络 | `wx.request` 桥接 `fetch` / `XMLHttpRequest` | three 的 FileLoader 与 addons 可直接工作 |
|
|
64
|
-
| 对象 URL | `mini-three-blob:` → `data:` URI | 宿主图片加载器可直接识别,无需拦截 `Image.src` |
|
|
65
|
-
| 构建工具集成 | Rollup 兼容插件核心 + Vite 薄封装 | 一套逻辑覆盖 Vite / Rollup,Node 依赖不进小游戏包 |
|
|
66
|
-
|
|
67
|
-
## 1.6 能力边界
|
|
68
|
-
|
|
69
|
-
**做**:
|
|
70
|
-
|
|
71
|
-
- 补全 three 与主流生态(three-stdlib / @react-three / @tresjs)用到的浏览器全局、DOM 属性与构造器判定。
|
|
72
|
-
- 把平台 `touch` 事件转换为符合 three controls 预期的 `pointer*` / `mouse*` 事件。
|
|
73
|
-
- 统一窗口尺寸、DPR、resize、可见性、帧循环。
|
|
74
|
-
- 构建期收集 worker / wasm / decoder 资源并生成分包建议。
|
|
75
|
-
- 提供 H5 双端可运行的 `browser` 平台。
|
|
76
|
-
|
|
77
|
-
**不做**:
|
|
78
|
-
|
|
79
|
-
- 不提供完整 DOM / CSS 布局 / 事件冒泡树;DOM 密集型 UI 应使用 WebView 方案。
|
|
80
|
-
- 不模拟 WebGPU;`createImageBitmap`、`FileReader`、`WebSocket` 保持 `undefined`,让依赖它们的库走降级分支。
|
|
81
|
-
- 不在运行时改写 `WebGLRenderer` 的行为;平台差异补丁一律显式、可关闭、可观测。
|
|
82
|
-
- 不默认改写业务代码(插件只处理 `node_modules` 中的三方生态模块)。
|
|
83
|
-
- 不内置物理、动画、UI 等 3D 引擎能力。
|
|
84
|
-
|
|
85
|
-
## 1.7 关键设计决策一览
|
|
86
|
-
|
|
87
|
-
| 决策 | 落地位置 | 详情 |
|
|
88
|
-
| --- | --- | --- |
|
|
89
|
-
| 显式可逆作用域 | `src/scope.ts` | [ADR-0001](./adr/0001-scoped-globals.md) |
|
|
90
|
-
| 单一运行生命周期 | `src/core/runtime.ts` | [ADR-0002](./adr/0002-unified-runtime-lifecycle.md) |
|
|
91
|
-
| AST 作用域重写 | `src/build/scope-rewrite.ts` | [ADR-0003](./adr/0003-ast-rewrite.md) |
|
|
92
|
-
| 就地画布补丁 | `src/core/element.ts` | [ADR-0004](./adr/0004-in-place-patching.md) |
|
|
93
|
-
| WebGL2 优先 | `src/core/capabilities.ts` | [ADR-0005](./adr/0005-webgl2-only.md) |
|
|
94
|
-
| 零 three 依赖、构建运行隔离 | `tsup.config.ts` | [ADR-0006](./adr/0006-zero-three-dependency.md) |
|
|
95
|
-
|
|
96
|
-
## 1.8 规范链接
|
|
97
|
-
|
|
98
|
-
平台与渲染引擎的权威规范,用于核对能力边界:
|
|
99
|
-
|
|
100
|
-
- [微信开放文档 · Adapter](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html)
|
|
101
|
-
- [微信开放文档 · 渲染](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html)
|
|
102
|
-
- [微信开放文档 · 使用 WXWebAssembly](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html)
|
|
103
|
-
- [微信开放文档 · iOS 高性能与高性能+模式](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/iOSOptimization.html)
|
|
104
|
-
- 微信开放文档 · 小游戏配置(game.json 的 workers / subpackages / iOSHighPerformance 字段)
|
|
105
|
-
- [three.js Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide)
|
|
1
|
+
# 01 · 设计目标与技术约束
|
|
2
|
+
|
|
3
|
+
> 本文档描述 `mini-three-adapter` 自身的设计目标、运行环境约束、技术选型与能力边界。它是阅读 [02 架构设计](./02-architecture.md) 之前的总纲。
|
|
4
|
+
|
|
5
|
+
## 1.1 项目定位
|
|
6
|
+
|
|
7
|
+
`mini-three-adapter` 让 three.js 运行在微信小游戏 / 小程序的**非 WebView 原生渲染环境**中,目标是让业务侧的场景代码尽可能保持标准 three.js 写法:
|
|
8
|
+
|
|
9
|
+
- 用 `new THREE.WebGLRenderer({ canvas })` 创建渲染器,不改写 three 源码、不引入定制版 three。
|
|
10
|
+
- 用 `three/addons/*` 的控制器、加载器,交互行为与浏览器一致。
|
|
11
|
+
- 同一份场景代码可以在小游戏、小程序和 H5 双端运行。
|
|
12
|
+
- 适配层本身不参与渲染管线、不管理材质与资源生命周期,这些仍归 three 与业务代码。
|
|
13
|
+
|
|
14
|
+
## 1.2 运行环境约束
|
|
15
|
+
|
|
16
|
+
微信小游戏的 JavaScript 运行时在 iOS 是 JavaScriptCore、Android 是 V8,**没有 BOM 与 DOM**:不存在全局 `window`、`document`、`Image`、`URL`、`XMLHttpRequest`、`EventTarget`。基础库只提供 `wx.*` 平台 API 与 `setTimeout` / `requestAnimationFrame` 等基础方法;DOM 兼容层需要由应用自行引入。
|
|
17
|
+
|
|
18
|
+
由此派生出几条硬约束:
|
|
19
|
+
|
|
20
|
+
| 约束 | 对实现的要求 |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| 只有一个上屏画布:首次 `wx.createCanvas()` 得到上屏画布,后续调用得到的都是离屏画布 | 必须把这一次调用收敛到单一位置并缓存;能力探测只能用 `wx.createOffscreenCanvas()` |
|
|
23
|
+
| 宿主内部按对象身份保存画布校验数据 | 画布补丁必须作用于原对象,不能包装、克隆或改原型 |
|
|
24
|
+
| `Canvas.getContext('webgl2')` 是可用的标准 WebGL2 上下文 | three ≥ r163 仅支持 WebGL2,适配层以 WebGL2 为唯一主线 |
|
|
25
|
+
| Worker 并发上限为 1,且配置只支持一个目录 | worker 与 wasm 必须输出到同一目录,分包 Worker 需先预下载 |
|
|
26
|
+
| 代码包有体积上限(主包 / 分包各 4MB、总包 8MB,以控制台额度为准) | three 本体、decoder、wasm 需要分包;`.wasm.br` 是有效的减包手段 |
|
|
27
|
+
| iOS 高性能模式内存限制更严,高性能+ 建议用于 WebGL2 场景 | 启动阶段就要能报告能力、避免不必要的大对象常驻 |
|
|
28
|
+
|
|
29
|
+
小程序(非小游戏)额外约束:画布节点要通过 `createSelectorQuery().select(...).fields({ node, rect, size })` **异步**取得,触摸事件由 WXML 绑定下发,而不是 `wx.onTouch*`。
|
|
30
|
+
|
|
31
|
+
## 1.3 Three.js 版本约束
|
|
32
|
+
|
|
33
|
+
| 版本 | 关系 |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `>= 0.163.0`(r163+) | 目标区间。`WebGLRenderer` 要求 WebGL2 |
|
|
36
|
+
| `0.187.0` | 当前构建与单元测试所依据的版本 |
|
|
37
|
+
| `0.151.0 ~ 0.162.x` | 不保证:未针对 WebGL1 路径做专门适配 |
|
|
38
|
+
| `< 0.151.0` | 不提供保证 |
|
|
39
|
+
| `three/webgpu` + TSL / NodeMaterial | 小游戏环境没有 WebGPU,构建插件默认告警;复杂 WebGPU 项目需使用 WebGL 构建目标 |
|
|
40
|
+
|
|
41
|
+
版本升级时需要复核:导入路径(`three/addons/*`)、`renderer.outputColorSpace`、`renderer.setAnimationLoop()`、以及 three 新增的浏览器全局与 DOM 属性清单。检查项固化在 [`docs/11-compat-matrix.md`](./11-compat-matrix.md)。
|
|
42
|
+
|
|
43
|
+
## 1.4 设计目标
|
|
44
|
+
|
|
45
|
+
1. **不 fork three**:构建期只重定向三方模块对浏览器全局的自由引用,不修改 three 的语义。适配层与 three 版本解耦。
|
|
46
|
+
2. **零全局污染**:所有 shim 存放在显式的 `MiniThreeScope` 中,可被替换、可被卸载;写 `globalThis` 只发生在显式调用且可逆的路径上。
|
|
47
|
+
3. **一套 API 覆盖三端**:`createRuntime()` 返回唯一的 `MiniThreeRuntime`,平台差异收敛在 `PlatformBinding` 内部。
|
|
48
|
+
4. **单一生命周期**:所有订阅、定时器、全局注入统一登记,`dispose()` 之后不留副作用。
|
|
49
|
+
5. **可测试**:平台宿主可注入,核心逻辑能在 Node + Vitest 中完整验证,无需真实设备。
|
|
50
|
+
6. **可观测**:分级日志、一次性告警、能力报告与构建报告,让环境问题在启动/构建阶段就能定位。
|
|
51
|
+
7. **可 tree-shake**:ESM + 子路径导出 + 显式 `sideEffects`,运行时不携带构建工具依赖。
|
|
52
|
+
|
|
53
|
+
## 1.5 技术选型
|
|
54
|
+
|
|
55
|
+
| 领域 | 选型 | 理由 |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| 语言与模块 | TypeScript strict + ESM | 完整 `.d.ts`,编译期捕获平台类型差异 |
|
|
58
|
+
| 运行时构建目标 | `es2019`(esbuild / tsup) | 降级可选链与空值合并,避免开发者工具语法报错 |
|
|
59
|
+
| 全局重定向 | `@babel/parser` + `@babel/traverse` + `magic-string` | 依赖真实作用域绑定信息,只改写自由变量,保留 sourcemap |
|
|
60
|
+
| 画布兼容 | `Object.defineProperty` + `Symbol.hasInstance` 注册表 | 保持对象身份,满足 three 的 `instanceof` 分支 |
|
|
61
|
+
| 平台抽象 | 结构化接口 `PlatformBinding` | 以组合方式表达平台差异,新增平台只需实现一组字段与方法 |
|
|
62
|
+
| 作用域 | `getActiveScope()` 惰性读取 | 支持运行时替换、多实例与测试注入 |
|
|
63
|
+
| 网络 | `wx.request` 桥接 `fetch` / `XMLHttpRequest` | three 的 FileLoader 与 addons 可直接工作 |
|
|
64
|
+
| 对象 URL | `mini-three-blob:` → `data:` URI | 宿主图片加载器可直接识别,无需拦截 `Image.src` |
|
|
65
|
+
| 构建工具集成 | Rollup 兼容插件核心 + Vite 薄封装 | 一套逻辑覆盖 Vite / Rollup,Node 依赖不进小游戏包 |
|
|
66
|
+
|
|
67
|
+
## 1.6 能力边界
|
|
68
|
+
|
|
69
|
+
**做**:
|
|
70
|
+
|
|
71
|
+
- 补全 three 与主流生态(three-stdlib / @react-three / @tresjs)用到的浏览器全局、DOM 属性与构造器判定。
|
|
72
|
+
- 把平台 `touch` 事件转换为符合 three controls 预期的 `pointer*` / `mouse*` 事件。
|
|
73
|
+
- 统一窗口尺寸、DPR、resize、可见性、帧循环。
|
|
74
|
+
- 构建期收集 worker / wasm / decoder 资源并生成分包建议。
|
|
75
|
+
- 提供 H5 双端可运行的 `browser` 平台。
|
|
76
|
+
|
|
77
|
+
**不做**:
|
|
78
|
+
|
|
79
|
+
- 不提供完整 DOM / CSS 布局 / 事件冒泡树;DOM 密集型 UI 应使用 WebView 方案。
|
|
80
|
+
- 不模拟 WebGPU;`createImageBitmap`、`FileReader`、`WebSocket` 保持 `undefined`,让依赖它们的库走降级分支。
|
|
81
|
+
- 不在运行时改写 `WebGLRenderer` 的行为;平台差异补丁一律显式、可关闭、可观测。
|
|
82
|
+
- 不默认改写业务代码(插件只处理 `node_modules` 中的三方生态模块)。
|
|
83
|
+
- 不内置物理、动画、UI 等 3D 引擎能力。
|
|
84
|
+
|
|
85
|
+
## 1.7 关键设计决策一览
|
|
86
|
+
|
|
87
|
+
| 决策 | 落地位置 | 详情 |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| 显式可逆作用域 | `src/scope.ts` | [ADR-0001](./adr/0001-scoped-globals.md) |
|
|
90
|
+
| 单一运行生命周期 | `src/core/runtime.ts` | [ADR-0002](./adr/0002-unified-runtime-lifecycle.md) |
|
|
91
|
+
| AST 作用域重写 | `src/build/scope-rewrite.ts` | [ADR-0003](./adr/0003-ast-rewrite.md) |
|
|
92
|
+
| 就地画布补丁 | `src/core/element.ts` | [ADR-0004](./adr/0004-in-place-patching.md) |
|
|
93
|
+
| WebGL2 优先 | `src/core/capabilities.ts` | [ADR-0005](./adr/0005-webgl2-only.md) |
|
|
94
|
+
| 零 three 依赖、构建运行隔离 | `tsup.config.ts` | [ADR-0006](./adr/0006-zero-three-dependency.md) |
|
|
95
|
+
|
|
96
|
+
## 1.8 规范链接
|
|
97
|
+
|
|
98
|
+
平台与渲染引擎的权威规范,用于核对能力边界:
|
|
99
|
+
|
|
100
|
+
- [微信开放文档 · Adapter](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html)
|
|
101
|
+
- [微信开放文档 · 渲染](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html)
|
|
102
|
+
- [微信开放文档 · 使用 WXWebAssembly](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html)
|
|
103
|
+
- [微信开放文档 · iOS 高性能与高性能+模式](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/iOSOptimization.html)
|
|
104
|
+
- 微信开放文档 · 小游戏配置(game.json 的 workers / subpackages / iOSHighPerformance 字段)
|
|
105
|
+
- [three.js Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide)
|
package/docs/03-module-map.md
CHANGED
|
@@ -1,99 +1,99 @@
|
|
|
1
|
-
# 03 · 模块地图(AI 修改入口索引)
|
|
2
|
-
|
|
3
|
-
> **给 AI 用**:动手前先在这张表里定位目标文件;「改这里」列给出常见需求的最小改动面,「会影响」列给出必须同步检查的下游。
|
|
4
|
-
> 依赖层级:`types → scope / polyfills → core → platforms`;`build` 是独立分支。
|
|
5
|
-
|
|
6
|
-
## 3.1 根与协议层
|
|
7
|
-
|
|
8
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
9
|
-
| --- | --- | --- | --- | --- |
|
|
10
|
-
| `src/types.ts` | 全部公开类型,纯 type-only | `Rect`、`WindowInfo`、`Capabilities`、`PatchedCanvas`、`TouchLikeEvent`、`FrameScheduler`、`RuntimeEvents` 等 | 新增平台能力字段、事件名称 | `core/*`、`platforms/*`、`dist/*.d.ts`、`docs/04` |
|
|
11
|
-
| `src/scope.ts` | 作用域协议:`MiniThreeScope`、活动作用域单例、显式全局注入、未初始化占位对象 | `createScope`、`getActiveScope`、`setActiveScope`、`hasActiveScope`、`installGlobals`、`getEarlyScopeReads`、`clearEarlyScopeReads` | 新增三方代码可能访问的浏览器全局;`UNDEFINED_BEFORE_RUNTIME` 里「探测型全局」的取舍 | **构建插件注入的 import**、[ADR-0001](./adr/0001-scoped-globals.md)、`docs/04`、`tests/scope.test.ts` |
|
|
12
|
-
| `src/index.ts` | 汇总导出 | 全部公开 API | 新增公共入口 | `package.json` `exports`、`docs/04` |
|
|
13
|
-
| `src/core/index.ts` | core 子路径导出 | core API | 同上 | `docs/04` |
|
|
14
|
-
| `src/polyfills/index.ts` | polyfills 子路径导出 | polyfill API | 同上 | `docs/04` |
|
|
15
|
-
|
|
16
|
-
## 3.2 polyfills(自包含,无平台知识)
|
|
17
|
-
|
|
18
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
19
|
-
| --- | --- | --- | --- | --- |
|
|
20
|
-
| `src/polyfills/event.ts` | W3C 事件系统,`patchEventTarget` 把方法绑到内部载体但把 `this` / `event.target` / `currentTarget`
|
|
21
|
-
| `src/polyfills/blob-url.ts` | Blob / URL / base64 / URL 相对解析 | `MiniBlob`、`MiniURL`、`bytesToBase64`、`resolveUrl` | `createObjectURL` 的目标格式、URL 解析边界 | `image.ts` 的 `src` 解析;`tests/polyfills.test.ts` |
|
|
22
|
-
| `src/polyfills/text-encoding.ts` | `atob`/`btoa`/`TextEncoder`/`TextDecoder` | 同名 | 编码边界、BOM、utf-16 | `network.ts`、`blob-url.ts`;`tests/polyfills.test.ts` |
|
|
23
|
-
| `src/polyfills/network.ts` | `fetch`、`XMLHttpRequest`、`AbortController` | `createFetch`、`createXMLHttpRequestFactory`、`MiniAbortController` | `wx.request` 返回结构差异、进度事件 | `runtime.ts` 的 scope 组装;`tests/polyfills.test.ts` |
|
|
24
|
-
|
|
25
|
-
> 约束:polyfills 不得 import `core/*`,不得读取 `globalThis.wx`。
|
|
26
|
-
|
|
27
|
-
## 3.3 core(平台无关运行时)
|
|
28
|
-
|
|
29
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
30
|
-
| --- | --- | --- | --- | --- |
|
|
31
|
-
| `src/core/platform.ts` |
|
|
32
|
-
| `src/core/runtime.ts` | **总装配**:画布补丁、scope 组装、订阅、生命周期 | `createRuntime`、`MiniThreeRuntime`、`RuntimeOptions`、`RendererHints` | 新增 runtime API、新增/移除全局项、调整启动顺序 | 几乎所有模块;`tests/runtime.test.ts` |
|
|
33
|
-
| `src/core/element.ts` | 就地 DOM 属性补丁 + `Symbol.hasInstance`
|
|
34
|
-
| `src/core/canvas.ts` | canvas 补丁:getContext 缓存、WebGL 归一化、离屏画布 | `patchCanvas`、`createOffscreenCanvas` | 上下文丢失、扩展返回值异常、`canvas.canvas` 指向 | `dom.ts`、`runtime.ts`;`tests/runtime.test.ts` |
|
|
35
|
-
| `src/core/image.ts` | Image / ImageData 工厂,blob URL → data URL,**原生事件 →
|
|
36
|
-
| `src/core/dom.ts` | `document` / `body` / `screen` / `DOMRect` / `OffscreenCanvas` 构造器 | `createDocument`、`createScreen`、`ShimDOMRect`、`createOffscreenCanvasCtor` | `document.createElement` 新标签、`visibilityState` | `runtime.ts` |
|
|
37
|
-
| `src/core/pointer.ts` | **touch → pointer/mouse
|
|
38
|
-
| `src/core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 | `createFrameScheduler` | 帧率限制、慢帧告警 | `runtime.ts` |
|
|
39
|
-
| `src/core/window-info.ts` | 窗口信息 + DPR 封顶 + resize 广播 | `createWindowInfoStore`、`readWindowInfo` | 新 API 替代 `getWindowInfo`、安全区 | `runtime.ts`;`tests/runtime.test.ts` |
|
|
40
|
-
| `src/core/capabilities.ts` | 能力探测(离屏优先,主画布回退;**不消费上屏画布**) | `detectCapabilities`、`versionAtLeast`、`webgl2Source` | 新增探测项、「探测不到」的语义 | 所有 `platforms/*`、`runtime.report()`;`tests/capabilities.test.ts` |
|
|
41
|
-
| `src/core/diagnostics.ts` | 分级日志、`warnOnce`、能力报告 | `createDiagnostics`、`capabilityReport` | 日志格式、报告字段 | 全局;`tests/runtime.test.ts` |
|
|
42
|
-
|
|
43
|
-
> 约束:`core/*` 不得 import `platforms/*`,不得 import `three`,不得直接写 `globalThis`。
|
|
44
|
-
|
|
45
|
-
## 3.4 platforms(平台差异收敛点)
|
|
46
|
-
|
|
47
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
48
|
-
| --- | --- | --- | --- | --- |
|
|
49
|
-
| `src/platforms/wx-types.ts` | 手写最小 `wx` 结构化类型(不依赖官方 typings) | `WxLike`、`WxCanvas`、`WxTouchEvent`、`resolveWx` | 用到新的 `wx.*` API 时补类型 | 所有平台;`docs/04` |
|
|
50
|
-
| `src/platforms/wechat-common.ts` | rAF / now / touch / visibility / 离屏画布 / 能力探测共用实现 | `watchWxTouch`、`createRafPair`、`probeContext`(返回 `boolean \| undefined`;无 `createOffscreenCanvas` 时不兜底,兜底时按 `reservedCanvases` 身份拒绝探测任何候选上屏画布)等 | 微信 API 变更、探测回退策略(ADR-0007、ADR-0008) | `wechat-game.ts`、`wechat-miniprogram.ts` |
|
|
51
|
-
| `src/platforms/wechat-game.ts` | 小游戏绑定 + 入口 | `createWeChatGameRuntime`、`createWeChatGameBinding`、`getScreenCanvas` | **上屏画布获取顺序**、锁帧 | `examples/wechat-minigame` |
|
|
52
|
-
| `src/platforms/wechat-miniprogram.ts` | 小程序绑定(`createSelectorQuery`) | `createWeChatMiniProgramRuntime` | 选择器查询、组件作用域 `selectorCtx` | `examples/wechat-miniprogram` |
|
|
53
|
-
| `src/platforms/browser.ts` | 浏览器 / Node
|
|
54
|
-
|
|
55
|
-
## 3.5 build(Node 侧,不进小游戏 bundle)
|
|
56
|
-
|
|
57
|
-
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
58
|
-
| --- | --- | --- | --- | --- |
|
|
59
|
-
| `src/build/scope-rewrite.ts` | **AST 全局重写**,`@babel/parser` + `path.scope.hasBinding` | `rewriteGlobals`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF` | 需要改写的全局清单、访问器名、注入的 import | 所有三方模块;`tests/scope-rewrite.test.ts`、[ADR-0003](./adr/0003-ast-rewrite.md) |
|
|
60
|
-
| `src/build/assets.ts` | worker/wasm 引用扫描、解析、拷贝、manifest | `collectAssetReferences`、`collectAssets`、`copyAssets`、`AssetManifest` | 新 decoder 类型、输出目录、`game.json` 建议 | `plugin-core.ts`;`tests/plugin.test.ts` |
|
|
61
|
-
| `src/build/plugin-core.ts` | Rollup/Vite 兼容插件核心 | `miniThreePlugin`、`BuildReport` | include 规则、WebGPU 策略、构建报告 | `vite.ts`、`rollup.ts`;`tests/plugin.test.ts` |
|
|
62
|
-
| `src/build/vite.ts` | Vite 入口 + `optimizeDeps.exclude` 配置 | `miniThree`(default) | Vite 版本兼容 | `examples/*/vite.config.ts` |
|
|
63
|
-
| `src/build/rollup.ts` | Rollup 入口 + 高级 API 再导出 | `miniThree`、`rewriteGlobals` 等 | Rollup 集成 | `docs/05` |
|
|
64
|
-
|
|
65
|
-
> 约束:`build/*` 不得 import `core/*` / `platforms/*`;`node:fs` 只允许出现在这里。
|
|
66
|
-
|
|
67
|
-
## 3.6 配置与示例
|
|
68
|
-
|
|
69
|
-
| 文件 | 作用 |
|
|
70
|
-
| --- | --- |
|
|
71
|
-
| `package.json` | `exports` 子路径、`sideEffects`、peer(`three`/`vite`/`rollup` 均 optional) |
|
|
72
|
-
| `tsconfig.json` | strict + `noUncheckedIndexedAccess` + `verbatimModuleSyntax`;`include` 覆盖 `src/tests/config` |
|
|
73
|
-
| `tsup.config.ts` | 两套构建:runtime(es2019 / neutral / dts / splitting)与 build tooling(node18 / 无 splitting) |
|
|
74
|
-
| `vitest.config.ts` | 单 fork 执行(规避 Windows 临时目录权限),`cache: false` |
|
|
75
|
-
| `tests/helpers/mock-wx.ts` | 可注入的 wx 模拟器;`__setSize` 触发 resize,`__touch` 触发触摸 |
|
|
76
|
-
| `examples/wechat-minigame/` | 小游戏完整工程(vite + game.json + project.config.json + postbuild) |
|
|
77
|
-
| `examples/wechat-miniprogram/` | 小程序页面(WXML 事件转发) |
|
|
78
|
-
| `examples/h5/` | H5 双端 |
|
|
79
|
-
|
|
80
|
-
## 3.7 常见任务 → 文件清单(AI 速查)
|
|
81
|
-
|
|
82
|
-
| 需求 | 最小改动面 |
|
|
83
|
-
| --- | --- |
|
|
84
|
-
| three 报 `xxx is not defined` | `src/build/scope-rewrite.ts` 的 `DEFAULT_GLOBAL_NAMES` → `src/scope.ts` 的 `MiniThreeScope` → `src/core/runtime.ts` 组装 |
|
|
85
|
-
| 新 three 版本用了新的 DOM 属性 | `src/core/element.ts` `patchElement`(+ canvas 的 `extra`)→ 补 `tests/runtime.test.ts` |
|
|
86
|
-
| 触摸在小程序里不生效 | `src/core/pointer.ts`(`tap`/无 touches)→ `examples/wechat-miniprogram/pages/index/index.ts` 转发 |
|
|
87
|
-
| 新增一个平台(如抖音小游戏) | 新建 `src/platforms/xxx.ts` 实现 `PlatformBinding` → `src/index.ts` 导出 → `package.json` exports → `docs/08` |
|
|
88
|
-
| 新增 decoder 资源 | `src/build/assets.ts` 的 `DECODER_KEYWORDS` / `defaultRoots` → `examples/*/vite.config.ts` 的 `roots` |
|
|
89
|
-
| WebGPU 相关代码报错 | `src/build/plugin-core.ts` `webgpu` 策略 → `docs/06` |
|
|
90
|
-
| resize 后画面变形 | `src/core/window-info.ts`、`src/core/runtime.ts` 的 `resize()`、`docs/06` |
|
|
91
|
-
| 包体过大 | `docs/06`(分包 / Brotli / manualChunks)+ `src/build/assets.ts` |
|
|
92
|
-
| 发布新版本 | `docs/09-testing-and-release.md` + `CHANGELOG.md` + `package.json` |
|
|
93
|
-
|
|
94
|
-
## 3.8 修改后必做
|
|
95
|
-
|
|
96
|
-
1. `npm run check`(typecheck +
|
|
97
|
-
2. 更新本表(若职责变化)、`docs/04-api-reference.md`(若导出变化)、`CHANGELOG.md`。
|
|
98
|
-
3. 若触及架构不变量,新增或修订 `docs/adr/*.md`。
|
|
99
|
-
4. 若新增了平台能力,更新 `docs/11-compat-matrix.md`。
|
|
1
|
+
# 03 · 模块地图(AI 修改入口索引)
|
|
2
|
+
|
|
3
|
+
> **给 AI 用**:动手前先在这张表里定位目标文件;「改这里」列给出常见需求的最小改动面,「会影响」列给出必须同步检查的下游。
|
|
4
|
+
> 依赖层级:`types → scope / polyfills → core → platforms`;`build` 是独立分支。
|
|
5
|
+
|
|
6
|
+
## 3.1 根与协议层
|
|
7
|
+
|
|
8
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
9
|
+
| --- | --- | --- | --- | --- |
|
|
10
|
+
| `src/types.ts` | 全部公开类型,纯 type-only | `Rect`、`WindowInfo`、`Capabilities`、`PatchedCanvas`、`TouchLikeEvent`、`FrameScheduler`、`RuntimeEvents` 等 | 新增平台能力字段、事件名称 | `core/*`、`platforms/*`、`dist/*.d.ts`、`docs/04` |
|
|
11
|
+
| `src/scope.ts` | 作用域协议:`MiniThreeScope`、活动作用域单例、显式全局注入、未初始化占位对象 | `createScope`、`getActiveScope`、`setActiveScope`、`hasActiveScope`、`installGlobals`、`getEarlyScopeReads`、`clearEarlyScopeReads` | 新增三方代码可能访问的浏览器全局;`UNDEFINED_BEFORE_RUNTIME` 里「探测型全局」的取舍 | **构建插件注入的 import**、[ADR-0001](./adr/0001-scoped-globals.md)、`docs/04`、`tests/scope.test.ts` |
|
|
12
|
+
| `src/index.ts` | 汇总导出 | 全部公开 API | 新增公共入口 | `package.json` `exports`、`docs/04` |
|
|
13
|
+
| `src/core/index.ts` | core 子路径导出 | core API | 同上 | `docs/04` |
|
|
14
|
+
| `src/polyfills/index.ts` | polyfills 子路径导出 | polyfill API | 同上 | `docs/04` |
|
|
15
|
+
|
|
16
|
+
## 3.2 polyfills(自包含,无平台知识)
|
|
17
|
+
|
|
18
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
19
|
+
| --- | --- | --- | --- | --- |
|
|
20
|
+
| `src/polyfills/event.ts` | W3C 事件系统,`patchEventTarget` 把方法绑到内部载体但把 `this` / `event.target` / `currentTarget` 转发给宿主元素;`dispatchEvent` 只对 `MiniEvent` 写 `target`(真实 DOM 事件只读,ADR-0010) | `MiniEvent`、`MiniPointerEvent`、`MiniMouseEvent`、`MiniEventTarget`、`patchEventTarget`、`MiniDOMException` | 事件字段缺失(如 controls 读 `movementX`)、`onxxx` 内联处理器、监听器拿不到事件目标 | `pointer.ts`、`dom.ts`;`tests/polyfills.test.ts`、`tests/event-dispatch.test.ts` |
|
|
21
|
+
| `src/polyfills/blob-url.ts` | Blob / URL / base64 / URL 相对解析 | `MiniBlob`、`MiniURL`、`bytesToBase64`、`resolveUrl` | `createObjectURL` 的目标格式、URL 解析边界 | `image.ts` 的 `src` 解析;`tests/polyfills.test.ts` |
|
|
22
|
+
| `src/polyfills/text-encoding.ts` | `atob`/`btoa`/`TextEncoder`/`TextDecoder` | 同名 | 编码边界、BOM、utf-16 | `network.ts`、`blob-url.ts`;`tests/polyfills.test.ts` |
|
|
23
|
+
| `src/polyfills/network.ts` | `fetch`、`XMLHttpRequest`、`AbortController` | `createFetch`、`createXMLHttpRequestFactory`、`MiniAbortController` | `wx.request` 返回结构差异、进度事件 | `runtime.ts` 的 scope 组装;`tests/polyfills.test.ts` |
|
|
24
|
+
|
|
25
|
+
> 约束:polyfills 不得 import `core/*`,不得读取 `globalThis.wx`。
|
|
26
|
+
|
|
27
|
+
## 3.3 core(平台无关运行时)
|
|
28
|
+
|
|
29
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
30
|
+
| --- | --- | --- | --- | --- |
|
|
31
|
+
| `src/core/platform.ts` | **平台契约**(结构化接口,替代抽象基类);`nativeEventTarget` / `createEvent` 声明宿主是否自带原生事件系统 | `PlatformBinding`、`PlatformFactory` | 平台要新增能力时**先改这里** | 所有 `platforms/*`、`runtime.ts` |
|
|
32
|
+
| `src/core/runtime.ts` | **总装配**:画布补丁、scope 组装、订阅、生命周期 | `createRuntime`、`MiniThreeRuntime`、`RuntimeOptions`、`RendererHints` | 新增 runtime API、新增/移除全局项、调整启动顺序 | 几乎所有模块;`tests/runtime.test.ts`、`tests/native-events.test.ts` |
|
|
33
|
+
| `src/core/element.ts` | 就地 DOM 属性补丁 + `Symbol.hasInstance` 注册表。原生事件目标上**只补缺失成员**,不覆盖宿主的 `style` / `getBoundingClientRect` / 事件方法 | `patchElement`、`createMockClass`、`*Shim`、`normalizeRect` | three 报「DOM 属性缺失」、`instanceof` 失败、H5 上原生成员被覆盖 | `canvas.ts`、`image.ts`、`dom.ts`;`tests/native-events.test.ts` |
|
|
34
|
+
| `src/core/canvas.ts` | canvas 补丁:getContext 缓存、WebGL 归一化、离屏画布 | `patchCanvas`、`createOffscreenCanvas` | 上下文丢失、扩展返回值异常、`canvas.canvas` 指向 | `dom.ts`、`runtime.ts`;`tests/runtime.test.ts` |
|
|
35
|
+
| `src/core/image.ts` | Image / ImageData 工厂,blob URL → data URL,**原生事件 → 合成事件桥接(四级兜底)**;`onload`/`onerror` 访问器不遮蔽原生槽位(非派发期间 getter 恒回桥接,[ADR-0011](./adr/0011-host-callback-slot-bridging.md)) | `createImageFactory`、`ShimImageData` | 图片加载、crossOrigin、`complete` / `decode`、事件不触发、WebP 解码失败 | `platforms/*`、`dom.ts`;`tests/image-events.test.ts` |
|
|
36
|
+
| `src/core/dom.ts` | `document` / `body` / `screen` / `DOMRect` / `OffscreenCanvas` 构造器 | `createDocument`、`createScreen`、`ShimDOMRect`、`createOffscreenCanvasCtor` | `document.createElement` 新标签、`visibilityState` | `runtime.ts` |
|
|
37
|
+
| `src/core/pointer.ts` | **touch → pointer/mouse 状态机**;`createEvent` 存在时派发真实 DOM 事件,`nativeEventTarget` 为真时不向 scoped `document` / `window` 转派 | `PointerBridge` | 多指、capture、`tap` 无 touches、坐标换算、H5 事件对象形态 | `runtime.ts`、`examples/*`;`tests/runtime.test.ts`、`tests/native-events.test.ts` |
|
|
38
|
+
| `src/core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 | `createFrameScheduler` | 帧率限制、慢帧告警 | `runtime.ts` |
|
|
39
|
+
| `src/core/window-info.ts` | 窗口信息 + DPR 封顶 + resize 广播 | `createWindowInfoStore`、`readWindowInfo` | 新 API 替代 `getWindowInfo`、安全区 | `runtime.ts`;`tests/runtime.test.ts` |
|
|
40
|
+
| `src/core/capabilities.ts` | 能力探测(离屏优先,主画布回退;**不消费上屏画布**) | `detectCapabilities`、`versionAtLeast`、`webgl2Source` | 新增探测项、「探测不到」的语义 | 所有 `platforms/*`、`runtime.report()`;`tests/capabilities.test.ts` |
|
|
41
|
+
| `src/core/diagnostics.ts` | 分级日志、`warnOnce`、能力报告 | `createDiagnostics`、`capabilityReport` | 日志格式、报告字段 | 全局;`tests/runtime.test.ts` |
|
|
42
|
+
|
|
43
|
+
> 约束:`core/*` 不得 import `platforms/*`,不得 import `three`,不得直接写 `globalThis`。
|
|
44
|
+
|
|
45
|
+
## 3.4 platforms(平台差异收敛点)
|
|
46
|
+
|
|
47
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 |
|
|
48
|
+
| --- | --- | --- | --- | --- |
|
|
49
|
+
| `src/platforms/wx-types.ts` | 手写最小 `wx` 结构化类型(不依赖官方 typings) | `WxLike`、`WxCanvas`、`WxTouchEvent`、`resolveWx` | 用到新的 `wx.*` API 时补类型 | 所有平台;`docs/04` |
|
|
50
|
+
| `src/platforms/wechat-common.ts` | rAF / now / touch / visibility / 离屏画布 / 能力探测共用实现 | `watchWxTouch`、`createRafPair`、`probeContext`(返回 `boolean \| undefined`;无 `createOffscreenCanvas` 时不兜底,兜底时按 `reservedCanvases` 身份拒绝探测任何候选上屏画布)等 | 微信 API 变更、探测回退策略(ADR-0007、ADR-0008) | `wechat-game.ts`、`wechat-miniprogram.ts` |
|
|
51
|
+
| `src/platforms/wechat-game.ts` | 小游戏绑定 + 入口 | `createWeChatGameRuntime`、`createWeChatGameBinding`、`getScreenCanvas` | **上屏画布获取顺序**、锁帧 | `examples/wechat-minigame` |
|
|
52
|
+
| `src/platforms/wechat-miniprogram.ts` | 小程序绑定(`createSelectorQuery`) | `createWeChatMiniProgramRuntime` | 选择器查询、组件作用域 `selectorCtx` | `examples/wechat-miniprogram` |
|
|
53
|
+
| `src/platforms/browser.ts` | 浏览器 / Node 测试平台;`nativeEventTarget: true` + 真实 `Event` 构造器(ADR-0010) | `createBrowserRuntime`、`createBrowserBinding` | H5 双端能力、原生事件目标 | `examples/h5`;`tests/native-events.test.ts` |
|
|
54
|
+
|
|
55
|
+
## 3.5 build(Node 侧,不进小游戏 bundle)
|
|
56
|
+
|
|
57
|
+
| 文件 | 职责 | 关键导出 | 改这里 | 会影响 / 测试 |
|
|
58
|
+
| --- | --- | --- | --- | --- |
|
|
59
|
+
| `src/build/scope-rewrite.ts` | **AST 全局重写**,`@babel/parser` + `path.scope.hasBinding` | `rewriteGlobals`、`DEFAULT_GLOBAL_NAMES`、`DEFAULT_FORCE_UNDEF` | 需要改写的全局清单、访问器名、注入的 import | 所有三方模块;`tests/scope-rewrite.test.ts`、[ADR-0003](./adr/0003-ast-rewrite.md) |
|
|
60
|
+
| `src/build/assets.ts` | worker/wasm 引用扫描、解析、拷贝、manifest | `collectAssetReferences`、`collectAssets`、`copyAssets`、`AssetManifest` | 新 decoder 类型、输出目录、`game.json` 建议 | `plugin-core.ts`;`tests/plugin.test.ts` |
|
|
61
|
+
| `src/build/plugin-core.ts` | Rollup/Vite 兼容插件核心 | `miniThreePlugin`、`BuildReport` | include 规则、WebGPU 策略、构建报告 | `vite.ts`、`rollup.ts`;`tests/plugin.test.ts` |
|
|
62
|
+
| `src/build/vite.ts` | Vite 入口 + `optimizeDeps.exclude` 配置 | `miniThree`(default) | Vite 版本兼容 | `examples/*/vite.config.ts` |
|
|
63
|
+
| `src/build/rollup.ts` | Rollup 入口 + 高级 API 再导出 | `miniThree`、`rewriteGlobals` 等 | Rollup 集成 | `docs/05` |
|
|
64
|
+
|
|
65
|
+
> 约束:`build/*` 不得 import `core/*` / `platforms/*`;`node:fs` 只允许出现在这里。
|
|
66
|
+
|
|
67
|
+
## 3.6 配置与示例
|
|
68
|
+
|
|
69
|
+
| 文件 | 作用 |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| `package.json` | `exports` 子路径、`sideEffects`、peer(`three`/`vite`/`rollup` 均 optional) |
|
|
72
|
+
| `tsconfig.json` | strict + `noUncheckedIndexedAccess` + `verbatimModuleSyntax`;`include` 覆盖 `src/tests/config` |
|
|
73
|
+
| `tsup.config.ts` | 两套构建:runtime(es2019 / neutral / dts / splitting)与 build tooling(node18 / 无 splitting) |
|
|
74
|
+
| `vitest.config.ts` | 单 fork 执行(规避 Windows 临时目录权限),`cache: false` |
|
|
75
|
+
| `tests/helpers/mock-wx.ts` | 可注入的 wx 模拟器;`__setSize` 触发 resize,`__touch` 触发触摸 |
|
|
76
|
+
| `examples/wechat-minigame/` | 小游戏完整工程(vite + game.json + project.config.json + postbuild) |
|
|
77
|
+
| `examples/wechat-miniprogram/` | 小程序页面(WXML 事件转发) |
|
|
78
|
+
| `examples/h5/` | H5 双端 |
|
|
79
|
+
|
|
80
|
+
## 3.7 常见任务 → 文件清单(AI 速查)
|
|
81
|
+
|
|
82
|
+
| 需求 | 最小改动面 |
|
|
83
|
+
| --- | --- |
|
|
84
|
+
| three 报 `xxx is not defined` | `src/build/scope-rewrite.ts` 的 `DEFAULT_GLOBAL_NAMES` → `src/scope.ts` 的 `MiniThreeScope` → `src/core/runtime.ts` 组装 |
|
|
85
|
+
| 新 three 版本用了新的 DOM 属性 | `src/core/element.ts` `patchElement`(+ canvas 的 `extra`)→ 补 `tests/runtime.test.ts` |
|
|
86
|
+
| 触摸在小程序里不生效 | `src/core/pointer.ts`(`tap`/无 touches)→ `examples/wechat-miniprogram/pages/index/index.ts` 转发 |
|
|
87
|
+
| 新增一个平台(如抖音小游戏) | 新建 `src/platforms/xxx.ts` 实现 `PlatformBinding` → `src/index.ts` 导出 → `package.json` exports → `docs/08` |
|
|
88
|
+
| 新增 decoder 资源 | `src/build/assets.ts` 的 `DECODER_KEYWORDS` / `defaultRoots` → `examples/*/vite.config.ts` 的 `roots` |
|
|
89
|
+
| WebGPU 相关代码报错 | `src/build/plugin-core.ts` `webgpu` 策略 → `docs/06` |
|
|
90
|
+
| resize 后画面变形 | `src/core/window-info.ts`、`src/core/runtime.ts` 的 `resize()`、`docs/06` |
|
|
91
|
+
| 包体过大 | `docs/06`(分包 / Brotli / manualChunks)+ `src/build/assets.ts` |
|
|
92
|
+
| 发布新版本 | `docs/09-testing-and-release.md` + `CHANGELOG.md` + `package.json` |
|
|
93
|
+
|
|
94
|
+
## 3.8 修改后必做
|
|
95
|
+
|
|
96
|
+
1. `npm run check`(typecheck + 100 例单测 + tsup 构建)。
|
|
97
|
+
2. 更新本表(若职责变化)、`docs/04-api-reference.md`(若导出变化)、`CHANGELOG.md`。
|
|
98
|
+
3. 若触及架构不变量,新增或修订 `docs/adr/*.md`。
|
|
99
|
+
4. 若新增了平台能力,更新 `docs/11-compat-matrix.md`。
|