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.

chore(renderer): whoever mints a mesh says how it comes back

esengine1776c7eec2fc
diff --git a/src/esengine/resource/Mesh.hpp b/src/esengine/resource/Mesh.hpp
index 3952c9eb6..b90b6c9a7 100644
--- a/src/esengine/resource/Mesh.hpp
+++ b/src/esengine/resource/Mesh.hpp
@@ -21,6 +21,11 @@ namespace esengine {
* @details One record because the three are inseparable: a buffer without its
* layout cannot be drawn, and bounds kept elsewhere go stale. Material,
* layer and transform belong to the entity, so one mesh serves many.
+ *
+ * The handle is a LOGICAL identity: the buffers and the layout realize
+ * it on ONE device generation and a lost device takes all three, while
+ * the handle survives. Where the geometry comes back FROM is the
+ * minting producer's to declare — tools/meshProducers.mjs.
*/
class Mesh {
public:
diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hpp
index d3f5ff66c..3d73778f3 100644
--- a/src/esengine/resource/ResourceManager.hpp
+++ b/src/esengine/resource/ResourceManager.hpp
@@ -455,6 +455,10 @@ public:
* rewritten by the CPU each frame — a per-frame re-upload of anything
* that does not change. The layout travels with the buffers: one whose
* attribute description lives elsewhere is a rename from garbage.
+ * Every caller is a mesh PRODUCER and owes a row in
+ * tools/meshProducers.mjs saying how the handles it mints come back
+ * after a device generation ends; check-mesh-provenance keeps that
+ * census closed in both directions.
* @param vertexBytes Raw vertex data, laid out as @p layout describes.
* @param indices Triangle-list indices into it.
* @return Handle to the mesh, or invalid on failure.
diff --git a/tools/check-mesh-provenance.mjs b/tools/check-mesh-provenance.mjs
new file mode 100644
index 000000000..8857cd51c
--- /dev/null
+++ b/tools/check-mesh-provenance.mjs
@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-mesh-provenance.mjs — every path that mints a persistent
+ * MeshHandle has answered how that handle comes back.
+ *
+ * A MeshHandle outlives the GPU objects realizing it, so a lost device is
+ * supposed to be invisible to whoever holds one. That only works if the geometry
+ * can be produced a second time, and nothing downstream can work out where from:
+ * by the time recovery runs, the producer is long gone and all that is left is a
+ * number. So the answer has to be given where the handle is minted, and this
+ * gate is what makes giving it unavoidable.
+ *
+ * Closed in both directions on purpose. Forwards, a new producer that never
+ * registered would inherit whatever recovery happens to do — which is how a
+ * third minting path arrives already broken. Backwards, a declaration whose
+ * producer is gone is worse than no table: it reads as an answered question. A
+ * one-way census becomes a graveyard, and a graveyard is what a reader trusts.
+ *
+ * What this gate deliberately does NOT do is let recovery infer the answer at
+ * runtime. Missing provenance for a mesh declared recoverable is a defect to be
+ * reported, not evidence that the mesh was host-only all along.
+ *
+ * node tools/check-mesh-provenance.mjs
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MESH_PRODUCERS, CLASSES, MINT } from './meshProducers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** The engine sources. This gate never reads tools/, so the table below and the
+ * gate's own prose cannot answer it. */
+const ROOTS = ['src', 'native'];
+const EXTS = new Set(['.cpp', '.hpp', '.h', '.cc']);
+
+function sources(dir, out = []) {
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
+ if (e.name === 'third_party' || e.name === 'build' || e.name.startsWith('.')) continue;
+ const p = path.join(dir, e.name);
+ if (e.isDirectory()) sources(p, out);
+ else if (EXTS.has(path.extname(e.name))) out.push(p);
+ }
+ return out;
+}
+
+/**
+ * Comments, string and character literals and preprocessor lines blanked to
+ * spaces. Same length as the input, so an index still names a line — and braces
+ * inside a comment or a shader string stop moving the scope depth.
+ */
+function blank(src) {
+ const out = src.split('');
+ const space = (i) => { if (src[i] !== '\n') out[i] = ' '; };
+ let i = 0;
+ let lineStart = true;
+ while (i < src.length) {
+ const c = src[i];
+ if (c === '\n') { lineStart = true; i++; continue; }
+ if (lineStart && /\s/.test(c)) { i++; continue; }
+ if (lineStart && c === '#') {
+ while (i < src.length && !(src[i] === '\n' && src[i - 1] !== '\\')) { space(i); i++; }
+ continue;
+ }
+ lineStart = false;
+ if (c === '/' && src[i + 1] === '/') {
+ while (i < src.length && src[i] !== '\n') { space(i); i++; }
+ continue;
+ }
+ if (c === '/' && src[i + 1] === '*') {
+ while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) { space(i); i++; }
+ space(i); space(i + 1); i += 2;
+ continue;
+ }
+ const raw = /^R"([^("\s]*)\(/.exec(src.slice(i, i + 24));
+ if (raw && c === 'R') {
+ const end = src.indexOf(`)${raw[1]}"`, i);
+ const stop = end < 0 ? src.length : end + raw[1].length + 2;
+ while (i < stop) { space(i); i++; }
+ continue;
+ }
+ if (c === '"' || c === "'") {
+ space(i); i++;
+ while (i < src.length && src[i] !== c) {
+ if (src[i] === '\\') { space(i); i++; }
+ space(i); i++;
+ }
+ space(i); i++;
+ continue;
+ }
+ i++;
+ }
+ return out.join('');
+}
+
+const KEYWORD = /^(if|for|while|switch|catch|do|else|return|case|try)\b/;
+/** A `{` that opens a function body, as opposed to a namespace, a type, an
+ * initializer or a control-flow block. */
+function opensBody(head) {
+ if (!head.includes('(')) return false;
+ const t = head.replace(/\s+/g, ' ').trim();
+ if (KEYWORD.test(t)) return false;
+ return /\)(\s*(const|noexcept|override|final|mutable|volatile|&{1,2}))*\s*(->[\w:<>,*&\s]+)?$/.test(t)
+ || /\)\s*:\s*[^;]*$/.test(t);
+}
+
+/** The function a body's `{` belongs to; null for a lambda, whose calls are
+ * attributed to the function hosting it. */
+function bodyName(head) {
+ const m = /([A-Za-z_~][A-Za-z0-9_]*(?:\s*::\s*~?[A-Za-z0-9_]+)*)\s*$/
+ .exec(head.slice(0, head.indexOf('(')).trim());
+ return m ? m[1].replace(/\s+/g, '') : null;
+}
+
+const NEEDLES = ['createMesh(', `${MINT.pool}.add(`];
+
+/** Each needle occurrence with the function it sits in. */
+function occurrences(code) {
+ const found = [];
+ const stack = [];
+ let head = '';
+ let i = 0;
+ while (i < code.length) {
+ const c = code[i];
+ const before = code[i - 1] ?? ' ';
+ if (!/[A-Za-z0-9_]/.test(before)) {
+ for (const needle of NEEDLES) {
+ if (!code.startsWith(needle, i)) continue;
+ found.push({
+ index: i,
+ needle,
+ fn: stack.find((s) => s.fn)?.fn ?? null,
+ qualifier: (/([A-Za-z_]\w*)\s*::\s*$/.exec(code.slice(Math.max(0, i - 96), i))
+ ?? [])[1] ?? null,
+ });
+ }
+ }
+ if (c === '{') { stack.unshift({ fn: opensBody(head) ? bodyName(head) : null }); head = ''; }
+ else if (c === '}') { stack.shift(); head = ''; }
+ else if (c === ';') head = '';
+ else head += c;
+ i++;
+ }
+ return found;
+}
+
+const problems = [];
+const lineOf = (code, index) => code.slice(0, index).split('\n').length;
+
+for (const p of MESH_PRODUCERS) {
+ const spec = CLASSES[p.class];
+ if (!spec) { problems.push(`${p.id}: class "${p.class}" is not one this contract defines`); continue; }
+ if (!p[spec.owes]) {
+ problems.push(`${p.id}: declared ${p.class} and owes a \`${spec.owes}\` — ${spec.means}`);
+ }
+}
+
+const files = ROOTS.map((r) => path.join(ROOT, r)).filter(existsSync).flatMap((d) => sources(d));
+if (files.length === 0) problems.push(`no engine sources under ${ROOTS.join(', ')} — this gate read nothing`);
+
+const declared = new Map(MESH_PRODUCERS.map((p) => [p.id, p]));
+/** Producers this run actually found in the sources, for the backwards half. */
+const discovered = new Map();
+let mints = 0;
+
+for (const file of files) {
+ const rel = path.relative(ROOT, file);
+ const code = blank(readFileSync(file, 'utf8'));
+ for (const hit of occurrences(code)) {
+ const where = `${rel}:${lineOf(code, hit.index)}`;
+ if (hit.needle !== 'createMesh(') {
+ mints++;
+ if (rel !== MINT.file || hit.fn !== MINT.fn) {
+ problems.push(`${where}: ${MINT.pool}.add outside ${MINT.fn} — a MeshHandle`
+ + ` minted here would carry no producer, so nothing could ever say how it`
+ + ` comes back. Identity has one authority.`);
+ }
+ continue;
+ }
+ if (hit.qualifier === 'ResourceManager' || hit.fn === MINT.fn) continue;
+ if (hit.fn === null) {
+ if (rel === MINT.header) continue;
+ problems.push(`${where}: a createMesh this gate cannot attribute to a function`
+ + ' — it can neither be declared nor cleared, so it is a hole either way');
+ continue;
+ }
+ if (!discovered.has(hit.fn)) discovered.set(hit.fn, { file: rel, where });
+ const decl = declared.get(hit.fn);
+ if (!decl) {
+ problems.push(`${where}: ${hit.fn} mints a persistent MeshHandle and is not in`
+ + ' tools/meshProducers.mjs. Declare how a handle it minted survives a device'
+ + ` generation — ${Object.keys(CLASSES).join(' or ')}.`);
+ } else if (decl.file !== rel) {
+ problems.push(`${where}: ${hit.fn} is declared in ${decl.file} and found here`);
+ }
+ }
+}
+
+if (mints === 0) {
+ problems.push(`no ${MINT.pool}.add found in ${MINT.file} — either the mesh pool moved or this`
+ + ' gate is reading for a shape that no longer exists; it cannot be green either way');
+}
+
+for (const p of MESH_PRODUCERS) {
+ if (discovered.has(p.id)) continue;
+ problems.push(`${p.id} is declared ${p.class} in tools/meshProducers.mjs and no longer mints`
+ + ` a mesh in ${p.file}. A declaration outliving its producer reads as an answered`
+ + ' question; drop the row.');
+}
+
+if (problems.length > 0) {
+ console.error('check-mesh-provenance: a persistent MeshHandle can be minted without saying'
+ + ' how it comes back:');
+ for (const p of problems) console.error(` ${p}`);
+ process.exit(1);
+}
+
+const byClass = Object.keys(CLASSES)
+ .map((c) => `${MESH_PRODUCERS.filter((p) => p.class === c).length} ${c}`)
+ .join(', ');
+console.log(`check-mesh-provenance: ${MESH_PRODUCERS.length} mesh producer(s) declared and found`
+ + ` (${byClass}); ${MINT.pool} is minted only by ${MINT.fn}.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index de2bd94c2..e2cbd51a7 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -170,6 +170,9 @@ export const GATES = [
{ 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' },
+ // …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' },
{ id: 'shader-blocks', run: 'node tools/check-shader-blocks.mjs' },
{ id: 'wgsl-twin', run: 'node tools/check-wgsl-twin.mjs' },
{
diff --git a/tools/meshProducers.mjs b/tools/meshProducers.mjs
new file mode 100644
index 000000000..a3c00187a
--- /dev/null
+++ b/tools/meshProducers.mjs
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file meshProducers.mjs — every path that can mint a persistent MeshHandle,
+ * and what each one promises about surviving a device generation.
+ *
+ * A MeshHandle is a LOGICAL resource identity. The VBO, the EBO and the vertex
+ * layout it points at are that identity's realization on one device generation,
+ * and a lost device takes all three; recovery replaces them underneath the same
+ * handle, so nothing that stored one ever hears about it.
+ *
+ * Which leaves the only question recovery cannot answer for itself: where does
+ * the geometry come back FROM? Only whoever minted the handle knows, so only a
+ * producer can say — in advance, here.
+ *
+ * The distinction this table exists to keep: the ABSENCE of a recorded source is
+ * a fact about a handle, never a recovery policy. A production mesh whose
+ * provenance went missing is a broken contract and has to be reported as one; it
+ * is not, and must never be quietly downgraded into, a mesh that was never
+ * recoverable. Only a producer declared `host-only-non-recoverable` below is
+ * allowed to have no way back.
+ */
+
+/**
+ * The one seam that adds a record to the mesh pool. Everything below reaches a
+ * new MeshHandle through it — a second minting path would be a second identity
+ * authority, and the census cannot see past this one.
+ */
+export const MINT = {
+ file: 'src/esengine/resource/ResourceManager.cpp',
+ header: 'src/esengine/resource/ResourceManager.hpp',
+ fn: 'ResourceManager::createMesh',
+ pool: 'meshes_',
+};
+
+/**
+ * `source` (recoverable) and `why` (non-recoverable) are each owed: a class on
+ * its own is a label, and the sentence beside it is what a later reader checks
+ * the class against.
+ */
+export const CLASSES = {
+ 'asset-backed-recoverable': {
+ owes: 'source',
+ means: 'the geometry is replayable from an asset the loader can load again;'
+ + ' a handle of this class with no recorded source is a contract violation',
+ },
+ 'host-only-non-recoverable': {
+ owes: 'why',
+ means: 'the geometry exists only in the process that built it, by design;'
+ + ' a device generation ends it, and no source can bring it back',
+ },
+};
+
+export const MESH_PRODUCERS = [
+ {
+ id: 'mesh_createFromChannels',
+ file: 'src/esengine/bindings/RendererBindings.cpp',
+ class: 'asset-backed-recoverable',
+ source: 'the .esmesh (or `builtin:` template) MeshAssetLoader decoded; Assets records'
+ + ' `mesh:<handle>` → path on the load, so the file can be decoded and uploaded again',
+ },
+ {
+ id: 'freezeMeshGeometry',
+ file: 'src/esengine/bindings/RendererBindings.cpp',
+ class: 'host-only-non-recoverable',
+ why: 'it uploads a MeshRenderer\'s INLINE payload — vertices that live in a component,'
+ + ' authored by whoever built the entity, with no asset under them — and clears the'
+ + ' payload afterwards, so the geometry survives nowhere else. Its only callers are'
+ + ' render-host and headless (meshRenderer_makeAllResident), which use it to prove the'
+ + ' resident path draws the frame the inline path draws. Verification infrastructure:'
+ + ' never a production mesh, and never to be treated as one.',
+ },
+];