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.

17.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// Boot the real SDK ECS World over the native (embedded-Dawn) core.
//
// On web the World is connected to the wasm module's embind Registry; here it is
// connected to the native registry + memory backend, both composed from the host's
// generated bindings (createNativeRegistry / NativeMemoryProvider). The result is
// the SAME World class the web build uses — spawn / insert / get / query / parent
// authoring runs in the JS engine, writing the native C++ ECS, which the native
// host renders. No wasm module: entity generations fall back to World's JS path.

import { bindAssetReferenceTracking } from '../../asset/assetReferenceTracking';
import { App, setAppSurfaceSize } from '../../app/app';
import { World } from '../world';
import { inputPlugin } from '../../input/input';
import { prefabsPlugin } from '../../prefab/prefabServer';
import { breakablePlugin } from '../../breakable/breakable';
import { sceneManagerPlugin } from '../../scene/scenePlugin';
import { headlessBasePlugins } from '../../runtime/webAppFactory';
import { presentationBasePlugins, inBuildOrder } from '../../app/pluginSets';
import { entryPlugins } from '../../runtime/entryPlugins';
import { ensureBuiltinComponentsRegistered } from '../component';
import { installNativePlatform, type NativeBridge } from '../../platform/native';
import { createNativeRegistry } from './nativeRegistry';
import { NativeMemoryProvider } from './memoryProvider';
import type { NativeComposition } from './BuiltinBridge';
import { createNativeResourceManager } from './nativeResourceManager';
import { COMPOSITION_BINDINGS, HOST_FLAGS, REGISTRY_BINDINGS, TEXT_BINDINGS, hasTextBindings, hasRendererBindings } from './nativeBindings';
import { createNativeRendererBackend, nativeSurfaceSize } from './nativeRenderer';
import { createNativeEngineApi } from './nativeEngineApi.generated';
import { setNativeEngineApi, engineApi } from './engineApi';
import { createNativeHeap } from './nativeHeap';
import { createNativeSideModules } from './nativeSideModules';
import { initPostProcessAPI } from '../../postprocess';
import { initDrawAPI } from '../../render/draw';
import { initGeometryAPI } from '../../render/geometry';
import { initMaterialAPI } from '../../render/material';
import type { ESEngineModule } from '../../wasm';
import { log } from '../../util/logger';
import { setRendererBackend } from '../../render/renderer';
import { RenderPipeline } from '../../render/renderPipeline';
import { cameraPlugin } from '../../camera/CameraPlugin';
import { applyAppOptions, applyColorSpace, applyFrameOptions, type RenderOptions } from '../../app/renderOptions';
import { UICameraInfo } from '../../ui/core/ui-camera-info';
import { ScreenLayout } from '../../ui/core/screen-layout';
import { ScreenOverlay, defaultScreenOverlay } from '../../ui/core/screen-overlay';
import { DEFAULT_UI_CAMERA_INFO } from '../../app/corePlugin';
import { uiPlugin } from '../../ui/ui-plugin';
import { setNativeTextSubmit } from '../../ui/text/submit';
import { initResourceManager } from '../../wasm/resourceManager';
import { Assets as AssetsClass } from '../../asset/Assets';
import { Assets as AssetsResource } from '../../asset/AssetPlugin';
import { FileSystemBackend } from '../../asset/Backend';
import { platformLoadImagePixels } from '../../platform';

/**
 * Create a World bound to the native core. `scope` is where the host installed its
 * bindings (the QuickJS global object on a device; a plain object in tests). The
 * returned World is the real SDK World — the game script authors entities and
 * components through it, and the native host reads the resulting ECS each frame.
 */
/**
 * The composition seam over the host's two bindings. The epoch is a view over the
 * engine's own word, so a producer STORES rather than calling.
 *
 * A host binding neither leaves the seam absent; `assertNativeBindings` says so at
 * boot rather than at the first frame that does not move.
 */
