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.

6.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    WasmBridge.ts
 * @brief   Single base class for every SDK→WASM subsystem bridge.
 *
 * @details The SDK historically reached into the WASM module five different
 *          ways (a class wrapper for ECS, six global-singleton init/shutdown
 *          modules, and per-subsystem typed interfaces for physics/spine/
 *          tilemap/timeline). Each reinvented its own loader, ready state,
 *          missing-binding policy, and — critically — its own error handling,
 *          so only the ECS bridge ({@link ./ecs/BuiltinBridge}) honoured the
 *          terminal-abort guard. physics/spine/timeline called straight into a
 *          possibly-dead module.
 *
 *          `WasmBridge` is the single channel. A subsystem connects its module
 *          here once; the base installs the abort guard (see moduleHealth.ts)
 *          and hands back a guarded view of the module in which EVERY function
 *          call short-circuits with {@link WasmModuleAborted} after an abort
 *          instead of touching a corpse. Existing call sites are unchanged:
 *          `bridge.module` has the same type as the raw module, so the guard is
 *          transparent.
 *
 *          The guarded view passes through, unguarded:
 *            - non-function properties (HEAP* views, constants) — read live so
 *              they stay valid across ALLOW_MEMORY_GROWTH heap replacement;
 *            - `_malloc`/`_free` — allocator infrastructure that
 *              {@link ./wasmScratch withScratch} must still be able to call in
 *              its `finally` after an abort, so re-guarding them would mask the
 *              original error.
 */

import {
    installAbortGuard,
    isModuleAborted,
    throwIfModuleAborted,
    WasmModuleAborted,
} from './moduleHealth';

/** Properties that must reach the raw module untouched (allocator infra). */
function isAllocatorProp(prop: PropertyKey): boolean {
    return prop === '_malloc' || prop === '_free';
}

/**
 * Base class for a subsystem's bridge to its WASM module.
 *
 * @typeParam M - the module's call-surface type (e.g. `PhysicsWasmModule`).
 *
 * Subclasses only declare a {@link label} for diagnostics:
 * ```ts
 * export class PhysicsBridge extends WasmBridge<PhysicsWasmModule> {
 *     protected readonly label = 'physics';
 * }
 * ```
 */
export abstract class WasmBridge<M extends object> {
    /** Short subsystem name used in {@link WasmModuleAborted} diagnostics. */
    protected abstract readonly label: string;

    private raw_: M | null = null;
    private guarded_: M | null = null;
    /**
     * The module whose `onAbort`/dead-flag is authoritative. For a standalone
     * module (its own emscripten runtime, e.g. the shipped physics module) this
     * is the module itself. For a side module that shares the main module's
     * heap, pass the main module as `healthModule` — that is where emscripten
     * fires `onAbort` and where the dead flag must be read.
     */
    private health_: object | null = null;

    /**
     * Bind this bridge to a freshly-loaded module. Installs the terminal-abort
     * guard and builds the guarded view. Calling again rebinds to a new module.
     *
     * @param module        the module call surface used by `bridge.module`.
     * @param healthModule   the abort-authoritative module; defaults to `module`.
     */
    connect(module: M, healthModule: object = module): void {
        this.raw_ = module;
        this.health_ = healthModule;
        installAbortGuard(healthModule);
        this.guarded_ = this.makeGuarded_(module, healthModule);
    }

    /** Unbind. Subsequent `module` access throws until reconnected. */
    disconnect(): void {
        this.raw_ = null;
        this.guarded_ = null;
        this.health_ = null;
    }

    /** True once {@link connect} has run and before {@link disconnect}. */
    get connected(): boolean {
        return this.raw_ !== null;
    }

    /**
     * The guarded module. Every function call is gated through the abort guard;
     * HEAP views, constants, and `_malloc`/`_free` pass through to the live
     * module. Same static type as the raw module, so call sites are unchanged.
     *
     * @throws if the bridge is not connected.
     */
    get module(): M {
        if (!this.guarded_) {
            throw new Error(`${this.label} bridge is not connected to a WASM module`);
        }
        return this.guarded_;
    }

    /**
     * The unguarded module, or null if not connected. Prefer {@link module};
     * reach for `raw` only when the guard is provably unwanted (it almost never
     * is — `_malloc`/`_free` and HEAP views already pass through `module`).
     */
    get raw(): M | null {
        return this.raw_;
    }

    private makeGuarded_(module: M, health: object): M {
        const label = this.label;
        // One wrapper per accessed function, built lazily and reused, so the
        // steady-state cost is a proxy get + Map lookup rather than a fresh
        // closure per call.
        const wrappers = new Map<PropertyKey, (...args: unknown[]) => unknown>();

        return new Proxy(module, {
            get(target, prop): unknown {
                // Read with `target` as receiver so any getter (e.g. a side
                // module's HEAPF32 proxy getter) resolves against the module.
                const value = Reflect.get(target, prop, target);
                if (typeof value !== 'function' || isAllocatorProp(prop)) {
                    return value;
                }
                let wrapped = wrappers.get(prop);
                if (!wrapped) {
                    const fn = value as (...args: unknown[]) => unknown;
                    const op = `${label}.${typeof prop === 'string' ? prop : String(prop)}`;
                    wrapped = (...args: unknown[]): unknown => {
                        // Pre-check: never enter a dead module.
                        throwIfModuleAborted(health, op);
                        try {
                            return fn.apply(target, args);
                        } catch (err) {
                            // If THIS call aborted the module, surface it as the
                            // terminal error rather than letting the corpse's
                            // return value (undefined memory) propagate.
                            if (isModuleAborted(health)) {
                                throw new WasmModuleAborted(op, undefined, err);
                            }
                            throw err;
                        }
                    };
                    wrappers.set(prop, wrapped);
                }
                return wrapped;
            },
        }) as M;
    }
}