Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

refactor(sdk): guard the C++ ResourceManager via WasmBridge (F2 closure)

esenginecc67505e2b72
diff --git a/docs/REARCH_FOUNDATION_CONSOLIDATION.md b/docs/REARCH_FOUNDATION_CONSOLIDATION.md
index 8e62dfb0e..daafeda51 100644
--- a/docs/REARCH_FOUNDATION_CONSOLIDATION.md
+++ b/docs/REARCH_FOUNDATION_CONSOLIDATION.md
@@ -59,7 +59,7 @@ RC1–RC5 坍缩了五个正确性根因,但留下四处"半成品 / 未统一
- **迁移方式**:每个子系统在其 init/connect 接缝处把存储的 module 引用替换为 `bridge.module`,**数百个调用点零改动**继承守卫。
- **覆盖**:abort 守卫从"仅主模块经 BuiltinBridge"扩展到 physics / spine / tilemap / timeline / ui / 六个 core facet **全覆盖**——补全 RC3 空洞。
- **验证**:29 个新测试(wasm-bridge 12 / spine-bridge 7 / core-bridge 4 / timeline-tilemap-ui 6);typecheck 通过;全量 SDK 套件 **2052 通过 / 0 失败**。
-- **待闭环**:`ResourceManager`(经 `module.getResourceManager()` 的 embind 对象,非文档点名的 5 套之一)尚未经守卫——作为小后续。`Camera` 的 module 触点归 F3。
+- **`ResourceManager` 闭环 — ✅**:embind RM 对象经 `WasmBridge`(health=主模块)守卫,`initResourceManager(rm, module)` 接缝路由;测试路径(无 module)保持 raw 向后兼容。至此 SDK 全部 WASM 调用面均经守卫。`Camera` 的 module 触点归 F3。
---
diff --git a/sdk/src/corePlugin.ts b/sdk/src/corePlugin.ts
index f5aeb408e..07c547415 100644
--- a/sdk/src/corePlugin.ts
+++ b/sdk/src/corePlugin.ts
@@ -14,7 +14,7 @@ export const corePlugin: Plugin = {
build(app) {
const module = app.wasmModule!;
- initResourceManager(module.getResourceManager());
+ initResourceManager(module.getResourceManager(), module);
initDrawAPI(module);
initGeometryAPI(module);
initMaterialAPI(module);
diff --git a/sdk/src/resourceManager.ts b/sdk/src/resourceManager.ts
index c00488842..be11ff080 100644
--- a/sdk/src/resourceManager.ts
+++ b/sdk/src/resourceManager.ts
@@ -1,19 +1,41 @@
-import type { CppResourceManager } from './wasm';
+import type { CppResourceManager, ESEngineModule } from './wasm';
+import { WasmBridge } from './WasmBridge';
export interface TextureDimensions {
width: number;
height: number;
}
+/**
+ * The C++ ResourceManager is an embind object reached via
+ * `module.getResourceManager()`, not a module itself — it owns no heap or
+ * onAbort. Guard its method calls with the main module as the abort authority
+ * (proxying the embind instance is safe: methods are invoked with the real
+ * instance as `this`, and HEAP/$$ pass straight through).
+ */
+class ResourceManagerBridge extends WasmBridge<CppResourceManager> {
+ protected readonly label = 'resourceManager';
+}
+
+const bridge = new ResourceManagerBridge();
let rm_: CppResourceManager | null = null;
const dimsCache_ = new Map<number, TextureDimensions>();
-export function initResourceManager(rm: CppResourceManager): void {
- rm_ = rm;
+export function initResourceManager(rm: CppResourceManager, module?: ESEngineModule): void {
+ // Production (corePlugin) passes the main module → guarded calls. Tests pass
+ // only a mock rm → kept raw (unguarded), since they don't exercise abort.
+ if (module) {
+ bridge.connect(rm, module);
+ rm_ = bridge.module;
+ } else {
+ bridge.disconnect();
+ rm_ = rm;
+ }
dimsCache_.clear();
}
export function shutdownResourceManager(): void {
+ bridge.disconnect();
rm_ = null;
dimsCache_.clear();
}
diff --git a/sdk/tests/resourcemanager-bridge.test.ts b/sdk/tests/resourcemanager-bridge.test.ts
new file mode 100644
index 000000000..e17c336cc
--- /dev/null
+++ b/sdk/tests/resourcemanager-bridge.test.ts
@@ -0,0 +1,50 @@
+/**
+ * @file resourcemanager-bridge.test.ts
+ * @brief The C++ ResourceManager embind object is guarded via WasmBridge with
+ * the main module as abort authority. Closes the last un-guarded WASM
+ * touchpoint after the F2 five-pattern unification.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { WasmModuleAborted } from '../src/moduleHealth';
+import {
+ initResourceManager, shutdownResourceManager,
+ requireResourceManager, getResourceManager,
+} from '../src/resourceManager';
+import type { CppResourceManager, ESEngineModule } from '../src/wasm';
+
+function makeRm() {
+ return {
+ getTextureDimensions: vi.fn((h: number) => ({ width: h, height: h })),
+ } as unknown as CppResourceManager;
+}
+function makeModule(): ESEngineModule {
+ return { onAbort: undefined } as unknown as ESEngineModule;
+}
+
+describe('ResourceManager bridge', () => {
+ afterEach(() => shutdownResourceManager());
+
+ it('guards rm methods when the module is provided (production path)', () => {
+ const rm = makeRm();
+ const m = makeModule();
+ initResourceManager(rm, m);
+
+ expect(requireResourceManager().getTextureDimensions(4)).toEqual({ width: 4, height: 4 });
+
+ (m as unknown as { onAbort: (w: unknown) => void }).onAbort('oom');
+ let caught: unknown;
+ try { requireResourceManager().getTextureDimensions(8); } catch (e) { caught = e; }
+ expect(caught).toBeInstanceOf(WasmModuleAborted);
+ expect((caught as WasmModuleAborted).context).toBe('resourceManager.getTextureDimensions');
+ // the dead module was not called for handle 8
+ expect((rm as unknown as { getTextureDimensions: ReturnType<typeof vi.fn> })
+ .getTextureDimensions).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps the raw rm when no module is passed (test/back-compat path)', () => {
+ const rm = makeRm();
+ initResourceManager(rm);
+ // identity preserved — embind object not wrapped
+ expect(getResourceManager()).toBe(rm);
+ });
+});