function nativeTransformComposition(scope: Record<string, unknown>) {
    const buffer = scope[REGISTRY_BINDINGS.transformEpoch];
    const ensure = scope[REGISTRY_BINDINGS.ensureComposed];
    if (typeof buffer !== 'function' || typeof ensure !== 'function') return undefined;
    const bytes = (buffer as () => ArrayBuffer | null)();
    if (!bytes) return undefined;
    // The arena never moves, unlike a growable wasm heap, so one view lasts.
    const epoch = new Uint32Array(bytes, 0, 1);
    const track = scope[COMPOSITION_BINDINGS.setChangeTracking];
    const last = scope[COMPOSITION_BINDINGS.compositionChanges];
    const reports = typeof track === 'function' && typeof last === 'function'
        && typeof scope[COMPOSITION_BINDINGS.takeChanges] === 'function';
    return {
        epoch,
        ensure: () => { (ensure as () => void)(); },
        // A host too old to report the delta simply has no third half, and every
        // consumer of it rebuilds instead.
        setChangeTracking: reports ? (on: boolean) => { (track as (v: boolean) => void)(on); } : undefined,
        compositionChanges: reports ? () => (last as () => NativeComposition)() : undefined,
        takeChanges: reports ? () => { (scope[COMPOSITION_BINDINGS.takeChanges] as () => void)(); } : undefined,
    };
}

export function createNativeWorld(
    scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): World {
    // Idempotent: register every engine component so a scene can't silently drop one
    // (the native entry does this too, but keep the boot self-contained for hosts /
    // tests that call this directly).
    ensureBuiltinComponentsRegistered();

    const world = new World();
    world.connectCpp(createNativeRegistry(scope), undefined, {
        memory: new NativeMemoryProvider(scope),
        transformComposition: nativeTransformComposition(scope),
    });
    return world;
}

/**
 * Boot a native App — the SAME App class the web build uses, over the native core
 * and the native platform. This is the system-binding layer on top of the ECS
 * (Stage B): `installNativePlatform(bridge)` routes the SDK's platform (input, and
 * later assets / audio) to the host's `NativeBridge`; the app runs the standard
 * plugins (input to start) against native ECS. No wasm module and no render plugin
 * — the native C++ host owns rendering and reads the ECS the app authors.
 *
 * The game authors through `app.world` and reads resources like `Input`; drive it
 * with `app.tick(dt)` each frame from the host loop.
 */
export function createNativeApp(
    bridge: NativeBridge,
    scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
    options?: RenderOptions,
): App {
    ensureBuiltinComponentsRegistered();
    // Route the SDK platform to the host before any plugin builds (inputPlugin binds
    // getPlatform().bindInputEvents in build()).
    installNativePlatform(bridge);

    const app = App.new();
    app.connectCpp(createNativeRegistry(scope), undefined, {
        memory: new NativeMemoryProvider(scope),
        transformComposition: nativeTransformComposition(scope),
    });
    // The optional subsystems (physics today) come from the host binary rather than
    // a fetched wasm side module, through the same acquirer the web realms use — so
    // the runtime's own self-gating installs them without knowing the difference.
    app.setSideModules(createNativeSideModules(scope));
    // The same order the web app builds in (see _createWebApp): the frame first,
    // then assets, then the gameplay stack. assetPlugin is the one plugin that
    // cannot be shared as-is — it wires the wasm heap — so installNativeAssets
    // builds the equivalent over the native ResourceManager; prefabs and scene
    // loading declare Assets as a required resource, so it precedes them.
    installNativeEngine(scope);
    // What the project declares about its frame, at the same moments the web app applies it (renderOptions.ts).
    const api = engineApi(app);
    if (api) applyColorSpace(api, options);
    installNativeRenderer(app, scope);
    if (api) applyFrameOptions(api, options);
    installNativeAssets(app, scope);
    installNativeUI(app, scope);
    app.addPlugin(inputPlugin);
    app.addPlugin(prefabsPlugin);
    app.addPlugin(breakablePlugin);
    app.addPlugin(sceneManagerPlugin);
    app.addPlugins(headlessBasePlugins());
    // The presentation stack — the same list the web factory installs. These used to
    // be absent on a device, which is why a scene's tilemaps, particles, trails,
    // meshes and post-process volumes did nothing there: not because the engine
    // cannot draw them (it is the same C++) but because the plugins that drive them
    // reached the core as `app.wasmModule`. They go through `engineApi(app)` now, and
    // each one reports a core that compiles its subsystem out.
    installNativeCoreApis(app);
    // Ordered with the base set, exactly as the web factory does it: every
    // optional subsystem reaches an App through `entryPlugins`, and a factory
    // that names a couple of them by hand ships a device the rest never reach.
    app.addPlugins(inBuildOrder([...presentationBasePlugins(), ...entryPlugins()]));
    applyAppOptions(app, options);
    return app;
}

