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.

11.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    host.ts
 * @brief   The realm-agnostic acquirer for optional native modules.
 *
 * @details One {@link SideModuleHost} per realm answers "give me module X for
 *          this realm", caching the result so repeat callers (e.g. several spine
 *          entities of the same version) share one instance. The host is pure
 *          orchestration: id → descriptor lookup + cache. The realm supplies the
 *          *transport* as an {@link SideModuleInstantiator}; the fetch / embedded
 *          / WeChat transports live in sibling files.
 */
import { log } from '../util/logger';
import { SIDE_MODULES, sideModuleDescriptor, type SideModuleDescriptor, type SideModuleId } from './registry';

/** The instantiated emscripten module. Consumers cwrap their own `_*` exports. */
export type SideModule = Record<string, unknown>;

/** Realm-agnostic acquirer for optional native modules. */
export interface SideModuleHost {
    /** Instantiate `id` for this realm (cached); null if unavailable or it failed. */
    acquire(id: SideModuleId): Promise<SideModule | null>;
    /** The glue and binary `id` is instantiated from, for a worker to instantiate
     *  its own copy; absent where the realm has none to hand over. */
    source?(id: SideModuleId): Promise<SideModuleSource | null>;
    /**
     * Tie something to this host's life: a pool of workers that each instantiated
     * one of its modules. `release` runs once, when the host is disposed — or at
     * once, if it already has been.
     */
    onDispose?(release: () => void): void;
    /**
     * Let go of everything the host holds: the instances it cached and whatever
     * was tied to it. Whoever made the host calls this when the realm it served
     * is over; an App does it on quit for a host it created itself. Idempotent,
     * and a disposed host answers every later `acquire` with null.
     *
     * Nothing else ends these. A worker is never collected while it runs, and
     * each one holds a WebAssembly memory, so a host dropped without this leaks
     * them for as long as the page lives.
     */
    dispose?(): void;
}

export interface SideModuleSource {
    readonly glueText: string;
    /** The global the glue defines its factory as. */
    readonly globalName: string;
    readonly wasmBytes: ArrayBuffer;
}

/** A realm's transport: turn a descriptor into an instantiated module. */
export type SideModuleInstantiator = (descriptor: SideModuleDescriptor, id: SideModuleId) => Promise<SideModule>;

/**
 * Thrown by a transport for a module its realm was never built to carry, rather
 * than one that should be there and would not load. A native host decodes KTX2 in
 * C++ and so has no `basis` to give — reported as a failure, that made every game
 * with a Spine atlas read as a broken boot.
 */
export class SideModuleAbsent extends Error {
    constructor(id: SideModuleId, why: string) {
        super(`"${id}" is not part of this realm — ${why}`);
        this.name = 'SideModuleAbsent';
    }
}

/**
 * Build a host over a transport. Caches per id (including failures-as-null so a
 * missing artifact isn't refetched every frame). The transport is the only
 * realm-specific part; everything above it — gating, plugin install — is shared.
 */
export interface SideModuleHostOptions {
    /**
     * The transport instantiates a WebAssembly binary through the realm's own
     * `WebAssembly` (the web's fetch and embedded hosts). A native host links its
     * modules in C++, and a mini-game host instantiates through the vendor's
     * WXWebAssembly, so neither needs the global, and iOS (QuickJS) and WeChat have
     * none: asking every host for it turned off physics, Spine and DragonBones on
     * every iOS build.
     */
    requiresWebAssembly?: boolean;
}

export function createSideModuleHost(instantiate: SideModuleInstantiator, options: SideModuleHostOptions = {}): SideModuleHost {
    const cache = new Map<SideModuleId, Promise<SideModule | null>>();
    const releases: Array<() => void> = [];
    let disposed = false;
    const run = (release: () => void): void => {
        try { release(); } catch (e) { log.warn('sidemodule', 'a release tied to the module host failed', e); }
    };
    return {
        onDispose(release: () => void): void {
            if (disposed) run(release);
            else releases.push(release);
        },
        dispose(): void {
            if (disposed) return;
            disposed = true;
            // Last tied, first released: what was built on a module goes before the module's own entry.
            for (const release of releases.splice(0).reverse()) run(release);
            cache.clear();
        },
        acquire(id: SideModuleId): Promise<SideModule | null> {
            if (disposed) return Promise.resolve(null);
            const cached = cache.get(id);
            if (cached) return cached;
            const descriptor = sideModuleDescriptor(id);
            // On the web a side module is a WebAssembly binary; a page with none runs
            // the engine's JavaScript build, which carries the core and nothing beside
            // it. Said once, by name, instead of "WebAssembly is not defined".
            if (descriptor && options.requiresWebAssembly && typeof WebAssembly === 'undefined') {
                log.error('sidemodule', `"${id}" is a WebAssembly module and this host has no WebAssembly: `
                    + 'the engine runs as JavaScript here, and the features it provides are unavailable');
                const none = Promise.resolve(null);
                cache.set(id, none);
                return none;
            }
            const pending: Promise<SideModule | null> = descriptor
                ? instantiate(descriptor, id).catch((e: unknown) => {
                      // Absent BY DESIGN is the answer null already means; only a
                      // module that was meant to be here is a failure to report.
                      if (e instanceof SideModuleAbsent) log.info('sidemodule', e.message);
                      else log.error('sidemodule', `failed to load "${id}" (${descriptor.file}) — ${howToFix(id, e)}`, e);
                      return null;
                  })
                // Unknown ids used to be impossible (the type was closed) and so
                // returned null in silence. Now that a project can name its own,
                // silence is how a typo becomes "this runtime just doesn't work".
                : (log.warn('sidemodule', `no module named "${id}" is registered — a built-in id, or one `
                    + 'declared in .esengine/modules/<id>/module.json and picked up by the export'),
                   Promise.resolve(null));
            cache.set(id, pending);
            return pending;
        },
    };
}

