Skip to content

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.

19.3 KB
Raw Blame
// 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);
}