/**
 * The core-API facets `corePlugin` binds on the web — draw, geometry, material,
 * post-process — need the API connected to the core before the plugins that use
 * them build. A
 * native app does not run corePlugin, so wire the ones this core compiles here,
 * each guarded by an entry point it defines so a core built without one is skipped
 * rather than half-connected. draw/geometry malloc their scratch buffers through
 * the host arena the engine api carries as its heap (installNativeEngine), so the
 * ESEngineModule they expect is satisfied at runtime.
 */
function installNativeCoreApis(app: App): void {
    const engine = engineApi(app);
    if (!engine) return;
    const module = engine as unknown as ESEngineModule;
    if (typeof engine.draw_begin === 'function') initDrawAPI(module);
    if (typeof engine.geometry_create === 'function') initGeometryAPI(module);
    // Materials feed both custom .esshader assets and every post-process pass
    // (its effect shaders compile through material_compileEsshader), so this
    // precedes the post-process wiring below.
    if (typeof engine.material_compileEsshader === 'function') {
        initMaterialAPI(engine);
    } else {
        log.info('material', 'not available — this engine core was built without it');
    }
    if (typeof engine.postprocess_init === 'function') {
        initPostProcessAPI(engine);
    } else {
        log.info('postprocess', 'not available — this engine core was built without it');
    }
}

/**
 * Install the native asset channel — the same `Assets` class the web build uses,
 * over the native core. The native analog of the AssetPlugin / runtimeLoader
 * wiring: no wasm module (the {@link createNativeResourceManager} uploads texture
 * bytes directly), a filesystem backend that reads packaged files through the
 * host `NativeBridge`, and the pixel-decode channel (`bridge.loadImagePixels`)
 * wechat / playable also use — so `Assets.loadTexture(path)` returns a handle the
 * native ResourceManager tracks, replacing hand-rolled host texture creation.
 *
 * Kept deliberately lean (no KTX2 side-module / import-settings / ref-counter
 * wiring yet) — those arrive with the cooked-asset manifest in the export
 * pipeline. Same-signature loaders, so it never diverges from the web channel.
 */
/**
 * Install the frame — the same `CameraPlugin` + `RenderPipeline` the web build
 * runs, over the native core.
 *
 * The native host used to write its own frame in C++: one hard-coded projection,
 * collect, flush, present. Every decision the SDK makes about a frame — which
 * cameras exist, their viewport rects and clear flags, the design-resolution fit,
 * y-sort layers, which scenes are active, what draws just before the flush —
 * either had to be written a second time in C++ or was simply absent on device.
 *
 * With the renderer bindings in place the frame is the SDK's one implementation
 * on both platforms, and the host keeps only what is genuinely its own: the
 * swapchain and the present. Gated on the host having bound the whole surface, so
 * a host that still drives its own frame keeps working.
 */
function installNativeEngine(scope: Record<string, unknown>): void {
    // The engine entry points, by the names the wasm module uses — generated from
    // the same C++ declarations embind registers (nativeEngineApi.generated.ts).
    // With this installed, a plugin that calls uiLayout_update / uiHitTest_* /
    // uiRenderOrder_update reaches the native core without knowing it is native.
    //
    // The heap rides along: an entry point that takes a `…Ptr` needs somewhere for
    // the caller to write the bytes, and on this core that is the host's arena
    // (nativeHeap.ts). Together they make the two cores interchangeable for the
    // subsystems that marshal buffers — tilemaps, particles, post-processing.
    setNativeEngineApi({ ...createNativeEngineApi(scope), ...(createNativeHeap(scope) ?? {}) });
}

