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
fix(native): a rigged model reaches the registry on a device
esenginea149ea6b3419
diff --git a/native/host/bindings/EcsBindings.cpp b/native/host/bindings/EcsBindings.cppindex 16ddf16eb..94df6f6f3 100644--- a/native/host/bindings/EcsBindings.cpp+++ b/native/host/bindings/EcsBindings.cpp@@ -24,6 +24,7 @@#include "esengine/ecs/TransformSystem.hpp" // ecs::setParent#include "esengine/ecs/components/Hierarchy.hpp" // Parent / Children+#include "esengine/ecs/components/Mesh2D.hpp" // MeshSkinusing namespace esengine;@@ -67,6 +68,36 @@ JSValue js_getChildren(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {return arr;}+// MeshSkin's joints are a variable-length entity list, so the component has no POD+// layout and nothing generated can carry it — the same reason Children is here. A+// glTF with a rig inserts one, and without these the insert fails on a device.+JSValue js_getMeshSkinJoints(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {+ JSValue arr = JS_NewArray(ctx);+ if (auto* s = host().registry->tryGet<ecs::MeshSkin>(esn_entity(ctx, argv[0]))) {+ uint32_t i = 0;+ for (Entity joint : s->joints) {+ JS_SetPropertyUint32(ctx, arr, i++, JS_NewUint32(ctx, joint.id()));+ }+ }+ return arr;+}+JSValue js_setMeshSkinJoints(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 2) return JS_UNDEFINED;+ auto& skin = host().registry->getOrEmplace<ecs::MeshSkin>(esn_entity(ctx, argv[0]));+ skin.joints.clear();+ uint32_t len = 0;+ JSValue lenv = JS_GetPropertyStr(ctx, argv[1], "length");+ JS_ToUint32(ctx, &len, lenv);+ JS_FreeValue(ctx, lenv);+ skin.joints.reserve(len);+ for (uint32_t i = 0; i < len; ++i) {+ JSValue v = JS_GetPropertyUint32(ctx, argv[1], i);+ skin.joints.push_back(esn_entity(ctx, v));+ JS_FreeValue(ctx, v);+ }+ return JS_UNDEFINED;+}+} // namespacevoid registerEcsBindings(HostState& h, JSValue global) {@@ -78,6 +109,8 @@ void registerEcsBindings(HostState& h, JSValue global) {bindGlobal(h, global, "es_removeParent", js_removeParent, 1);bindGlobal(h, global, "es_hasChildren", js_hasChildren, 1);bindGlobal(h, global, "es_getChildren", js_getChildren, 1);+ bindGlobal(h, global, "es_getMeshSkinJoints", js_getMeshSkinJoints, 1);+ bindGlobal(h, global, "es_setMeshSkinJoints", js_setMeshSkinJoints, 2);}} // namespace eshostdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 3d3f9aa85..9ffe04168 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -6155,7 +6155,7 @@ static prototype: QueryInstance<any>## REGISTRY_BINDINGS — const @experimental```-{ readonly createEntity: "es_createEntity"; readonly destroyEntity: "es_destroyEntity"; readonly setParent: "es_setParent"; readonly hasParent: "es_hasParent"; readonly getParent: "es_getParent"; readonly removeParent: "es_removeParent"; readonly hasChildren: "es_hasChildren"; readonly getChildren: "es_getChildren"; }+{ readonly createEntity: "es_createEntity"; readonly destroyEntity: "es_destroyEntity"; readonly setParent: "es_setParent"; readonly hasParent: "es_hasParent"; readonly getParent: "es_getParent"; readonly removeParent: "es_removeParent"; readonly hasChildren: "es_hasChildren"; readonly getChildren: "es_getChildren"; readonly getMeshSkinJoints: "es_getMeshSkinJoints"; readonly setMeshSkinJoints: "es_setMeshSkinJoints"; }```## REPLICATION_CHANNEL — const @experimentaldiff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.tsindex 2d6f5d368..df6139c3a 100644--- a/sdk/src/ecs/bridge/nativeBindings.ts+++ b/sdk/src/ecs/bridge/nativeBindings.ts@@ -33,6 +33,10 @@ export const REGISTRY_BINDINGS = {removeParent: 'es_removeParent',hasChildren: 'es_hasChildren',getChildren: 'es_getChildren',+ // MeshSkin's joints are a variable-length entity list, so the component has no+ // POD layout and no generated accessor — the same reason Children is here.+ getMeshSkinJoints: 'es_getMeshSkinJoints',+ setMeshSkinJoints: 'es_setMeshSkinJoints',} as const;/**diff --git a/sdk/src/ecs/bridge/nativeRegistry.ts b/sdk/src/ecs/bridge/nativeRegistry.tsindex 16c23cade..c22bc4c17 100644--- a/sdk/src/ecs/bridge/nativeRegistry.ts+++ b/sdk/src/ecs/bridge/nativeRegistry.ts@@ -121,6 +121,19 @@ export function createNativeRegistry(const kids = (hostCall(scope, REGISTRY_BINDINGS.getChildren, [parent]) as Entity[] | undefined) ?? [];for (const child of kids) hostCall(scope, REGISTRY_BINDINGS.removeParent, [child]);};+ // MeshSkin, the third component with no POD layout: its joints are a variable+ // -length entity list, so it has no ptr accessor and the loop below never+ // reaches it. Without these, every rigged glTF dies at `insertBuiltin(MeshSkin)`.+ reg.hasMeshSkin = (e: Entity): boolean =>+ !!hostCallOpt(scope, `es_MeshSkin_has`, [e]);+ reg.removeMeshSkin = (e: Entity): void => { hostCallOpt(scope, `es_MeshSkin_remove`, [e]); };+ reg.getMeshSkin = (e: Entity): { joints: Entity[] } => ({+ joints: (hostCall(scope, REGISTRY_BINDINGS.getMeshSkinJoints, [e]) as Entity[] | undefined) ?? [],+ });+ reg.addMeshSkin = (e: Entity, data: { joints?: Iterable<Entity> }): void => {+ hostCall(scope, REGISTRY_BINDINGS.setMeshSkinJoints, [e, [...(data.joints ?? [])]]);+ };+reg.delete = (): void => {};// The scene queries the wasm module answers as module-level functions. There isdiff --git a/sdk/tests/native-registry.test.ts b/sdk/tests/native-registry.test.tsindex 7cff8a93f..6bd3a011a 100644--- a/sdk/tests/native-registry.test.ts+++ b/sdk/tests/native-registry.test.ts@@ -150,6 +150,34 @@ describe('createNativeRegistry', () => {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('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.iteratordiff --git a/tools/check-native-components.mjs b/tools/check-native-components.mjsnew file mode 100644index 000000000..eebaf8974--- /dev/null+++ b/tools/check-native-components.mjs@@ -0,0 +1,56 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-native-components — every builtin reaches the registry on a device.+ *+ * `BuiltinBridge` resolves a component through add/get/has/remove, and on a device+ * those come from `createNativeRegistry`: from PTR_ACCESSORS for anything with a+ * POD layout, and by hand for anything without one. A component in neither has no+ * route at all — it throws "C++ Registry missing methods" the first time a scene+ * inserts it, and only on a device.+ *+ * MeshSkin was that for as long as it existed: its joints are a variable-length+ * entity list, so no accessor was generated and the native binding generator wrote+ * `// skip joints … needs a bespoke binding` into code nobody reads. Every rigged+ * glTF was unshippable to a phone and the web build said nothing.+ */+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');++const meta = read('sdk/src/ecs/component.generated.ts');+const components = [...new Set(+ [...meta.matchAll(/^ {4}([A-Z][A-Za-z0-9_]*):\s*\{/gm)].map((m) => m[1]),+)];++const ptrSrc = read('sdk/src/ecs/bridge/ptrAccessors.generated.ts');+const table = /export const PTR_ACCESSORS[^{]*\{([\s\S]*?)\n\};/.exec(ptrSrc);+const withAccessor = new Set(+ table ? [...table[1].matchAll(/^\s+([A-Za-z0-9_]+):/gm)].map((m) => m[1]) : [],+);++// Hand-presented: `reg.add<Name> =` in the native registry, which is how the+// components with no POD layout are given the same four methods.+const regSrc = read('sdk/src/ecs/bridge/nativeRegistry.ts');+const byHand = new Set(+ [...regSrc.matchAll(/reg\.add([A-Z][A-Za-z0-9_]*)\s*=/g)].map((m) => m[1]),+);++const stranded = components.filter((c) => !withAccessor.has(c) && !byHand.has(c));+if (stranded.length) {+ console.error('check-native-components: no route to the registry on a device for '+ + `${stranded.length} component(s):`);+ for (const c of stranded) {+ console.error(` ${c} — no ptr accessor and no reg.add${c} in nativeRegistry.ts`);+ }+ console.error('\nGive it a POD layout, or present it by hand the way MeshSkin and the '+ + 'hierarchy components are.');+ process.exit(1);+}++console.log(`check-native-components: ${components.length} builtin(s) reach the registry on a `+ + `device — ${withAccessor.size} by ptr accessor, ${byHand.size} presented by hand `+ + `(${[...byHand].sort().join(', ')}).`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex c3e45c370..c8a55ad5b 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -75,6 +75,9 @@ export const GATES = [{ id: 'capabilities', run: 'node tools/check-capabilities.mjs' },{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs' },{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },+ // …and that each of them can be reached on a device, where the registry is+ // assembled from ptr accessors rather than from embind.+ { id: 'native-components', run: 'node tools/check-native-components.mjs' },{ id: 'shader-conditionals', run: 'node tools/check-shader-conditionals.mjs' },{ id: 'mesh-vocabulary', run: 'node tools/check-mesh-vocabulary.mjs' },{ id: 'shader-blocks', run: 'node tools/check-shader-blocks.mjs' },