/** The engine refused the memory: the artifact was found and compiled, so this is not a missing build. */
export function isOutOfWasmMemory(error: unknown): boolean {
    const message = error instanceof Error ? error.message : String(error);
    return /out of memory|cannot allocate wasm memory/i.test(message);
}

/**
 * What to do about a module that would not load, which differs by who built it.
 *
 * For an engine module a 404 is almost always a missing local build artifact, so
 * the advice is the build command. For a project's own module the engine has no
 * idea how it is produced — pointing someone at `pnpm build -t rive` would be a
 * command that does not exist — so it says where the export looked instead.
 *
 * Neither applies when the process had no WebAssembly memory left to give: the
 * module is there, and telling someone to rebuild it sends them the wrong way.
 */
function howToFix(id: SideModuleId, error: unknown): string {
    if (isOutOfWasmMemory(error)) {
        return 'the module is present, but this process has no WebAssembly memory left to start it: '
            + 'something is holding earlier instances (in the editor, restart it and report this)';
    }
    if (id in SIDE_MODULES) {
        return 'likely not built locally: run the matching wasm build (spine 4.2 = '
            + '`pnpm build -t spine`, others match their file name, `-t all` builds '
            + 'everything), then rebuild the editor';
    }
    return `this is a project module: check that .esengine/modules/${id}/ carries a build for `
        + 'this platform, and that the export staged it';
}

/** A factory produced by an emscripten `MODULARIZE` glue. */
export type EmscriptenFactory = (opts: Record<string, unknown>) => Promise<SideModule>;

/**
 * Run an emscripten module factory, handing it the wasm bytes through
 * `instantiateWasm` so the glue never fetches anything itself (the byte source
 * is the realm's concern, already resolved by the caller). emscripten's
 * `instantiateWasm` has no failure channel — a failed async instantiation just
 * never calls back and the factory promise hangs forever — so we race it against
 * a reject gate and surface the error instead.
 */
export function instantiateWithBytes(
    factory: EmscriptenFactory,
    wasmBytes: ArrayBuffer,
    extraOpts: Record<string, unknown> = {},
): Promise<SideModule> {
    let rejectOnError: (e: unknown) => void = () => {};
    const errorGate = new Promise<never>((_, reject) => {
        rejectOnError = reject;
    });
    const opts: Record<string, unknown> = {
        ...extraOpts,
        instantiateWasm(imports: WebAssembly.Imports, cb: (inst: WebAssembly.Instance, mod?: WebAssembly.Module) => void) {
            WebAssembly.instantiate(wasmBytes, imports).then(
                (r) => cb(r.instance, r.module),
                (e) => rejectOnError(e),
            );
            return {};
        },
    };
    return Promise.race([factory(opts), errorGate]);
}

/**
 * Resolve the module factory out of emscripten glue *text* and instantiate it
 * with `wasmBytes`. Browser realms (fetch + embedded) share this: the glue is
 * run as an ES module via a blob URL (its own scope, no global leakage). A glue
 * with `EXPORT_ES6` exposes the factory as `default`; a `MODULARIZE` glue with a
 * named `EXPORT_NAME` (spine) leaves it module-scoped, so the descriptor's
 * `globalName` tells us to hoist it onto `globalThis` for one tick to retrieve it.
 */
export async function instantiateFromGlueText(
    glueText: string,
    wasmBytes: ArrayBuffer,
    descriptor: SideModuleDescriptor,
): Promise<SideModule> {
    const factory = await resolveFactory(glueText, descriptor);
    if (typeof factory !== 'function') {
        throw new Error(`side module "${descriptor.file}": glue exposed no factory`);
    }
    return instantiateWithBytes(factory as EmscriptenFactory, wasmBytes);
}

const HOIST_KEY = '__es_side_module_factory__';

async function resolveFactory(glueText: string, descriptor: SideModuleDescriptor): Promise<unknown> {
    const g = globalThis as Record<string, unknown>;
    const source = descriptor.globalName
        ? `${glueText};globalThis[${JSON.stringify(HOIST_KEY)}]=${descriptor.globalName};`
        : glueText;
    const url = URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
    try {
        const mod = (await import(/* @vite-ignore */ /* webpackIgnore: true */ url)) as { default?: unknown };
        if (descriptor.globalName) {
            const factory = g[HOIST_KEY];
            delete g[HOIST_KEY];
            return factory;
        }
        return mod.default;
    } finally {
        URL.revokeObjectURL(url);
    }
}