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): native component registry — the SDK's ECS lifecycle on the native core

yhh98cf2b6313e4
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 5073d5300..45dc69ebd 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: 1326 stable · 22 beta · 0 deprecated
+Symbols: 1327 stable · 22 beta · 0 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -8438,6 +8438,11 @@ Plugin
(options?: MemoryTransportOptions): [MemoryTransport, MemoryTransport]
```
+## createNativeRegistry — function
+```
+(scope?: Record<string, unknown>): CppRegistry
+```
+
## createProgress — function
```
(opts: ProgressOptions): ProgressHandle
diff --git a/sdk/src/ecs/nativeRegistry.ts b/sdk/src/ecs/nativeRegistry.ts
new file mode 100644
index 000000000..e19b8a944
--- /dev/null
+++ b/sdk/src/ecs/nativeRegistry.ts
@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+//
+// The native component registry — the embedded-Dawn sibling of the embind-bound
+// C++ Registry. It presents the exact surface BuiltinBridge.getBuiltinMethods
+// consumes (add<Name> / get<Name> / has<Name> / remove<Name> per component), so
+// the real SDK component API runs on the native core unchanged.
+//
+// It is composed, not a second marshaller: field IO reuses the generated
+// ptrAccessors (the one marshalling path, proven on device) over the host's
+// zero-copy es_<Component>_buffer binding; lifecycle reuses the generated
+// es_<Component>_has / _remove bindings. The only shape bridge is color naming —
+// embind marshals colors as {x,y,z,w}, ptrAccessors as {r,g,b,a} — handled by the
+// same convertForWasm/convertFromWasm the web methods path uses, keyed off
+// COMPONENT_META.colorFields.
+
+import type { CppRegistry } from '../wasm';
+import type { Entity } from '../types';
+import { PTR_ACCESSORS } from './ptrAccessors.generated';
+import { COMPONENT_META } from '../component.generated';
+import { convertForWasm, convertFromWasm } from './BuiltinBridge';
+
+/** A host-injected entity->ArrayBuffer accessor over one native ECS component. */
+type BufferFn = (entity: number) => ArrayBuffer | null | undefined;
+type HasFn = (entity: number) => boolean;
+type RemoveFn = (entity: number) => void;
+
+function views(buf: ArrayBuffer): [Float32Array, Uint32Array, Uint8Array] {
+ return [new Float32Array(buf), new Uint32Array(buf), new Uint8Array(buf)];
+}
+
+/**
+ * Build a CppRegistry over the host's native component bindings. `scope` holds the
+ * generated `es_<Component>_buffer` / `_has` / `_remove` globals (the QuickJS
+ * global object on a device; a plain object in tests). Only components whose three
+ * bindings are present get methods, so a host that binds a subset still connects.
+ */
+export function createNativeRegistry(
+ scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
+): CppRegistry {
+ const reg: Record<string, unknown> = {};
+
+ for (const cppName of Object.keys(PTR_ACCESSORS)) {
+ const accessor = PTR_ACCESSORS[cppName];
+ const bufFn = scope[`es_${cppName}_buffer`] as BufferFn | undefined; // getOrEmplace = add
+ const hasFn = scope[`es_${cppName}_has`] as HasFn | undefined;
+ const removeFn = scope[`es_${cppName}_remove`] as RemoveFn | undefined;
+ if (typeof bufFn !== 'function' || typeof hasFn !== 'function'
+ || typeof removeFn !== 'function') {
+ continue;
+ }
+ const colorFields = (COMPONENT_META[cppName]?.colorFields ?? []) as readonly string[];
+
+ // add: emplace (the buffer binding getOrEmplaces) + write every field. The
+ // SDK hands embind-shape data ({x,y,z,w} colors); ptrAccessors want
+ // {r,g,b,a}, so bridge colors back before writing.
+ reg[`add${cppName}`] = (entity: Entity, data: Record<string, unknown>): void => {
+ const buf = bufFn(entity);
+ if (!buf) return;
+ const ptrData = colorFields.length ? convertFromWasm(data, colorFields) : data;
+ const [f32, u32, u8] = views(buf);
+ accessor.write(f32, u32, u8, 0, ptrData);
+ };
+
+ // get: read into a fresh object (embind returns fresh, so callers may
+ // retain it), then present colors in embind {x,y,z,w} shape for the SDK,
+ // which converts them back. Never creates: checks has first.
+ reg[`get${cppName}`] = (entity: Entity): unknown => {
+ const out = accessor.create() as Record<string, unknown>;
+ if (hasFn(entity)) {
+ const buf = bufFn(entity);
+ if (buf) {
+ const [f32, u32, u8] = views(buf);
+ accessor.fill(f32, u32, u8, 0, out);
+ }
+ }
+ return colorFields.length ? convertForWasm(out, colorFields) : out;
+ };
+
+ reg[`has${cppName}`] = (entity: Entity): boolean => hasFn(entity);
+ reg[`remove${cppName}`] = (entity: Entity): void => { removeFn(entity); };
+ }
+
+ return reg as unknown as CppRegistry;
+}
diff --git a/sdk/src/index.native.ts b/sdk/src/index.native.ts
index f52be1739..388e14e7e 100644
--- a/sdk/src/index.native.ts
+++ b/sdk/src/index.native.ts
@@ -44,6 +44,11 @@ export type { NativeBridge, NativeInputListener, NativeFetchResult } from './pla
export { NativeMemoryProvider } from './ecs/memoryProvider';
export type { MemoryProvider, ComponentHeap, NativeComponentBufferFn } from './ecs/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/nativeRegistry';
+
// 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-registry.test.ts b/sdk/tests/native-registry.test.ts
new file mode 100644
index 000000000..c3b1e6495
--- /dev/null
+++ b/sdk/tests/native-registry.test.ts
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file native-registry.test.ts
+ * @brief The native component registry (embind-Registry sibling). A mock host
+ * scope backs es_<C>_buffer/_has/_remove with JS ArrayBuffers + a Set,
+ * so the full SDK component API (BuiltinBridge.insert/get/has/remove +
+ * the fast path) runs on the native backend end-to-end, headless, no
+ * device — proving Stage A: one SDK, native core.
+ */
+import { describe, expect, it } from 'vitest';
+import { BuiltinBridge } from '../src/ecs/BuiltinBridge';
+import { createNativeRegistry } from '../src/ecs/nativeRegistry';
+import { NativeMemoryProvider } from '../src/ecs/memoryProvider';
+import { PTR_ACCESSORS } from '../src/ecs/ptrAccessors.generated';
+import { Sprite } from '../src/component';
+
+/**
+ * A fake native host: each component's storage is an entity->ArrayBuffer map, with
+ * the three generated bindings the SDK expects. es_<C>_buffer getOrEmplaces (mirrors
+ * the native binding); _has / _remove complete the lifecycle.
+ */
+function mockNativeScope(byteSize = 256): Record<string, unknown> {
+ const scope: Record<string, unknown> = {};
+ for (const cppName of Object.keys(PTR_ACCESSORS)) {
+ const store = new Map<number, ArrayBuffer>();
+ scope[`es_${cppName}_buffer`] = (e: number) => {
+ let b = store.get(e);
+ if (!b) { b = new ArrayBuffer(byteSize); store.set(e, b); }
+ return b;
+ };
+ scope[`es_${cppName}_has`] = (e: number) => store.has(e);
+ scope[`es_${cppName}_remove`] = (e: number) => { store.delete(e); };
+ }
+ return scope;
+}
+
+describe('createNativeRegistry', () => {
+ it('round-trips a component through add / has / get / remove (embind shape)', () => {
+ const reg = createNativeRegistry(mockNativeScope()) as unknown as Record<string, Function>;
+
+ expect(reg.hasSprite(1)).toBe(false);
+ // add takes a full component (the SDK always merges defaults first). Start
+ // from the generated defaults, then restate color in embind {x,y,z,w} shape.
+ const data = PTR_ACCESSORS.Sprite.create() as Record<string, any>;
+ data.color = { x: 0.5, y: 0.25, z: 0.125, w: 1 };
+ data.size = { x: 12, y: 34 };
+ data.lit = true;
+ reg.addSprite(1, data);
+ expect(reg.hasSprite(1)).toBe(true);
+
+ const got = reg.getSprite(1) as Record<string, any>;
+ // get returns embind shape ({x,y,z,w}) for the SDK boundary.
+ expect(got.color.x).toBeCloseTo(0.5);
+ expect(got.color.y).toBeCloseTo(0.25);
+ expect(got.color.z).toBeCloseTo(0.125);
+ expect(got.size).toMatchObject({ x: 12, y: 34 });
+ expect(got.lit).toBe(true);
+
+ reg.removeSprite(1);
+ expect(reg.hasSprite(1)).toBe(false);
+ });
+
+ it('drives the real SDK BuiltinBridge lifecycle on the native backend', () => {
+ const scope = mockNativeScope();
+ const reg = createNativeRegistry(scope);
+ const bridge = new BuiltinBridge();
+ // No wasm module — the native memory backend + registry stand in for it.
+ bridge.connect(reg, undefined, { memory: new NativeMemoryProvider(scope) });
+
+ const e = 42;
+ expect(bridge.has(e, Sprite)).toBe(false);
+
+ // insert() speaks the SDK {r,g,b,a} color shape; convertForWasm + the
+ // registry's convertFromWasm bridge it to native memory and back.
+ const { isNew } = bridge.insert(e, Sprite, {
+ color: { r: 0.5, g: 0.25, b: 0.125, a: 1 },
+ size: { x: 20, y: 40 },
+ lit: true,
+ });
+ expect(isNew).toBe(true);
+ expect(bridge.has(e, Sprite)).toBe(true);
+
+ const sprite = bridge.get(e, Sprite) as { color: any; size: any; lit: boolean };
+ expect(sprite.color.r).toBeCloseTo(0.5);
+ expect(sprite.color.g).toBeCloseTo(0.25);
+ expect(sprite.color.b).toBeCloseTo(0.125);
+ expect(sprite.color.a).toBeCloseTo(1);
+ expect(sprite.size).toMatchObject({ x: 20, y: 40 });
+ expect(sprite.lit).toBe(true);
+ });
+
+ it('get never creates a component (has stays false)', () => {
+ const scope = mockNativeScope();
+ const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
+ reg.getSprite(9); // read a missing component
+ expect(reg.hasSprite(9)).toBe(false); // must not have emplaced it
+ });
+
+ it('skips components whose host bindings are absent', () => {
+ // Only Sprite is bound; other components must not get registry methods.
+ const scope: Record<string, unknown> = {
+ es_Sprite_buffer: (_e: number) => new ArrayBuffer(256),
+ es_Sprite_has: (_e: number) => false,
+ es_Sprite_remove: (_e: number) => {},
+ };
+ const reg = createNativeRegistry(scope) as unknown as Record<string, unknown>;
+ expect(typeof reg.addSprite).toBe('function');
+ expect(reg.addTransform).toBeUndefined();
+ });
+});
diff --git a/tools/eht/generators/native_bindings.py b/tools/eht/generators/native_bindings.py
index a9ebeabb6..539cdf1cf 100644
--- a/tools/eht/generators/native_bindings.py
+++ b/tools/eht/generators/native_bindings.py
@@ -73,12 +73,27 @@ class NativeBindingsGenerator:
# Fast path: es_<Component>_buffer(entityId) -> a zero-copy ArrayBuffer over
# the native component, which the shared generated ptrAccessors write. Same
# POD layout as wasm32, so ptrAccessors.generated.ts works unchanged.
+ # getOrEmplace so a first write (component add) also creates the component.
out.append(f'static JSValue es_{comp.name}_buffer(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {{')
out.append(' if (argc < 1) return JS_UNDEFINED;')
out.append(' esengine::Entity e = esn_entity(ctx, argv[0]);')
out.append(f' auto& c = esn_reg().getOrEmplace<{full}>(e);')
out.append(f' return esn_arraybuffer(ctx, &c, sizeof({full}));')
out.append('}')
+ # Lifecycle: the native siblings of the embind Registry's has/remove. With
+ # the buffer (getOrEmplace = add) + ptrAccessors (fields), these complete the
+ # component API the SDK's BuiltinBridge drives (getBuiltinMethods).
+ out.append(f'static JSValue es_{comp.name}_has(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {{')
+ out.append(' if (argc < 1) return JS_UNDEFINED;')
+ out.append(' esengine::Entity e = esn_entity(ctx, argv[0]);')
+ out.append(f' return JS_NewBool(ctx, esn_reg().has<{full}>(e));')
+ out.append('}')
+ out.append(f'static JSValue es_{comp.name}_remove(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {{')
+ out.append(' if (argc < 1) return JS_UNDEFINED;')
+ out.append(' esengine::Entity e = esn_entity(ctx, argv[0]);')
+ out.append(f' if (esn_reg().has<{full}>(e)) esn_reg().remove<{full}>(e);')
+ out.append(' return JS_UNDEFINED;')
+ out.append('}')
out.append('')
return out
@@ -109,10 +124,16 @@ class NativeBindingsGenerator:
for comp in components:
setter = f'es_set_{comp.name}'
buffer = f'es_{comp.name}_buffer'
+ has = f'es_{comp.name}_has'
+ remove = f'es_{comp.name}_remove'
lines.append(f' JS_SetPropertyStr(ctx, global, "{setter}", '
f'JS_NewCFunction(ctx, {setter}, "{setter}", 2));')
lines.append(f' JS_SetPropertyStr(ctx, global, "{buffer}", '
f'JS_NewCFunction(ctx, {buffer}, "{buffer}", 1));')
+ lines.append(f' JS_SetPropertyStr(ctx, global, "{has}", '
+ f'JS_NewCFunction(ctx, {has}, "{has}", 1));')
+ lines.append(f' JS_SetPropertyStr(ctx, global, "{remove}", '
+ f'JS_NewCFunction(ctx, {remove}, "{remove}", 1));')
lines.append('}')
lines.append('')
return '\n'.join(lines)