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.

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