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.

5.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { App, createWebApp as _createWebApp, type Plugin, type WebAppOptions } from '../app/app';
import type { CppRegistry, ESEngineModule } from '../wasm';
import { log } from '../util/logger';
import { assetPlugin } from '../asset';
import { prefabsPlugin } from '../prefab/prefabServer';
import { breakablePlugin } from '../breakable/breakable';
import { sceneManagerPlugin } from '../scene/scenePlugin';
import { seedEngineComponents } from '../ecs/component';
import { uiPlugins } from '../app/uiPlugins';
import { simulationBasePlugins, webBasePlugins, inBuildOrder } from '../app/pluginSets';
import { createFetchSideModuleHost, type SideModuleHost } from '../sideModules';
// The optional subsystems an ENTRY installs. A mini-game inlines the SDK, so a
// subsystem reached from here is in every package whether a project uses it or
// not — 259KB of it, measured. See tools/check-core-carries-options.mjs.
import { entryPlugins } from './entryPlugins';


export interface CreateWebAppOptions extends WebAppOptions {
    /**
     * Convenience for the fetch realms (editor / web / desktop): the base URL the
     * side-module artifacts (physics.wasm, spine38.js/.wasm, …) are served from —
     * usually the same directory as esengine.wasm. Builds a fetch {@link SideModuleHost}
     * when no explicit `sideModules` is given. Realms that inline their modules
     * (playable / WeChat) pass `sideModules` directly instead.
     */
    wasmBaseUrl?: string;
}

// Simulation + presentation, in build order (see pluginSets.ts — one definition,
// so the headless and native factories cannot drift from this one).
const basePlugins = webBasePlugins();



export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {
    // A host built here is this App's alone and ends with it; one passed in may serve others.
    const ownsSideModules = !options?.sideModules && Boolean(options?.wasmBaseUrl);
    const sideModules: SideModuleHost | undefined = options?.sideModules
        ?? (options?.wasmBaseUrl ? createFetchSideModuleHost(options.wasmBaseUrl) : undefined);
    // Spine and DragonBones each fetch their wasm only when asked, so installing
    // them costs nothing at RUN time. BUILD time is what they cost, which is why
    // the entry decides and this does not.

    // Ordered, not concatenated: where a plugin came from is not where it goes.
    const plugins = [...uiPlugins, ...inBuildOrder([...basePlugins, ...entryPlugins()]),
        ...(options?.plugins ?? [])];
    return _createWebApp(module, { ...options, sideModules, ownsSideModules, plugins });
}

export interface HeadlessAppOptions {
    plugins?: Plugin[];
    /** Optional-native-module acquirer (physics on the server). */
    sideModules?: SideModuleHost;
}

/** The simulation stack with no presentation: timers/lifecycle, gameplay AI, audio
 *  (silent on a host with no device) and replication. Presentation plugins exist to
 *  be seen, so a headless app leaves them out — see pluginSets.ts. */
export const headlessBasePlugins = (): Plugin[] => simulationBasePlugins();

/**
 * An App with the full simulation stack and no presentation: no renderer, no
 * render pipeline, no input device, no UI. This is the authoritative-server
 * shape (same wasm module, same gameplay code, same fixed-tick loop) — also
 * useful for workers and tests. Drive it with {@link runHeadless} or
 * `app.tick(dt)`.
 *
 * @beta Pre-1.0: the headless asset story (gameplay data without textures)
 * is still settling and may change this factory's options.
 */
export function createHeadlessApp(module: ESEngineModule, options?: HeadlessAppOptions): App {
    seedEngineComponents();
    const app = App.new();
    if (options?.sideModules) app.setSideModules(options.sideModules);
    const cppRegistry = new module.Registry() as unknown as CppRegistry;
    try {
        app.connectCpp(cppRegistry, module, { strict: true, ownedRegistry: true });

        // No corePlugin: it wires the render facades (ResourceManager, draw,
        // material, post-process) that only exist after initRenderer().
        app.addPlugin(assetPlugin);
        app.addPlugin(prefabsPlugin);
        app.addPlugin(breakablePlugin);
        app.addPlugin(sceneManagerPlugin);
        // A server steps what the client steps: the optional subsystems an entry
        // installed run here too.
        app.addPlugins(inBuildOrder([...headlessBasePlugins(), ...entryPlugins()]));
        if (options?.plugins) app.addPlugins(options.plugins);
        return app;
    } catch (error) {
        try { app.quit({ keepRenderer: true }); }
        catch (releaseError) { log.warn('app', 'Failed headless App construction cleanup error', releaseError); }
        throw error;
    }
}

/**
 * Drive an app on a wall-clock interval (no requestAnimationFrame on a
 * server). Delta is measured, so the fixed-step accumulator keeps simulation
 * cadence exact across timer jitter. Returns a stop function.
 *
 * @beta Pre-1.0: paired with {@link createHeadlessApp}, evolves with it.
 */
export function runHeadless(app: App, options?: { fps?: number }): () => void {
    const intervalMs = 1000 / (options?.fps ?? 60);
    let last = Date.now();
    let ticking = false;
    const timer = setInterval(() => {
        if (ticking) return; // a slow async tick must not pile up re-entrantly
        const now = Date.now();
        const delta = (now - last) / 1000;
        last = now;
        ticking = true;
        void app.tick(delta).finally(() => { ticking = false; });
    }, intervalMs);
    return () => clearInterval(timer);
}