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 shipped component somebody has authored
esengine7ab7073a5d05
diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjsnew file mode 100644index 000000000..1be6ff78d--- /dev/null+++ b/tools/check-corpus-authoring.mjs@@ -0,0 +1,294 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-corpus-authoring.mjs — a shipped component somebody has authored.+ *+ * The corpus that ships to users — `examples/` plus the editor's `templates/` —+ * is the only place where a person can see a component the way they will meet+ * it: placed in a scene, its fields set in the Inspector, saved to a document.+ * A component with runtime tests and a docs page but no authored instance+ * anywhere has never had that path walked, and nothing noticed: the audio demo+ * named its clip in code for two years while `AudioSource`, the engine's own+ * audio component, appeared in no scene in the entire corpus.+ *+ * So the polarity is inverted, as in check-gizmo-coverage. DISCOVERY is the+ * engine's own registry — every authorable component, transient ones excepted,+ * since runtime readings are not authored. The EVIDENCE side answers itself:+ * a component a corpus document actually carries needs no entry here, and gains+ * one the moment an example is written. What must be answered by hand is the+ * remainder — every component the corpus has never authored:+ *+ * authored (not written here — a scene or prefab carries it)+ * code-only an example uses it from TypeScript, and code is its honest+ * surface; say why authoring it would not be the demonstration+ * structural the editor refuses to add it at all (HIDDEN_COMPONENTS)+ * derived a system inserts it at runtime; in an authored document it+ * would be a bug, not coverage+ * owed debt. A creator-facing component nothing in the corpus has+ * ever authored. The reason is the work item, never an excuse+ *+ * The check runs both ways. A disposition that claims debt for a component the+ * corpus now authors fails ("promote it"), so paying it off is not something+ * one can do quietly; `code-only` fails when no example imports it, because an+ * accounting error and a real gap read identically from here.+ *+ * Run: node tools/check-corpus-authoring.mjs [--list]+ */+import { readFileSync, readdirSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const SNAPSHOT = path.join(ROOT, 'docs', 'astro', 'src', 'data', 'components.generated.json');+/** Where the editor decides what a person may add to an entity at all. */+const EDITOR_SCHEMA = path.join(ROOT, 'desktop', 'src', 'engine', 'schema.ts');+/** Every project directory that ships to users — the same two roots check-examples walks. */+const CORPUS_ROOTS = ['examples', 'templates'];++/**+ * The authored documents a component instance can live in. Nothing else can+ * carry one: a `.esanimator` names clips, a `.esbt` names behaviours, an+ * `.estileset` names tiles — none of them places a component on an entity.+ */+const INSTANCE_FORMATS = ['.esscene', '.esprefab'];++/**+ * Every other extension the corpus holds, and why a component instance cannot+ * be hiding in it. An extension in neither list fails — a format nobody+ * classified is one this reader is silently not reading, which is how a census+ * reports full coverage of a world smaller than the real one.+ */+const NOT_INSTANCE_FORMATS = {+ '.ts': 'example source — read separately, as the code-only evidence',+ '.esproject': 'project settings; it names scenes rather than entities',+ '.esanimator': 'an animator graph: states and transitions over clips',+ '.estimeline': 'a timeline: tracks over time, addressed to entities the scene owns',+ '.esanim': 'a clip: curves over time',+ '.esmaterial': 'a material: shader + uniform values',+ '.esshader': 'shader source',+ '.esenv': 'an environment: sky, ambient and the HDR behind them',+ '.estileset': 'a tileset: tiles, collision shapes and terrain rules',+ '.eslocale': 'translated strings',+ '.esbt': 'a behaviour tree',+ '.esfsm': 'a state machine',+ '.esmesh': 'an import result, regenerated from the model beside it',+ '.inputmap': 'input actions and their bindings',+ '.tmj': 'a Tiled map; the engine derives RuntimeOnly entities from it',+ '.json': 'tsconfig / package metadata / user component schemas',+ '.meta': 'import settings for the file beside it',+ '.md': 'prose about the project, not the project',+ '.mjs': 'the project\'s own tooling',+ '.js': 'built output or a host shim',+ '.html': 'a page hosting the built game',+ '.gitignore': 'version control, not content',+ '.png': 'a texture',+ '.ktx2': 'a compressed texture',+ '.hdr': 'an environment map',+ '.gltf': 'an imported model',+ '.bin': 'model or compressed-asset payload',+ '.atlas': 'a Spine atlas, written by Spine',+ '.skel': 'a Spine skeleton, written by Spine',+ '.wav': 'audio content',+ '.mp4': 'video content',+ '.zip': 'a packaged fixture',+ '.wasm': 'a side module binary',+};++/**+ * Every component the corpus has never authored, and what that silence means.+ * Keyed by component name; value is [disposition, reason]. A component a scene+ * or prefab carries is NOT listed — the evidence answers for it.+ */+const DISPOSITION = {+ // — structural: the editor's HIDDEN_COMPONENTS refuses them. Not every hidden+ // component is here — UIController, UIGear and EventBinding have an authoring+ // panel of their own, and the corpus authors them through it. —+ Parent: ['structural'],+ Children: ['structural'],+ Name: ['structural'],++ // — derived: a system writes them; authored, they would be a bug —+ RuntimeOnly: ['derived', 'tags a world-only entity a system re-derives; scene serialization skips tagged entities, so authoring one would delete it on save'],+ NetGhost: ['derived', 'replication tags a remote proxy with it; the authority writes it, never the scene'],+ SceneOwner: ['derived', 'scene loading records which scene an entity came from; authoring it would claim an ownership the loader never granted'],++ // — code-only: an example demonstrates it from TypeScript, honestly —+ Replicated: ['code-only', 'multiplayer-arena declares its replicated set beside the server systems that own it; the wire table is a contract both ends compile against, not scene content'],++ // — owed: a creator-facing component nothing in the shipped corpus authors.+ // Each reason names where the coverage belongs. —+ AudioListener: ['owed', 'spatial audio has no corpus at all: no scene sets AudioSource.spatial, so the listener every 3D mix needs is absent and the engine\'s "spatial audio used but no AudioListener entity found" warning has never been seen. audio-demo or third-person-3d'],+ UIDialog: ['owed', 'the Create picker builds a Dialog in one click and its own header promises a prefab dialog works "without any code hookup" — ui-controls calls createDialog() from code instead, so the promise has no witness'],+ UIToggle: ['owed', 'Create > UI > Toggle exists; ui-controls builds toggles with createToggle() and no scene carries one'],+ UIToggleGroup: ['owed', 'exclusive toggles (tab bar, difficulty picker) sit on the common ancestor — a relationship only an authored hierarchy demonstrates'],+ UISlider: ['owed', 'ui-controls drives sliders from code; the widget prefab the editor drops has never been in a shipped scene'],+ UIDropdown: ['owed', 'same picker, same silence — and a dropdown is the widget whose authored structure (list, item template) is hardest to get right from a screenshot'],+ UIScroll: ['owed', 'no corpus scene scrolls anything; ui-list virtualizes from code'],+ UIMask: ['owed', 'clipping a subtree is authored geometry, and nothing in the corpus clips one'],+ TextInput: ['owed', 'chat and rich-text create inputs in code; the editor offers TextInput as a one-click widget that no scene has ever held'],+ ThemeStyle: ['owed', 'the widget factories mark entities with theme roles so re-theming reaches them; a hand-authored UI gets none of that, and no corpus scene shows how to tag one'],++ CapsuleCollider2D: ['owed', 'physics-playground and physics-spinner build capsules in code; the Inspector shape and its gizmo have no authored instance'],+ ChainCollider2D: ['owed', 'physics-spinner builds its chain in code — the one 2D shape whose authored form (a point list) the editor actually has an editing mode for'],+ PolygonCollider2D: ['owed', 'no project authors a polygon collider, in code or in a scene'],+ SegmentCollider2D: ['owed', 'no project authors a segment collider, in code or in a scene'],+ SphereCollider3D: ['owed', 'physics-3d authors 45 boxes and no other 3D shape; the whole shape family rests on BoxCollider3D'],+ CapsuleCollider3D: ['owed', 'the shape a character body actually uses, and physics-3d authors none'],+ MeshCollider3D: ['owed', 'static level geometry collides against meshes; Jolt ships the single-sided MeshShape and no corpus scene authors one'],+ ConvexCollider3D: ['owed', 'the shape a dynamic prop needs, absent everywhere'],+ DistanceJoint2D: ['owed', 'physics-playground authors Hinge/Motor/Slider and stops there'],+ FixedJoint2D: ['owed', 'same scene, same gap'],+ WheelJoint2D: ['owed', 'a vehicle is the demonstration, and the corpus has no vehicle'],+ DistanceJoint3D: ['owed', 'physics-3d authors HingeJoint3D alone; four 3D joints ship with no instance anywhere, not even a fixture'],+ FixedJoint3D: ['owed', 'ships with no instance anywhere, not even a fixture'],+ PointJoint3D: ['owed', 'ships with no instance anywhere, not even a fixture'],+ SliderJoint3D: ['owed', 'ships with no instance anywhere, not even a fixture'],++ SortingGroup: ['owed', 'the component that makes a subtree sort as one unit — the fix for every "my character\'s sword draws behind the wrong prop", demonstrated nowhere'],+ CacheAsBitmap: ['owed', 'flattening a static subtree into one texture is a performance decision with no example showing when to take it'],+ BitmapText: ['owed', 'Create > Bitmap Text exists; every corpus scene uses Text instead, so the pixel-font path ships unwitnessed'],+ SpriteMask: ['owed', 'space-shooter masks from code; masking is authored geometry and belongs in a scene'],+ TrailRenderer: ['owed', 'Create > Trail exists and trail-demo builds its trail in code'],+ ParticleForceField: ['owed', 'particle-demo adds force fields from code, and the field has a radius gizmo the Inspector already draws'],+ NavArea: ['owed', 'cost-modifying nav regions (mud, road) never appear; enemy-ai-3d authors NavVolume, NavLink and NavObstacle but no area'],+ Marker: ['owed', 'Create > Marker and Create > Trigger Area are one click each, and not one project places either — the converged target for .tmj object groups has no hand-authored instance'],+ Disabled: ['owed', 'the engine can deactivate an entity and the editor has no switch for it (the Outliner eye toggles visibility, a different thing), so no scene ships one'],+ Velocity: ['owed', 'motion without a physics body — the cheapest thing in the engine, authored nowhere'],+};++const snapshot = JSON.parse(readFileSync(SNAPSHOT, 'utf8'));+const authorable = snapshot.components.filter((c) => !c.transient).map((c) => c.name);++function walk(dir, out = []) {+ for (const e of readdirSync(dir, { withFileTypes: true })) {+ // `.esengine/` stages a full SDK copy inside every project: read it and every+ // component matches, from the engine's own source rather than anyone's scene.+ if (e.isDirectory()) {+ if (!['node_modules', '.esengine', 'dist', 'build'].includes(e.name)) walk(path.join(dir, e.name), out);+ } else out.push(path.join(dir, e.name));+ }+ return out;+}++const files = [];+for (const root of CORPUS_ROOTS) {+ const dir = path.join(ROOT, root);+ if (existsSync(dir)) walk(dir, files);+}++const problems = [];++/** A format nobody classified is a reader that silently skips it. */+const unclassified = new Set();+for (const f of files) {+ const ext = path.extname(f);+ if (!ext || INSTANCE_FORMATS.includes(ext) || ext in NOT_INSTANCE_FORMATS) continue;+ unclassified.add(ext);+}+for (const ext of unclassified) {+ problems.push(`the corpus holds "${ext}" files and nothing says whether a component instance can live in one`+ + ' — classify the FORMAT in check-corpus-authoring.mjs, so the answer holds for every file of it');+}++/** Which projects author each component, and which import it from TypeScript. */+const authored = new Map();+const inCode = new Map();+const projectOf = (f) => path.relative(ROOT, f).split(path.sep).slice(0, 2).join('/');++for (const f of files) {+ const ext = path.extname(f);+ if (INSTANCE_FORMATS.includes(ext)) {+ const text = readFileSync(f, 'utf8');+ for (const m of text.matchAll(/"type"\s*:\s*"([A-Za-z0-9_]+)"/g)) {+ if (!authored.has(m[1])) authored.set(m[1], new Set());+ authored.get(m[1]).add(projectOf(f));+ }+ } else if (ext === '.ts') {+ const text = readFileSync(f, 'utf8');+ for (const name of authorable) {+ if (!new RegExp(`\\b${name}\\b`).test(text)) continue;+ if (!inCode.has(name)) inCode.set(name, new Set());+ inCode.get(name).add(projectOf(f));+ }+ }+}++const hidden = existsSync(EDITOR_SCHEMA) ? readFileSync(EDITOR_SCHEMA, 'utf8') : null;+const hiddenNames = hidden+ ? new Set((hidden.match(/const HIDDEN_COMPONENTS = new Set\(\[([^\]]*)\]/)?.[1] ?? '')+ .split(',').map((s) => s.trim().replace(/^'|'$/g, '')).filter(Boolean))+ : null;++const counts = { authored: 0, 'code-only': 0, structural: 0, derived: 0, owed: 0 };+const owed = [];+const unused = new Set(Object.keys(DISPOSITION));++for (const name of authorable) {+ unused.delete(name);+ const carriers = authored.get(name);+ const declared = DISPOSITION[name];++ if (carriers?.size) {+ counts.authored++;+ // Debt somebody paid without saying so goes on claiming a hole that is filled.+ if (declared) {+ problems.push(`${name} is declared "${declared[0]}" and ${[...carriers].join(', ')} now authors it`+ + ' — drop the entry; the evidence answers for it');+ }+ continue;+ }++ if (!declared) {+ problems.push(`no corpus scene or prefab authors ${name}, and nothing says why`+ + ' — add it to an example, or give it a disposition (code-only / structural / derived / owed)'+ + ' in tools/check-corpus-authoring.mjs');+ continue;+ }++ const [kind, reason] = declared;+ if (!(kind in counts)) {+ problems.push(`${name} declares an unknown disposition "${kind}"`);+ continue;+ }+ counts[kind]++;++ if (kind === 'structural') {+ if (hiddenNames && !hiddenNames.has(name)) {+ problems.push(`${name} is declared structural, but the editor's HIDDEN_COMPONENTS does not list it`+ + ' — the Add Component menu offers it, so a person can author it');+ }+ continue;+ }+ if (!reason) {+ problems.push(`${name} is declared "${kind}" with no reason — say what the silence means`);+ continue;+ }+ if (kind === 'code-only' && !inCode.has(name)) {+ problems.push(`${name} is declared code-only and no example imports it either`+ + ' — it is owed, not demonstrated');+ continue;+ }+ if (kind === 'owed') owed.push(` ${name} — ${reason}`);+}++for (const name of unused) {+ problems.push(`DISPOSITION names "${name}", which the engine no longer registers as an authorable component`);+}++if (process.argv.includes('--list')) {+ console.log(`${authorable.length} authorable component(s): `+ + Object.entries(counts).map(([k, n]) => `${k} ${n}`).join(', '));+ if (owed.length) console.log(`owed — nothing in the shipped corpus authors it:\n${owed.join('\n')}`);+}++if (problems.length) {+ console.error(`check-corpus-authoring: ${problems.length} problem(s)`);+ for (const p of problems) console.error(` ${p}`);+ process.exit(1);+}++const note = hiddenNames ? '' : ' (no editor checkout — "structural" was not verified against HIDDEN_COMPONENTS)';+console.log(`check-corpus-authoring: ${authorable.length} authorable component(s) judged`+ + ` — ${counts.authored} authored in the corpus, ${counts['code-only']} demonstrated from code,`+ + ` ${counts.structural} structural, ${counts.derived} engine-written, ${counts.owed} owed`+ + ` (--list names them).${note}`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex b34ba6986..8fbd77e67 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -219,6 +219,7 @@ export const GATES = [{ id: 'shader-literals', run: 'node tools/check-shader-literals.mjs' },{ id: 'import-settings', run: 'node tools/check-import-settings.mjs' },{ id: 'gizmo-coverage', run: 'node tools/check-gizmo-coverage.mjs', needs: 'editor' },+ { id: 'corpus-authoring', run: 'node tools/check-corpus-authoring.mjs' },{ id: 'lod-authoring', run: 'node tools/check-lod-authoring.mjs', needs: 'editor' },{ id: 'shadow-plan', run: 'node tools/check-shadow-plan.mjs' },{ id: 'light-cap', run: 'node tools/check-light-cap.mjs' },