function installNativeRenderer(app: App, scope: Record<string, unknown>): void {
    if (!hasRendererBindings(scope)) return;
    setRendererBackend(createNativeRendererBackend(scope));
    app.setPipeline(new RenderPipeline());
    app.insertResource(UICameraInfo, { ...DEFAULT_UI_CAMERA_INFO });
    app.insertResource(ScreenLayout, { ...ScreenLayout._default });
    app.insertResource(ScreenOverlay, defaultScreenOverlay());
    // The viewport is read per frame, so a rotation reaches the projection without
    // anyone pushing a resize event.
    app.addPlugin(cameraPlugin(() => nativeSurfaceSize(scope)));
    // The same answer for anyone else who asks — the debug channel's screenshot
    // read nothing here and reported a host that "did not say what size it draws at".
    setAppSurfaceSize(app, () => nativeSurfaceSize(scope));
    // Tell the host to stop drawing its fallback frame: from here the pipeline
    // above opens and closes every pass, and a second one would clear over it.
    scope[HOST_FLAGS.ownsFrame] = true;
}

/**
 * Install the UI — the same `uiPlugin` the web build runs: layout, masks, safe
 * area, text, interaction, behavior, drag, focus and render order.
 *
 * The plugins drive the engine through {@link engineApi}, which answers with the
 * native host's bindings here and with the wasm module on the web, so none of
 * them had to learn about a second core. Two things text cannot take from the
 * web are the glyph source (the device has no 2D canvas — the host's font stack
 * answers through `PlatformAdapter.rasterizeGlyph`) and the batch submit (no wasm
 * heap — the host takes the typed arrays and calls `RenderFrame::submitTextBatch`
 * itself); everything between, atlas through batching, is one implementation.
 *
 * Gated on the host having bound the text surface: one that has not draws no
 * text, exactly as a host without an audio device stays silent.
 */
function installNativeUI(app: App, scope: Record<string, unknown>): void {
    if (!hasTextBindings(scope)) {
        // Named, because what this drops is the whole UI plugin — layout, masks,
        // interaction, focus — and a host missing one binding looks from the frame
        // like a scene that simply has no UI in it.
        const missing = Object.values(TEXT_BINDINGS).filter((n) => typeof scope[n] !== 'function');
        log.warn('native', `no UI: this host binds no ${missing.join(', ')}, and the UI plugin `
            + 'owns layout and interaction as well as text');
        return;
    }

    // The engine's own renderer_submitTextBatch, generated for QuickJS: same
    // argument list as the wasm call in ui/text/submit.ts, because it IS that
    // call — the typed arrays stand in for the heap pointers, and the entry
    // point's BoundarySpan check runs on the far side either way.
    const submit = scope[TEXT_BINDINGS.submitTextBatch] as (
        vertices: Float32Array, vertexCount: number, indices: Uint16Array, indexCount: number,
        textureId: number, transform: Float32Array, entity: number, layer: number,
        depth: number, glyphMode: number, cullBit: number,
    ) => void;
    setNativeTextSubmit((vertices, vertexCount, indices, textureId, transform, entity, layer, depth, mode, cullBit) => {
        submit(vertices, vertexCount, indices, indices.length, textureId, transform,
               entity, layer, depth, mode, cullBit);
    });
    app.addPlugin(uiPlugin);
}

function installNativeAssets(app: App, scope: Record<string, unknown>): void {
    // The host's es_* texture bindings back the SDK's resource surface, so
    // requireResourceManager() resolves for the whole asset path.
    initResourceManager(createNativeResourceManager(scope));

    const assets = AssetsClass.create({
        backend: new FileSystemBackend(),
        module: null,   // no wasm heap on native — the RM takes bytes directly
    });
    // Textures take the Path-2 pixel-decode route: the platform decodes the image
    // to RGBA (bridge.loadImagePixels), then TextureLoader uploads through the
    // native ResourceManager's createTextureFromBytes. `flip` is applied on upload.
    assets.getTextureLoader().setPixelDecoder((path) => platformLoadImagePixels(path));
    // The same binding the web and packaged factories make: references dropped
    // with their entity, and asset paths written at run time loaded into handles.
    bindAssetReferenceTracking(app.world, assets,
        () => app.hasResource(AssetsResource) ? app.getResource(AssetsResource) : null);
    app.insertResource(AssetsResource, assets);
}