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 packagedRuntime.ts
* @brief The asset assembly every PACKAGED realm shares — a WeChat mini-game,
* a native app: realms that ship cooked content beside the runtime and
* read it off the device rather than over HTTP.
* @details The addressable manifest is the single source: it resolves a ref to a
* staged path, and its atlas metadata builds the catalog the loaders
* consult for their inner text refs (a material's shader). Everything
* here is DOM-free and transport-free — the platform layer decides how
* the bytes arrive, so the same code serves both realms.
*/
import type { QualityConfig } from '../render/quality';
import type { RuntimeBuildConfig } from '../defaults';
import type { DebugChannelConfig } from './debugChannelProtocol';
import { extractUuid } from '../asset/AssetRegistry';
import { platformReadTextFile, platformLoadImagePixels } from '../platform';
import { ManifestModel, type AddressableManifest } from '../asset/AddressableManifest';
import { Catalog, atlasCatalogFields, type CatalogEntry } from '../asset/Catalog';
import { FileSystemBackend, type Backend } from '../asset/Backend';
import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';
import type { SpineCullingRect } from '../asset/spineImportSettings';
import { Audio } from '../audio/Audio';
import type { AudioProjectConfig } from '../audio/AudioProjectConfig';
import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import { parseThemeOverrides, type ThemeOverrides } from '../ui/theme/tokens';
import { VideoPlayer } from '../video/VideoAPI';
import type { App } from '../app/app';
import type { RuntimeAssetSource } from './runtimeAssets';
import { registerSideModule, type Physics3DBackend } from '../sideModules/registry';
import type { Physics3DWorldConfig } from '../physics3d/worldConfig';
import type { AotManifest } from '../ecs/aot/AotSystems';
/**
* `game.config.json` — what an export bakes about the project, and the contract
* between the export pipeline that writes it and every runtime that reads it.
* One declaration so the two sides cannot drift.
*/
export interface PackagedGameConfig {
/** External Web distribution SDK selected by this export. */
webChannel?: 'poki' | 'crazygames' | 'youtube';
/** Public client encryption key for invited CrazyGames leaderboards; never a server API key. */
leaderboardEncryptionKey?: string;
/** Project-relative path of the scene the game boots into. */
entryScene: string;
/** Every switchable scene (SceneManager name + cooked path); includes the entry. */
scenes?: Array<{ name: string; path: string }>;
/**
* Scenes the cook cut into cells, each with the manifest describing them.
* Deliberately not in `scenes`: a cell is content residency brings in, not a
* place a game switches to.
*/
worlds?: Array<{ scene: string; manifest: string }>;
/**
* The project's own bundled code, as a payload-relative file name. Absent
* means this build has none — which is how a host tells "no project script"
* from "the project script failed to load". Guessing between those with a
* catch runs the empty world and calls it a success.
*/
scripts?: string;
/** Bitmask of render layers (0..31) that y-sort within the layer. */
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. */
colorSpace?: 'gamma' | 'linear';
/** The curve the frame applies on the way to the display; absent = none. */
outputTransform?: 'none' | 'aces' | 'neutral';
/** Scene-target multisampling the project asked for; absent ⇒ 4. Clamped by
* the device, which answers capability and never policy. */
msaaSamples?: number;
quality?: QualityConfig;
/** GPU backend the build asks for; absent ⇒ WebGL2. A request for
* 'webgpu' falls back where the machine cannot serve one. */
renderBackend?: 'webgl2' | 'webgpu';
/** Project camera fit (design resolution + scale mode) — letterboxes the main
* camera without a UI Canvas; absent = no fit. */
screenFit?: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number };
/** Project widget theme; absent = dark. */
uiTheme?: 'light';
/** Project theme color overrides (role → #rrggbbaa hex). */
uiThemeColors?: Record<string, string>;
/** The achievement ids this game declares. The runtime refuses an unlock
* outside the set, because a store accepts an unknown id and does nothing. */
achievements?: string[];
/** The Steam application id, when this build ships to Steam. Its presence is
* what makes the runtime try to bring a Steam client up at all. */
steamAppId?: number;
/**
* The engine binary's size as it arrives in the page, decompressed. A host
* that compresses states a Content-Length for fewer bytes than a download
* counts, so the boot bar measures against this instead.
*/
engineBytes?: number;
/** The package carries the engine built as plain JavaScript (wasm/esengine.asm.js),
* which the page loads where there is no WebAssembly. */
engineJs?: boolean;
/**
* Install physics even when the shipped scene shows no bodies — a project
* that spawns them from script (Project Settings → Physics → Enabled).
* Absent ⇒ physics installs only when a scene actually uses it.
*/
physicsEnabled?: boolean;
/** The physics world the project declared: gravity, solver, collision matrix.
* Absent ⇒ the engine's own defaults. */
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 mixer state: bus volumes, custom buses, effects, duck rules.
* Absent ⇒ the default mix. */
audioConfig?: AudioProjectConfig;
/** The runtime tuning the project declared (scene transition, frame limits, asset timeouts, cache budgets).
* Absent ⇒ the engine's own values; only fields that differ from them are written. */
runtime?: RuntimeBuildConfig;
/** Hot-update delivery: the CDN root `remote`-group assets resolve against +
* the storage key an applied update persists under (both optional). */
hotUpdate?: { remoteRoot?: string; persistUpdateKey?: string };
/**
* Optional native modules this project supplied itself, staged beside the
* engine's own (see `.esengine/modules/<id>/`).
*
* The declaration ships rather than being discovered, because discovery is not
* possible where it matters: a mini-game cannot list a directory and a
* playable has no directory at all. The export knows what it staged, so it
* says so, and every transport resolves these ids exactly like a built-in.
*/
sideModules?: Array<{ id: string; file: string; globalName?: string }>;
/**
* The compiled twins this build produced (docs/REARCH_AOT.md). `wasm` is
* package-relative; the manifest rides here so there is not a second file to
* keep in step. Absent unless the project marked something `@compiled`, so a
* runtime reads presence and needs no mode flag.
*/
aot?: { module: string; manifest: AotManifest };
/** Where the editor that made this development build listens for it. Never
* written by a shipping export. */
debugChannel?: DebugChannelConfig;
}
/** The packaged realm's resolved asset index — manifest, catalog, resolution. */
export interface PackagedAssetIndex {
manifest: AddressableManifest;
model: ManifestModel;
/** Logical → staged mapping for the loaders' inner refs; absent when the
* build stages assets under their logical paths (nothing to remap). */
catalog?: Catalog;
/** Resolve any ref spelling (`@uuid:`, logical, "/"-rooted) to a staged path. */
resolvePath(ref: string): string;
/** The asset's LOGICAL source path for any ref spelling (including its own staged
* path), or null when unknown — recovers the authored directory a
* content-addressed rename hid. */
addressOf(ref: string): string | null;
/** Every staged asset path — content-driven discovery (locale tables). */
assetPaths(): string[];
/** How a texture is sampled and 9-sliced, for any ref spelling. */
textureImport(ref: string): ParsedTextureImportSettings | undefined;
/** The culling contract shipped for a spine PAIR, for any ref spelling. */
spineCulling(skeleton: string, atlas: string): SpineCullingRect | undefined;
}
/**
* Build the catalog from an addressable manifest. Content-addressed packs rename
* physical files, so assets carrying an `address` (their logical source path) get
* a catalog buildPath. Atlas-packed frames additionally register frame/uv, keyed
* by every ref spelling a scene can use.
*/
/**
* Register the project modules this build staged, so `sideModules.acquire(id)`
* resolves them the way it resolves the engine's own.
*
* Every realm calls this after reading its config and before anything acquires —
* one line each rather than one clever shared boot, because the four realms do
* not share a boot: the web fetches its config, native reads it off disk, a
* mini-game requires it, and a playable has it inlined.
*/
export function registerPackagedSideModules(config: Pick<PackagedGameConfig, 'sideModules'>): void {
for (const m of config.sideModules ?? []) {
if (!m?.id || !m.file) continue;
registerSideModule(m.id, m.globalName ? { file: m.file, globalName: m.globalName } : { file: m.file });
}
}
/**
* The app options a packaged config declares — everything an App must be built
* WITH (shaders compile against the colour space; the layer masks are renderer
* state set before the first frame).
*
* Every host projected these by hand and each list was a chance to miss one: the
* web host was still building its App without the 2.5D depth mask after the
* export had started shipping it, so a shipped game could carry the setting and
* ignore it. One projection, so a field added to the config reaches every realm
* that spreads it.
*/
/**
* The attributes every host creates the engine's WebGL2 context with. WebGL
* gives no stencil buffer unless asked, and sprite masks draw through one.
* `preserveDrawingBuffer` is for a harness that reads a composited frame back.
*/
export function glContextAttributes(preserveDrawingBuffer = false): WebGLContextAttributes {
return {
alpha: false,
antialias: true,
depth: true,
stencil: true,
premultipliedAlpha: false,
preserveDrawingBuffer,
};
}
export function packagedAppOptions(
config: Pick<PackagedGameConfig,
'ySortLayers' | 'depthLayers' | 'colorSpace' | 'outputTransform' | 'screenFit'
| 'msaaSamples' | 'quality'>,
): {
ySortLayers?: number;
depthLayers?: number;
colorSpace?: 'gamma' | 'linear';
outputTransform?: 'none' | 'aces' | 'neutral';
msaaSamples?: number;
quality?: QualityConfig;
/** GPU backend the build asks for; absent ⇒ WebGL2. A request for
* 'webgpu' falls back where the machine cannot serve one. */
renderBackend?: 'webgl2' | 'webgpu';
screenFit?: PackagedGameConfig['screenFit'];
} {
return {
ySortLayers: config.ySortLayers,
depthLayers: config.depthLayers,
colorSpace: config.colorSpace,
outputTransform: config.outputTransform,
msaaSamples: config.msaaSamples,
quality: config.quality,
screenFit: config.screenFit,
};
}
/**
* The {@link initRuntime} arguments a packaged config declares — everything
* applied to a LIVE app rather than baked into its construction. The twin of
* {@link packagedAppOptions}; between them a host names the config once.
*/
export function packagedRuntimeInit(
config: Pick<PackagedGameConfig,
'physicsEnabled' | 'physicsConfig' | 'physics3dBackend' | 'physics3dWorld' | 'audioConfig' | 'uiTheme' | 'uiThemeColors'
| 'achievements' | 'steamAppId' | 'screenFit' | 'aot' | 'debugChannel' | 'runtime'>,
): {
physicsEnabled?: boolean;
physicsConfig?: Physics2DPluginConfig;
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>;
audioConfig?: AudioProjectConfig;
runtime?: RuntimeBuildConfig;
uiTheme?: 'light';
uiThemeOverrides?: ThemeOverrides;
achievements?: string[];
steamAppId?: number;
screenFit?: PackagedGameConfig['screenFit'];
aot?: PackagedGameConfig['aot'];
debugChannel?: DebugChannelConfig;
} {
return {
physicsEnabled: config.physicsEnabled,
physicsConfig: config.physicsConfig,
physics3dBackend: config.physics3dBackend,
physics3dWorld: config.physics3dWorld,
audioConfig: config.audioConfig,
runtime: config.runtime,
uiTheme: config.uiTheme,
uiThemeOverrides: parseThemeOverrides(config.uiThemeColors),
achievements: config.achievements,
steamAppId: config.steamAppId,
// Also here, not only in packagedAppOptions: the camera fit is baked into
// the app's construction, but the WINDOW is sized on a live one.
screenFit: config.screenFit,
// Here rather than per host: a host that names the fields it knows about
// is a host the next one never reaches, and this one reached none of the
// native road until it was asked for by hand.
aot: config.aot,
debugChannel: config.debugChannel,
};
}
export function catalogFromManifest(manifest: AddressableManifest): Catalog | undefined {
const entries: Record<string, CatalogEntry> = {};
for (const group of Object.values(manifest.groups)) {
for (const [uuid, asset] of Object.entries(group.assets)) {
const md = asset.metadata;
const atlasFields = md?.atlasFrame && md.atlasPageWidth && md.atlasPageHeight
? atlasCatalogFields(
{ page: md.atlasPage, frame: md.atlasFrame, pageWidth: md.atlasPageWidth, pageHeight: md.atlasPageHeight },
asset.path,
)
: null;
const tail = asset.streamTail ? { streamTail: asset.streamTail } : {};
if (atlasFields || asset.streamTail) {
entries[`@uuid:${uuid}`] = { type: asset.type, buildPath: asset.path, ...(atlasFields ?? {}), ...tail };
}
// A texture with a small copy is found by whatever spelling a load uses, the build path among them.
if (asset.streamTail) entries[asset.path] = { type: asset.type, buildPath: asset.path, ...tail };
if (!asset.address || asset.address === asset.path) continue;
entries[asset.address] = { type: asset.type, buildPath: asset.path, ...(atlasFields ?? {}), ...tail };
entries[`/${asset.address}`] = { type: asset.type, buildPath: asset.path, ...(atlasFields ?? {}), ...tail };
}
}
return Object.keys(entries).length > 0 ? Catalog.fromJson({ version: 1, entries }) : undefined;
}
/** Read + index the packaged addressable manifest through the platform's reader. */
export async function loadPackagedAssetIndex(
manifestPath = 'asset-manifest.json',
): Promise<PackagedAssetIndex> {
const manifest = JSON.parse(await platformReadTextFile(manifestPath)) as AddressableManifest;
return indexPackagedManifest(manifest);
}
/** {@link loadPackagedAssetIndex} over an already-parsed manifest. */
export function indexPackagedManifest(manifest: AddressableManifest): PackagedAssetIndex {
const model = ManifestModel.fromJson(manifest);
return {
manifest,
model,
catalog: catalogFromManifest(manifest),
// A scene spells asset refs `@uuid:<v4>`, while the manifest indexes bare
// uuids — strip the prefix before looking up, or every `@uuid:` ref falls
// through as a literal path and 404s.
resolvePath: (ref) => model.resolvePath(extractUuid(ref) ?? ref),
// The authored logical path behind any spelling — its uuid, its logical
// address, or its staged (content-addressed) path. Lets a loader recover the
// directory a sibling was authored in after the rename hid it.
addressOf: (ref) => {
const asset = model.assetByKey(extractUuid(ref) ?? ref) ?? model.assetByPath(ref);
return asset ? (asset.address ?? asset.path) : null;
},
// The logical address where there is one (content-addressed packs rename
// the staged file), else the staged path — either keeps the extension
// .eslocale discovery filters on.
assetPaths: () => model.allAssets().map((a) => a.address ?? a.path),
// Built once per index: a scene preload asks for every texture it uses,
// and rebuilding the spelling map per ref would walk the whole manifest
// each time.
textureImport: model.textureImportLookup(),
spineCulling: model.spineCullingLookup(),
};
}
/** Transport overrides for realms that do not read bytes off a device. */
export interface PackagedAssetSourceOptions {
/** Where bytes come from; the platform's packaged-file reader by default. */
backend?: Backend;
/** Image → RGBA; the platform's decode by default. A cooked web build passes
* a fetch+blob decoder instead: drawing a cross-origin image into a canvas
* taints it, and getImageData then throws. */
decodePixels?: RuntimeAssetSource['decodePixels'];
}
/**
* The asset source a packaged realm runs on: manifest-driven ref resolution over
* whatever transport the realm has. One construction for every realm that ships
* cooked content — a mini-game, a native app, a cooked web build — so a fix to
* how refs or asset listings resolve reaches all three.
*/
export function createPackagedAssetSource(
index: PackagedAssetIndex,
options: PackagedAssetSourceOptions = {},
): RuntimeAssetSource {
return {
backend: options.backend ?? new FileSystemBackend(),
decodePixels: options.decodePixels ?? ((path) => platformLoadImagePixels(path)),
resolveRef: index.resolvePath,
resolveAddress: index.addressOf,
listAssetPaths: index.assetPaths,
textureImportSettings: index.textureImport,
spineCulling: index.spineCulling,
};
}
/**
* Route audio and video refs through the same resolver as every other asset.
* `playSFX` / a video source take plain paths rather than `@uuid:` refs, so
* without this they would miss the logical→staged mapping a cooked build needs —
* one resolution channel, not a parallel base-URL scheme per media type.
*/
export function applyAssetRefResolvers(app: App, resolveRef: (ref: string) => string): void {
if (app.hasResource(Audio)) app.getResource(Audio).setRefResolver(resolveRef);
if (app.hasResource(VideoPlayer)) app.getResource(VideoPlayer).setRefResolver(resolveRef);
}