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(mesh): a rig too big to pose says so instead of coming apart

esenginecff49d7780a1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 75f26e446..228d38be5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,6 +39,25 @@ published separately; it ships inside the editor.
### Fixed
+- **A rig too big to pose says so, instead of coming apart.** A draw is posed by
+ a uniform block of 64 bone matrices; a skin binding more joints than that had
+ its extra ones indexing a matrix nobody uploaded, and the vertices they move
+ went somewhere arbitrary. Nothing said a word — not the importer, which wrote
+ the joint channel whatever the count, and not the renderer, which posed the
+ first 64 and drew the rest wrong. A rig with fingers passes 64 easily.
+
+ Both importers now read an over-budget skin the way they already read
+ `JOINTS_0` with no weights: **imported static, and it says why and by how
+ much**. The renderer takes the same answer for a file it did not write — the
+ bind pose, once, in the log — because a joint index answered by no uploaded
+ matrix is the wrong-matrix read it already refuses elsewhere.
+
+ `MESH_MAX_BONES` is now one number both halves read, alongside the channel
+ vocabulary they already shared by hand: `MeshChannelType` is a real enum on
+ the C++ side rather than a switch with a comment, and `check-mesh-vocabulary`
+ holds the eleven values together — a `.esmesh` cannot be written with one
+ meaning and drawn with another.
+
- **The 3D view button turns the eye.** It swapped the editor camera's projection
and nothing else, and swapping projection is invisible: looked at head-on, a
perspective picture of the z = 0 plane is the orthographic one, pixel for pixel.
diff --git a/desktop/tests/gltf-import.test.ts b/desktop/tests/gltf-import.test.ts
index ff965215c..817639682 100644
--- a/desktop/tests/gltf-import.test.ts
+++ b/desktop/tests/gltf-import.test.ts
@@ -13,7 +13,7 @@ import {
assembleModelPrefab, materialProducts,
type ImportedMesh, type PrefabAssembly, type ProductRefs,
} from '../../pipeline/src/assets/modelImport';
-import { BlendMode, CullMode, MeshChannel } from 'esengine';
+import { BlendMode, CullMode, MESH_MAX_BONES, MeshChannel } from 'esengine';
import { plainTriangle, meshoptTriangle, dracoTriangle } from '../scripts/lib/gltfFixtures.mjs';
const PNG_1PX = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';
@@ -682,7 +682,9 @@ describe('glTF animation import', () => {
* The triangle bound to two joints. Accessors 3/4 are JOINTS_0 (u16) and
* WEIGHTS_0; 5 is the skin's inverse bind matrices unless the caller drops it.
*/
-function skinnedGltf(opts: { noBindMatrices?: boolean; skinOnNode?: boolean; weights?: boolean } = {}): Uint8Array {
+function skinnedGltf(opts: {
+ noBindMatrices?: boolean; skinOnNode?: boolean; weights?: boolean; extraJoints?: number;
+} = {}): Uint8Array {
const geo = geometryBuffer();
const geoBytes = Buffer.from(geo.uri.split(',')[1]!, 'base64');
const pad = Buffer.alloc((4 - (geoBytes.length % 4)) % 4);
@@ -703,6 +705,7 @@ function skinnedGltf(opts: { noBindMatrices?: boolean; skinOnNode?: boolean; wei
at += p.length;
}
+ const extra = Array.from({ length: opts.extraJoints ?? 0 });
const doc: Record<string, unknown> = {
asset: { version: '2.0' },
buffers: [{ byteLength: bytes.length, uri: `data:application/octet-stream;base64,${bytes.toString('base64')}` }],
@@ -724,16 +727,19 @@ function skinnedGltf(opts: { noBindMatrices?: boolean; skinOnNode?: boolean; wei
}],
}],
nodes: [
- { name: 'Rig', children: [1, 2, 3] },
+ { name: 'Rig', children: [1, 2, 3, ...extra.map((_, i) => 4 + i)] },
{ name: 'Hip' },
{ name: 'Knee', translation: [30, 0, 0] },
{ name: 'Body', mesh: 0, ...(opts.skinOnNode === false ? {} : { skin: 0 }) },
+ ...extra.map((_, i) => ({ name: `Spare${i}` })),
],
scenes: [{ nodes: [0] }],
scene: 0,
skins: [{
- joints: [1, 2],
- ...(opts.noBindMatrices ? {} : { inverseBindMatrices: 5 }),
+ joints: [1, 2, ...extra.map((_, i) => 4 + i)],
+ // A longer joint list than the accessor has matrices for is its own
+ // (already covered) warning, so drop the accessor when the list grows.
+ ...(opts.noBindMatrices || extra.length > 0 ? {} : { inverseBindMatrices: 5 }),
}],
};
return new TextEncoder().encode(JSON.stringify(doc));
@@ -776,6 +782,29 @@ describe('glTF skinning import', () => {
}
});
+ it('imports static, and says the budget, when a skin binds more joints than a draw can pose', async () => {
+ // The joint indices in the vertices index the SKIN's list, so a list longer
+ // than the pose block means indices no uploaded matrix answers to. Drawn
+ // wrong, the vertices go somewhere arbitrary; this is the file saying so.
+ const over = MESH_MAX_BONES + 1;
+ const { meshes, warnings } = await importGltfMeshes(
+ skinnedGltf({ extraJoints: over - 2 }), 'rig');
+ expect(meshes[0]!.data.channels.some((c) => c.semantic === MeshChannel.Joints)).toBe(false);
+ expect(meshes[0]!.data.inverseBindMatrices).toBeUndefined();
+ expect(meshes[0]!.skinJoints).toBeUndefined();
+ expect(warnings.some((w) => w.includes(`binds ${over} joints`)
+ && w.includes(`${MESH_MAX_BONES}`) && /imported static/.test(w))).toBe(true);
+ });
+
+ it('poses a skin that fills the budget exactly', async () => {
+ // The boundary itself, so the check cannot be an off-by-one that quietly
+ // costs a rig its last bone.
+ const { meshes, warnings } = await importGltfMeshes(
+ skinnedGltf({ extraJoints: MESH_MAX_BONES - 2 }), 'rig');
+ expect(meshes[0]!.skinJoints).toHaveLength(MESH_MAX_BONES);
+ expect(warnings.some((w) => /imported static/.test(w))).toBe(false);
+ });
+
it('names the joint entities the prefab gives those nodes', async () => {
const { meshes, nodes } = await importGltfMeshes(skinnedGltf(), 'rig');
const prefab = assembleModelPrefab('rig', meshes, { nodes });
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index a888f31bc..285cef863 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 73,
- "experimental": 1571,
+ "experimental": 1572,
"deprecated": 3
},
- "total": 1757,
+ "total": 1758,
"subsystems": [
{
"id": "ecs",
diff --git a/pipeline/src/assets/fbxImport.ts b/pipeline/src/assets/fbxImport.ts
index 15674cbfb..8f50aa60e 100644
--- a/pipeline/src/assets/fbxImport.ts
+++ b/pipeline/src/assets/fbxImport.ts
@@ -13,7 +13,7 @@
* arrays — rather than a heap this side would walk. @ref tools/ufbx-wasm/bridge.c
* is the other half of that contract.
*/
-import { MeshChannel, MeshChannelType, packChannels } from 'esengine';
+import { MESH_MAX_BONES, MeshChannel, MeshChannelType, packChannels } from 'esengine';
import {
alignQuaternionSigns, animationProductName, ANIMATED_PATHS, disambiguateNodes,
nodeChildPaths, nodeNameFor, samplerKeyframes, timelineDocument,
@@ -396,7 +396,7 @@ function buildNodes(scene: FbxScene, meshIndexOf: Map<string, number[]>): Import
/** One material run of one FBX mesh as the `.esmesh` payload it becomes. */
function buildMesh(part: FbxMeshPart, name: string, payload: Uint8Array,
- material: ImportedMaterial | undefined): ImportedMesh {
+ material: ImportedMaterial | undefined, warnings: string[]): ImportedMesh {
const positions = floats(payload, part.positions);
const normals = part.normals ? floats(payload, part.normals) : null;
const uvs = part.uvs ? floats(payload, part.uvs) : null;
@@ -405,7 +405,15 @@ function buildMesh(part: FbxMeshPart, name: string, payload: Uint8Array,
const weights = part.weights ? floats(payload, part.weights) : null;
const indices = uints(payload, part.indices);
const vertexCount = part.vertexCount;
- const skinned = !!(joints && weights && part.skinJoints?.length);
+ // A pose the renderer cannot hold is not a pose — see the same read in the
+ // glTF importer. Static, and it says why, rather than joints indexing a
+ // matrix that was never uploaded.
+ const bones = part.skinJoints?.length ?? 0;
+ if (bones > MESH_MAX_BONES) {
+ warnings.push(`${name}: the skin binds ${bones} joints and one draw can be posed by`
+ + ` ${MESH_MAX_BONES} — imported static`);
+ }
+ const skinned = !!(joints && weights && bones > 0 && bones <= MESH_MAX_BONES);
const { channels, vertexStride } = packChannels([
{ semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32 },
@@ -566,7 +574,7 @@ export async function importFbxMeshes(bytes: Uint8Array, stem: string,
// so the product falls back to the source's own stem the way a glTF's
// single primitive does.
const name = single ? stem : `${stem}_${part.mesh}_${part.part}`;
- return buildMesh(part, name, payload, materialFor(part.material));
+ return buildMesh(part, name, payload, materialFor(part.material), warnings);
});
if (meshes.length === 0 && warnings.length === 0) {
diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.ts
index 32b83f8a0..b40b15df4 100644
--- a/pipeline/src/assets/gltfImport.ts
+++ b/pipeline/src/assets/gltfImport.ts
@@ -11,7 +11,7 @@
* the cook then ships them as the engine format they already are.
*/
/// <reference path="./draco3dgltf.d.ts" />
-import { MeshChannel, MeshChannelType, packChannels } from 'esengine';
+import { MESH_MAX_BONES, MeshChannel, MeshChannelType, packChannels } from 'esengine';
import { MeshoptDecoder } from 'meshoptimizer/decoder';
import {
ANIMATED_PATHS, alignQuaternionSigns, animationProductName, disambiguateNodes,
@@ -903,10 +903,17 @@ export async function importGltfMeshes(
// no bone to apply. A skin is what says which bind pose they mean.
const skinIndex = meshSkin.get(meshIndex);
const skin = skinIndex !== undefined ? json.skins?.[skinIndex] : undefined;
- const joints = skin ? attribute('JOINTS_0', prim.attributes.JOINTS_0) : null;
- const weights = skin ? attribute('WEIGHTS_0', prim.attributes.WEIGHTS_0) : null;
+ // Joints past the pose block index a matrix nothing uploads, so
+ // those vertices land somewhere arbitrary. Static is the honest
+ // read, and the one JOINTS_0-without-WEIGHTS_0 already takes.
+ const overBudget = (skin?.joints?.length ?? 0) > MESH_MAX_BONES;
+ const joints = skin && !overBudget ? attribute('JOINTS_0', prim.attributes.JOINTS_0) : null;
+ const weights = skin && !overBudget ? attribute('WEIGHTS_0', prim.attributes.WEIGHTS_0) : null;
const skinned = !!(skin?.joints?.length && joints && weights);
- if (prim.attributes.JOINTS_0 !== undefined && !skinned) {
+ if (overBudget) {
+ warnings.push(`${label}: the skin binds ${skin!.joints.length} joints and one`
+ + ` draw can be posed by ${MESH_MAX_BONES} — imported static`);
+ } else if (prim.attributes.JOINTS_0 !== undefined && !skinned) {
warnings.push(`${label}: JOINTS_0 without ${!skin?.joints?.length
? 'a skin naming joints on any node drawing it' : 'WEIGHTS_0'}`
+ ' — imported static');
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 58c1e8750..217f49dd8 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1457 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1458 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4261,6 +4261,11 @@ code: string
"1.0"
```
+## MESH_MAX_BONES — const @experimental
+```
+64
+```
+
## ManifestModel — class @experimental
```
allAssets: () => AddressableManifestAsset[]
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a0827c61b..0a8e2f1fc 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: 113 public · 71 beta · 1476 experimental · 3 deprecated
+Symbols: 113 public · 71 beta · 1477 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4269,6 +4269,11 @@ code: string
"1.0"
```
+## MESH_MAX_BONES — const @experimental
+```
+64
+```
+
## ManifestModel — class @experimental
```
allAssets: () => AddressableManifestAsset[]
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index fe0e185d7..ec72669f3 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 68 beta · 1456 experimental · 3 deprecated
+Symbols: 113 public · 68 beta · 1457 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4256,6 +4256,11 @@ code: string
"1.0"
```
+## MESH_MAX_BONES — const @experimental
+```
+64
+```
+
## ManifestModel — class @experimental
```
allAssets: () => AddressableManifestAsset[]
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 8877de339..7a3e3d3d2 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1477 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1478 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4256,6 +4256,11 @@ code: string
"1.0"
```
+## MESH_MAX_BONES — const @experimental
+```
+64
+```
+
## ManifestModel — class @experimental
```
allAssets: () => AddressableManifestAsset[]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index bb741880c..b0850d1fe 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1467 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1468 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4263,6 +4263,11 @@ code: string
"1.0"
```
+## MESH_MAX_BONES — const @experimental
+```
+64
+```
+
## ManifestModel — class @experimental
```
allAssets: () => AddressableManifestAsset[]
diff --git a/sdk/src/asset/meshFormat.ts b/sdk/src/asset/meshFormat.ts
index 486467c59..26b79056e 100644
--- a/sdk/src/asset/meshFormat.ts
+++ b/sdk/src/asset/meshFormat.ts
@@ -20,6 +20,14 @@ const CHANNEL_BYTES = 8;
/** One inverse bind matrix: 16 floats. */
const MATRIX_BYTES = 64;
+/**
+ * Joints one draw can be posed by — what the RENDERER holds (64 mat4 is 4KB,
+ * inside WebGL2's guaranteed block), not what the format carries. A mesh bound
+ * to more is drawn in its bind pose: a joint index no uploaded matrix answers
+ * moves the vertex nowhere in particular. Mirrors GfxEnums.hpp.
+ */
+export const MESH_MAX_BONES = 64;
+
/**
* What a channel means. The value IS the shader attribute location, and the first
* three match the 2D batch layout, so one attribute vocabulary serves both vertex
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 83a025ebd..becf941ef 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -114,8 +114,8 @@ export { setTextureBudget, getResourceStats, trimTextureCache, type ResourceStat
* @beta
*/
export {
- MeshChannel, MeshChannelType, packChannels, encodeMesh, decodeMesh, encodeChannelTable,
- type MeshChannelDesc, type MeshData,
+ MeshChannel, MeshChannelType, MESH_MAX_BONES, packChannels, encodeMesh, decodeMesh,
+ encodeChannelTable, type MeshChannelDesc, type MeshData,
} from './asset/meshFormat';
export type { MeshResult } from './asset/loaders/MeshAssetLoader';
/**
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 76e926afd..5953513fa 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -286,13 +286,13 @@ u32 mesh_createFromChannels(uintptr_t channelsPtr, u32 channelCount, u32 vertexS
}
}
- // The file's channel TYPE code (0 float, 1 unorm8, 2 uint16), in the asset
- // layer's vocabulary — the boundary the format crosses as bytes.
+ // The file's channel type, which is the asset layer's vocabulary, into the
+ // device's — the boundary the format crosses as bytes.
auto channelType = [](u8 code) {
- switch (code) {
- case 1: return GfxDataType::UnsignedByte;
- case 2: return GfxDataType::UnsignedShort;
- default: return GfxDataType::Float;
+ switch (static_cast<MeshChannelType>(code)) {
+ case MeshChannelType::UNorm8: return GfxDataType::UnsignedByte;
+ case MeshChannelType::UInt16: return GfxDataType::UnsignedShort;
+ default: return GfxDataType::Float;
}
};
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 322d85e3c..7cdf45a20 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -42,11 +42,22 @@ u32 mulColor(u32 a, u32 b) {
* the vertex somewhere arbitrary.
*/
u32 skinPose(ecs::Registry& registry, Entity entity, const Mesh& mesh,
- std::vector<glm::mat4>& out) {
+ std::vector<glm::mat4>& out, bool& warnedBones) {
if (!mesh.isSkinned()) return 0;
const auto* skin = registry.tryGet<ecs::MeshSkin>(entity);
if (!skin || skin->joints.size() != mesh.inverseBind.size()) return 0;
- const u32 count = static_cast<u32>(std::min<usize>(skin->joints.size(), MESH_MAX_BONES));
+ // Posing the first MESH_MAX_BONES leaves the rest indexing a matrix this
+ // draw never uploads — the wrong-matrix read the count check above already
+ // rejects, so it takes the same answer. For files no importer here wrote.
+ if (skin->joints.size() > MESH_MAX_BONES) {
+ if (!warnedBones) {
+ warnedBones = true;
+ ES_LOG_WARN("MeshSkin: {} joints exceeds the {} one draw can be posed by; drawing the"
+ " bind pose", skin->joints.size(), MESH_MAX_BONES);
+ }
+ return 0;
+ }
+ const u32 count = static_cast<u32>(skin->joints.size());
out.resize(count);
for (u32 i = 0; i < count; ++i) {
@@ -262,7 +273,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// The pose, when this entity says what moves it. The bones are
// world-space, so the entity's own transform is not read — which is
// what glTF requires of a skinned mesh.
- const u32 poseSize = skinPose(registry, entity, *resident, pose_scratch_);
+ const u32 poseSize = skinPose(registry, entity, *resident, pose_scratch_, warned_bones_);
const bool skinned = poseSize > 0;
// `lit` is the draw's own word and is honoured either way: geometry
diff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hpp
index 7cf84a353..5f63692a8 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.hpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.hpp
@@ -39,6 +39,7 @@ private:
u32 meshProgram(RenderFrameContext& ctx, bool normals, bool lit, bool normalMapped,
bool skinned, bool depthOnly = false, bool envMapped = false);
bool warned_material_ = false; ///< A material on resident geometry is said once.
+ bool warned_bones_ = false; ///< A skin over the pose budget is said once.
};
} // namespace esengine
diff --git a/src/esengine/renderer/rhi/GfxEnums.hpp b/src/esengine/renderer/rhi/GfxEnums.hpp
index 6ff1649ad..e5cae28ac 100644
--- a/src/esengine/renderer/rhi/GfxEnums.hpp
+++ b/src/esengine/renderer/rhi/GfxEnums.hpp
@@ -125,6 +125,18 @@ enum class MeshChannel : u8 {
Weights = 6,
};
+/**
+ * @brief How a channel's components are stored, as the file spells it.
+ * @details The asset layer's vocabulary rather than the device's: these are the
+ * codes written into a .esmesh, and one of them (UInt16) exists because
+ * a joint index is neither a float nor a byte. Append only — serialized.
+ */
+enum class MeshChannelType : u8 {
+ Float32 = 0,
+ UNorm8 = 1,
+ UInt16 = 2,
+};
+
// =============================================================================
// Data Type (vertex attributes, index type, pixel data type)
// =============================================================================
diff --git a/tools/check-mesh-vocabulary.mjs b/tools/check-mesh-vocabulary.mjs
new file mode 100644
index 000000000..9601a63f9
--- /dev/null
+++ b/tools/check-mesh-vocabulary.mjs
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-mesh-vocabulary.mjs — the two halves of the .esmesh vocabulary agree.
+ *
+ * A channel's semantic IS its shader attribute location, and the number is
+ * serialized into every `.esmesh`. It is spelled twice — `MeshChannel` in
+ * GfxEnums.hpp for the engine that binds it, and in meshFormat.ts for the
+ * importers that write it — because neither half can import the other's
+ * language. Nothing else notices when they drift: a file would simply be read
+ * with one meaning and drawn with another.
+ *
+ * MESH_MAX_BONES is here for the same reason and a sharper one: the importer
+ * uses it to decide what it can promise, and the renderer uses it to size the
+ * block it uploads. A TS copy that grew past the C++ one would produce meshes
+ * whose joints index a matrix that was never sent.
+ */
+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 CPP = path.join('src', 'esengine', 'renderer', 'rhi', 'GfxEnums.hpp');
+const TS = path.join('sdk', 'src', 'asset', 'meshFormat.ts');
+
+const cpp = readFileSync(path.join(ROOT, CPP), 'utf8');
+const ts = readFileSync(path.join(ROOT, TS), 'utf8');
+
+/** `enum class <name> : <type> { A = 0, B = 1 };` → Map(name → value). */
+function cppEnum(source, name) {
+ const body = new RegExp(`enum class ${name}\\s*:[^{]*\\{([^}]*)\\}`, 'm').exec(source);
+ if (!body) return null;
+ const out = new Map();
+ for (const [, key, value] of body[1].matchAll(/^\s*(\w+)\s*=\s*(\d+)\s*,?\s*$/gm)) {
+ out.set(key, Number(value));
+ }
+ return out;
+}
+
+/** `export const <name> = { A: 0, B: 1 } as const;` → Map(name → value). */
+function tsObject(source, name) {
+ const body = new RegExp(`export const ${name} = \\{([^}]*)\\}`, 'm').exec(source);
+ if (!body) return null;
+ const out = new Map();
+ for (const [, key, value] of body[1].matchAll(/^\s*(\w+)\s*:\s*(\d+)\s*,?\s*$/gm)) {
+ out.set(key, Number(value));
+ }
+ return out;
+}
+
+const problems = [];
+let checked = 0;
+
+for (const name of ['MeshChannel', 'MeshChannelType']) {
+ const a = cppEnum(cpp, name);
+ const b = tsObject(ts, name);
+ if (!a || a.size === 0) { problems.push(`${CPP}: no enum class ${name} found`); continue; }
+ if (!b || b.size === 0) { problems.push(`${TS}: no export const ${name} found`); continue; }
+ for (const [key, value] of a) {
+ if (!b.has(key)) problems.push(`${name}.${key} = ${value} is in C++ and not in TS`);
+ else if (b.get(key) !== value) {
+ problems.push(`${name}.${key} is ${value} in C++ and ${b.get(key)} in TS`);
+ }
+ checked++;
+ }
+ for (const key of b.keys()) {
+ if (!a.has(key)) problems.push(`${name}.${key} is in TS and not in C++`);
+ }
+}
+
+const cppBones = /MESH_MAX_BONES\s*=\s*(\d+)/.exec(cpp);
+const tsBones = /MESH_MAX_BONES\s*=\s*(\d+)/.exec(ts);
+if (!cppBones) problems.push(`${CPP}: no MESH_MAX_BONES found`);
+else if (!tsBones) problems.push(`${TS}: no MESH_MAX_BONES found`);
+else if (cppBones[1] !== tsBones[1]) {
+ problems.push(`MESH_MAX_BONES is ${cppBones[1]} in C++ and ${tsBones[1]} in TS`);
+} else checked++;
+
+if (problems.length > 0) {
+ console.error('check-mesh-vocabulary: the engine and the importers disagree about what a'
+ + ' .esmesh means:');
+ for (const p of problems) console.error(` ${p}`);
+ process.exit(1);
+}
+
+console.log(`check-mesh-vocabulary: ${checked} shared value(s) agree across ${CPP} and ${TS}`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 82e755c4d..706bddf31 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -76,6 +76,7 @@ export const GATES = [
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs' },
{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },
{ id: 'shader-conditionals', run: 'node tools/check-shader-conditionals.mjs' },
+ { id: 'mesh-vocabulary', run: 'node tools/check-mesh-vocabulary.mjs' },
{ id: 'import-settings', run: 'node tools/check-import-settings.mjs' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },