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.

fix(gates): the two gates that exist to catch this had the same blind spot

esenginec05fc8a9ba72
diff --git a/tools/check-gizmo-coverage.mjs b/tools/check-gizmo-coverage.mjs
index 019c84370..13a2b21c4 100644
--- a/tools/check-gizmo-coverage.mjs
+++ b/tools/check-gizmo-coverage.mjs
@@ -9,11 +9,33 @@
* gate — which is how a NavVolume shipped with a number nobody could see the
* extent of.
*
- * The rule here is the one that can be decided statically: a field named for a
- * spatial extent means the component occupies a volume of the world, and the
- * viewport must name it somewhere — the only place a gizmo is computed. Whether
- * the drawing actually reaches the screen is gizmo-chrome's question, so add a
- * case there too; this one is about not forgetting.
+ * That is why this file does NOT hold a list of spatial field names. It held one
+ * for a while, and the list is the same failure one level up: `loadRadius`,
+ * `prefetchRadius`, `unloadRadius` and `cellSize` arrived with world streaming,
+ * none of them was in the enum, so the newest feature in the engine was never
+ * judged at all while this gate reported every component green.
+ *
+ * So the rule is inverted. DISCOVERY is broad and structural — an authored,
+ * numeric field whose name carries a length word. Every pair it finds must then
+ * carry a DISPOSITION saying what the number is:
+ *
+ * extent a region of world nothing renders — the viewport must name the
+ * component, which is where a gizmo's geometry is computed
+ * renders a world length whose own drawing IS the picture (a sprite's size)
+ * no-place a world length that limits or parameterises something else and
+ * has no region of its own (a step height, a contact skin)
+ * not-world not measured in world space at all (type metrics, a screen
+ * fraction, a texture's pixel size)
+ * owed an extent nothing draws. Debt, recorded as debt — never a reason
+ *
+ * A pair with no disposition FAILS. That is the whole point: the next component
+ * with a number in it cannot be quietly skipped because nobody thought to add
+ * its field name anywhere. It has to be answered.
+ *
+ * Granularity note: a disposition is per FIELD, the drawn check is per COMPONENT
+ * (textually, the viewport naming it at all). A component that draws one of its
+ * extents and forgets another still passes here — that is gizmo-chrome's
+ * question. This one is about not forgetting a component entirely.
*/
import { readFileSync, existsSync } from 'node:fs';
import path from 'node:path';
@@ -24,60 +46,192 @@ const SNAPSHOT = path.join(ROOT, 'docs', 'astro', 'src', 'data', 'components.gen
/** The one file where a gizmo's geometry is computed. */
const VIEWPORT = path.join(ROOT, 'desktop', 'src', 'engine', 'ViewportController.ts');
-/** Field names that mean "this component occupies a region of world". */
-const SPATIAL_FIELDS = new Set(['halfExtents', 'radius', 'shapeRadius', 'halfHeight', 'extents', 'size']);
+/** A name that carries any of these could be naming a length. Deliberately loose:
+ * a false positive costs one line of disposition, a false negative costs a
+ * feature nobody can see. */
+const LENGTH_WORDS = /(radius|extent|bounds|size|width|height|depth|distance|range)/i;
+/** Only a number can be a length; `Dimension`, `enum` and the curve objects cannot. */
+const NUMERIC = /^(number|Vec2|Vec3|Vec4)$/;
/**
- * Components whose `size` IS what they draw, so the picture is the component.
- * Listed rather than excluded by field name: `size` covers both a sprite (drawn,
- * needs no outline) and a post-process volume (drawn by nothing at all), and
- * dropping the name to avoid the first hid the second for as long as it existed.
+ * What every discovered field IS. Keyed `Component.field`, because the same name
+ * means different things on different components: `cellSize` is a voxel on a
+ * NavVolume, a tile on a TilemapLayer, and a streamed cell of world on a
+ * StreamedWorld.
*/
-const DRAWS_ITSELF = new Set(['Sprite', 'ShapeRenderer', 'MeshRenderer', 'BitmapText', 'UIVisual', 'UINode']);
+const DISPOSITION = {
+ // A region of world nothing renders — the viewport has to outline it.
+ 'BoxCollider2D.halfExtents': 'extent',
+ 'BoxCollider2D.radius': 'extent',
+ 'BoxCollider3D.halfExtents': 'extent',
+ 'CapsuleCollider2D.radius': 'extent',
+ 'CapsuleCollider2D.halfHeight': 'extent',
+ 'CapsuleCollider3D.radius': 'extent',
+ 'CapsuleCollider3D.halfHeight': 'extent',
+ 'CircleCollider2D.radius': 'extent',
+ 'PolygonCollider2D.radius': 'extent',
+ 'SphereCollider3D.radius': 'extent',
+ 'CharacterController3D.radius': 'extent',
+ 'CharacterController3D.halfHeight': 'extent',
+ 'Camera.orthoSize': 'extent',
+ 'Light.radius': 'extent',
+ 'MeleeAttack.radius': 'extent',
+ 'NavAgent.radius': 'extent',
+ 'NavAgent.arriveRadius': 'extent',
+ 'NavArea.halfExtents': 'extent',
+ 'NavObstacle.halfExtents': 'extent',
+ 'NavLink.radius': 'extent',
+ 'NavVolume.halfExtents': 'extent',
+ 'ParticleForceField.radius': 'extent',
+ 'ParticleEmitter.shapeRadius': 'extent',
+ 'ParticleEmitter.shapeSize': 'extent',
+ 'PostProcessVolume.size': 'extent',
+ 'ShadowCaster2D.size': 'extent',
+ 'TilemapLayer.cellSize': 'extent',
+
+ // The component's own drawing is the picture; an outline round it would trace
+ // what is already on screen.
+ 'Sprite.size': ['renders', 'the sprite drawn at it is the outline'],
+ 'Sprite.tileSize': ['renders', 'the repeat of a drawn sprite'],
+ 'ShapeRenderer.size': ['renders', 'the shape drawn at it is the outline'],
+ 'ShapeRenderer.cornerRadius': ['renders', 'a corner of the shape it draws'],
+ 'UIVisual.tileSize': ['renders', 'the repeat of a drawn nine-slice'],
+ 'BitmapText.fontSize': ['renders', 'type metrics — the glyphs are the picture'],
+ 'Text.fontSize': ['renders', 'type metrics — the glyphs are the picture'],
+ 'Text.lineHeight': ['renders', 'type metrics — the laid-out lines are the picture'],
+ 'Text.strokeWidth': ['renders', 'the stroke it draws round its own glyphs'],
+ 'TextInput.fontSize': ['renders', 'type metrics — the glyphs are the picture'],
+ 'TrailRenderer.startWidth': ['renders', 'the ribbon drawn at it is the outline'],
+ 'TrailRenderer.endWidth': ['renders', 'the ribbon drawn at it is the outline'],
+ 'ParticleEmitter.startSizeMin': ['renders', 'the particles drawn at it are the picture'],
+ 'ParticleEmitter.startSizeMax': ['renders', 'the particles drawn at it are the picture'],
+ 'ParticleEmitter.endSizeMin': ['renders', 'the particles drawn at it are the picture'],
+ 'ParticleEmitter.endSizeMax': ['renders', 'the particles drawn at it are the picture'],
+ 'ParticleEmitter.trailWidth': ['renders', 'the ribbon drawn at it is the outline'],
+
+ // A world length with no region of its own: it bounds or feeds something else,
+ // and a shape drawn for it would claim a place it does not occupy.
+ 'CharacterController2D.skinWidth': ['no-place', 'a contact skin held off the collider; drawn, it is that outline\'s own line width'],
+ 'CharacterController3D.stepHeight': ['no-place', 'the tallest step it will climb — a limit on motion, not a volume'],
+ 'NavVolume.cellSize': ['no-place', 'the voxel the box is diced into; the box is what has a place'],
+ 'NavVolume.cellHeight': ['no-place', 'the voxel the box is diced into; the box is what has a place'],
+ 'NavVolume.agentHeight': ['no-place', 'the agent the mesh is baked for, not a region of the volume'],
+ 'NavVolume.agentRadius': ['no-place', 'the agent the mesh is baked for, not a region of the volume'],
+ 'NavVolume.stepHeight': ['no-place', 'the agent the mesh is baked for, not a region of the volume'],
+ 'Light.shadowDistance': ['no-place', 'how far the directional cascade reaches from the CAMERA, so it has no place round this light'],
+ 'Light.shadowExtent': ['no-place', 'the shadow map\'s coverage, sized on the view rather than on the light\'s own place'],
+ 'PostProcessVolume.blendDistance': ['no-place', 'a fade band on the volume\'s own edge, which is already drawn'],
+ 'ParticleEmitter.trailMinDistance': ['no-place', 'how far a particle moves before a trail point is kept — a sampling step'],
+ 'TrailRenderer.minVertexDistance': ['no-place', 'how far the entity moves before a point is kept — a sampling step'],
+
+ // Not a length in world space at all.
+ 'Canvas.matchWidthOrHeight': ['not-world', 'a 0..1 blend between two fits, not a length'],
+ 'CacheAsBitmap.width': ['not-world', 'the cache texture\'s pixel size'],
+ 'CacheAsBitmap.height': ['not-world', 'the cache texture\'s pixel size'],
+ 'UIDropdown.optionHeight': ['not-world', 'a row height inside a laid-out box, resolved by layout rather than placed'],
+ 'LODGroup.lod1Size': ['not-world', 'a fraction of SCREEN height — a property of the view, not of the entity'],
+ 'LODGroup.lod2Size': ['not-world', 'a fraction of SCREEN height — a property of the view, not of the entity'],
+ 'LODGroup.lod3Size': ['not-world', 'a fraction of SCREEN height — a property of the view, not of the entity'],
+ 'LODGroup.cullSize': ['not-world', 'a fraction of SCREEN height — a property of the view, not of the entity'],
-/** Components whose extent is deliberately not drawn, and why. */
-const DECLARED_GAPS = {};
+ // Each of these IS a region of world and nothing draws it. An entry leaves this
+ // block by being drawn, never by being explained; adding one is a visible diff,
+ // which is the only ratchet there is.
+ 'AudioSource.minDistance': ['owed', 'the sphere inside which a 3D source is at full volume'],
+ 'AudioSource.maxDistance': ['owed', 'the sphere past which a 3D source is inaudible'],
+ 'Hunter.attackRange': ['owed', 'the reach it closes to before swinging — MeleeAttack.radius is drawn, this twin is not'],
+ 'Perceiver.range': ['owed', 'how far it can see; the cone it sees through is not drawn either'],
+ 'StreamedWorld.cellSize': ['owed', 'the grid the whole world is partitioned on, visible nowhere'],
+ 'ThirdPersonCamera.distance': ['owed', 'the boom length — where the camera actually ends up'],
+ 'ThirdPersonCamera.obstructionRadius': ['owed', 'the probe swept along the boom'],
+ 'WorldStreamingSource.prefetchRadius': ['owed', 'cells this close are prepared, and nothing on screen says where that is'],
+ 'WorldStreamingSource.loadRadius': ['owed', 'cells this close are brought in, and nothing on screen says where that is'],
+ 'WorldStreamingSource.unloadRadius': ['owed', 'resident cells are kept until past this, shown nowhere'],
+};
const components = JSON.parse(readFileSync(SNAPSHOT, 'utf8')).components;
// The editor is an optional submodule, and it is where every gizmo lives. Without
// it there is nothing to judge — reported, never rounded down to a pass.
if (!existsSync(VIEWPORT)) {
- console.log('check-gizmo-coverage: no editor checkout — the viewport was not scanned,'
- + ' so no component was judged.');
- process.exit(0);
+ console.log('check-gizmo-coverage: no editor checkout — the viewport was not scanned,'
+ + ' so no component was judged.');
+ process.exit(0);
}
const viewport = readFileSync(VIEWPORT, 'utf8');
+/** Every authored field a length word could be hiding in. A transient component
+ * is a runtime reading rather than something authored, and a readonly field is
+ * an output — neither is a number anybody sets, so neither can be drawn wrong. */
+function discover() {
+ const found = [];
+ for (const component of components) {
+ if (component.transient) continue;
+ for (const field of component.fields ?? []) {
+ if (field.readonly) continue;
+ if (!NUMERIC.test(field.type ?? '')) continue;
+ if (!LENGTH_WORDS.test(field.key)) continue;
+ found.push({ component: component.name, field: field.key, key: `${component.name}.${field.key}` });
+ }
+ }
+ return found;
+}
+
+const discovered = discover();
const problems = [];
-const unusedGaps = new Set(Object.keys(DECLARED_GAPS));
-let judged = 0;
-for (const component of components) {
- const spatial = (component.fields ?? []).map((f) => f.key).filter((k) => SPATIAL_FIELDS.has(k));
- if (spatial.length === 0) continue;
- if (DRAWS_ITSELF.has(component.name)) continue;
- judged++;
- if (DECLARED_GAPS[component.name]) {
- unusedGaps.delete(component.name);
- continue;
+const owed = [];
+const counts = { extent: 0, renders: 0, 'no-place': 0, 'not-world': 0, owed: 0 };
+const unused = new Set(Object.keys(DISPOSITION));
+
+for (const { component, field, key } of discovered) {
+ unused.delete(key);
+ const disposition = DISPOSITION[key];
+ if (!disposition) {
+ problems.push(`${key} has no disposition — say what this number is`
+ + ' (extent / renders / no-place / not-world), in tools/check-gizmo-coverage.mjs');
+ continue;
+ }
+ const kind = Array.isArray(disposition) ? disposition[0] : disposition;
+ if (!(kind in counts)) {
+ problems.push(`${key} declares an unknown disposition "${kind}"`);
+ continue;
+ }
+ counts[kind]++;
+ if (kind === 'owed') {
+ owed.push(` ${key} — ${disposition[1]}`);
+ // An owed extent that IS now named is debt somebody paid without saying so;
+ // left in the list it would go on claiming a hole that has been filled.
+ if (new RegExp(`\\b${component}\\b`).test(viewport)) {
+ problems.push(`${key} is listed as owed, but the viewport now names ${component}`
+ + ' — promote it to "extent"');
}
- // Named in the viewport at all: every gizmo path starts by asking the world
- // for the component, so the name is there by construction when one exists.
- if (new RegExp(`\\b${component.name}\\b`).test(viewport)) continue;
- problems.push(`${component.name} declares ${spatial.join(', ')} and the viewport never names it`
- + ' — its extent is a number with nothing on screen to show it');
+ continue;
+ }
+ if (kind !== 'extent') continue;
+ // Named in the viewport at all: every gizmo path starts by asking the world for
+ // the component, so the name is there by construction when one exists.
+ if (new RegExp(`\\b${component}\\b`).test(viewport)) continue;
+ problems.push(`${key} is an extent and the viewport never names ${component}`
+ + ' — its extent is a number with nothing on screen to show it');
+}
+
+for (const key of unused) {
+ problems.push(`DISPOSITION names "${key}", which is no longer an authored numeric field`);
}
-for (const name of unusedGaps) {
- problems.push(`DECLARED_GAPS names "${name}", which no longer declares a spatial field`);
+if (process.argv.includes('--list')) {
+ console.log(`discovered ${discovered.length} authored length-ish field(s): `
+ + Object.entries(counts).map(([k, n]) => `${k} ${n}`).join(', '));
+ if (owed.length) console.log(`owed — an extent nothing draws:\n${owed.join('\n')}`);
}
if (problems.length) {
- console.error(`check-gizmo-coverage: ${problems.length} problem(s)`);
- for (const p of problems) console.error(` ${p}`);
- console.error('\n Draw it in ViewportController and add a case to the editor\'s gizmo-chrome check,');
- console.error(' or record it in DECLARED_GAPS with the reason its extent needs no picture.');
- process.exit(1);
+ console.error(`check-gizmo-coverage: ${problems.length} problem(s)`);
+ for (const p of problems) console.error(` ${p}`);
+ console.error('\n Draw it in ViewportController and add a case to the editor\'s gizmo-chrome check,');
+ console.error(' or give the field a disposition saying what its number actually is.');
+ process.exit(1);
}
-console.log(`check-gizmo-coverage: ${judged} component(s) declare a spatial extent and the viewport draws each`
- + `${Object.keys(DECLARED_GAPS).length ? `; ${Object.keys(DECLARED_GAPS).length} declared gap(s)` : ''}.`);
+console.log(`check-gizmo-coverage: ${discovered.length} authored length-ish field(s) judged`
+ + ` — ${counts.extent} extent(s) drawn, ${counts.renders} self-drawn, ${counts['no-place']} placeless,`
+ + ` ${counts['not-world']} not world-space, ${counts.owed} owed (--list names them).`);
diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjs
index d85790477..6340e262f 100644
--- a/tools/check-project-settings.mjs
+++ b/tools/check-project-settings.mjs
@@ -19,10 +19,25 @@
* editor applied to the edit session, so authoring shows what ships
* play forwarded into the play realm
* packaged written into a shipped build
+ * authoring a CREATOR can set it, and this says where
*
* A field that legitimately cannot reach one of them declares that HERE, with a
* reason. The point is not that everything reaches everywhere; it is that a gap
* is a sentence somebody wrote, not an omission nobody noticed.
+ *
+ * `authoring` is the one that is not about transport. The four above ask whether
+ * a value SURVIVES the trip; that question was green for `msaaSamples` while the
+ * only way to set it was to hand-edit project.esproject, because nothing here
+ * asked whether a human could reach it at all. So it answers a different
+ * question, and it has its own vocabulary:
+ *
+ * ui a row in the settings registry — the id is named and checked
+ * manual deliberately manifest-only (advanced, or edited as a file), + why
+ * internal not creator-authored: derived, or a machine's business, + why
+ * owed creator-facing, reachable from no editor surface. Debt, recorded
+ * as debt — an entry leaves by growing a UI, never by being explained
+ *
+ * No answer is not an option: a setting nobody decided about fails here.
*/
import { readFileSync } from 'node:fs';
import path from 'node:path';
@@ -34,6 +49,8 @@ const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
const RUNTIME_CONFIG = 'pipeline/src/project/runtimeConfig.ts';
const FORMAT = 'pipeline/src/project/format.ts';
const STORE = 'desktop/src/project/ProjectStore.ts';
+/** Where a project setting becomes a row a creator can see. */
+const SETTINGS = 'desktop/src/settings/projectSettings.ts';
/**
* Where each field of RuntimeProjectConfig has to show up, and the reason when
@@ -95,6 +112,35 @@ const PARSE_KEY = {
msaaSamples: 'r.msaa',
};
+/**
+ * How a CREATOR sets each field — see the header for the four answers. `ui` names
+ * the settings-registry id, which is looked for in that file rather than trusted:
+ * a claim of "there is a UI" that nobody checked is the same as no UI.
+ */
+const AUTHORING = {
+ achievements: { ui: 'project.packaging.achievements' },
+ steamAppId: { ui: 'project.packaging.desktop.steam.appId' },
+ physicsEnabled: { ui: 'project.physics.enabled' },
+ physicsConfig: { ui: ['project.physics.gravityX', 'project.physics.gravityY', 'project.physics.fixedTimestep'] },
+ audioConfig: {
+ owed: 'buses, effects and duck rules are forwarded to Play and shipped, and the only '
+ + 'door into them is the automation surface (setSettings.audio) — ProjectStore.setAudio '
+ + 'has no human caller, so a person authors the mixer by editing project.esproject',
+ },
+ uiTheme: { ui: 'project.ui.theme' },
+ uiThemeColors: { ui: 'project.ui.color.' },
+ ySortLayers: { ui: 'project.rendering.ySortLayers' },
+ depthLayers: { ui: 'project.rendering.depthLayers' },
+ colorSpace: { ui: 'project.rendering.colorSpace' },
+ outputTransform: { ui: 'project.rendering.outputTransform' },
+ msaaSamples: {
+ owed: 'parsed, applied to the edit viewport, forwarded to Play and written into every '
+ + 'build — and set nowhere but by hand in project.esproject',
+ },
+ renderBackend: { ui: 'project.rendering.backend' },
+ screenFit: { ui: 'project.display.cameraFit' },
+};
+
/** Field names of the RuntimeProjectConfig interface, in declaration order. */
function runtimeConfigFields(src) {
const body = src.slice(src.indexOf('export interface RuntimeProjectConfig {'));
@@ -105,6 +151,7 @@ function runtimeConfigFields(src) {
const runtimeSrc = read(RUNTIME_CONFIG);
const formatSrc = read(FORMAT);
const storeSrc = read(STORE);
+const settingsSrc = read(SETTINGS);
const fields = runtimeConfigFields(runtimeSrc);
if (fields.length === 0) {
@@ -134,8 +181,32 @@ const CONSUMERS = {
packaged: inPackagedSlice,
};
+/**
+ * The authoring answer for one field, as a problem string or null. Kept apart
+ * from CONSUMERS because it is not the same question: those ask whether a value
+ * survives a trip, this asks whether anybody can set it in the first place.
+ */
+function authoringProblem(field) {
+ const answer = AUTHORING[field];
+ if (!answer) {
+ return `${field} says nothing about authoring — declare one of ui / manual / internal `
+ + `in tools/check-project-settings.mjs (AUTHORING.${field}), or record it as owed`;
+ }
+ const [kind] = Object.keys(answer);
+ if (kind === 'manual' || kind === 'internal' || kind === 'owed') {
+ return answer[kind] ? null : `${field} declares "${kind}" with no reason`;
+ }
+ if (kind !== 'ui') return `${field} declares an unknown authoring kind "${kind}"`;
+ const ids = Array.isArray(answer.ui) ? answer.ui : [answer.ui];
+ const missing = ids.filter((id) => !settingsSrc.includes(id));
+ return missing.length
+ ? `${field} claims a settings row (${missing.join(', ')}) that ${SETTINGS} does not register`
+ : null;
+}
+
const problems = [];
const gaps = [];
+const owed = [];
for (const field of fields) {
for (const [role, carries] of Object.entries(CONSUMERS)) {
const declared = DECLARED_GAPS[field]?.[role];
@@ -152,6 +223,9 @@ for (const field of fields) {
);
}
}
+ const authoring = authoringProblem(field);
+ if (authoring) problems.push(authoring);
+ if (AUTHORING[field]?.owed) owed.push(` ${field} → ${AUTHORING[field].owed}`);
// A field nobody parses is a field a manifest can hold and nothing will read.
if (!PARSE_KEY[field]) {
problems.push(`${field} has no PARSE_KEY entry — say which manifest branch reads it.`);
@@ -161,6 +235,7 @@ for (const field of fields) {
if (process.argv.includes('--list')) {
console.log(`project settings (${fields.length}): ${fields.join(', ')}`);
if (gaps.length) console.log(`declared gaps:\n${gaps.join('\n')}`);
+ if (owed.length) console.log(`owed — creator-facing, authorable from no editor surface:\n${owed.join('\n')}`);
}
if (problems.length) {
@@ -169,4 +244,5 @@ if (problems.length) {
process.exit(1);
}
-console.log(`check-project-settings: ${fields.length} settings, ${gaps.length} declared gaps — ok`);
+console.log(`check-project-settings: ${fields.length} settings, ${gaps.length} declared gaps,`
+ + ` ${owed.length} owed an authoring surface (--list names them) — ok`);