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.

feat(gates): a component that declares a space must be drawn

esengine3d8aa2b91f01
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cccd8abb3..a05d42bda 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,16 @@ published separately; it ships inside the editor.
### Fixed
+- **A component that describes a space is drawn, and a gate says so.** `NavAgent`'s
+ routing width and `ParticleForceField`'s reach were authorable numbers with
+ nothing on screen to show what they covered — the same gap the light gizmos had.
+ Both now draw a world radius ring, from one table rather than a gizmo path each:
+ a radius is a circle wherever it comes from, and what differs is what it means,
+ which is its colour. New gate `check-gizmo-coverage`: a component declaring a
+ spatial field (`halfExtents`, `radius`, `shapeRadius`, `halfHeight`, `extents`)
+ must be named in the viewport, because `gizmo-chrome`'s list is written by hand
+ and cannot notice a component nobody added to it.
+
- **A navigation volume is visible while it is being placed.** Nothing renders a
`NavVolume` and nothing collides with it, so the box that decides where agents
may walk was invisible in the editor — the one thing about it worth checking.
diff --git a/desktop b/desktop
index dd9ca4108..8bb5fd75b 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit dd9ca4108e5e2cfdc5208d25ef64de9f24d5c774
+Subproject commit 8bb5fd75bdeaa4c2ef73a001d5e0e0d3955f3527
diff --git a/tools/check-gizmo-coverage.mjs b/tools/check-gizmo-coverage.mjs
new file mode 100644
index 000000000..efc24d121
--- /dev/null
+++ b/tools/check-gizmo-coverage.mjs
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-gizmo-coverage.mjs — a component that describes a SPACE is drawn.
+ *
+ * `gizmo-chrome` proves that the gizmos it lists paint something. What it cannot
+ * do is notice a new component: its list is written by hand, so a component added
+ * with a radius or a box on it is invisible in the editor AND invisible to the
+ * 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.
+ */
+import { readFileSync, 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');
+/** 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 volume of world". Deliberately
+ * short: a name that also describes something flat (`size` on a UI node, `scale`)
+ * would make the rule about layout rather than about space.
+ */
+const SPATIAL_FIELDS = new Set(['halfExtents', 'radius', 'shapeRadius', 'halfHeight', 'extents']);
+
+/** Components whose extent is deliberately not drawn, and why. */
+const DECLARED_GAPS = {};
+
+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);
+}
+const viewport = readFileSync(VIEWPORT, 'utf8');
+
+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;
+ judged++;
+ if (DECLARED_GAPS[component.name]) {
+ unusedGaps.delete(component.name);
+ 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.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');
+}
+
+for (const name of unusedGaps) {
+ problems.push(`DECLARED_GAPS names "${name}", which no longer declares a spatial field`);
+}
+
+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.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)` : ''}.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 54893b6b2..179100bc1 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -94,6 +94,7 @@ export const GATES = [
{ id: 'wgsl-twin', run: 'node tools/check-wgsl-twin.mjs' },
{ 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: 'dirty-source', run: 'node tools/check-dirty-source.mjs', needs: 'editor' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },
{ id: 'key-codes', run: 'node tools/check-key-codes.mjs' },