mini-three-adapter 0.1.4 → 0.1.5
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 +1 -1
- package/README.md +1 -1
- package/dist/{chunk-NC2FTUEU.js → chunk-F7CSLEUI.js} +3 -3
- package/dist/{chunk-NC2FTUEU.js.map → chunk-F7CSLEUI.js.map} +1 -1
- package/dist/{chunk-2WNTAMJZ.js → chunk-LE4FRYNG.js} +4 -4
- package/dist/{chunk-2WNTAMJZ.js.map → chunk-LE4FRYNG.js.map} +1 -1
- package/dist/{chunk-26BRT4GS.js → chunk-VA7SZFLN.js} +3 -3
- package/dist/{chunk-26BRT4GS.js.map → chunk-VA7SZFLN.js.map} +1 -1
- package/dist/{chunk-HJIO6AFC.js → chunk-ZB3AYNOS.js} +4 -4
- package/dist/{chunk-HJIO6AFC.js.map → chunk-ZB3AYNOS.js.map} +1 -1
- package/dist/{chunk-XUKHCVAV.js → chunk-ZFJLEEF4.js} +179 -44
- package/dist/chunk-ZFJLEEF4.js.map +1 -0
- package/dist/core/index.d.ts +3 -3
- package/dist/core/index.js +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +5 -5
- package/dist/platforms/browser.d.ts +2 -2
- package/dist/platforms/browser.js +2 -2
- package/dist/platforms/wechat-game.d.ts +2 -2
- package/dist/platforms/wechat-game.js +3 -3
- package/dist/platforms/wechat-miniprogram.d.ts +2 -2
- package/dist/platforms/wechat-miniprogram.js +3 -3
- package/dist/polyfills/index.d.ts +1 -1
- package/dist/{runtime-DnEkKZjo.d.ts → runtime-BrHExTjl.d.ts} +1 -1
- package/dist/{wx-types-NMNyrsWO.d.ts → wx-types-BZTQ2jWG.d.ts} +17 -0
- package/docs/03-module-map.md +2 -2
- package/docs/04-api-reference.md +2 -2
- package/docs/06-platform-notes.md +39 -1
- package/docs/07-integration-guide.md +1 -1
- package/docs/09-testing-and-release.md +4 -4
- package/docs/11-compat-matrix.md +100 -96
- package/llms.txt +1 -1
- package/package.json +1 -1
- package/dist/chunk-XUKHCVAV.js.map +0 -1
package/dist/core/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import '../chunk-QYQQ5J6E.js';
|
|
2
|
-
export { DOMRectShim, HTMLCanvasElementShim, HTMLElementShim, HTMLImageElementShim, ImageDataShim, OffscreenCanvasShim, PointerBridge, ShimDOMRect, ShimImageData, WebGL2RenderingContextShim, WebGLRenderingContextShim, capabilityReport, createDiagnostics, createDocument, createFrameScheduler, createImageFactory, createMockClass, createOffscreenCanvas, createRuntime, createScreen, createWindowInfoStore, currentScope, detectCapabilities, isMarked, markAs, normalizeRect, patchCanvas, patchElement, readWindowInfo, versionAtLeast } from '../chunk-
|
|
2
|
+
export { DOMRectShim, HTMLCanvasElementShim, HTMLElementShim, HTMLImageElementShim, ImageDataShim, OffscreenCanvasShim, PointerBridge, ShimDOMRect, ShimImageData, WebGL2RenderingContextShim, WebGLRenderingContextShim, capabilityReport, createDiagnostics, createDocument, createFrameScheduler, createImageFactory, createMockClass, createOffscreenCanvas, createRuntime, createScreen, createWindowInfoStore, currentScope, detectCapabilities, isMarked, markAs, normalizeRect, patchCanvas, patchElement, readWindowInfo, versionAtLeast } from '../chunk-ZFJLEEF4.js';
|
|
3
3
|
import '../chunk-35XVAVDB.js';
|
|
4
4
|
import '../chunk-LCJNTN6F.js';
|
|
5
5
|
import '../chunk-V6TY7KAL.js';
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
export { D as DOMRectShim, a as Diagnostics, H as HTMLCanvasElementShim, b as HTMLElementShim, c as HTMLImageElementShim, I as ImageDataShim, d as ImageFactory, L as LogLevel, M as MiniImageData, e as MiniThreeRuntime, f as MockClass, O as OffscreenCanvasShim, P as PatchElementOptions, g as PatchedElement, h as PlatformBinding, i as PlatformFactory, j as PointerBridge, k as PointerBridgeOptions, l as PointerTargets, R as RendererHints, m as Reporter, n as RuntimeOptions, S as ShimImageData, W as WebGL2RenderingContextShim, o as WebGLRenderingContextShim, p as capabilityReport, q as createDiagnostics, r as createImageFactory, s as createMockClass, t as createRuntime, u as currentScope, v as isMarked, w as markAs, x as normalizeRect, y as patchElement } from './runtime-
|
|
1
|
+
export { D as DOMRectShim, a as Diagnostics, H as HTMLCanvasElementShim, b as HTMLElementShim, c as HTMLImageElementShim, I as ImageDataShim, d as ImageFactory, L as LogLevel, M as MiniImageData, e as MiniThreeRuntime, f as MockClass, O as OffscreenCanvasShim, P as PatchElementOptions, g as PatchedElement, h as PlatformBinding, i as PlatformFactory, j as PointerBridge, k as PointerBridgeOptions, l as PointerTargets, R as RendererHints, m as Reporter, n as RuntimeOptions, S as ShimImageData, W as WebGL2RenderingContextShim, o as WebGLRenderingContextShim, p as capabilityReport, q as createDiagnostics, r as createImageFactory, s as createMockClass, t as createRuntime, u as currentScope, v as isMarked, w as markAs, x as normalizeRect, y as patchElement } from './runtime-BrHExTjl.js';
|
|
2
2
|
export { FrameSchedulerOptions, PatchCanvasOptions, PatchedCanvasResult, ShimDOMRect, WindowInfoOptions, WindowInfoStore, createDocument, createFrameScheduler, createOffscreenCanvas, createScreen, createWindowInfoStore, detectCapabilities, patchCanvas, readWindowInfo, versionAtLeast } from './core/index.js';
|
|
3
3
|
export { C as CanvasStyleLike, a as Capabilities, b as ContextType, D as Disposer, E as EventListenerLike, c as EventTargetLike, F as FrameHandle, d as FrameScheduler, M as MiniPointerEvent, P as PatchedCanvas, R as Rect, e as RuntimeEvents, T as TouchEventName, f as TouchLikeEvent, g as TouchPoint, W as WindowInfo } from './types-X_5SJh4y.js';
|
|
4
4
|
export { DocumentLike, ElementLike, InstallGlobalsOptions, MiniThreeScope, NavigatorLike, clearEarlyScopeReads, createScope, getActiveScope, getEarlyScopeReads, hasActiveScope, installGlobals, setActiveScope } from './scope.js';
|
|
5
5
|
export { WeChatGameOptions, WeChatGameRuntimeOptions, createWeChatGameBinding, createWeChatGameRuntime, getScreenCanvas, resetScreenCanvasCache } from './platforms/wechat-game.js';
|
|
6
6
|
export { SelectorCtx, WeChatMiniProgramOptions, WeChatMiniProgramRuntimeOptions, createWeChatMiniProgramBinding, createWeChatMiniProgramRuntime } from './platforms/wechat-miniprogram.js';
|
|
7
7
|
export { BrowserPlatformOptions, BrowserRuntimeOptions, createBrowserBinding, createBrowserRuntime } from './platforms/browser.js';
|
|
8
|
-
export { W as WxCanvas, a as WxImage, b as WxLike, c as WxRect, d as WxRequestOptions, e as WxRequestResult, f as WxSelectorQuery, g as WxSelectorQueryResult, h as WxTouchEvent, i as WxTouchPoint, j as WxWindowInfo, r as resolveWx } from './wx-types-
|
|
8
|
+
export { W as WxCanvas, a as WxImage, b as WxLike, c as WxRect, d as WxRequestOptions, e as WxRequestResult, f as WxSelectorQuery, g as WxSelectorQueryResult, h as WxTouchEvent, i as WxTouchPoint, j as WxWindowInfo, r as resolveWx } from './wx-types-BZTQ2jWG.js';
|
package/dist/index.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import './chunk-QYQQ5J6E.js';
|
|
2
|
-
export { createBrowserBinding, createBrowserRuntime } from './chunk-
|
|
3
|
-
export { createWeChatGameBinding, createWeChatGameRuntime, getScreenCanvas, resetScreenCanvasCache } from './chunk-
|
|
4
|
-
export { createWeChatMiniProgramBinding, createWeChatMiniProgramRuntime } from './chunk-
|
|
5
|
-
export { resolveWx } from './chunk-
|
|
6
|
-
export { DOMRectShim, HTMLCanvasElementShim, HTMLElementShim, HTMLImageElementShim, ImageDataShim, OffscreenCanvasShim, PointerBridge, ShimDOMRect, ShimImageData, WebGL2RenderingContextShim, WebGLRenderingContextShim, capabilityReport, createDiagnostics, createDocument, createFrameScheduler, createImageFactory, createMockClass, createOffscreenCanvas, createRuntime, createScreen, createWindowInfoStore, currentScope, detectCapabilities, isMarked, markAs, normalizeRect, patchCanvas, patchElement, readWindowInfo, versionAtLeast } from './chunk-
|
|
2
|
+
export { createBrowserBinding, createBrowserRuntime } from './chunk-F7CSLEUI.js';
|
|
3
|
+
export { createWeChatGameBinding, createWeChatGameRuntime, getScreenCanvas, resetScreenCanvasCache } from './chunk-ZB3AYNOS.js';
|
|
4
|
+
export { createWeChatMiniProgramBinding, createWeChatMiniProgramRuntime } from './chunk-LE4FRYNG.js';
|
|
5
|
+
export { resolveWx } from './chunk-VA7SZFLN.js';
|
|
6
|
+
export { DOMRectShim, HTMLCanvasElementShim, HTMLElementShim, HTMLImageElementShim, ImageDataShim, OffscreenCanvasShim, PointerBridge, ShimDOMRect, ShimImageData, WebGL2RenderingContextShim, WebGLRenderingContextShim, capabilityReport, createDiagnostics, createDocument, createFrameScheduler, createImageFactory, createMockClass, createOffscreenCanvas, createRuntime, createScreen, createWindowInfoStore, currentScope, detectCapabilities, isMarked, markAs, normalizeRect, patchCanvas, patchElement, readWindowInfo, versionAtLeast } from './chunk-ZFJLEEF4.js';
|
|
7
7
|
export { clearEarlyScopeReads, createScope, getActiveScope, getEarlyScopeReads, hasActiveScope, installGlobals, setActiveScope } from './chunk-35XVAVDB.js';
|
|
8
8
|
import './chunk-LCJNTN6F.js';
|
|
9
9
|
import './chunk-V6TY7KAL.js';
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { a as Capabilities } from '../types-X_5SJh4y.js';
|
|
2
|
-
import { a as Diagnostics, n as RuntimeOptions, h as PlatformBinding, e as MiniThreeRuntime } from '../runtime-
|
|
2
|
+
import { a as Diagnostics, n as RuntimeOptions, h as PlatformBinding, e as MiniThreeRuntime } from '../runtime-BrHExTjl.js';
|
|
3
3
|
import '../scope.js';
|
|
4
|
-
import '../wx-types-
|
|
4
|
+
import '../wx-types-BZTQ2jWG.js';
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
7
|
* Browser platform. Used for H5 dual-target builds (uni-app / weapp-vite H5)
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
export { createBrowserBinding, createBrowserRuntime } from '../chunk-
|
|
2
|
-
import '../chunk-
|
|
1
|
+
export { createBrowserBinding, createBrowserRuntime } from '../chunk-F7CSLEUI.js';
|
|
2
|
+
import '../chunk-ZFJLEEF4.js';
|
|
3
3
|
import '../chunk-35XVAVDB.js';
|
|
4
4
|
import '../chunk-LCJNTN6F.js';
|
|
5
5
|
import '../chunk-V6TY7KAL.js';
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { a as Capabilities } from '../types-X_5SJh4y.js';
|
|
2
|
-
import { a as Diagnostics, n as RuntimeOptions, h as PlatformBinding, e as MiniThreeRuntime } from '../runtime-
|
|
3
|
-
import { b as WxLike, W as WxCanvas } from '../wx-types-
|
|
2
|
+
import { a as Diagnostics, n as RuntimeOptions, h as PlatformBinding, e as MiniThreeRuntime } from '../runtime-BrHExTjl.js';
|
|
3
|
+
import { b as WxLike, W as WxCanvas } from '../wx-types-BZTQ2jWG.js';
|
|
4
4
|
import '../scope.js';
|
|
5
5
|
|
|
6
6
|
/** WeChat Mini Game (小游戏) platform binding. */
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
export { createWeChatGameBinding, createWeChatGameRuntime, getScreenCanvas, resetScreenCanvasCache } from '../chunk-
|
|
2
|
-
import '../chunk-
|
|
3
|
-
import '../chunk-
|
|
1
|
+
export { createWeChatGameBinding, createWeChatGameRuntime, getScreenCanvas, resetScreenCanvasCache } from '../chunk-ZB3AYNOS.js';
|
|
2
|
+
import '../chunk-VA7SZFLN.js';
|
|
3
|
+
import '../chunk-ZFJLEEF4.js';
|
|
4
4
|
import '../chunk-35XVAVDB.js';
|
|
5
5
|
import '../chunk-LCJNTN6F.js';
|
|
6
6
|
import '../chunk-V6TY7KAL.js';
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { a as Capabilities } from '../types-X_5SJh4y.js';
|
|
2
|
-
import { a as Diagnostics, n as RuntimeOptions, h as PlatformBinding, e as MiniThreeRuntime } from '../runtime-
|
|
3
|
-
import { f as WxSelectorQuery, b as WxLike } from '../wx-types-
|
|
2
|
+
import { a as Diagnostics, n as RuntimeOptions, h as PlatformBinding, e as MiniThreeRuntime } from '../runtime-BrHExTjl.js';
|
|
3
|
+
import { f as WxSelectorQuery, b as WxLike } from '../wx-types-BZTQ2jWG.js';
|
|
4
4
|
import '../scope.js';
|
|
5
5
|
|
|
6
6
|
/** WeChat Mini Program (小程序, canvas type="webgl2") platform binding. */
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
export { createWeChatMiniProgramBinding, createWeChatMiniProgramRuntime } from '../chunk-
|
|
2
|
-
import '../chunk-
|
|
3
|
-
import '../chunk-
|
|
1
|
+
export { createWeChatMiniProgramBinding, createWeChatMiniProgramRuntime } from '../chunk-LE4FRYNG.js';
|
|
2
|
+
import '../chunk-VA7SZFLN.js';
|
|
3
|
+
import '../chunk-ZFJLEEF4.js';
|
|
4
4
|
import '../chunk-35XVAVDB.js';
|
|
5
5
|
import '../chunk-LCJNTN6F.js';
|
|
6
6
|
import '../chunk-V6TY7KAL.js';
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { c as EventTargetLike, E as EventListenerLike } from '../types-X_5SJh4y.js';
|
|
2
|
-
import { b as WxLike } from '../wx-types-
|
|
2
|
+
import { b as WxLike } from '../wx-types-BZTQ2jWG.js';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Blob + URL shims. WeChat mini games have neither. GLTFLoader, KTX2Loader,
|
|
@@ -1,6 +1,6 @@
|
|
|
1
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-X_5SJh4y.js';
|
|
2
2
|
import { MiniThreeScope, DocumentLike } from './scope.js';
|
|
3
|
-
import { b as WxLike, W as WxCanvas } from './wx-types-
|
|
3
|
+
import { b as WxLike, W as WxCanvas } from './wx-types-BZTQ2jWG.js';
|
|
4
4
|
|
|
5
5
|
/** Structured, level-filtered diagnostics. No console spam in production. */
|
|
6
6
|
|
|
@@ -25,6 +25,21 @@ interface WxImage {
|
|
|
25
25
|
complete?: boolean;
|
|
26
26
|
[key: string]: unknown;
|
|
27
27
|
}
|
|
28
|
+
interface WxImageInfo {
|
|
29
|
+
width: number;
|
|
30
|
+
height: number;
|
|
31
|
+
path?: string;
|
|
32
|
+
type?: string;
|
|
33
|
+
orientation?: string;
|
|
34
|
+
}
|
|
35
|
+
interface WxGetImageInfoOptions {
|
|
36
|
+
src: string;
|
|
37
|
+
success?: (info: WxImageInfo) => void;
|
|
38
|
+
fail?: (error: {
|
|
39
|
+
errMsg?: string;
|
|
40
|
+
[key: string]: unknown;
|
|
41
|
+
}) => void;
|
|
42
|
+
}
|
|
28
43
|
interface WxRect {
|
|
29
44
|
top: number;
|
|
30
45
|
left: number;
|
|
@@ -101,6 +116,8 @@ interface WxLike {
|
|
|
101
116
|
}): WxCanvas;
|
|
102
117
|
createImage?(): WxImage;
|
|
103
118
|
createImageData?(width: number, height: number): unknown;
|
|
119
|
+
/** Metadata-only decode: proves an asset is readable without loading it. */
|
|
120
|
+
getImageInfo?(options: WxGetImageInfoOptions): void;
|
|
104
121
|
getWindowInfo?(): WxWindowInfo;
|
|
105
122
|
getSystemInfoSync?(): WxWindowInfo;
|
|
106
123
|
onWindowResize?(listener: (res: {
|
package/docs/03-module-map.md
CHANGED
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
| `src/core/runtime.ts` | **总装配**:画布补丁、scope 组装、订阅、生命周期 | `createRuntime`、`MiniThreeRuntime`、`RuntimeOptions`、`RendererHints` | 新增 runtime API、新增/移除全局项、调整启动顺序 | 几乎所有模块;`tests/runtime.test.ts` |
|
|
33
33
|
| `src/core/element.ts` | 就地 DOM 属性补丁 + `Symbol.hasInstance` 注册表 | `patchElement`、`createMockClass`、`*Shim`、`normalizeRect` | three 报「DOM 属性缺失」、`instanceof` 失败 | `canvas.ts`、`image.ts`、`dom.ts` |
|
|
34
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
|
|
35
|
+
| `src/core/image.ts` | Image / ImageData 工厂,blob URL → data URL,**原生事件 → 合成事件桥接(四级兜底)** | `createImageFactory`、`ShimImageData` | 图片加载、crossOrigin、`complete` / `decode`、事件不触发、WebP 解码失败 | `platforms/*`、`dom.ts`;`tests/image-events.test.ts` |
|
|
36
36
|
| `src/core/dom.ts` | `document` / `body` / `screen` / `DOMRect` / `OffscreenCanvas` 构造器 | `createDocument`、`createScreen`、`ShimDOMRect`、`createOffscreenCanvasCtor` | `document.createElement` 新标签、`visibilityState` | `runtime.ts` |
|
|
37
37
|
| `src/core/pointer.ts` | **touch → pointer/mouse 状态机** | `PointerBridge` | 多指、capture、`tap` 无 touches、坐标换算 | `runtime.ts`、`examples/*`;`tests/runtime.test.ts` |
|
|
38
38
|
| `src/core/frames.ts` | rAF 包装、delta、fpsCap、FPS 测量 | `createFrameScheduler` | 帧率限制、慢帧告警 | `runtime.ts` |
|
|
@@ -93,7 +93,7 @@
|
|
|
93
93
|
|
|
94
94
|
## 3.8 修改后必做
|
|
95
95
|
|
|
96
|
-
1. `npm run check`(typecheck +
|
|
96
|
+
1. `npm run check`(typecheck + 79 例单测 + tsup 构建)。
|
|
97
97
|
2. 更新本表(若职责变化)、`docs/04-api-reference.md`(若导出变化)、`CHANGELOG.md`。
|
|
98
98
|
3. 若触及架构不变量,新增或修订 `docs/adr/*.md`。
|
|
99
99
|
4. 若新增了平台能力,更新 `docs/11-compat-matrix.md`。
|
package/docs/04-api-reference.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 04 · API 参考
|
|
2
2
|
|
|
3
|
-
> 版本:0.1.
|
|
3
|
+
> 版本:0.1.5。所有签名以 `src/**` 与 `npm run build` 生成的 `dist/*.d.ts` 为准。
|
|
4
4
|
> 子路径导入可最大化 tree-shaking;`mini-three-adapter` 是汇总入口。
|
|
5
5
|
|
|
6
6
|
## 4.1 子路径
|
|
@@ -174,7 +174,7 @@ function clearEarlyScopeReads(): void;
|
|
|
174
174
|
| `*Shim` | `HTMLCanvasElementShim`、`HTMLImageElementShim`、`HTMLElementShim`、`OffscreenCanvasShim`、`ImageDataShim`、`WebGLRenderingContextShim`、`WebGL2RenderingContextShim`、`DOMRectShim` |
|
|
175
175
|
| `patchCanvas(raw, options)` | 返回 `{ canvas, contexts, updateRect, element, disposers }` |
|
|
176
176
|
| `createOffscreenCanvas(wx, w?, h?, options?)` | 直接创建并补丁离屏画布 |
|
|
177
|
-
| `createImageFactory(wx, diagnostics?)` | `{ Image, HTMLImageElement, ImageData, createImage, createImageData, createImageBitmap: undefined }
|
|
177
|
+
| `createImageFactory(wx, diagnostics?)` | `{ Image, HTMLImageElement, ImageData, createImage, createImageData, createImageBitmap: undefined }`。工厂按「原生 `addEventListener` → `onload`/`onerror` 赋值 → `wx.getImageInfo` → 2s watchdog」四级兜底把宿主事件桥接成合成事件:`img.onload = fn` 与 `addEventListener('load', fn)` 都能收到通知,`complete` 在成功/失败后都为 `true`,`decode()` 据此 resolve/reject。宿主既无事件入口也无 `getImageInfo` 时不再静默挂起,而是在 2s 内派发带 `reason` 的 `error` |
|
|
178
178
|
| `createDocument(options)` / `createScreen(w, h)` / `ShimDOMRect` | 伪 DOM 容器 |
|
|
179
179
|
| `PointerBridge` | `dispatch(event, opts?)`、`dispatchMouse(event)`、`setRect`、`refreshRect`、`setPointerCapture`、`releasePointerCapture`、`activePointerCount`、`dispose` |
|
|
180
180
|
| `createFrameScheduler(raf, caf, options)` | `request` / `cancel` / `loop(cb)` / `setFpsCap` / `fps` / `dispose` |
|
|
@@ -46,7 +46,8 @@ const { startScene } = await import('./scene.js'); // scene.js 里才 import thr
|
|
|
46
46
|
| 重复调用 `wx.createCanvas()` 导致黑屏 | 第二个画布是离屏的,不显示 | `getScreenCanvas()` 缓存;额外画布一律走 `createOffscreenCanvas` / `runtime.createCanvas()` |
|
|
47
47
|
| WebGPU 相关 API 报错 | 小游戏无 WebGPU | 插件 `webgpu` 策略;默认告警 |
|
|
48
48
|
| three 版本升级后控件失效 | r170+ 用 `three/addons/`,`outputColorSpace` 取代 `outputEncoding` | 示例与 `rendererHints` 使用新 API;插件 include 覆盖两种路径 |
|
|
49
|
-
| `img.onload` / `addEventListener('load')` 永不触发,纹理靠超时兜底 | 图片 shim 只建了「合成事件 → 用户回调」这条边,没有「原生 load →
|
|
49
|
+
| `img.onload` / `addEventListener('load')` 永不触发,纹理靠超时兜底 | 图片 shim 只建了「合成事件 → 用户回调」这条边,没有「原生 load → 合成事件」;部分宿主的 `onload`/`onerror` 读不到描述符,但支持直接赋值 | `createImageFactory` 在 patch 前抓原生入口,按「原生 `addEventListener` → `onload` 赋值 → `wx.getImageInfo` 诊断 → 2s watchdog」四级兜底;宿主形态写入 `image-native-events` 告警的 payload |
|
|
50
|
+
| 纹理是 `.webp` 但真机加载失败 | 该设备的图片解码器不支持 WebP | 纹理改用 PNG / JPEG;`wx.getImageInfo` 失败时告警会点名格式与路径 |
|
|
50
51
|
| `canvas.onpointerdown = fn` 之类行内处理器不触发 | 事件方法被绑定到内部对象,`this['on'+type]` 查找落空 | `patchEventTarget` 把宿主对象作为行内处理器宿主传入 |
|
|
51
52
|
| `texture.image` 是个没有 `src` 的空壳,贴图不显示 | 监听器里的 `this` 是内部 `MiniEventTarget`,three `ImageLoader` 把它当成 `<img>` 存进 `Texture.source.data` | `dispatchEvent` 把 `this`、`event.target`、`currentTarget` 全部转发到宿主元素;`event.target` 不再暴露内部监听表 |
|
|
52
53
|
| 预置 `GameGlobal.screencanvas` 的宿主偶发黑屏 | 探测回退拿到的正是上屏画布,`getContext` + `WEBGL_lose_context` 把它废掉 | 无 `createOffscreenCanvas` 时干脆不兜底;兜底时按 `reservedCanvases`(本次使用的画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`)逐个比对身份,命中任一即放弃并退回 `webgl2Source: 'inferred'`(ADR-0008) |
|
|
@@ -61,6 +62,43 @@ renderer.setAnimationLoop(() => {
|
|
|
61
62
|
});
|
|
62
63
|
```
|
|
63
64
|
|
|
65
|
+
### 6.3.1 图片事件桥接的宿主形态
|
|
66
|
+
|
|
67
|
+
`wx.createImage()` 返回的对象在模拟器与不同真机 / 基础库上形状不一致。「能读描述符」只是其中一种形态,
|
|
68
|
+
所以 `createImageFactory` 在 `patchElement` **之前**按顺序抓取四种入口:
|
|
69
|
+
|
|
70
|
+
| 宿主形态 | 抓取方式 | 结果 |
|
|
71
|
+
| --- | --- | --- |
|
|
72
|
+
| 原生 `addEventListener('load'/'error')` | patch 前 `bind` 保存,patch 后直接调用原生方法 | 最优;`onload` 描述符是否存在都不影响 |
|
|
73
|
+
| `onload` / `onerror` 可赋值(访问器或无描述符但可写) | 在定义 shim 访问器**之前**直接 `img.onload = forward` | 正常出图 |
|
|
74
|
+
| 只能读描述符、且不可赋值 | — | 走下一级 |
|
|
75
|
+
| 只有 `wx.getImageInfo` | `src` 赋值时调用 `getImageInfo({ src })` | **不出图**:`getImageInfo` 只解码元数据、不填充图片像素,合成 `load` 会让 three 上传空纹理,因此改为派发带 `reason` 的 `error` |
|
|
76
|
+
| 以上都没有 | 2s watchdog | 派发 `error`(`reason: 'image-events-timeout'`),不再静默挂到业务自己的超时 |
|
|
77
|
+
|
|
78
|
+
要点:
|
|
79
|
+
|
|
80
|
+
- 描述符不是唯一入口:有的宿主 `Object.getOwnPropertyDescriptor(img, 'onload')` 返回 `undefined`,但 `img.onload = fn` 仍然有效并能触发。
|
|
81
|
+
- `patchElement` 会覆盖 `addEventListener`,任何「用原生事件」的方案都必须在它之前保存引用,否则拿到的是 shim。
|
|
82
|
+
- `src` 同样可能只是可写数据属性。这种情况下 shim 访问器会吞掉写入,`image.ts` 会临时还原宿主属性写一次再装回访问器。
|
|
83
|
+
- `complete` 在 `load` 与 `error` 后都为 `true`,`decode()` 在 `error` 时 reject(与浏览器一致)。
|
|
84
|
+
- 退化路径的告警 payload 带宿主形状(`onload: 'missing' | 'data' | 'data-readonly' | 'accessor'`、`addEventListener`、`getImageInfo`、`ownNames`),可直接贴进 issue。
|
|
85
|
+
|
|
86
|
+
真机自证(避免把宿主问题误判成路径或打包问题):
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
const img = wx.createImage()
|
|
90
|
+
console.log({
|
|
91
|
+
ownOnload: Object.getOwnPropertyDescriptor(img, 'onload'),
|
|
92
|
+
hasAddEventListener: typeof img.addEventListener,
|
|
93
|
+
onloadType: typeof img.onload,
|
|
94
|
+
ownNames: Object.getOwnPropertyNames(img).slice(0, 16),
|
|
95
|
+
})
|
|
96
|
+
const probe = wx.createImage()
|
|
97
|
+
probe.onload = () => console.log('native onload fired')
|
|
98
|
+
probe.onerror = (e) => console.log('native error', e)
|
|
99
|
+
probe.src = 'textures/normal.png'
|
|
100
|
+
```
|
|
101
|
+
|
|
64
102
|
## 6.4 尺寸 / DPR / 安全区
|
|
65
103
|
|
|
66
104
|
- `windowInfo.pixelRatio = min(rawPixelRatio, pixelRatioCap)`,默认上限 2(避免 3~4 倍 DPR 造成 GPU 压力)。
|
|
@@ -218,7 +218,7 @@ Page({
|
|
|
218
218
|
| --- | --- | --- |
|
|
219
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
220
|
| `SyntaxError: Unexpected token '.'`,产物里出现 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
|
|
221
|
-
| 纹理永远加载不出来、`ImageLoader` 卡满超时;`img.onload` 与 `addEventListener('load')` 都不触发 | 图片 shim 没有把原生 `onload` 桥接到合成事件 |
|
|
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
222
|
| 纹理"加载成功"但画面无变化、法线 / 环境贴图不生效;`texture.image` 没有 `src` 也没有宽高 | 监听器里的 `this` 是内部事件载体,`ImageLoader` 把它当成 `<img>` 存进了 `Texture.source.data` | 升级适配层(0.1.3+)。若业务里自己写过 `image.inlineHost` 取真图,可以删掉 |
|
|
223
223
|
| `capabilities.webgl2 === false`,但 `#version 300 es` 能正常渲染 | 能力探测用了离屏画布,离屏与上屏能力不同 | 看 `capabilities.webgl2Source`:`'inferred'` 表示未实测;需要以实测为准时显式传 `capabilities: { webgl2: true }` |
|
|
224
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` 说明特性检测走了「非浏览器」分支,同样需要调整入口顺序 |
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
```bash
|
|
6
6
|
npm install # 安装依赖
|
|
7
7
|
npm run typecheck # tsc --noEmit(strict)
|
|
8
|
-
npm test # vitest run(
|
|
8
|
+
npm test # vitest run(79 例)
|
|
9
9
|
npm test -- --watch # 观察模式
|
|
10
10
|
npm run build # tsup:dist/*.js + *.d.ts + sourcemap
|
|
11
11
|
npm run check # typecheck + test + build
|
|
@@ -25,7 +25,7 @@ TMP="$PWD/.tmp/vitest" TEMP="$PWD/.tmp/vitest" npm test
|
|
|
25
25
|
| `tests/polyfills.test.ts` | EventTarget/once/remove、PointerEvent、Blob/URL/base64、URL 解析、TextEncoder、fetch、AbortController |
|
|
26
26
|
| `tests/runtime.test.ts` | 画布补丁、scope 隔离、上下文缓存、触摸桥、多指、installGlobals 可逆、resize/dispose、能力报告 |
|
|
27
27
|
| `tests/plugin.test.ts` | 资产扫描、未解析资源、模块过滤、WebGPU 告警、manifest 输出 |
|
|
28
|
-
| `tests/image-events.test.ts` |
|
|
28
|
+
| `tests/image-events.test.ts` | 图片事件宿主矩阵:可写描述符 / 仅原生 `addEventListener` / 仅 `wx.getImageInfo` / 三者皆无的 2s watchdog;`complete` 与 `decode()` 的成功/失败语义;`src` 为数据属性时的写入;终态只派发一次;告警去重与宿主形状 payload |
|
|
29
29
|
| `tests/event-dispatch.test.ts` | 监听器 `this`、`event.target` / `currentTarget` 指向宿主元素(含 three `ImageLoader` 取图场景)、`event.target` 不暴露内部监听表 |
|
|
30
30
|
| `tests/capabilities.test.ts` | 离屏优先 / 无离屏 API 时不兜底 / 主画布回退 / 无法探测返回 `undefined`、`webgl2Source` 三态、回退拿到任一候选上屏画布时按身份放弃(含宿主显式传 `canvas` 的组合) |
|
|
31
31
|
| `tests/scope.test.ts` | 未初始化占位作用域:环境全局读作 `undefined`、`typeof window.document` 不抛、真实 API 仍抛可读错误、早读被 `createRuntime()` 点名一次 |
|
|
@@ -90,13 +90,13 @@ jobs:
|
|
|
90
90
|
### 9.5.1 发布前检查
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
|
-
npm run check # typecheck +
|
|
93
|
+
npm run check # typecheck + 79 例测试 + tsup 构建
|
|
94
94
|
npm run release:check # npm pack --dry-run --json,看将要发布的文件清单
|
|
95
95
|
```
|
|
96
96
|
|
|
97
97
|
`package.json` 已配置 `prepublishOnly: "npm run clean && npm run check"`,`npm publish` 会自动清空 `dist/` 并跑一次完整构建与测试,既不会把未构建的产物发出去,也不会带入历史 hash chunk。发布前确认:
|
|
98
98
|
|
|
99
|
-
- `files` 白名单只包含 `dist/`、`README.md`、`AGENTS.md`、`llms.txt`、`docs/`(0.1.
|
|
99
|
+
- `files` 白名单只包含 `dist/`、`README.md`、`AGENTS.md`、`llms.txt`、`docs/`(0.1.5 实测 88 个文件、解包 945 KB、tarball 254 KB)。体积主要是 `docs/` 的 Markdown 与 `dist/` 的 `.d.ts`,两者都压缩率极高,tarball 增量很小。
|
|
100
100
|
- `exports` 里每个子路径的 `.js` 与 `.d.ts` 都存在。
|
|
101
101
|
- `CHANGELOG.md` 已补上本次版本条目。
|
|
102
102
|
- `docs/04-api-reference.md` 与 `package.json exports` 一致;`docs/03-module-map.md` 与文件树一致。
|
package/docs/11-compat-matrix.md
CHANGED
|
@@ -1,96 +1,100 @@
|
|
|
1
|
-
# 11 · 兼容矩阵
|
|
2
|
-
|
|
3
|
-
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
-
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
-
|
|
6
|
-
## 11.1 three.js 版本
|
|
7
|
-
|
|
8
|
-
| three 版本 | 状态 | 说明 |
|
|
9
|
-
| --- | --- | --- |
|
|
10
|
-
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
-
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
-
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
-
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
-
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
-
|
|
16
|
-
### 每次 three 升级需要复核的点
|
|
17
|
-
|
|
18
|
-
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
-
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
-
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
-
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
-
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
-
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
-
|
|
25
|
-
## 11.2 微信基础库 / 平台
|
|
26
|
-
|
|
27
|
-
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
-
| --- | --- | --- | --- |
|
|
29
|
-
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
-
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
-
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ | 离屏画布首选来源;**API 完全不存在时不做回退**,退回版本推断([ADR-0008](./adr/0008-probe-fallback-boundary.md)) |
|
|
32
|
-
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
-
| 回退探测与上屏画布的身份冲突 | — | ✅ | `probeContext` 接收 `reservedCanvases`(本次画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`),`createCanvas()` 返回其中任一对象即放弃、不 `getContext`(含宿主显式传 `canvas` 的窄口子) |
|
|
34
|
-
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
35
|
-
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
36
|
-
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
37
|
-
| `.wasm.br` Brotli | — | 🟡 | `assets.brotli: true` |
|
|
38
|
-
| Worker(分包) | 2.0.10 | 🟡 | 需 `wx.preDownloadSubpackage({packageType:'workers'})`;并发上限 1 |
|
|
39
|
-
| 分包加载 | 2.1.0 | 🟡 | `game.json` 建议由 manifest 生成 |
|
|
40
|
-
| iOS 高性能 / 高性能+ | 需后台开通 | 🟡 | `game.json` 的 `iOSHighPerformance` / `iOSHighPerformance+`;官方建议 WebGL2 场景开启高性能+ |
|
|
41
|
-
| `wx.triggerGC` | — | ✅ | 影响 image 创建路径判定 |
|
|
42
|
-
|
|
43
|
-
## 11.3 平台支持
|
|
44
|
-
|
|
45
|
-
| 平台 | 入口 | 状态 | 备注 |
|
|
46
|
-
| --- | --- | --- | --- |
|
|
47
|
-
| 微信小游戏 | `mini-three-adapter/wechat-game` | ✅ 单元级 | 自动订阅 `wx.onTouch*`;完整示例 |
|
|
48
|
-
| 微信小程序(`<canvas type="webgl2">`) | `mini-three-adapter/wechat-miniprogram` | 🟡 | 需 WXML 转发 `bindtouch*`;`selectorCtx` 传组件实例 |
|
|
49
|
-
| 浏览器 / H5 双端 | `mini-three-adapter/browser` | ✅ 单元级 | 真实 DOM 不被覆盖;可跑 Node 测试 |
|
|
50
|
-
| 其他小程序 / 小游戏平台 | 自定义 `PlatformBinding` | 🟡 框架就绪 | 按 [`docs/08`](./08-extension-guide.md#81-新增一个平台) 实现 |
|
|
51
|
-
| WebView 套壳 | 不在范围内 | ❌ | 本方案用于非 WebView 原生渲染 |
|
|
52
|
-
|
|
53
|
-
## 11.4 Web / DOM API 覆盖
|
|
54
|
-
|
|
55
|
-
| API | 提供方式 | 状态 |
|
|
56
|
-
| --- | --- | --- |
|
|
57
|
-
| `window` / `self` / `globalThis`(作用域内) | `MiniThreeScope` 自引用 | ✅ |
|
|
58
|
-
| `document.createElement('canvas' \| 'img')` | `createDocument` | ✅ |
|
|
59
|
-
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
60
|
-
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
61
|
-
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
62
|
-
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | `mini-three-blob:` → `data:` | ✅ |
|
|
63
|
-
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
64
|
-
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
65
|
-
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
66
|
-
| `requestAnimationFrame` / `cancelAnimationFrame` | `FrameScheduler` | ✅ |
|
|
67
|
-
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
68
|
-
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
69
|
-
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
70
|
-
| `
|
|
71
|
-
|
|
|
72
|
-
| `
|
|
73
|
-
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
1
|
+
# 11 · 兼容矩阵
|
|
2
|
+
|
|
3
|
+
> 状态说明:✅ 已验证 / 🟡 理论支持或单元测试覆盖,待真机 / ⚠️ 有限制 / ❌ 不支持。
|
|
4
|
+
> 每次发布前更新;真机验收清单见 [`docs/09`](./09-testing-and-release.md#97-真机验收清单发布前)。
|
|
5
|
+
|
|
6
|
+
## 11.1 three.js 版本
|
|
7
|
+
|
|
8
|
+
| three 版本 | 状态 | 说明 |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| `>= 0.163.0`(r163+) | ✅ 目标区间 | r163 起 `WebGLRenderer` 要求 WebGL2,与本适配层默认一致 |
|
|
11
|
+
| `0.187.0` | 🟡 单元级 | 2026-11-08 npm 最新版;已按 Migration Guide 检查 `three/addons`、`outputColorSpace`、`setAnimationLoop`;待真机全量回归 |
|
|
12
|
+
| `0.151.0 ~ 0.162.x` | ⚠️ | 未针对 WebGL1 路径做专门适配,建议升级到 r163+ |
|
|
13
|
+
| `< 0.151.0` | ❌ | 不提供保证 |
|
|
14
|
+
| `three/webgpu` + TSL / NodeMaterial | ❌ | 小游戏无 WebGPU;插件默认告警,可选 `webgpu:'rewrite'` 仅适用于纯 WebGLRenderer 的简单场景 |
|
|
15
|
+
|
|
16
|
+
### 每次 three 升级需要复核的点
|
|
17
|
+
|
|
18
|
+
1. `DEFAULT_GLOBAL_NAMES`(`src/build/scope-rewrite.ts`)是否覆盖新增浏览器全局。
|
|
19
|
+
2. `patchElement` / `patchCanvas`(`src/core/element.ts`、`canvas.ts`)是否覆盖新增 DOM 属性。
|
|
20
|
+
3. import 路径:`three/addons/*` 与旧 `three/examples/jsm/*` 都要在插件 include 规则里。
|
|
21
|
+
4. `RGBELoader → HDRLoader`、`EffectComposer → PostProcessing` 等破坏性改名(r180+)。
|
|
22
|
+
5. `three/webgpu` 使用比例上升时,插件 `webgpu` 默认策略是否需要调整。
|
|
23
|
+
6. 用 `examples/` 的三个平台工程对 controls / loaders / postprocessing 类别做增量回归。
|
|
24
|
+
|
|
25
|
+
## 11.2 微信基础库 / 平台
|
|
26
|
+
|
|
27
|
+
| 能力 | 最低基础库 | 状态 | 依据 / 处理 |
|
|
28
|
+
| --- | --- | --- | --- |
|
|
29
|
+
| `wx.createCanvas` / `getContext('webgl2')` | — | ✅ | [渲染文档](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html) |
|
|
30
|
+
| 唯一上屏画布规则 | — | ✅ | `getScreenCanvas()` 单次缓存 |
|
|
31
|
+
| `wx.createOffscreenCanvas` | 2.7.0(小程序)/ 小游戏同期 | ✅ | 离屏画布首选来源;**API 完全不存在时不做回退**,退回版本推断([ADR-0008](./adr/0008-probe-fallback-boundary.md)) |
|
|
32
|
+
| WebGL2 能力判定 | — | ✅ | 顺序:离屏实测 → 主画布实测 → 按基础库版本推断;`capabilities.webgl2Source` 标明来源,`'inferred'` 表示未实测 |
|
|
33
|
+
| 回退探测与上屏画布的身份冲突 | — | ✅ | `probeContext` 接收 `reservedCanvases`(本次画布 + 缓存画布 + `GameGlobal.screencanvas` + `globalThis.canvas`),`createCanvas()` 返回其中任一对象即放弃、不 `getContext`(含宿主显式传 `canvas` 的窄口子) |
|
|
34
|
+
| `wx.getWindowInfo` | 较新版本 | ✅ | 回退 `getSystemInfoSync` |
|
|
35
|
+
| `wx.onWindowResize` | — | 🟡 | 不可用时告警,需手动 `runtime.resize()` |
|
|
36
|
+
| `WXWebAssembly` | 2.13.0(Worker 内 2.15.0) | 🟡 | [官方文档](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html);插件按引用拷贝 wasm |
|
|
37
|
+
| `.wasm.br` Brotli | — | 🟡 | `assets.brotli: true` |
|
|
38
|
+
| Worker(分包) | 2.0.10 | 🟡 | 需 `wx.preDownloadSubpackage({packageType:'workers'})`;并发上限 1 |
|
|
39
|
+
| 分包加载 | 2.1.0 | 🟡 | `game.json` 建议由 manifest 生成 |
|
|
40
|
+
| iOS 高性能 / 高性能+ | 需后台开通 | 🟡 | `game.json` 的 `iOSHighPerformance` / `iOSHighPerformance+`;官方建议 WebGL2 场景开启高性能+ |
|
|
41
|
+
| `wx.triggerGC` | — | ✅ | 影响 image 创建路径判定 |
|
|
42
|
+
|
|
43
|
+
## 11.3 平台支持
|
|
44
|
+
|
|
45
|
+
| 平台 | 入口 | 状态 | 备注 |
|
|
46
|
+
| --- | --- | --- | --- |
|
|
47
|
+
| 微信小游戏 | `mini-three-adapter/wechat-game` | ✅ 单元级 | 自动订阅 `wx.onTouch*`;完整示例 |
|
|
48
|
+
| 微信小程序(`<canvas type="webgl2">`) | `mini-three-adapter/wechat-miniprogram` | 🟡 | 需 WXML 转发 `bindtouch*`;`selectorCtx` 传组件实例 |
|
|
49
|
+
| 浏览器 / H5 双端 | `mini-three-adapter/browser` | ✅ 单元级 | 真实 DOM 不被覆盖;可跑 Node 测试 |
|
|
50
|
+
| 其他小程序 / 小游戏平台 | 自定义 `PlatformBinding` | 🟡 框架就绪 | 按 [`docs/08`](./08-extension-guide.md#81-新增一个平台) 实现 |
|
|
51
|
+
| WebView 套壳 | 不在范围内 | ❌ | 本方案用于非 WebView 原生渲染 |
|
|
52
|
+
|
|
53
|
+
## 11.4 Web / DOM API 覆盖
|
|
54
|
+
|
|
55
|
+
| API | 提供方式 | 状态 |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| `window` / `self` / `globalThis`(作用域内) | `MiniThreeScope` 自引用 | ✅ |
|
|
58
|
+
| `document.createElement('canvas' \| 'img')` | `createDocument` | ✅ |
|
|
59
|
+
| `document.createElementNS` / `body` / `visibilityState` | `createDocument` | ✅ |
|
|
60
|
+
| `HTMLCanvasElement` / `HTMLImageElement` / `HTMLElement` / `OffscreenCanvas` / `ImageData` / `DOMRect` 的 `instanceof` | `Symbol.hasInstance` 注册表 | ✅ |
|
|
61
|
+
| `Event` / `EventTarget` / `CustomEvent` / `PointerEvent` / `MouseEvent` / `MessageEvent` / `ProgressEvent` | `polyfills/event.ts` | ✅ |
|
|
62
|
+
| `Blob` / `URL.createObjectURL` / `URL.revokeObjectURL` | `mini-three-blob:` → `data:` | ✅ |
|
|
63
|
+
| `URL` 构造 / 相对路径解析 | `MiniURL` | ✅ |
|
|
64
|
+
| `TextEncoder` / `TextDecoder` / `atob` / `btoa` | `polyfills/text-encoding.ts` | ✅ |
|
|
65
|
+
| `fetch` / `XMLHttpRequest` / `AbortController` | `wx.request` 桥接 | 🟡 单元级,真机网络待验证 |
|
|
66
|
+
| `requestAnimationFrame` / `cancelAnimationFrame` | `FrameScheduler` | ✅ |
|
|
67
|
+
| `performance.now` | `wx.getPerformance` → `Date.now` 回退 | ✅ |
|
|
68
|
+
| `getComputedStyle` / `matchMedia` / `screen` / `navigator` | 轻量模拟 | ⚠️ 仅够 three 使用,非完整实现 |
|
|
69
|
+
| `createImageBitmap` | **故意为 `undefined`** | ✅ 让 three 走降级分支 |
|
|
70
|
+
| 图片原生事件(`img.onload` / `addEventListener('load')` / `decode()`) | 三级桥接:原生 `addEventListener` → `onload` 赋值 → `wx.getImageInfo` 诊断 | 🟡 模拟器与单元测试通过;真机宿主形态差异大,见 `docs/06` §6.3 |
|
|
71
|
+
| 纹理格式 | PNG / JPEG | ✅ WebP 在部分真机解码失败,见 §11.6 |
|
|
72
|
+
| `FileReader` / `WebSocket` / `AudioContext` | 缺省或透传 | ⚠️ 业务需要时按 `docs/08` 扩展 |
|
|
73
|
+
| `Worker` / `WebAssembly` | 透传宿主全局(`WXWebAssembly`) | 🟡 |
|
|
74
|
+
| `ResizeObserver` | no-op | ⚠️ |
|
|
75
|
+
| 完整 DOM(布局、CSS、事件冒泡树) | 不提供 | ❌ 超出范围 |
|
|
76
|
+
|
|
77
|
+
## 11.5 场景回归记录
|
|
78
|
+
|
|
79
|
+
以 three 官方示例场景为主体建立回归集,用 `examples/` 的三个平台工程逐一接入验证。
|
|
80
|
+
|
|
81
|
+
| 类别 | 覆盖目标 | 状态 | 备注 |
|
|
82
|
+
| --- | --- | --- | --- |
|
|
83
|
+
| `controls_*` | OrbitControls / TrackballControls / TransformControls 的多指交互 | ⬜ 未回归 | 优先验证 pointerId、capture、`pointercancel` |
|
|
84
|
+
| `loader_*` | GLTF / DRACO / KTX2 / OBJ / FBX | ⬜ 未回归 | 需配置 decoder 路径与分包 |
|
|
85
|
+
| `postprocessing_*` | EffectComposer / bloom / SSAO | ⬜ 未回归 | 注意深度缓冲与 render target 尺寸 |
|
|
86
|
+
| `animation_*` / `physics_*` | 骨骼动画 / wasm 物理 | ⬜ 未回归 | 涉及 wasm 资源预下载 |
|
|
87
|
+
| 基础渲染 | `examples/wechat-minigame`、`wechat-miniprogram`、`h5` | ✅ 单元级 | 79 个 Vitest 用例覆盖画布、事件、作用域、插件 |
|
|
88
|
+
|
|
89
|
+
每回归一条,在本表追加:`场景 id | three 版本 | 基础库 | 设备 | 结果 | 失败原因 | 新增 polyfill`。
|
|
90
|
+
|
|
91
|
+
## 11.6 已知限制汇总
|
|
92
|
+
|
|
93
|
+
1. 不模拟 WebGPU;`three/webgpu` 项目需改用 WebGL 构建目标。
|
|
94
|
+
2. `createImageBitmap` 恒为 `undefined`,依赖该 API 的库需自带降级。
|
|
95
|
+
3. 不提供完整 DOM;DOM 密集型 UI 库应走 WebView 方案。
|
|
96
|
+
4. 插件默认只改写 `node_modules` 中的三方生态代码;应用代码里直接写 `window` 不会自动改写(可开 `includeUserCode`)。
|
|
97
|
+
5. 对象 URL 是 `mini-three-blob:` + `data:`,不是浏览器 `blob:`;若有库硬编码 `blob:` 前缀判断,需要适配。
|
|
98
|
+
6. Worker 分包、`.wasm.br`、iOS 高性能+ 需业务按 `mini-three-assets.json` 的 `gameJsonSuggestion` 自行配置,插件不直接改 `game.json`。
|
|
99
|
+
7. 纹理请使用 PNG / JPEG。**WebP 在部分真机上无法解码**(`wx.createImage` 直接触发 `error`),这与适配层无关;`mini-three-adapter` 只会在 `wx.getImageInfo` 失败时给出指向格式的告警。
|
|
100
|
+
8. 图片事件桥接需要宿主提供至少一个入口(原生 `addEventListener`、可写的 `onload`/`onerror`,或 `wx.getImageInfo`)。三者都不存在的宿主只能快速失败:2s 内派发 `error`,无法出图。
|
package/llms.txt
CHANGED
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
- [tests/scope-rewrite.test.ts](./tests/scope-rewrite.test.ts): AST correctness.
|
|
60
60
|
- [tests/polyfills.test.ts](./tests/polyfills.test.ts): event/blob/url/network.
|
|
61
61
|
- [tests/plugin.test.ts](./tests/plugin.test.ts): plugin and assets.
|
|
62
|
-
- [tests/image-events.test.ts](./tests/image-events.test.ts):
|
|
62
|
+
- [tests/image-events.test.ts](./tests/image-events.test.ts): host matrix for the image event bridge (native addEventListener / assignable onload / getImageInfo-only / watchdog), complete + decode semantics.
|
|
63
63
|
- [tests/event-dispatch.test.ts](./tests/event-dispatch.test.ts): listener `this` / event.target / currentTarget resolve to the host element.
|
|
64
64
|
- [tests/capabilities.test.ts](./tests/capabilities.test.ts): context probing fallback, screen-canvas identity guard (candidate set), webgl2Source.
|
|
65
65
|
- [tests/scope.test.ts](./tests/scope.test.ts): placeholder scope before a runtime (environment globals read as undefined, early-read reporting).
|
package/package.json
CHANGED