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 playRealmRuntime.ts
* @brief Editor play-realm runtime entry — the SAME shipping runtime
* (`initRuntime`) the playable/wechat paths use, but driven from a live
* scene SNAPSHOT + a uuid→url asset manifest fetched over the realm
* origin. So what the editor "plays" is literally the shipping runtime
* (play == ship). Mirrors {@link initPlayableRuntime} minus the
* base64/embedded asset packing.
*
* Builtin components/systems run as-is. Project-defined components/systems
* are already registered by the time this runs: the host imports the project
* bundle (esengine external + import map → the shared instance) BEFORE booting,
* so its defineComponent/defineSystem populate the registry this drains. This
* entry only owns the runtime + snapshot + asset fetch.
*/
import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';
import type { App } from '../app/app';
import type { ESEngineModule } from '../wasm';
import { Audio } from '../audio/Audio';
import { VideoPlayer } from '../video/VideoAPI';
import { initRuntime } from './runtimeLoader';
import { cutWorld, resolvePrefabRoots, type CutWorld } from '../residency/cutWorld';
import { registryEntityFields } from '../residency/componentRefs';
import type { ThemeOverrides } from '../ui';
import type { RuntimeAssetSource } from './runtimeAssets';
import { HttpBackend } from '../asset/Backend';
import { Catalog, type CatalogData } from '../asset/Catalog';
import { ManifestModel, type AddressableManifest } from '../asset/AddressableManifest';
import type { SceneData } from '../scene/scene';
import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
import type { RuntimeBuildConfig } from '../defaults';
import { fetchDecodePixels } from '../asset/imageDecode';
import { applyAssetRefResolvers } from './packagedRuntime';
import { extractUuid, UUID_REF_PREFIX } from '../asset/AssetRegistry';
import type { Physics3DBackend } from '../sideModules/registry';
import type { Physics3DWorldConfig } from '../physics3d/worldConfig';
export interface PlayRealmRuntimeConfig {
app: App;
module: ESEngineModule;
canvas: HTMLCanvasElement;
/** The current scene as RAW (`@uuid:`) SceneData — handles are realm-local. */
sceneData: SceneData;
/** Where the host keeps this realm's textures compressed (RuntimeAssetSource). */
compressedTexture?: RuntimeAssetSource['compressedTexture'];
/** Additional switchable scenes beyond the entry (SceneManager targets).
* `path` entries load lazily through the runtime Assets on first switch. */
extraScenes?: Array<{ name: string; data?: SceneData; path?: string }>;
/** SceneManager name of the entry `sceneData` (default '__play'). Shipped
* builds pass the real scene name so game code can switch back to it. */
entrySceneName?: string;
/** Lowercased uuid → fetchable URL (e.g. `estella://project/<path>`). */
assetManifest: Record<string, string>;
/**
* Logical (source) path → fetchable staged path, for cooked builds whose
* content-addressed staging renamed the physical files. Path-style refs
* (a scene's "assets/x.esmaterial") resolve through this BEFORE extension
* sniffing, exactly like uuid refs — so a .png staged as .ktx2 transcodes.
* Omit when files are served at their logical paths (the editor realm).
*/
assetPathMap?: Record<string, string>;
/**
* Logical path → build-path catalog for the same cooked case: loaders fetch
* their INNER text refs (a material's shader) through Catalog.getBuildPath,
* which is identity without this. Omit alongside assetPathMap.
*/
catalogData?: CatalogData | null;
manifest?: AddressableManifest | null;
/** CDN root `remote`-group assets resolve against — turns on hot-update delivery. */
remoteRoot?: string;
/** Storage key an applied hot-update persists under; boot restores it if present. */
persistUpdateKey?: string;
/** Base URL the engine side-modules (physics.wasm, …) are served from — same
* dir as esengine.wasm. When set, the realm can load physics on demand. */
wasmBaseUrl?: string;
/** Project-root URL for path-addressed runtime assets. Textures resolve
* through the uuid manifest, but the audio channel takes plain project-relative
* paths (`audio.playSFX('assets/…')`), so it needs this base to fetch from the
* project rather than the play-realm subdir. */
assetBaseUrl?: string;
/** Project-declared physics enable (`.uproject` features analog) — installs
* physics even for runtime-spawned bodies the static scene doesn't show. */
physicsEnabled?: boolean;
/** Project-declared physics world config (gravity, solver tuning, collision-layer
* masks, sleep/continuous) from the editor's Project Settings. */
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), so Play runs under what ships. */
runtime?: RuntimeBuildConfig;
/** The project's declared achievement ids — Play checks an unlock against the
* same set a shipped build does, so a typo is found here. */
achievements?: string[];
/** Turn on per-phase / per-system frame timing (editor profiler; off in shipped games). */
enableStats?: boolean;
}
/**
* Build the realm's asset source: `@uuid:` refs resolve through the editor-supplied
* manifest (`resolveRef`), fetch goes over the realm origin via `HttpBackend`, and
* images go fetch → blob → decode (NOT `<img crossorigin>`: Chromium refuses
* CORS-mode images for custom schemes like `estella://`, and a non-CORS `<img>`
* taints the canvas so getImageData throws — fetch+blob sidesteps both).
* `estella://` is fetchable because it's a privileged supportFetchAPI scheme; the
* editor returns `access-control-allow-origin: *`.
*/
/**
* Resolve a play-realm asset ref to a fetchable URL. UUID refs go through the
* editor-supplied manifest — a `@uuid:` prefix is explicit intent (any body), and
* a BARE uuid-shaped ref counts too ({@link extractUuid}'s canonical forms):
* `.esanim` flipbook frames serialize bare uuids, and the old prefix-only check
* dropped those into the path branch → guaranteed 404s, blank sprite animation
* in play. Any other ref is a project-relative path (spine skel/atlas, …) and
* resolves against the project root, not the `.esengine/play/` subdir the realm
* runs from. Pure.
*/
export function resolvePlayAssetRef(
ref: string,
manifest: Record<string, string>,
assetBaseUrl?: string,
pathMap?: Record<string, string>,
): string {
const uuid = ref.startsWith(UUID_REF_PREFIX)
? ref.slice(UUID_REF_PREFIX.length).toLowerCase()
: extractUuid(ref);
if (uuid !== null) {
const url = manifest[uuid];
if (!url) throw new Error(`asset not in play manifest: ${ref}`);
return url;
}
// Cooked builds: a logical path maps to its staged file (content-addressed
// rename + possible extension swap) — resolved here so the result is the
// extension-bearing physical path, same contract as the uuid branch.
if (pathMap) {
const staged = pathMap[ref] ?? pathMap[ref.replace(/^\.?\//, '')];
if (staged) return staged;
}
const base = (assetBaseUrl ?? '').replace(/\/$/, '');
// Idempotent, like HttpBackend.resolveUrl: an already-resolved absolute URL or
// base-prefixed path must not be prefixed again. Preload resolves a ref once to
// bucket it by type, then the loader resolves it a second time — without this
// guard a plain path would gain the base twice (estella://…/estella://…/404).
if (ref.includes('://') || (base && ref.startsWith(`${base}/`))) return ref;
return base ? `${base}/${ref.replace(/^\//, '')}` : ref;
}
/**
* What a manifest tells a realm about its assets, in one place: two lookups a
* packaged build and an editor Play session read identically. Assembled once per
* source — rebuilding a spelling map per ref would walk the manifest on every
* asset a scene preloads.
*/
function manifestBackedSettings(model: ManifestModel): Partial<RuntimeAssetSource> {
return {
textureImportSettings: model.textureImportLookup(),
spineCulling: model.spineCullingLookup(),
};
}
/**
* A manifest's texture settings for a realm whose refs can be URLs. A material names its textures beside itself, and
* beside a URL is another URL: one the manifest knows by path or uuid. Without this its maps miss their settings and are
* decoded as colour, and every value in them bends.
*/
export function playRealmTextureSettings(
lookup: (ref: string) => ParsedTextureImportSettings | undefined,
manifest: Record<string, string>,
assetBaseUrl?: string,
): (ref: string) => ParsedTextureImportSettings | undefined {
const keyOf = new Map(Object.entries(manifest).map(([key, url]) => [url, key]));
const base = assetBaseUrl?.replace(/\/$/, '');
return (ref) => {
const direct = lookup(ref);
if (direct) return direct;
const key = keyOf.get(ref);
if (key !== undefined) return lookup(key);
return base && ref.startsWith(`${base}/`) ? lookup(ref.slice(base.length + 1)) : undefined;
};
}
function createPlayRealmSource(
manifest: Record<string, string>,
assetBaseUrl?: string,
pathMap?: Record<string, string>,
addressable?: AddressableManifest | null,
compressedTexture?: RuntimeAssetSource['compressedTexture'],
): RuntimeAssetSource {
const backend = new HttpBackend({ baseUrl: '' });
return {
backend,
...(compressedTexture ? { compressedTexture } : {}),
decodePixels: (path, _flip, maxEdge) => fetchDecodePixels(backend.resolveUrl(path), maxEdge),
resolveRef: (ref) => resolvePlayAssetRef(ref, manifest, assetBaseUrl, pathMap),
// Cooked builds: logical paths (the pathMap keys). Editor play: the
// manifest's resolved URLs — both keep the real extension, which is all
// the .eslocale discovery filters on.
listAssetPaths: () => (pathMap ? Object.keys(pathMap) : Object.values(manifest)),
// Sampling, and the spine culling contract, both come off the addressable
// manifest — the same fields a cooked build reads, so Play and ship
// cannot disagree about what an author promised.
...(addressable ? withUrlSettings(manifestBackedSettings(ManifestModel.fromJson(addressable)), manifest, assetBaseUrl) : {}),
};
}
function withUrlSettings(settings: Partial<RuntimeAssetSource>, manifest: Record<string, string>, assetBaseUrl?: string): Partial<RuntimeAssetSource> {
const lookup = settings.textureImportSettings;
return lookup ? { ...settings, textureImportSettings: playRealmTextureSettings(lookup, manifest, assetBaseUrl) } : settings;
}
/**
* Cut the snapshot the way a cook would, or answer null when it is not a world.
*
* Here rather than on disk because the scene an author is playing may never
* have been saved. Same `cutWorld`, so the cells and the manifest are what the
* package would carry — only the documents stay in memory.
*/
export async function cutPlayWorld(
scene: SceneData, sceneName: string, resolveRef: (ref: string) => string,
): Promise<CutWorld | null> {
const resolvePrefab = await resolvePrefabRoots(scene, async (ref) => {
const response = await fetch(resolveRef(ref));
return response.ok ? await response.json() as unknown : null;
});
const cut = cutWorld(scene, sceneName, {
// The realm's registry, which by now holds the project's own components
// as well as the engine's — so a cross-cell reference a cook could not
// see is found HERE, before it is packaged.
entityFieldsOf: registryEntityFields(),
resolvePrefab,
});
if (cut !== null && cut.errors.length > 0) {
// Refused, not played whole: a world the editor agreed to run streamed is
// one the author will ship, and this same cut fails the build.
throw new Error(
`scene "${sceneName}" cannot be cut into cells, so it cannot be played `
+ `as the streamed world it declares:\n`
+ cut.errors.map((e) => ` ${e}`).join('\n'),
);
}
return cut;
}
/**
* Boot the shipping runtime against a single in-memory scene snapshot. The host
* page has already created `app` (createWebApp) + bound a GL context; here we
* register the snapshot as the sole scene, wire a fetch-backed source, and run.
*/
export async function initPlayRealmRuntime(config: PlayRealmRuntimeConfig): Promise<void> {
const { app, module, canvas, sceneData, assetManifest, assetBaseUrl } = config;
const source = createPlayRealmSource(assetManifest, assetBaseUrl, config.assetPathMap, config.manifest,
config.compressedTexture);
applyAssetRefResolvers(app, (ref) => resolvePlayAssetRef(ref, assetManifest, assetBaseUrl, config.assetPathMap));
const entryName = config.entrySceneName ?? '__play';
const cut = await cutPlayWorld(
sceneData, entryName,
(ref) => resolvePlayAssetRef(ref, assetManifest, assetBaseUrl, config.assetPathMap),
);
await initRuntime({
app,
module,
source,
manifest: config.manifest,
remoteRoot: config.remoteRoot,
persistUpdateKey: config.persistUpdateKey,
catalog: config.catalogData ? Catalog.fromJson(config.catalogData) : undefined,
scenes: [
// The persistent world when there is one: what a package boots is the
// part residency never removes, and the places arrive as it asks.
{ name: entryName, data: cut?.persistent ?? sceneData },
...(config.extraScenes ?? []).filter((s) => s.name !== entryName),
],
...(cut ? { worlds: [cut.manifest], cellDocuments: cut.documents } : {}),
firstScene: entryName,
aspectRatio: canvas.width / canvas.height,
physicsEnabled: config.physicsEnabled,
physicsConfig: config.physicsConfig,
physics3dBackend: config.physics3dBackend,
physics3dWorld: config.physics3dWorld,
uiTheme: config.uiTheme,
uiThemeOverrides: config.uiThemeOverrides,
audioConfig: config.audioConfig,
runtime: config.runtime,
achievements: config.achievements,
// Physics (and spine) are acquired from app.sideModules — the fetch host
// createWebApp built from this realm's wasmBaseUrl.
});
// Per-phase / per-system frame timing for the editor profiler (enabled before
// the loop starts so the runner instruments from frame zero).
if (config.enableStats) app.enableStats();
app.run();
}