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.

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.cpp
index 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" // MeshSkin
using 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;
+}
+
} // namespace
void 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 eshost
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 @experimental
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index 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.ts
index 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 is
diff --git a/sdk/tests/native-registry.test.ts b/sdk/tests/native-registry.test.ts
index 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.iterator
diff --git a/tools/check-native-components.mjs b/tools/check-native-components.mjs
new file mode 100644
index 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.mjs
index 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' },