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
test(gates): a parameter gameplay writes is one the graph answers
esenginee0f828f61deb
diff --git a/tools/check-animator-parameters.mjs b/tools/check-animator-parameters.mjsnew file mode 100644index 000000000..ec860eb22--- /dev/null+++ b/tools/check-animator-parameters.mjs@@ -0,0 +1,83 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-animator-parameters.mjs — a parameter gameplay writes is one the+ * graph answers.+ *+ * `grounded` was published every fixed step, asserted by two unit tests, and+ * read by no transition in any shipped graph: a character left the ground and+ * went on looking exactly the same. Producer, tests and declaration all green,+ * player behaviour unchanged.+ *+ * The claim is narrow on purpose. Not "every declared parameter must be used" —+ * a graph may carry a knob for a game that has not been written yet — but: a+ * parameter the ENGINE writes on a game's behalf must reach at least one+ * consumer in the graph that declares it. A consumer is a transition condition+ * or the parameter a blend selects on.+ *+ * node tools/check-animator-parameters.mjs+ */+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)), '..');++/** Names gameplay code hands the animator, read from the constants that spell+ * them so a renamed parameter cannot quietly leave this list behind. */+function writtenByGameplay() {+ const src = readFileSync(path.join(ROOT, 'sdk/src/gameplay/ThirdPersonController.ts'), 'utf8');+ return [...src.matchAll(/^export const TPC_\w+ = '([^']+)';/gm)].map((m) => m[1]);+}++/** Every parameter a state, transition or blend in `scope` reads. */+function consumers(scope, into = new Set()) {+ for (const t of scope.anyStateTransitions ?? []) {+ for (const c of t.conditions ?? []) into.add(c.param);+ }+ for (const state of scope.states ?? []) {+ for (const t of state.transitions ?? []) {+ for (const c of t.conditions ?? []) into.add(c.param);+ }+ // A blend selects on one, which is a use as real as a condition.+ for (const motion of [state.motion, state.blend].filter(Boolean)) {+ collectMotion(motion, into);+ }+ if (state.stateMachine) consumers(state.stateMachine, into);+ }+ return into;+}++function collectMotion(motion, into) {+ if (!motion || typeof motion !== 'object') return;+ if (typeof motion.parameter === 'string') into.add(motion.parameter);+ for (const stop of motion.thresholds ?? []) collectMotion(stop.motion, into);+}++const written = new Set(writtenByGameplay());+const { files } = listTrackedSources(['examples', 'templates', 'fixtures', 'sdk/src']);+const graphs = files.filter((f) => f.endsWith('.esanimator'));++const problems = [];+for (const file of graphs) {+ let def;+ try {+ def = JSON.parse(readFileSync(path.join(ROOT, file), 'utf8'));+ } catch (e) {+ problems.push(`${file} is not readable as a graph — ${e.message}`);+ continue;+ }+ const used = consumers(def);+ for (const param of def.parameters ?? []) {+ if (!written.has(param.name) || used.has(param.name)) continue;+ problems.push(`${file}: "${param.name}" is written by the engine every step and read by `+ + 'no transition or blend here — a dead knob, not a feature waiting for one');+ }+}++for (const p of problems) console.log(`✗ ${p}`);+console.log(problems.length === 0+ ? `check-animator-parameters: ${graphs.length} graph(s) — every engine-written parameter has a consumer`+ : `check-animator-parameters: ${problems.length} finding(s)`);+process.exit(problems.length === 0 ? 0 : 1);diff --git a/tools/gates.mjs b/tools/gates.mjsindex 7a3b4e8eb..2129f196e 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -143,6 +143,7 @@ export const GATES = [{ id: 'capabilities', run: 'node tools/check-capabilities.mjs', needs: 'editor' },{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs', needs: 'editor' },{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },+ { id: 'animator-parameters', run: 'node tools/check-animator-parameters.mjs' },// A field declares that it carries an asset in one place; everything that acts// on live assets has to read THAT rather than keep a list of components beside it.{ id: 'live-asset-rebind', run: 'node tools/check-live-asset-rebind.mjs' },