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
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.mjsindex 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.mjsindex 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`);