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.

feat(gates): the per-object mesh record is described in one shape

esengine8479d22a6102
diff --git a/tools/check-mesh-instance-record.mjs b/tools/check-mesh-instance-record.mjs
new file mode 100644
index 000000000..a68455cac
--- /dev/null
+++ b/tools/check-mesh-instance-record.mjs
@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-mesh-instance-record.mjs — the per-object record says one thing.
+ *
+ * The engine appends a per-object record to every resident mesh's layout, and
+ * what it contains is written down FOUR times: mesh.esshader declares it in GLSL
+ * and again in WGSL, and ShaderParser injects the same pair into a material's
+ * mesh variant. ResourceManager builds the layout those four must match. Nothing
+ * held them together, and dropping a row from the model matrix meant editing all
+ * five by hand — one missed edit reads whatever the driver left in the slot.
+ *
+ * Two claims, because they fail differently:
+ *
+ * the four declarations disagree
+ * a material draws its mesh through a layout built for the other one; the
+ * frame is wrong and no error names the cause
+ * the declarations and MESH_INSTANCE_STRIDE disagree
+ * the record is read past its end, or a part of it is never sent
+ *
+ * Run: node tools/check-mesh-instance-record.mjs
+ */
+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 SHADER = 'src/esengine/data/shaders/mesh.esshader';
+const PARSER = 'src/esengine/resource/ShaderParser.cpp';
+const ENUMS = 'src/esengine/renderer/rhi/GfxEnums.hpp';
+
+const enums = read(ENUMS);
+const constant = (name) => {
+ const found = new RegExp(`${name}\\s*=\\s*(\\d+)`).exec(enums);
+ if (!found) throw new Error(`${ENUMS} no longer declares ${name}`);
+ return Number(found[1]);
+};
+const FIRST = constant('MESH_INSTANCE_FIRST_LOCATION');
+const STRIDE = constant('MESH_INSTANCE_STRIDE');
+const STRIDE_LIT = constant('MESH_INSTANCE_STRIDE_LIT');
+
+/** Every instance-range attribute a source declares: location → name, per language. */
+function declarations(text) {
+ const glsl = new Map();
+ const wgsl = new Map();
+ for (const [, loc, name] of text.matchAll(/layout\(location\s*=\s*(\d+)\)\s*in\s+\w+\s+(\w+)/g)) {
+ if (Number(loc) >= FIRST) glsl.set(Number(loc), name);
+ }
+ for (const [, loc, name] of text.matchAll(/@location\((\d+)\)\s*(\w+)\s*:/g)) {
+ if (Number(loc) >= FIRST) wgsl.set(Number(loc), name);
+ }
+ return { glsl, wgsl };
+}
+
+const problems = [];
+const sources = { [SHADER]: declarations(read(SHADER)), [PARSER]: declarations(read(PARSER)) };
+
+// All four must name the same thing at the same location. Compared as text so a
+// renamed attribute is a finding too: a name is how the twin's reader matches up.
+const spellings = new Map();
+for (const [file, langs] of Object.entries(sources)) {
+ for (const [lang, found] of Object.entries(langs)) {
+ for (const [loc, name] of found) {
+ const seen = spellings.get(loc);
+ if (!seen) { spellings.set(loc, { name, where: `${file} (${lang})` }); continue; }
+ if (seen.name !== name) {
+ problems.push(`location ${loc} is "${seen.name}" in ${seen.where}`
+ + ` and "${name}" in ${file} (${lang}) — one of them reads the other's bytes`);
+ }
+ }
+ }
+}
+
+// Each declaration set must cover the same locations: a part declared in one
+// language and not its twin is a backend that draws the record differently.
+const every = [...spellings.keys()].sort((a, b) => a - b);
+for (const [file, langs] of Object.entries(sources)) {
+ for (const [lang, found] of Object.entries(langs)) {
+ const missing = every.filter((loc) => !found.has(loc));
+ if (missing.length) {
+ problems.push(`${file} (${lang}) declares no attribute at location(s) `
+ + `${missing.join(', ')}, which the others do`);
+ }
+ }
+}
+
+/**
+ * What the declarations add up to, against what the packer sends. The model rows
+ * and the lightmap rectangle are vec4s, the tint is four bytes it packs itself,
+ * and the normal rows are the vec3s only lit geometry carries.
+ */
+const TINT = FIRST + 4;
+const NORMAL_FIRST = FIRST + 5;
+const wide = every.filter((loc) => loc < TINT).length;
+const normalRows = every.filter((loc) => loc >= NORMAL_FIRST).length;
+const base = wide * 16 + 4;
+const lit = base + normalRows * 12;
+if (!spellings.has(TINT)) {
+ problems.push(`no attribute at location ${TINT}, where the record's tint is`);
+}
+if (base !== STRIDE) {
+ problems.push(`${wide} vec4 part(s) plus the tint is ${base} bytes, but`
+ + ` MESH_INSTANCE_STRIDE is ${STRIDE} — the record is packed to a different shape`
+ + ' than it is declared');
+}
+if (lit !== STRIDE_LIT) {
+ problems.push(`with ${normalRows} normal row(s) that is ${lit} bytes, but`
+ + ` MESH_INSTANCE_STRIDE_LIT is ${STRIDE_LIT}`);
+}
+
+if (problems.length) {
+ console.error('check-mesh-instance-record: the per-object record is described'
+ + ' more than one way.\n');
+ for (const p of problems) console.error(` ${p}`);
+ console.error(`\nIt is declared in ${SHADER} (both languages) and injected by ${PARSER}`
+ + ` (both languages); ${ENUMS} says how many bytes it is.`);
+ process.exit(1);
+}
+
+console.log(`check-mesh-instance-record: ${every.length} part(s) of the per-object record,`
+ + ` spelled the same in all four declarations and adding to ${STRIDE}/${STRIDE_LIT} bytes.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 1378ce34d..a0d369550 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -195,6 +195,7 @@ export const GATES = [
{ id: 'shader-conditionals', run: 'node tools/check-shader-conditionals.mjs' },
{ id: 'mesh-vocabulary', run: 'node tools/check-mesh-vocabulary.mjs' },
{ id: 'mesh-shader-inputs', run: 'node tools/check-mesh-shader-inputs.mjs' },
+ { id: 'mesh-instance-record', run: 'node tools/check-mesh-instance-record.mjs' },
// …and that whoever mints one can say how it survives a device generation:
// recovery only ever holds a number, so the answer has to exist before it runs.
{ id: 'mesh-provenance', run: 'node tools/check-mesh-provenance.mjs' },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2ac315e3c..7cacb8346 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,13 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(gates): the per-object mesh record is described in one shape':
+ { internal: 'a gate over four declarations of one vertex layout — a game draws'
+ + ' the same whether or not they can drift' },
+ 'perf(render): a model matrix travels as three rows, not four':
+ { internal: '16 bytes an instance and one attribute slot, both spent on a row that'
+ + ' is (0,0,0,1) on every transform — the frame is identical either way' },
+
'fix(gates): the animator parameter census reads a blend over a plane':
{ internal: 'a gate reading a project\'s own animator files — a game plays the'
+ ' same whether or not the census can see a blend over a plane' },