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
// 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',
'.esaudioevent': 'an audio event definition; source instances belong to scenes',
'.esworld': 'world rules: biomes, recipes and layers as data; the WorldGen that names the file belongs to a scene',
'.esterrainlayer': 'a terrain layer: the textures one kind of ground is drawn with; the Terrain that lists it belongs to a scene',
'.esavatar': 'how one rig spells the joints another rig\'s clips name',
'.esmaterial': 'a material: shader + uniform values',
'.esshader': 'shader source',
'.esenv': 'an environment: sky, ambient and the HDR behind them',
'.esprobes': 'a bake\'s answer at a grid of points: nine coefficients each',
'.estileset': 'a tileset: tiles, collision shapes and terrain rules',
'.eslocale': 'translated strings',
'.esbt': 'a behaviour tree',
'.esfsm': 'a state machine',
'.esgraph': 'a script graph: events, an exec wire, and data wires between named verbs',
'.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',
'.jpg': 'a texture',
'.svg': 'editable vector artwork; component instances belong to its consuming scene',
'.ktx2': 'a compressed texture',
'.hdr': 'an environment map',
'.fnt': 'a bitmap font\'s metrics; the page beside it is a texture and what USES it is authored elsewhere',
'.gltf': 'an imported model',
'.glb': 'an imported model, binary',
'.txt': 'prose or a licence beside the project, not the project',
'.py': 'tooling beside the project, not the project',
'.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'],
Planet: ['owed', 'authored by a game today (star-neighbors, a round planet from its own generator); an example that registers a planet provider is owed'],
MeshInstances: ['derived', 'the foliage and world generation systems write it, one entity a kind and part of a cell; its places are data a system computes, not something a scene authors'],
ParticleCollider: ['owed', 'no example has a GPU emitter bouncing off a shape yet; the particle-gpu scenes are where the first one goes'],
Waterfall: ['owed', 'no example has water falling off a lip yet; the terrain-and-water example, where a river meets a cliff, is where the first one goes'],
Breakable: ['owed', 'no example scene breaks an object yet; a breakable crate in the physics-3d example is where the first one goes'],
Hitboxes: ['owed', 'no example scene authors a hitbox set yet; the first one goes in an example with melee combat'],
WaterfallAnchor: ['owed', 'no example fixes a fall to a river yet; it goes with the first Waterfall in the terrain-and-water example'],
GripProfile: ['owed', 'no example holds an object in its two hands yet; a character with a rifle is where the first one goes'],
GripHolder: ['owed', 'no example holds an object in its two hands yet; a character with a rifle is where the first one goes'],
GripPose: ['owed', 'no example holds a tool in a named pose yet; a character with something in its hand is where the first one goes'],
GripSurface: ['owed', 'no example marks where a hand may take hold of a mesh yet; the character with a rifle that gets the first grip is where the first one goes'],
UIWorldAnchor: ['owed', 'no example pins a HUD marker over a point in the 3D world yet; the first 3D example with an objective marker is where the first one goes'],
VoxelTerrain: ['owed', 'no example digs in a volume yet; a small mine is where the first one goes'],
RoadDecal: ['owed', 'no example lays a road over a terrain yet; wilds is where the first one goes'],
PlantProxy: ['derived', 'the plant interaction makes it for a plant near a contact, and takes it away again; a scene never holds one'],
FoliageContact: ['owed', 'no example has a character walking through plants yet; wilds gains one when it gets a player'],
PlacedFoliage: ['derived', 'a generated world grows its plants through the same machinery without the component, and a project that places plants by hand writes the kinds and records with a script from its own rules; the lists are generated data, not something a scene is authored by hand with'],
PlacedObject: ['derived', 'a generated world writes it on what it places for the game to interact with; authored, it would name a placement no rule made'],
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 —
SpringBone: ['owed', 'no example carries a rigged character with hair or a tail yet; the first one imported with its chains goes into one'],
ContentRect: ['owed', 'the Cocos importer writes it on every node it converts, and no example is an imported Cocos scene yet; the first one that is carries it'],
RectAnchors: ['owed', 'the Cocos importer writes it for a Widget; it arrives in the corpus with the first imported Cocos scene'],
NodeVisibility: ['owed', 'the glTF importer writes it for KHR_node_visibility; it arrives in the corpus with the first imported model that hides a node'],
ParticleModelUnits: ['owed', 'the glTF importer writes it for an emitter authored in model units; it arrives with the first imported scene that carries particles'],
CompoundCollider3D: ['owed', 'the glTF importer writes it for OMI physics shapes; it arrives with the first imported model that carries colliders'],
GroupOpacity: ['owed', 'the Cocos importer writes it for a UIOpacity; it arrives in the corpus with the first imported Cocos scene'],
SpringBoneCollider: ['owed', 'no example has a spring-bone chain to keep out of anything; it arrives with the first SpringBone'],
FirstPersonController: ['owed', 'no example has a player who walks in the first person yet; the first-person template, when there is one, authors it'],
FirstPersonViewModel: ['owed', 'arrives with FirstPersonController in the first-person template; a held thing needs a character to be held by'],
PathFollower: ['owed', 'no example moves a thing along a spline yet; a platform or a cart on a track is the first to'],
Ragdoll: ['owed', 'no example carries a skinned character that is knocked down yet; the first one with a rigged enemy goes into one'],
RagdollJoint: ['owed', 'arrives with the first example that has a Ragdoll, which is the only place a bone needs a say of its own'],
Bone2D: ['owed', 'no example carries a 2D rig yet; the first character built in the rig editor is the place for it'],
IK2D: ['owed', 'arrives with the first example that has a Bone2D, which is the only place a chain has bones to bend'],
BoneConstraint2D: ['owed', 'arrives with the first example that has a Bone2D, for the same reason'],
TerrainBand2D: ['owed', 'no example draws a 2D ground from a spline yet; the first side-scroller built on one carries it'],
Impostor: ['owed', 'no example has far objects small enough to stand a picture in for yet; an open 3D world with distant props is the first to'],
Billboard: ['owed', 'no example draws a card that faces the camera yet; a 3D scene with signs or far trees on cards is the first to'],
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. —
BlobShadow: ['owed', 'only the blob-shadow render fixture places one; an example for a phone-scale scene that wants a shadow without a shadow map is owed'],
Footsteps: ['owed', 'no committed example places one yet; it arrives with the top-down example CoverFade is owed'],
StepSurface: ['owed', 'no committed example places one yet; it arrives with the top-down example CoverFade is owed'],
SwayPusher: ['owed', 'no committed example places one yet; it arrives with the top-down example CoverFade is owed'],
FogOfWar: ['owed', 'no committed example places one yet; it arrives with the top-down example CoverFade is owed'],
SightViewer: ['owed', 'no committed example places one yet; it arrives with the top-down example CoverFade is owed'],
SightTarget: ['owed', 'no committed example places one yet; it arrives with the top-down example CoverFade is owed'],
CoverFade: ['owed', 'no committed example places one yet; an example of a top-down hut whose roof thins as the player walks in is owed'],
CoverFadeTarget: ['owed', 'the tag that goes with CoverFade, and owed with it'],
RainUpright: ['owed', 'no committed example places one yet; it arrives with the top-down rain example RainShelter is owed'],
RainShelter: ['owed', 'no committed example places one yet; it arrives with the top-down rain example CoverFade is owed'],
CompositeBatch: ['owed', 'no corpus scene has a model that moves as a whole yet: its parts are folded while the game runs, which a golden project has no frame to certify — tests/composite-batch.test.ts and the composite-batch editor check (same frame as the plain ship, a moved root re-merges nothing, an added part re-merges one chunk) hold it'],
StaticBatch: ['owed', 'no corpus scene marks a mesh yet: a marked mesh is merged while the game runs, which a golden project has no frame to certify — the static-batch-on / static-batch-off render scenes, tests/static-batch.test.ts and the static-batch editor check hold it'],
};
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}`);