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 miniGameRuntime.ts
* @brief Boot for the mini-game platform family — the shipped package's entry
* point on WeChat, Douyin, or a vendor a game brought itself.
*
* Everything here is written against the platform seam, never a vendor
* global: the display canvas and its size come from the family adapter
* (`createScreenCanvas`), the wasm binary through `instantiateWasm`
* (where the one genuine per-vendor divergence lives), scenes through
* `platformReadTextFile`. So a new vendor boots on this file unchanged
* — {@link initWeChatRuntime} is nothing but this function with
* WeChat's staged wasm name filled in.
*/
import { createWebApp } from './webAppFactory';
import { bootPercent, bootSays, type BootStage } from './bootStages';
import type { ESEngineModule } from '../wasm';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
import { initRuntime } from './runtimeLoader';
import type { ThemeOverrides } from '../ui';
import { applyBuildRuntimeConfig, type RuntimeBuildConfig } from '../defaults';
import { getPlatform, platformReadTextFile, platformInstantiateWasm } from '../platform';
import { MiniGamePlatformAdapter } from '../platform/minigame';
import {
loadPackagedAssetIndex, createPackagedAssetSource, applyAssetRefResolvers,
registerPackagedSideModules, glContextAttributes,
} from './packagedRuntime';
import { createMiniGameSideModuleHost, type MiniGameSideModuleFactories } from '../sideModules';
import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { SceneData } from '../scene/scene';
import type { AotManifest } from '../ecs/aot/AotSystems';
import { startDebugChannel } from './debugChannelHook';
import type { DebugChannelConfig } from './debugChannelProtocol';
import type { PackagedGameConfig } from './packagedRuntime';
import { log } from '../util/logger';
import { Schedule, defineSystem } from '../ecs/system';
import type { App } from '../app/app';
import type { Physics3DBackend } from '../sideModules/registry';
import type { Physics3DWorldConfig } from '../physics3d/worldConfig';
// =============================================================================
// Emscripten WASM Instantiation
// =============================================================================
function createWasmInstantiator(wasmPath: string, tag: string, onError?: (e: unknown) => void) {
return (imports: WebAssembly.Imports, successCallback: Function) => {
platformInstantiateWasm(wasmPath, imports).then((result) => {
successCallback(result.instance, result.module);
}).catch((e) => {
log.error(tag, `WASM instantiation failed: ${describeError(e)}`);
// emscripten's instantiateWasm has no failure channel: on a failed
// async instantiation successCallback is never called and the factory
// promise hangs forever. Surface the error so the caller can reject.
onError?.(e);
});
return {};
};
}
/**
* WebGL1 extensions WebGL2 made core. Emscripten asks for each unconditionally and
* swaps the context's own methods for any that answers; vivo's WebGL2 context
* answers OES_vertex_array_object and then hangs the first createVertexArray.
* Withheld, as the spec already says a WebGL2 context must.
*/
const CORE_IN_WEBGL2 = new Set(['OES_vertex_array_object', 'ANGLE_instanced_arrays', 'WEBGL_draw_buffers']);
export function hideCoreExtensions(gl: WebGLRenderingContext): void {
const getExtension = gl.getExtension.bind(gl);
(gl as { getExtension: (name: string) => unknown }).getExtension =
(name: string) => (CORE_IN_WEBGL2.has(name) ? null : getExtension(name));
}
/** A mini-game console prints a thrown object as `[object Object]`, so the one
* line a device gives you says nothing unless it is made into text here. */
function describeError(e: unknown): string {
if (e instanceof Error) return `${e.name}: ${e.message}`;
if (e && typeof e === 'object') {
const o = e as { message?: unknown; errMsg?: unknown };
if (typeof o.message === 'string') return o.message;
if (typeof o.errMsg === 'string') return o.errMsg;
try { return JSON.stringify(e); } catch { /* fall through */ }
}
return String(e);
}
// Wraps an emscripten module factory so an async instantiateWasm failure rejects
// the returned promise instead of hanging the module load indefinitely.
function instantiateModule<T>(
factory: (opts: unknown) => Promise<T>,
wasmPath: string,
tag: string,
extraOpts: Record<string, unknown> = {},
): Promise<T> {
let rejectOnError: (e: unknown) => void = () => {};
const errorGate = new Promise<never>((_, reject) => { rejectOnError = reject; });
const modulePromise = factory({
...extraOpts,
instantiateWasm: createWasmInstantiator(wasmPath, tag, rejectOnError),
});
return Promise.race([modulePromise, errorGate]);
}
// =============================================================================
// Public API
// =============================================================================
export interface MiniGameRuntimeConfig {
engineFactory: (opts: unknown) => Promise<ESEngineModule>;
/** Package-relative path of the engine wasm binary. The exporter stages the
* runtime under wasm/ and knows which glue it shipped, so it passes the
* glue's `.wasm` twin here. */
engineWasmPath: string;
sceneNames: string[];
firstScene: string;
runtimeConfig?: RuntimeBuildConfig;
/** The project's runtime tuning (Project Settings → Game → Runtime), applied by `initRuntime` before anything loads. */
runtime?: RuntimeBuildConfig;
/** Install physics even when the scene shows no bodies — a project that
* spawns them from script (Project Settings → Physics → Enabled). */
physicsEnabled?: boolean;
/** The physics world the project declared: gravity, solver, collision matrix.
* The FULL config, not a three-field subset: a collision matrix that reached
* Play and not a shipped build is a game that only collides in rehearsal. */
physicsConfig?: Physics2DPluginConfig;
/** The 3D physics backend the project chose; absent ⇒ Jolt. */
physics3dBackend?: Physics3DBackend;
/** The project's 3D world: scene units per metre and gravity (Project Settings → Physics → 3D). Absent ⇒ centimetre units, Earth gravity. */
physics3dWorld?: Partial<Physics3DWorldConfig>;
/** Project-declared UI theme; 'light' re-skins ThemeStyle-tagged widgets at boot. */
uiTheme?: 'dark' | 'light';
/** Project-declared theme token overrides (partial re-skin over the base). */
uiThemeOverrides?: ThemeOverrides;
/** Project-declared mixer state (routing labels only on mini-games — the host
* hands out finished players, not a DSP graph). */
audioConfig?: AudioProjectConfig;
/** Bitmask of render layers (0..31) that y-sort within the layer (Project Settings → Rendering). */
ySortLayers?: number;
/** Bitmask of render layers (0..31) that resolve by real depth (2.5D). */
depthLayers?: number;
/** Project color space — 'linear' boots the linear-light pipeline (Project Settings → Rendering). */
colorSpace?: 'gamma' | 'linear';
/** Project camera fit (Project Settings → Display) — letterboxes the design resolution
* without a UI Canvas; absent = no fit (raw orthoSize). */
screenFit?: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number };
/** id → emscripten factory (`require('./wasm/<file>.js')`); the generated
* game.js supplies exactly the modules the scene needs. Physics + spine
* self-gate off these via {@link createMiniGameSideModuleHost}. */
sideModuleFactories?: MiniGameSideModuleFactories;
/**
* Suffix the export staged those binaries under — `.wasm.br` where the
* vendor's loader takes one and the project asked for it. Declared rather
* than guessed: the package carries ONE binary per module, and a loader that
* spelled the suffix itself would name a file the package does not have.
*/
sideModuleSuffix?: string;
/**
* Project-supplied modules (`.esengine/modules/<id>/`) the export staged, so
* their ids resolve to an artifact name.
*
* Separate from the factories above because they answer different questions:
* a factory is the glue `game.js` already require()'d, this is where the
* BINARY sits — and a mini-game instantiates from a package path, so without
* it an acquired module has a factory and nowhere to load from. Built-in ids
* need no entry; the engine's table already has them.
*/
sideModules?: Array<{ id: string; file: string; globalName?: string }>;
/**
* The compiled twins this build produced (docs/REARCH_AOT.md), as the path
* the export staged them at. A path and never bytes: WXWebAssembly compiles
* a package file and nothing else, which is also why the seam instantiates.
*/
aot?: { module: string; manifest: AotManifest };
debugChannel?: DebugChannelConfig;
/** The CDN root remote groups resolve against, and the key an applied update
* is stored under — the same field every packaged runtime reads. */
hotUpdate?: PackagedGameConfig['hotUpdate'];
}
/**
* The host's loading indicator, driven by the same stage list the web start
* screen reads. It is the only progress surface a mini-game has: the display
* canvas is the GL surface, so nothing 2D can be drawn over it. Every call is
* optional — an indicator is something a boot SHOWS, never something it fails on.
*/
export function hostProgress(global: {
showLoading?: (o: { title: string; mask?: boolean; complete?: () => void }) => void;
hideLoading?: () => void;
}) {
const done: BootStage[] = [];
let unsettled = 0;
let hideWhenSettled = false;
const hide = (): void => {
try { global.hideLoading?.(); } catch { /* as above */ }
};
const say = (): void => {
try {
unsettled++;
global.showLoading?.({
title: `${bootSays(done)} ${bootPercent(done)}%`,
mask: true,
complete: () => { if (--unsettled === 0 && hideWhenSettled) hide(); },
});
} catch { /* an indicator must not take the boot down with it */ }
};
say();
return {
reach(stage: BootStage): void {
if (done.includes(stage)) return;
done.push(stage);
say();
},
/** vivo runs these calls asynchronously and out of order: a hide issued
* right after a show landed first, leaving the show up for good. So the
* hide goes once every show has landed, and once now for a host that
* never reports one landing. */
finish(): void {
hideWhenSettled = true;
hide();
},
};
}
/** What a GLX context carries (WeChat's "EmscriptenGLX 原生引擎接入"). */
export interface GlxContext { isWebGL2: boolean; platform: number; ctxid: number }
export type GlxModule = { ccall(name: string, ret: string | null, args: string[], values: unknown[]): unknown; wxContextGlobal?: GlxContext };
/** Starts the linked GLX in the order WeChat's guide gives: told whether the host
* gave a GLX context at all, then, when it did, its buffers and GL state. */
export function startGlx(module: GlxModule, glx: GlxContext | undefined): void {
module.ccall('glxInit', null, ['bool'], [!!glx]);
if (!glx || module.wxContextGlobal !== undefined) return;
module.wxContextGlobal = { ...glx };
module.ccall('glxInitBufferDataAndGlState', null, ['number', 'number'], [glx.isWebGL2 ? 2 : 1, glx.platform]);
}
export async function initMiniGameRuntime(config: MiniGameRuntimeConfig): Promise<void> {
// Before the engine boots, so a boot that fails is still heard by the editor.
if (config.debugChannel) startDebugChannel(config.debugChannel);
// Before the app exists, so a plugin that acquires during build finds them.
registerPackagedSideModules({ sideModules: config.sideModules });
// The family adapter owns the host global; boot refuses to guess at one.
const adapter = getPlatform();
if (!(adapter instanceof MiniGamePlatformAdapter)) {
throw new Error(
'[ESEngine] initMiniGameRuntime requires a mini-game platform — call ' +
'setPlatform(new MiniGamePlatformAdapter(profile)) (or installMiniGamePlatform(profile)) first.',
);
}
const tag = adapter.name;
const progress = hostProgress(adapter.host);
progress.reach('config');
progress.reach('scripts');
// The packaged-realm asset assembly, shared with the native runtime: read the
// addressable manifest off the device, index it, build the catalog.
const index = await loadPackagedAssetIndex();
const { model: manifestModel, catalog } = index;
progress.reach('manifest');
// The FIRST canvas of the process is the display surface on every vendor.
const canvas = adapter.createScreenCanvas();
const module = await instantiateModule(config.engineFactory, config.engineWasmPath, tag, { canvas });
progress.reach('engine');
// EmscriptenGLX runs the engine's GL calls inside the wasm and hands them to
// the host in batches. Asked for only when the engine was linked with it and
// the host offers it; anything else is the ordinary WebGL2 context.
const glxLinked = typeof (module as { _glxInit?: unknown })._glxInit === 'function';
const hostEnv = (adapter.host as { env?: { isSupportEmscriptenGLX?: boolean } }).env;
const wantGlx = glxLinked && hostEnv?.isSupportEmscriptenGLX === true;
const gl = canvas.getContext(wantGlx ? 'wxwebgl2' : 'webgl2', glContextAttributes()) as WebGLRenderingContext | null;
if (!gl) {
// The renderer is GLSL ES 3.0 throughout, so a WebGL1 context would boot
// to shader failures and a black screen; this says why instead.
const offersWebGL1 = canvas.getContext('webgl') !== null;
log.error(tag, offersWebGL1
? 'This host offers only WebGL1, and the engine renders on WebGL2 — the game cannot start here'
: 'Failed to create a WebGL2 context');
return;
}
const glx = (gl as { emscriptenGLX?: GlxContext }).emscriptenGLX;
if (glxLinked) startGlx(module as unknown as GlxModule, glx);
log.info(tag, glx ? 'rendering through EmscriptenGLX' : `rendering through WebGL2${glxLinked ? ' (this host offers no EmscriptenGLX)' : ''}`);
hideCoreExtensions(gl);
const glHandle = module.GL.registerContext(gl, {
majorVersion: 2,
minorVersion: 0,
enableExtensionsByDefault: true,
});
if (glx) (module as unknown as GlxModule).ccall('glxUpdateContextId', 'number', ['number'], [glx.ctxid]);
const app = createWebApp(module, {
renderSurface: { kind: 'gl-context', handle: glHandle, glx: glx !== undefined },
ySortLayers: config.ySortLayers,
depthLayers: config.depthLayers,
colorSpace: config.colorSpace,
screenFit: config.screenFit,
getViewportSize: () => ({
width: canvas.width,
height: canvas.height,
}),
// Physics + spine self-gate off these factories (require()'d in game.js).
sideModules: config.sideModuleFactories
? createMiniGameSideModuleHost(config.sideModuleFactories, config.sideModuleSuffix)
: undefined,
});
if (config.runtimeConfig) {
applyBuildRuntimeConfig(app, config.runtimeConfig);
}
// Canonical asset source: the host filesystem backend, host image decode,
// manifest ref resolution (bare-uuid → build path).
const source = createPackagedAssetSource(index);
applyAssetRefResolvers(app, index.resolvePath);
// The first scene loads eagerly (the game boots into it); every other
// registers lazily by path — SceneManager fetches scenes/<name>.json
// through the runtime Assets (host fs backend) on the first switchTo.
const scenes: Array<{ name: string; data?: SceneData; path?: string }> = [];
for (const name of config.sceneNames) {
if (name === config.firstScene) {
const sceneText = await platformReadTextFile(`scenes/${name}.json`);
scenes.push({ name, data: JSON.parse(sceneText) as SceneData });
} else {
scenes.push({ name, path: `scenes/${name}.json` });
}
}
// The manifest rides into initRuntime, which sets it on the per-App runtime
// Assets — so game code can `Assets.loadGroup(name)` on demand (a lazy
// subpackage group triggers the host's loadSubpackage first, an eager 'main'
// group loads directly), and it survives scene switches. Setting it on the
// pre-initRuntime Assets resource was a bug: the runtime instance replaced
// that resource, so loadGroup lost the manifest after the first scene load.
progress.reach('assets');
await initRuntime({
app,
module,
source,
manifest: manifestModel,
catalog,
scenes,
firstScene: config.firstScene,
physicsEnabled: config.physicsEnabled,
physicsConfig: config.physicsConfig,
physics3dBackend: config.physics3dBackend,
physics3dWorld: config.physics3dWorld,
uiTheme: config.uiTheme,
uiThemeOverrides: config.uiThemeOverrides,
audioConfig: config.audioConfig,
runtime: config.runtime,
aspectRatio: canvas.width / canvas.height,
...(config.aot ? { aot: config.aot } : {}),
...(config.debugChannel ? { debugChannel: config.debugChannel } : {}),
remoteRoot: config.hotUpdate?.remoteRoot,
persistUpdateKey: config.hotUpdate?.persistUpdateKey,
});
progress.reach('ready');
// Before run(), which may hand control to the engine's loop and not return.
progress.finish();
reportFirstFrame(app, adapter.host as { launchSuccess?: () => void });
app.run();
}
/**
* Tell the host the first screen has rendered, where it asks to be told:
* Bilibili reviews a game by it (「需要在游戏首页成功渲染时调用」`bl.launchSuccess`).
* At the end of the first frame, once; a host without the call is skipped.
*/
export function reportFirstFrame(app: Pick<App, 'addSystemToSchedule'>, host: { launchSuccess?: () => void }): void {
if (typeof host.launchSuccess !== 'function') return;
let told = false;
app.addSystemToSchedule(Schedule.Last, defineSystem([], () => {
if (told) return;
told = true;
try { host.launchSuccess!(); } catch (e) { log.warn('runtime', `launchSuccess threw: ${String(e)}`); }
}, { name: 'ReportFirstFrame' }));
}