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): 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.mdindex 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): ProgressHandlediff --git a/sdk/src/ecs/nativeRegistry.ts b/sdk/src/ecs/nativeRegistry.tsnew file mode 100644index 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.tsindex 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 './plaexport { 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.tsnew file mode 100644index 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.pyindex 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)