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.

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.md
index 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>): CppRegistry
diff --git a/sdk/src/ecs/nativeRuntime.ts b/sdk/src/ecs/nativeRuntime.ts
index 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.ts
index 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.ts
new file mode 100644
index 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
+ });
+});