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
// 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/bridge/BuiltinBridge';
import { createNativeRegistry } from '../src/ecs/bridge/nativeRegistry';
import { NativeMemoryProvider } from '../src/ecs/bridge/memoryProvider';
import { PTR_ACCESSORS } from '../src/ecs/bridge/ptrAccessors.generated';
import { Sprite } from '../src/ecs/component';
import { COMPONENT_META } from '../src/ecs/component.generated';
import { INSPECTION_BINDINGS, REGISTRY_BINDINGS, REGISTRY_OPS } from '../src/ecs/bridge/nativeBindings';
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
/**
* 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('uses optional bulk membership on hosts that provide it', () => {
const calls: number[] = [];
const reg = createNativeRegistry({ es_getBuiltinComponentNames: (entity: number) => {
calls.push(entity);
return 'Name|Sprite';
} });
expect(reg.getBuiltinComponentNames!(12 as never)).toBe('Name|Sprite');
expect(calls).toEqual([12]);
expect(createNativeRegistry({}).getBuiltinComponentNames).toBeUndefined();
});
it('resolves a three-byte native component without constructing misaligned word views', () => {
const buffer = new ArrayBuffer(3);
const resolve = new NativeMemoryProvider({ es_Interactable_buffer: () => buffer })
.resolveComponentHeap('Interactable')!;
const heap = {} as Parameters<typeof resolve>[1];
expect(resolve(1 as never, heap)).toBe(true);
expect(heap.f32.length).toBe(0);
expect(heap.u32.length).toBe(0);
expect(heap.u8.length).toBe(3);
});
it('round-trips native owned strings and scalars without wasm-offset access', () => {
const components = new Map<number, Record<string, unknown>>();
const scope = {
es_set_SpineAnimation: (e: number, data: Record<string, unknown>) => {
components.set(e, { ...components.get(e), ...structuredClone(data) });
},
es_get_SpineAnimation: (e: number) => structuredClone(components.get(e)!),
es_SpineAnimation_has: (e: number) => components.has(e),
es_SpineAnimation_remove: (e: number) => components.delete(e),
};
const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
expect(new NativeMemoryProvider(scope).resolveComponentHeap('SpineAnimation')).toBeNull();
expect(reg.getSpineAnimation(1)).toEqual({});
expect(components.size).toBe(0);
const data = { skeletonPath: 'assets/骨骼.json', atlasPath: 'long/path/'.repeat(8),
skin: 'default', animation: 'walk', timeScale: 0.5, enabled: true,
color: { x: 0.25, y: 0.5, z: 0.75, w: 1 } };
reg.addSpineAnimation(1, data);
reg.addSpineAnimation(1, { timeScale: 2, animation: 'run' });
const got = reg.getSpineAnimation(1);
expect(got).toEqual({ ...data, timeScale: 2, animation: 'run' });
got.skeletonPath = 'changed';
expect(reg.getSpineAnimation(1).skeletonPath).toBe(data.skeletonPath);
reg.removeSpineAnimation(1);
expect(reg.hasSpineAnimation(1)).toBe(false);
});
it('keeps fields following a native vector and preserves lists on scalar updates', () => {
let component: Record<string, unknown> | undefined;
let path: unknown[] = [];
const reg = createNativeRegistry({
es_set_ShadowCaster2D: (_e: number, data: Record<string, unknown>) => {
component = { ...component, ...data };
},
es_get_ShadowCaster2D: () => ({ size: component?.size, enabled: component?.enabled }),
es_ShadowCaster2D_has: () => !!component,
es_ShadowCaster2D_remove: () => { component = undefined; },
es_ShadowCaster2D_path_set: (_e: number, value: unknown[]) => { path = structuredClone(value); },
es_ShadowCaster2D_path_get: () => structuredClone(path),
}) as unknown as Record<string, Function>;
reg.addShadowCaster2D(1, { size: { x: 32, y: 48 }, enabled: true,
path: [{ x: 1, y: 2 }, { x: 3, y: 4 }] });
reg.addShadowCaster2D(1, { enabled: false });
expect(reg.getShadowCaster2D(1)).toEqual({ size: { x: 32, y: 48 }, enabled: false,
path: [{ x: 1, y: 2 }, { x: 3, y: 4 }] });
});
it('forwards shared destruction ownership to the host', () => {
const pending = new Set<number>();
const reg = createNativeRegistry({
es_registry_reserveDestruction: (e: number) => { if (pending.has(e)) return false; pending.add(e); return true; },
es_registry_releaseDestruction: (e: number) => { pending.delete(e); },
es_registry_destructionPending: (e: number) => pending.has(e),
});
expect(reg.reserveDestruction(1 as never)).toBe(true);
expect(reg.reserveDestruction(1 as never)).toBe(false);
expect(reg.destructionPending(1 as never)).toBe(true);
reg.releaseDestruction(1 as never);
expect(reg.destructionPending(1 as never)).toBe(false);
});
it('forwards entity activity to the host', () => {
let enabled = true;
const reg = createNativeRegistry({
es_registry_setEntityEnabled: (_e: number, value: boolean) => { enabled = value; return true; },
es_registry_isEntityEnabled: () => enabled,
es_registry_isEntityActive: () => enabled,
es_registry_hasInactiveEntities: () => !enabled,
es_registry_activityEpoch: () => 7,
});
expect(reg.setEntityEnabled(1 as never, false)).toBe(true);
expect(reg.isEntityEnabled(1 as never)).toBe(false);
expect(reg.isEntityActive(1 as never)).toBe(false);
expect(reg.hasInactiveEntities()).toBe(true);
expect(reg.activityEpoch()).toBe(7);
});
// #114: `valid` was the one op the native registry lacked, and the mutation
// reader's subtree walk called it, so PhysicsStepSystem threw every frame.
it('asks the host whether an entity is alive, destroyed ones included', () => {
const alive = new Set([42]);
const reg = createNativeRegistry({ es_registry_valid: (e: number) => alive.has(e) });
expect(reg.valid(42 as never)).toBe(true);
expect(reg.valid(43 as never)).toBe(false);
alive.delete(42);
expect(reg.valid(42 as never)).toBe(false);
});
it('names the binding when a host left an op unbound', () => {
expect(() => createNativeRegistry({}).valid(1 as never)).toThrow(/es_registry_valid/);
});
// The class of #114, not the instance: every non-component method the web's
// embind Registry has, the native registry has too. Read from the generated
// bindings, so a method added to embind without a native route fails here.
it('has every entity-level method the embind Registry has', () => {
const cpp = readFileSync(resolve(__dirname, '../../src/esengine/bindings/WebBindings.generated.cpp'), 'utf8');
const block = cpp.slice(cpp.indexOf('EMSCRIPTEN_BINDINGS(esengine_registry)'));
const perComponent = new Set(Object.keys(COMPONENT_META).flatMap(
(c) => ['has', 'get', 'add', 'remove'].map((verb) => `${verb}${c}`)));
const web = [...block.slice(0, block.indexOf('\n}')).matchAll(/\.function\("(\w+)"/g)]
.map((m) => m[1]).filter((name) => !perComponent.has(name));
expect(web).toContain('valid');
const scope: Record<string, unknown> = {};
for (const name of [...Object.values(REGISTRY_OPS), ...Object.values(REGISTRY_BINDINGS),
...Object.values(INSPECTION_BINDINGS)]) scope[name] = () => undefined;
const reg = createNativeRegistry(scope) as unknown as Record<string, unknown>;
expect(web.filter((name) => typeof reg[name] !== 'function')).toEqual([]);
});
it.each([true, false])('forwards native hierarchy acceptance %s', (accepted) => {
const reg = createNativeRegistry({ es_registry_setParent: () => accepted });
expect(reg.setParent(1 as never, 2 as never)).toBe(accepted);
});
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('adds a component whose native struct is not 4-byte aligned (Interactable is 3 bytes)', () => {
// The host returns a buffer the exact size of the component. Interactable is
// three bools = 3 bytes, not a multiple of 4, so building a Float32Array over
// the whole buffer throws "invalid length" on QuickJS. views() must cover only
// the 4-aligned prefix for the word views and the whole buffer for the byte view.
const store = new Map<number, ArrayBuffer>();
const scope: Record<string, unknown> = {
es_Interactable_buffer: (e: number) => {
let b = store.get(e);
if (!b) { b = new ArrayBuffer(3); store.set(e, b); }
return b;
},
es_Interactable_has: (e: number) => store.has(e),
es_Interactable_remove: (e: number) => { store.delete(e); },
};
const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
const data = PTR_ACCESSORS.Interactable.create() as Record<string, unknown>;
data.enabled = true; data.blockRaycast = false; data.raycastTarget = true;
expect(() => reg.addInteractable(1, data)).not.toThrow();
const got = reg.getInteractable(1) as Record<string, boolean>;
expect(got.enabled).toBe(true);
expect(got.blockRaycast).toBe(false);
expect(got.raycastTarget).toBe(true);
});
it('exposes Parent/Children the component way over the native entity-ops', () => {
// BuiltinBridge.getBuiltinMethods requires add/get/has/remove for the hierarchy
// components — the physics and hierarchy systems read them that way. The host
// binds only entity-ops (setParent/getParent/getChildren); the registry adapts.
const parents = new Map<number, number>();
const children = new Map<number, number[]>();
const scope: Record<string, unknown> = {
es_registry_setParent: (c: number, p: number) => {
parents.set(c, p);
(children.get(p) ?? children.set(p, []).get(p)!).push(c);
},
es_getParent: (c: number) => parents.get(c) ?? 0,
es_hasParent: (c: number) => parents.has(c),
es_removeParent: (c: number) => { parents.delete(c); },
es_hasChildren: (p: number) => (children.get(p)?.length ?? 0) > 0,
es_getChildren: (p: number) => children.get(p) ?? [],
};
const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
for (const m of ['addParent', 'getParent', 'hasParent', 'removeParent',
'addChildren', 'getChildren', 'hasChildren', 'removeChildren']) {
expect(typeof reg[m]).toBe('function');
}
reg.addParent(2, { entity: 1 });
expect(reg.hasParent(2)).toBe(true);
expect((reg.getParent(2) as { entity: number }).entity).toBe(1);
expect(reg.hasChildren(1)).toBe(true);
});
it('exposes MeshSkin the component way — its joints have no POD layout', () => {
// The third component outside PTR_ACCESSORS, and the one a rigged glTF
// inserts: without these four, a skinned model on a device died at
// `insertBuiltin(MeshSkin)` with "C++ Registry missing methods".
const skins = new Map<number, number[]>();
const scope: Record<string, unknown> = {
es_setMeshSkinJoints: (e: number, ids: number[]) => { skins.set(e, [...ids]); },
es_getMeshSkinJoints: (e: number) => skins.get(e) ?? [],
es_MeshSkin_has: (e: number) => skins.has(e),
es_MeshSkin_remove: (e: number) => { skins.delete(e); },
};
const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
for (const m of ['addMeshSkin', 'getMeshSkin', 'hasMeshSkin', 'removeMeshSkin']) {
expect(typeof reg[m]).toBe('function');
}
expect(reg.hasMeshSkin(4)).toBe(false);
reg.addMeshSkin(4, { joints: [7, 8, 9] });
expect(reg.hasMeshSkin(4)).toBe(true);
expect((reg.getMeshSkin(4) as { joints: number[] }).joints).toEqual([7, 8, 9]);
// The order IS the meaning: entry i drives joint i of the bind matrices.
reg.addMeshSkin(4, { joints: [9, 8, 7] });
expect((reg.getMeshSkin(4) as { joints: number[] }).joints).toEqual([9, 8, 7]);
reg.removeMeshSkin(4);
expect(reg.hasMeshSkin(4)).toBe(false);
expect((reg.getMeshSkin(4) as { joints: number[] }).joints).toEqual([]);
});
it('a list field crosses by its own pair, beside the buffer the rest goes through', () => {
// ShadowCaster2D is the first component with BOTH a POD field the accessors
// write into the zero-copy buffer and one whose storage is a pointer. Skip
// the pair and a native game's polygon walls silently become boxes.
const paths = new Map<number, unknown>();
const buffers = new Map<number, ArrayBuffer>();
const scope: Record<string, unknown> = {
es_ShadowCaster2D_buffer: (e: number) => {
let b = buffers.get(e);
if (!b) { b = new ArrayBuffer(64); buffers.set(e, b); }
return b;
},
es_ShadowCaster2D_has: (e: number) => buffers.has(e),
es_ShadowCaster2D_remove: (e: number) => { buffers.delete(e); paths.delete(e); },
es_ShadowCaster2D_path_set: (e: number, v: unknown) => { paths.set(e, v); },
es_ShadowCaster2D_path_get: (e: number) => paths.get(e) ?? [],
};
const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
const outline = [{ x: -1, y: -1 }, { x: 1, y: -1 }, { x: 0, y: 2 }];
reg.addShadowCaster2D(3, { size: { x: 20, y: 20 }, path: outline, enabled: true });
const got = reg.getShadowCaster2D(3) as { size: { x: number }; path: unknown };
expect(got.path).toEqual(outline);
expect(got.size.x).toBe(20);
// A caster authored with no outline says so, rather than keeping the last one.
reg.addShadowCaster2D(3, { size: { x: 20, y: 20 }, enabled: true });
expect((reg.getShadowCaster2D(3) as { path: unknown }).path).toEqual([]);
});
it('getChildren.entities is iterable (for...of) as well as vector-shaped', () => {
// The timeline/animator child-path resolver walks children with a for-of and
// types the field `Entity[]`; the VectorEntity shim must answer Symbol.iterator
// too, or that for-of throws "value is not iterable" on the native backend.
const scope: Record<string, unknown> = {
es_getChildren: (_p: number) => [10, 11, 12],
es_hasChildren: (_p: number) => true,
};
const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
const kids = (reg.getChildren(1) as { entities: Iterable<number> }).entities;
expect([...kids]).toEqual([10, 11, 12]);
const seen: number[] = [];
for (const c of kids) seen.push(c);
expect(seen).toEqual([10, 11, 12]);
});
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();
});
});