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 playableRuntime.ts
* @brief Playable ad runtime initialization (single-HTML builds)
*
* @details Side modules (physics, spine) are NOT wired here: the host page builds
* an {@link createEmbeddedSideModuleHost} from the exporter-inlined
* base64 registry and hands it to `createWebApp`, so physics and spine
* self-gate off `app.sideModules` exactly as in every other realm. This
* entry only owns the embedded asset source + the runtime boot.
*/
import type { App } from '../app/app';
import { setAppHostPaused } from '../app/app';
import type { ESEngineModule } from '../wasm';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
import type { RuntimeBuildConfig } from '../defaults';
import { initRuntime } from './runtimeLoader';
import { warmShaders } from '../render/shaderWarmup';
import { log } from '../util/logger';
import type { ThemeOverrides } from '../ui';
import type { RuntimeAssetSource } from './runtimeAssets';
import { EmbeddedBackend } from '../asset/Backend';
import { ManifestModel, type AddressableManifest } from '../asset/AddressableManifest';
import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { SceneData } from '../scene/scene';
import { Audio, setAudioHostSuspended } from '../audio/Audio';
import { Input, inputEventCallbacks } from '../input/input';
import { playableAdBridge } from './playableCta';
import { VideoPlayer } from '../video/VideoAPI';
import type { Physics3DBackend } from '../sideModules/registry';
import type { Physics3DWorldConfig } from '../physics3d/worldConfig';
export interface PlayableRuntimeConfig {
app: App;
module: ESEngineModule;
canvas: HTMLCanvasElement;
assets: Record<string, string>;
/**
* Logical (source) path → embedded-asset key (`@uuid:<id>`), so path-style
* refs (a scene's "assets/x.esmaterial", a material's rewritten logical
* refs) resolve to the inlined data. Applied as in-memory ALIASES onto the
* assets map — every channel (fetch, image decode, audio) reads that one
* map, and aliases share the data-URL strings (no payload duplication).
*/
assetPathMap?: Record<string, string>;
scenes: Array<{ name: string; data: SceneData }>;
firstScene: string;
/** 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 (bus volumes / effects / duck rules). */
audioConfig?: AudioProjectConfig;
/** The project's runtime tuning (Project Settings → Game → Runtime). */
runtime?: RuntimeBuildConfig;
/** 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;
manifest?: AddressableManifest | null;
/**
* Draw the first scene out of sight (the canvas hidden) until its shaders have compiled, and show it complete: `quality.prewarmShaders` of a
* project that also compiles them in the background. The wait is at most `timeoutMs`.
*/
prewarmShaders?: { timeoutMs?: number; /** Called after each frame drawn out of sight with how many shaders are still compiling and how much of the scene is still to be made. */ onProgress?: (pending: number, making: number) => void };
/** Called once everything is loaded and warmed, just before the loop starts: where a page takes its start screen away. */
onBeforeRun?: () => void;
}
function decodeDataUrlBinary(dataUrl: string): Uint8Array {
const raw = atob(dataUrl.split(',')[1]);
const bytes = new Uint8Array(raw.length);
for (let i = 0; i < raw.length; i++) {
bytes[i] = raw.charCodeAt(i);
}
return bytes;
}
function loadImagePixels(dataUrl: string): Promise<{ width: number; height: number; pixels: Uint8Array }> {
return new Promise((resolve, reject) => {
const img = new Image();
img.onload = () => {
const cv = document.createElement('canvas');
cv.width = img.width;
cv.height = img.height;
const ctx = cv.getContext('2d')!;
ctx.drawImage(img, 0, 0);
const id = ctx.getImageData(0, 0, img.width, img.height);
resolve({ width: img.width, height: img.height, pixels: new Uint8Array(id.data.buffer) });
};
img.onerror = reject;
img.src = dataUrl;
});
}
export async function initPlayableRuntime(config: PlayableRuntimeConfig): Promise<void> {
const { app, module, scenes, firstScene } = config;
// The playable boot pre-creates the app, so the project's y-sort layers are
// applied here rather than through createWebApp options.
if (config.ySortLayers) module.renderer_setYSortLayers?.(config.ySortLayers >>> 0);
if (config.depthLayers) module.renderer_setDepthLayers?.(config.depthLayers >>> 0);
// Alias logical paths onto the embedded map (both spellings the cook may
// emit) — the aliases point at the SAME data-URL strings, so path refs cost
// nothing and every consumer below resolves through one map.
const assets = { ...config.assets };
const keyToPath: Record<string, string> = {};
for (const [logical, key] of Object.entries(config.assetPathMap ?? {})) {
const data = assets[key];
if (!data) continue;
assets[logical] ??= data;
assets[`/${logical}`] ??= data;
// Reverse index (@uuid key → its logical source path); first path wins.
keyToPath[key] ??= logical;
}
// Canonical asset source: the shared EmbeddedBackend (data-URLs) + a DOM image
// decode over the same data-URL. `resolveRef` yields a logical PATH (not the
// bare @uuid key) so consumers that derive sibling paths from a resolved ref
// work — e.g. a Spine atlas names its texture pages by filename, resolved
// against the atlas's own directory. This matches the web/manifest runtime's
// resolveRef contract; a ref with no known path (or already a path) passes
// through, and the backend resolves both spellings off the same aliased map.
const backend = new EmbeddedBackend(assets);
const resolveRefToPath = (ref: string): string => keyToPath[ref] ?? ref;
const source: RuntimeAssetSource = {
backend,
resolveRef: resolveRefToPath,
decodePixels: (path) => loadImagePixels(backend.resolveUrl(path)),
// Map keys are the shippable paths (logical aliases included) — the
// .eslocale discovery filters on extension, so aliases resolve fine.
listAssetPaths: () => Object.keys(assets),
// A single-file playable inlines the bytes but still ships the manifest,
// so filter/wrap/sRGB and the 9-slice border reach it the same way they
// reach every other packaged realm.
textureImportSettings: config.manifest
? ManifestModel.fromJson(config.manifest).textureImportLookup()
: undefined,
};
if (app.hasResource(Audio)) {
app.getResource(Audio).setAssetResolver((url: string) => {
const dataUrl = assets[url];
if (!dataUrl) return null;
return decodeDataUrlBinary(dataUrl).buffer as ArrayBuffer;
});
}
// A single-file playable makes NO external requests, so a video's ref has to
// come out as the inlined data URL — the path→URL step the backend owns. Same
// composition the scene loader installs (it re-binds this per scene load); both
// spell it out so a play() before the first scene resolves too.
if (app.hasResource(VideoPlayer)) {
app.getResource(VideoPlayer).setRefResolver((ref) => backend.resolveUrl(resolveRefToPath(ref)));
}
await initRuntime({
app,
module,
source,
scenes,
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: config.canvas.width / config.canvas.height,
});
const bridge = playableAdBridge();
if (bridge?.onActive) {
const owner = {};
let release: (() => void) | undefined;
app.addPlugin({
name: 'playable-network-lifecycle',
build() {
release = bridge.onActive!(active => {
setAppHostPaused(app, owner, !active);
if (app.hasResource(Input)) inputEventCallbacks(app.getResource(Input)).onInputCancel?.();
if (app.hasResource(Audio)) setAudioHostSuspended(app.getResource(Audio), owner, !active);
});
},
cleanup() {
release?.();
setAppHostPaused(app, owner, false);
if (app.hasResource(Audio)) setAudioHostSuspended(app.getResource(Audio), owner, false);
},
});
}
if (config.prewarmShaders) {
// A playable has no splash to draw behind: the canvas itself is kept out of sight, and the page's background is what shows.
const style = config.canvas.style;
const shown = style.visibility;
style.visibility = 'hidden';
try {
const warmed = await warmShaders(app, { timeoutMs: config.prewarmShaders.timeoutMs, onProgress: config.prewarmShaders.onProgress });
if (warmed.timedOut) log.warn('playable', `${warmed.pending} shader(s) still compiling after ${Math.round(warmed.ms)} ms; opening anyway`);
} catch (e) {
log.warn('playable', 'shader warm-up failed', e);
} finally {
style.visibility = shown;
}
}
// A start screen that a throwing callback left up would cover the game for good.
try { config.onBeforeRun?.(); } catch (e) { log.warn('playable', 'onBeforeRun failed', e); }
await app.run();
bridge?.ready?.();
}