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
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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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' },