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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(native): createNativeApp — native App runtime + input via NativeBridge (Stage B)
yhh609df3987066
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 9cac53e0f..6235449ed 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1328 stable · 22 beta · 0 deprecated+Symbols: 1329 stable · 22 beta · 0 deprecated## ABI_LAYOUT_HASH — const```@@ -8438,6 +8438,11 @@ Plugin(options?: MemoryTransportOptions): [MemoryTransport, MemoryTransport]```+## createNativeApp — function+```+(bridge: NativeBridge, scope?: Record<string, unknown>): App+```+## createNativeRegistry — function```(scope?: Record<string, unknown>): CppRegistrydiff --git a/sdk/src/ecs/nativeRuntime.ts b/sdk/src/ecs/nativeRuntime.tsindex da01b030f..17b1fe8d1 100644--- a/sdk/src/ecs/nativeRuntime.ts+++ b/sdk/src/ecs/nativeRuntime.ts@@ -10,8 +10,11 @@// 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 { App } from '../app';import { World } from '../world';+import { inputPlugin } from '../input';import { ensureBuiltinComponentsRegistered } from '../component';+import { installNativePlatform, type NativeBridge } from '../platform/native';import { createNativeRegistry } from './nativeRegistry';import { NativeMemoryProvider } from './memoryProvider';@@ -35,3 +38,31 @@ export function createNativeWorld(});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>,+): 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),+ });+ app.addPlugin(inputPlugin);+ return app;+}diff --git a/sdk/src/index.native.ts b/sdk/src/index.native.tsindex 00484c9a4..ac37a78f7 100644--- a/sdk/src/index.native.ts+++ b/sdk/src/index.native.ts@@ -53,6 +53,10 @@ export { createNativeRegistry } from './ecs/nativeRegistry';// running the actual SDK (spawn/insert/query authoring) against native C++ ECS.export { createNativeWorld } from './ecs/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/nativeRuntime';+// 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 './component.generated';diff --git a/sdk/tests/native-app-input.test.ts b/sdk/tests/native-app-input.test.tsnew file mode 100644index 000000000..a0cc246b8--- /dev/null+++ b/sdk/tests/native-app-input.test.ts@@ -0,0 +1,64 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file native-app-input.test.ts+ * @brief The native App runtime (Stage B foundation): the same App + the native+ * platform. A mock NativeBridge captures the input listener the SDK's real+ * inputPlugin subscribes, so host touch flows through the actual+ * inputPlugin -> native adapter -> Input resource path, headless.+ */+import { describe, expect, it } from 'vitest';+import { createNativeApp } from '../src/ecs/nativeRuntime';+import { Input } from '../src/input';+import type { NativeBridge, NativeInputListener } from '../src/platform/native/bridge';++/** A NativeBridge whose registerInput captures the engine's listener; everything+ * else is a stub (input needs none of it). */+function makeBridge() {+ let listener: NativeInputListener | null = null;+ const bridge: NativeBridge = {+ readFile: async () => new ArrayBuffer(0),+ fileExists: async () => false,+ fetch: async () => ({ ok: false, status: 404 }),+ loadImagePixels: async () => ({ width: 0, height: 0, pixels: new Uint8Array(0) }),+ getStorageItem: () => null,+ setStorageItem: () => {},+ removeStorageItem: () => {},+ storageKeys: () => [],+ registerInput: (l) => { listener = l; return () => { listener = null; }; },+ devicePixelRatio: () => 1,+ };+ return { bridge, listener: () => listener };+}++describe('createNativeApp', () => {+ it('routes host touch through the real input plugin to the Input resource', async () => {+ const { bridge, listener } = makeBridge();+ const app = createNativeApp(bridge, {});++ // First tick finishes plugin builds: inputPlugin.build calls+ // getPlatform().bindInputEvents, which registers with the host bridge.+ await app.tick(0);+ const l = listener();+ expect(l).not.toBeNull(); // the SDK subscribed to host input++ // The host pushes touch; the native adapter synthesizes the primary pointer.+ l!.onTouchStart(0, 100, 200);+ l!.onTouchMove(0, 150, 250);+ await app.tick(1 / 60);++ const input = app.getResource(Input);+ expect(input.getMousePosition()).toEqual({ x: 150, y: 250 });++ l!.onTouchEnd(0);+ await app.tick(1 / 60);+ });++ it('gives the game the real World over the native core', async () => {+ const { bridge } = makeBridge();+ const app = createNativeApp(bridge, {});+ await app.tick(0);+ expect(app.world).toBeDefined();+ expect(app.world.hasCpp).toBe(true); // connected to the native registry+ });+});