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.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    index.native.ts
 * @brief   ESEngine SDK — native entry point (embedded Dawn + JS engine on
 *          iOS/Android; NOT a WebView). The same engine wasm + TS SDK runs on a
 *          host JavaScriptCore / V8 / Hermes; the C++ renderer binds to a native
 *          WebGPU surface via `{ kind: 'webgpu' }` (see RenderSurfaceSource).
 *
 *          Unlike the web/node/wechat entries, this one does NOT auto-install a
 *          platform: there is no platform until the native shell injects its
 *          {@link NativeBridge}. Boot shape:
 *
 *            import { installNativePlatform, createWebApp } from 'esengine/native';
 *            installNativePlatform(bridge);   // shell provides fs/fetch/input/…
 *            const module = await instantiateEngineWasm(bridge);   // shell-owned
 *            const app = createWebApp(module, {
 *              renderSurface: { kind: 'webgpu' },   // Dawn device set on the module factory
 *            });
 *
 * @beta   Pre-1.0: the native host is unshipped; this entry's shape (and the
 *         NativeBridge contract) will change as the shell lands.
 */
import { ensureBuiltinComponentsRegistered, markEngineComponentBaseline } from './ecs/component';
import { ensureBuiltinAiRegistrations } from './ai/builtins';
import { installNativeModuleRegistry } from './platform/nativeModuleRegistry';

// No setPlatform here — the shell calls installNativePlatform(bridge) at boot.
// Register every engine component / AI name up front so a scene can never silently
// drop one, and snapshot the baseline against a later project hot-reload.
ensureBuiltinComponentsRegistered();
ensureBuiltinAiRegistrations();
markEngineComponentBaseline();

// The public subpath namespaces, from THIS graph, so `Res(Physics3D)` in a game
// names the token the runtime installed. A resolution target, not public API:
// nothing re-exports it and the core namespace stays unflattened.
installNativeModuleRegistry();

export * from './core';
// Installs every optional subsystem on the apps this entry builds; a lean entry
// does not call it and ships without their code.
import { installOptionalPlugins } from './runtime/optionalPlugins';

installOptionalPlugins();
export * from './runtime/webAppFactory';

export { NativePlatformAdapter, installNativePlatform, createHostBridge, assertHostEnvironment, assertNativeHost } from './platform/native';
export type { NativeBridge, NativeInputListener, NativeFetchResult, NativeHostBindings } from './platform/native';

// Fast-path memory backend for the native core. The shell builds one over its
// host-injected `es_<Component>_buffer` bindings and passes it to the bridge
// (BuiltinBridge.connect's `memory` option), so the real SDK component API reads
// and writes native ECS memory through the same generated ptrAccessors as web.
export { NativeMemoryProvider } from './ecs/bridge/memoryProvider';
export type { MemoryProvider, ComponentHeap, NativeComponentBufferFn } from './ecs/bridge/memoryProvider';

// The native component registry — the embind-Registry sibling the SDK's bridge
// drives (add/get/has/remove). Built over the host's es_<Component>_buffer/_has/
// _remove bindings; pass to BuiltinBridge.connect as the cppRegistry.
export { createNativeRegistry } from './ecs/bridge/nativeRegistry';

// The es_* names a host binds, declared once and checked at boot.
export { REGISTRY_BINDINGS, REGISTRY_OPS, RESOURCE_BINDINGS, PLATFORM_BINDINGS, assertNativeBindings } from './ecs/bridge/nativeBindings';

// The native ResourceManager — the embind-ResourceManager sibling the SDK's asset
// pipeline drives (createTexture / releaseTexture / dims). Built over the host's
// es_createTexture / es_releaseTexture / es_getTextureDimensions bindings; uploads
// texture bytes directly (no wasm heap). createNativeApp installs one automatically.
export { createNativeResourceManager } from './ecs/bridge/nativeResourceManager';

// Boot the real SDK ECS World over the native core — the host's entry point for
// running the actual SDK (spawn/insert/query authoring) against native C++ ECS.
export { createNativeWorld } from './ecs/bridge/nativeRuntime';

// Boot a native App: the same App + the native platform (input via the host's
// NativeBridge) + native ECS. The system-binding layer (Stage B) over the World.
export { createNativeApp } from './ecs/bridge/nativeRuntime';

// Boot an EXPORTED project (cooked assets + scenes + game.config.json read off
// the device) rather than a hand-written game script — the native sibling of the
// WeChat runtime and the web game host.
export { initNativeGame } from './runtime/nativeGameRuntime';
export type { NativeGame, NativeGameOptions } from './runtime/nativeGameRuntime';

// ABI layout hash of the component schema this bundle was generated from — the
// native shell compares it against the wasm build it loads (same as the editor).
export { ABI_LAYOUT_HASH } from './ecs/component.generated';