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.

census(ecs): who can move a Transform, and who can see it happen

esenginebcfa103140fb
diff --git a/package.json b/package.json
index 3d1ef68fb..653cdcf2e 100644
--- a/package.json
+++ b/package.json
@@ -33,6 +33,7 @@
"census:mutation": "node tools/mutation-census.mjs",
"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: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.mjs
new file mode 100644
index 000000000..f1e4ddd2e
--- /dev/null
+++ b/tools/census-transform-writers.mjs
@@ -0,0 +1,90 @@
+// 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.
+ *
+ * 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.
+ *
+ * node tools/census-transform-writers.mjs
+ *
+ * Reports; asserts nothing. `worldPosition` and friends are excluded: they are
+ * composition OUTPUT, not input.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listTrackedSources } from './lib/sourceRoots.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * 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.
+ */
+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 FIELDS = String.raw`(position|rotation|scale)`;
+/** A write to a local field through something typed `Transform`. */
+const WRITE = new RegExp(String.raw`\b(\w+)\s*(?:\.|->)\s*${FIELDS}\s*(?:\.\w+\s*)?=[^=]`);
+const OUTPUT = /world(Position|Rotation|Scale)|cachedMatrix_|decomposed_/;
+/** Doc comments show the API; they do not write it. */
+const COMMENT = /^\s*(\*|\/\/)/;
+
+const { files, missing } = listTrackedSources(['src']);
+const cpp = files.filter((f) => /\.(cpp|hpp)$/.test(f));
+
+const hits = [];
+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;
+ lines.forEach((line, 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) });
+ });
+}
+
+const say = (s = '') => console.log(s);
+say('');
+say('Producers of a Transform\'s LOCAL inputs, and who observes them');
+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_}`);
+}
+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('');
+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}`);
+if (missing.length) say(` NOT scanned: ${missing.join(', ')}`);
+say('');