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
census(ecs): a Transform writer is a seam somebody named, or it is a finding
esenginea0cead261669
diff --git a/package.json b/package.jsonindex 653cdcf2e..5f0f65818 100644--- a/package.json+++ b/package.json@@ -34,6 +34,7 @@"probe:interest-space": "node tools/probe-interest-position-space.mjs","probe:headless-transform": "node tools/probe-headless-transform.mjs","census:transform-writers": "node tools/census-transform-writers.mjs",+ "verify:transform-writers": "node tools/census-transform-writers.mjs --gate","verify:render": "node tools/verify-render.mjs","test": "vitest run --config vitest.engine.config.ts","verify:aot": "rm -rf .aot-verify && node pipeline/bin/estella.mjs export examples/ecs-basics --out .aot-verify && node tools/run-electron.mjs tools/launchers/headless-aot-verify.mjs .aot-verify",diff --git a/tools/census-transform-writers.mjs b/tools/census-transform-writers.mjsindex f1e4ddd2e..773493eaf 100644--- a/tools/census-transform-writers.mjs+++ b/tools/census-transform-writers.mjs@@ -1,18 +1,25 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file Who can change a Transform's local inputs, and who can see them do it.+ * @file census-transform-writers.mjs — who can move a Transform, and how each+ * one says so.*- * A composed world transform is a function of `position`, `rotation`, `scale`- * and the hierarchy. Anything that wants to know "has the composition gone- * stale" needs every producer of those to reach one seam — so the first- * question is how many producers there are, and which side of the wasm boundary- * each one is observable from.+ * A composed world transform is a function of `position`, `rotation`, `scale` and+ * the hierarchy, and it is recomposed on a staleness epoch: a producer that+ * writes those and announces nothing is invisible, and the world answers every+ * later question with the answer it gave first.*- * node tools/census-transform-writers.mjs+ * So the scan is not a count. Each write site is one of: a seam that announces,+ * or a private world that composes its own registry in place. A site that is+ * neither is a producer nobody classified, and `--gate` refuses it — the count+ * moves with any honest refactor, but "there is a writer with no seam" does not.*- * Reports; asserts nothing. `worldPosition` and friends are excluded: they are- * composition OUTPUT, not input.+ * An approval is per (file, function) and is checked against the code, so a+ * declared seam that stopped announcing, and one that no longer writes anything,+ * both go red as well.+ *+ * node tools/census-transform-writers.mjs report+ * node tools/census-transform-writers.mjs --gate exit 1 on an unclassified writer*/import { readFileSync } from 'node:fs';import path from 'node:path';@@ -20,21 +27,58 @@ import { fileURLToPath } from 'node:url';import { listTrackedSources } from './lib/sourceRoots.mjs';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const GATE = process.argv.includes('--gate');++/** The call that says the composition's inputs moved. */+const SEAM_CALL = 'invalidateTransformComposition';/**- * Producers already understood, and what sees them. A scan finding something- * outside this list is the point of running it: a new writer nobody classified.+ * Every C++ writer of a Transform's local inputs, and on what ground it is+ * allowed to be one. `announces` means the subsystem calls the seam — once per+ * pass, not once per field, which is why the call may sit in a different function+ * of the same file than the write does.*/-const KNOWN = [- ['world.set / world.update (TS)', 'ptr setter → wasm heap', 'recordChanged', 'no'],- ['Query(Mut(Transform)) (TS)', 'ptr setter → wasm heap', 'recordChanged', 'no'],- ['Web AOT Mut(Transform)', 'compiled code → component address', 'markChanged_', 'no'],- ['Native AOT Mut(Transform)', 'compiled code → component address', 'markChanged_', 'no'],- ['setParent (C++)', 'hierarchy + TransformDirty', 'no', 'yes'],- ['UILayoutSystem (C++)', 'writes position.x/y from Yoga', 'no', 'yes'],- ['TweenSystem (C++)', 'writes position/scale/rotation', 'no', 'yes'],- ['physics transform sync (C++)', 'writes local AND composes world itself', 'no', 'yes'],- ['EditorAPI setField (C++)', 'writes position/rotation/scale', 'no', 'yes'],+const SEAMS = [+ {+ file: 'src/esengine/animation/TweenSystem.cpp', fn: 'applyTweenValue', role: 'announces',+ why: 'once per applied value, colour targets included: a recompose that changes nothing is cheaper than a missed one',+ },+ {+ file: 'src/esengine/ui/UILayoutSystem.cpp', fn: 'layoutUINodeSubtree', role: 'announces',+ why: 'the layout pass announces once for every node it will place',+ },+ {+ file: 'src/esengine/ui/UILayoutSystem.cpp', fn: 'placeScreenRoots', role: 'announces',+ why: 'same pass, same single announcement',+ },+ {+ file: 'src/esengine/bindings/RendererBindings.cpp', fn: 'registry_batchSyncPhysicsTransforms', role: 'announces',+ why: 'once per batch; it also writes the world fields itself, which is a second AUTHORSHIP of the output and a separate question',+ },+ {+ file: 'src/esengine/bindings/RendererBindings.cpp', fn: 'renderer_renderMeshPreview', role: 'private world',+ why: 'builds its own Registry and composes it in place, so nothing outside the call can read a stale value',+ },+ {+ file: 'src/esengine/bindings/EditorAPI.generated.cpp', fn: 'editor_setFloat', role: 'announces',+ why: 'emitted from WRITE_HOOKS; check-transform-seam holds which arms get it',+ },+];++/** The hierarchy is the composition's other input, and one function writes it. */+const HIERARCHY_WRITER = { file: 'src/esengine/ecs/TransformSystem.hpp', fn: 'setParent' };++/**+ * The TS producers, which write the component heap through a pointer setter and+ * call no C++ at all — invisible to any scan of these sources. They reach the+ * same epoch through `recordComponentWrite_`, and sdk/tests/world-transform-+ * authority.test.ts is what holds them to it.+ */+const TS_PRODUCERS = [+ ['world.set / insert / update', 'ptr setter → wasm heap'],+ ['Query(Mut(Transform)) write-back', 'ptr setter → wasm heap'],+ ['Web AOT Mut(Transform)', 'compiled code → component address'],+ ['Native AOT Mut(Transform)', 'compiled code → component address'],];const FIELDS = String.raw`(position|rotation|scale)`;@@ -43,48 +87,136 @@ const WRITE = new RegExp(String.raw`\b(\w+)\s*(?:\.|->)\s*${FIELDS}\s*(?:\.\w+\sconst OUTPUT = /world(Position|Rotation|Scale)|cachedMatrix_|decomposed_/;/** Doc comments show the API; they do not write it. */const COMMENT = /^\s*(\*|\/\/)/;+/**+ * The nearest preceding definition at column zero. A subsystem announces once per+ * pass, so the unit an approval is granted to is the function a reader would+ * name — not the lambda or the `if` the write happens to sit inside.+ */+const DEFINITION = /^[A-Za-z_][\w:<>&*,\s]*?\b([A-Za-z_]\w*)\s*\(/;+const NOT_A_DEFINITION = /^(if|for|while|switch|return|else|catch|do)\b/;++function enclosing(lines, at) {+ for (let i = at; i >= 0; i--) {+ if (NOT_A_DEFINITION.test(lines[i])) continue;+ const m = DEFINITION.exec(lines[i]);+ if (m) return { fn: m[1], start: i };+ }+ return { fn: '(file scope)', start: 0 };+}++/** Where `fn`'s body ends: the next definition at column zero. */+function bodyOf(lines, start) {+ for (let i = start + 1; i < lines.length; i++) {+ if (!NOT_A_DEFINITION.test(lines[i]) && DEFINITION.test(lines[i])) return lines.slice(start, i).join('\n');+ }+ return lines.slice(start).join('\n');+}++/**+ * The block that bound a name to a Transform. Scoped, because one generated+ * dispatcher binds `c` to every component in the engine, each inside its own arm.+ */+function depths(lines) {+ const out = [];+ let depth = 0;+ for (const line of lines) {+ out.push(depth);+ for (const ch of line.replace(/\/\/.*$/, '')) {+ if (ch === '{') depth++;+ else if (ch === '}') depth--;+ }+ }+ return out;+}const { files, missing } = listTrackedSources(['src']);const cpp = files.filter((f) => /\.(cpp|hpp)$/.test(f));const hits = [];+const bodies = new Map();for (const rel of cpp) {- const text = readFileSync(path.join(ROOT, rel), 'utf8');- const lines = text.split('\n');- // Names bound to a Transform in this file, so `t->position = …` counts only- // where `t` is one. Cheap and per-file, which is where these bindings live.- const bound = new Set();- for (const line of lines) {- const m = /\b(\w+)\s*=\s*[^;]*\b(?:get|tryGet|emplace)<(?:ecs::)?Transform>/.exec(line)- ?? /(?:ecs::)?Transform&\s+(\w+)\s*=/.exec(line)- ?? /(?:ecs::)?Transform\*\s+(\w+)\s*=/.exec(line);- if (m) bound.add(m[1]);- }- if (bound.size === 0) continue;+ const lines = readFileSync(path.join(ROOT, rel), 'utf8').split('\n');+ const depth = depths(lines);+ const bound = [];lines.forEach((line, i) => {+ while (bound.length && bound[bound.length - 1].depth > depth[i]) bound.pop();+ const b = /\b(\w+)\s*=\s*[^;]*\b(?:get|tryGet|emplace|emplaceOrReplace)<(?:[\w:]*::)?Transform>/.exec(line)+ ?? /(?:[\w:]*::)?Transform&\s+(\w+)\s*[=)]/.exec(line)+ ?? /(?:[\w:]*::)?Transform\*\s+(\w+)\s*=/.exec(line);+ if (b) bound.push({ name: b[1], depth: depth[i] });if (OUTPUT.test(line) || COMMENT.test(line)) return;const m = WRITE.exec(line);- if (m && bound.has(m[1])) hits.push({ file: rel, line: i + 1, code: line.trim().slice(0, 84) });+ if (!m || !bound.some((x) => x.name === m[1])) return;+ const { fn, start } = enclosing(lines, i);+ if (!bodies.has(`${rel}#${fn}`)) bodies.set(`${rel}#${fn}`, bodyOf(lines, start));+ hits.push({ file: rel, line: i + 1, fn, code: line.trim().slice(0, 78) });});}+const errors = [];+const seamOf = (h) => SEAMS.find((s) => s.file === h.file && s.fn === h.fn);+for (const h of hits) {+ if (!seamOf(h)) {+ errors.push(`${h.file}:${h.line} — ${h.fn}() writes a Transform input and is not a declared seam`);+ }+}+for (const seam of SEAMS) {+ const mine = hits.filter((h) => h.file === seam.file && h.fn === seam.fn);+ if (mine.length === 0) {+ errors.push(`${seam.file} — ${seam.fn}() is approved as a writer and no longer writes anything`);+ continue;+ }+ const text = missing.some((m) => seam.file.startsWith(m)) ? null : readFileSync(path.join(ROOT, seam.file), 'utf8');+ if (seam.role === 'announces' && text && !text.includes(`${SEAM_CALL}(`)) {+ errors.push(`${seam.file} — ${seam.fn}() writes Transform inputs and its file never calls ${SEAM_CALL}()`);+ }+ if (seam.role === 'private world') {+ const body = bodies.get(`${seam.file}#${seam.fn}`) ?? '';+ // The claim is that nothing outside can read a stale value, which holds+ // only while the registry is the function's own AND it composes it.+ if (!/\bRegistry\s+\w+\s*;/.test(body) || !/TransformSystem|->update\(/.test(body)) {+ errors.push(`${seam.file} — ${seam.fn}() is approved as a private world, but does not build a Registry and compose it`);+ }+ }+}+{+ const text = readFileSync(path.join(ROOT, HIERARCHY_WRITER.file), 'utf8');+ const i = text.split('\n').findIndex((l) => l.includes(`${HIERARCHY_WRITER.fn}(`) && l.includes('Registry&'));+ const body = i < 0 ? '' : bodyOf(text.split('\n'), i);+ if (!body.includes(`${SEAM_CALL}(`)) {+ errors.push(`${HIERARCHY_WRITER.file} — ${HIERARCHY_WRITER.fn}() moves a subtree without announcing it`);+ }+}+const say = (s = '') => console.log(s);say('');-say('Producers of a Transform\'s LOCAL inputs, and who observes them');+say('Producers of a Transform\'s composition inputs');say('');-const w = Math.max(...KNOWN.map((k) => k[0].length));-say(` ${'producer'.padEnd(w)} ${'writes through'.padEnd(38)} TS sees C++ sees`);-say(` ${'-'.repeat(w)} ${'-'.repeat(38)} ------- --------`);-for (const [who, how, ts, cpp_] of KNOWN) {- say(` ${who.padEnd(w)} ${how.padEnd(38)} ${ts.padEnd(7)} ${cpp_}`);+const w = Math.max(...SEAMS.map((s) => s.fn.length), ...TS_PRODUCERS.map((p) => p[0].length));+for (const seam of SEAMS) {+ const n = hits.filter((h) => h.file === seam.file && h.fn === seam.fn).length;+ say(` ${seam.fn.padEnd(w)} ${String(n).padStart(2)} write(s) ${seam.role}`);+ say(` ${' '.repeat(w)} ${seam.file}`);+ say(` ${' '.repeat(w)} ${seam.why}`);+ say('');}+say(` ${HIERARCHY_WRITER.fn.padEnd(w)} hierarchy announces`);+say(` ${' '.repeat(w)} ${HIERARCHY_WRITER.file}`);+say(` ${' '.repeat(w)} a reparent moves a subtree without touching one transform field`);say('');-say(' No layer sees all of them. A TS write reaches the component heap through a');-say(' ptr setter and calls no C++; a C++ system writes the same bytes and reports');-say(' nothing to the tracker. An epoch invalidated from either side alone is');-say(' therefore incomplete by construction.');+say(' From TypeScript, through a pointer setter that calls no C++:');+for (const [who, how] of TS_PRODUCERS) say(` ${who.padEnd(w)} ${how}`);say('');-say(` ${hits.length} C++ write site(s) found by scanning ${cpp.length} file(s):`);-for (const h of hits) say(` ${h.file}:${h.line} ${h.code}`);+say(` ${hits.length} C++ write site(s) across ${cpp.length} scanned file(s).`);if (missing.length) say(` NOT scanned: ${missing.join(', ')}`);say('');++if (errors.length) {+ console.error('Writers with no seam:\n');+ for (const e of errors) console.error(` ${e}`);+ console.error('\nA new producer needs an entry in SEAMS saying how the composition learns of it.');+ console.error(`Either call ${SEAM_CALL}() once per pass, or compose the registry you wrote in place.`);+ if (GATE) process.exit(1);+} else if (GATE) {+ console.log(`transform writers OK: ${hits.length} write site(s), every one under a declared seam.`);+}diff --git a/tools/gates.mjs b/tools/gates.mjsindex dd5ec853b..82be0db3e 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -56,6 +56,9 @@ export const GATES = [// disagree with nothing between them to notice.{ id: 'generated-fresh', run: 'node tools/check-generated-fresh.mjs' },{ id: 'transform-seam', run: 'node tools/check-transform-seam.mjs' },+ // …and the other direction: every C++ writer of a composition input is a+ // seam somebody classified, rather than a count that moves with a refactor.+ { id: 'transform-writers', run: 'node tools/census-transform-writers.mjs --gate' },{ id: 'api-surface', run: 'node tools/api-surface.mjs --check' },// Reads the snapshot the gate above just proved current, against the one the// last release tag shipped — drift says the surface moved, this says a promise did.