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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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);
}
}