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 declared component field has a reader

esenginecc04f66cafcd
diff --git a/sdk/src/ai/nav/NavPlugin.ts b/sdk/src/ai/nav/NavPlugin.ts
index 065237523..d0cee8982 100644
--- a/sdk/src/ai/nav/NavPlugin.ts
+++ b/sdk/src/ai/nav/NavPlugin.ts
@@ -96,7 +96,13 @@ export function stepNavigation(
tf.position.y = pos.y;
world.set(entity, Transform, tf);
- if (rt.index >= rt.waypoints.length) {
+ // Arrival is a DISTANCE, not the end of the list: an agent that has to
+ // stop short of what it is chasing never reaches the last waypoint, and
+ // one that walks the path exactly stands on top of its target.
+ const goal = rt.waypoints[rt.waypoints.length - 1];
+ const withinGoal = goal !== undefined && agent.arriveRadius > 0
+ && Math.hypot(goal.x - pos.x, goal.y - pos.y) <= agent.arriveRadius;
+ if (rt.index >= rt.waypoints.length || withinGoal) {
agent.arrived = true;
agent.hasTarget = false;
world.set(entity, NavAgent, agent);
diff --git a/sdk/tests/nav-step.test.ts b/sdk/tests/nav-step.test.ts
index 1888a1b74..dc6b80d10 100644
--- a/sdk/tests/nav-step.test.ts
+++ b/sdk/tests/nav-step.test.ts
@@ -94,7 +94,31 @@ describe('stepNavigation', () => {
frames++;
}
expect(world.agent(e).arrived).toBe(true);
- expect(world.pos(e).x).toBeCloseTo(90, 1);
+ // Within the agent's arrive radius of the goal, not standing on it.
+ const at = world.pos(e);
+ expect(Math.hypot(at.x - 90, at.y - 0)).toBeLessThanOrEqual(6);
+ });
+
+ it('stops at arriveRadius, so an agent can be told to keep its distance', () => {
+ // The field is the whole point: an agent chasing something must be able
+ // to stop short of it rather than walk onto it.
+ const nav = new Navigation();
+ nav.setGrid(new NavGrid({ width: 20, height: 3, cellSize: 10 }));
+ const world = new FakeWorld();
+ const runtimes = new Map<Entity, AgentRuntime>();
+ const e = world.spawnAgent(0, 0, {
+ speed: 150, repathInterval: 0, hasTarget: true, targetX: 150, targetY: 0, arriveRadius: 40,
+ });
+
+ let frames = 0;
+ while (!world.agent(e).arrived && frames < 200) {
+ stepNavigation(world, nav, 0.05, runtimes);
+ frames++;
+ }
+ expect(world.agent(e).arrived).toBe(true);
+ const stopped = world.pos(e);
+ expect(150 - stopped.x).toBeLessThanOrEqual(40);
+ expect(150 - stopped.x).toBeGreaterThan(20);
});
it('does not move an agent toward an unreachable target', () => {
diff --git a/tools/check-component-fields.mjs b/tools/check-component-fields.mjs
new file mode 100644
index 000000000..96c6b9a67
--- /dev/null
+++ b/tools/check-component-fields.mjs
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-component-fields.mjs — a declared field has a reader.
+ *
+ * A component field is a knob in the inspector. One nothing reads is a knob that
+ * does nothing, and it looks exactly like one that works: `Mesh2D.lit` sat there
+ * for five bricks while the mesh path picked its shader from the geometry
+ * instead, so imported models could not be drawn unlit and geometry without
+ * normals could not be lit at all.
+ *
+ * Reflection and serialization name every field by construction, so those are
+ * not readers: the generated code and the scene codec are excluded. What is left
+ * is the engine, its side modules, the SDK and the editor — wherever a field can
+ * actually change what happens.
+ */
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Fields with no reader because the feature behind them is not built. Each one is
+ * a promise the inspector currently makes and the engine does not keep; the entry
+ * says which, so the list reads as work rather than as permission.
+ */
+const DECLARED_GAPS = {
+ 'Camera.showFrustum': 'an editor-only flag for drawing a camera\'s view volume, which nothing draws yet',
+ 'TilemapLayer.originOffset': "Tiled's per-tileset tileoffset, which the loader does not read either",
+ 'TilemapLayer.tilesetRows': 'written by the Tiled loader; nothing bounds-checks a tile id against it yet',
+};
+
+const components = JSON.parse(
+ readFileSync(path.join(ROOT, 'docs', 'astro', 'src', 'data', 'components.generated.json'), 'utf8'),
+).components;
+
+// Every source a field can be READ from. Generated files name every field by
+// construction, so including them would make this gate vacuous.
+const files = execFileSync('git', ['ls-files', 'src', 'sdk/src', 'desktop/src', 'native', 'plugins'],
+ { cwd: ROOT, encoding: 'utf8' }).split('\n').filter(Boolean);
+const blob = files
+ .filter((f) => /\.(cpp|hpp|h|ts|tsx)$/.test(f) && !f.includes('generated'))
+ .map((f) => readFileSync(path.join(ROOT, f), 'utf8'))
+ .join('\n');
+
+const problems = [];
+const unusedGaps = new Set(Object.keys(DECLARED_GAPS));
+for (const component of components) {
+ for (const field of component.fields ?? []) {
+ const name = `${component.name}.${field.key}`;
+ // `.key`, `->key`, or the key quoted (a TS projection writes it by name).
+ if (new RegExp(`[.>'"]${field.key}\\b`).test(blob)) {
+ if (DECLARED_GAPS[name]) {
+ problems.push(`${name} is listed as a gap but something reads it — drop the entry`);
+ unusedGaps.delete(name);
+ }
+ continue;
+ }
+ unusedGaps.delete(name);
+ if (DECLARED_GAPS[name]) continue;
+ problems.push(`${name} has no reader — an inspector knob that does nothing`);
+ }
+}
+for (const name of unusedGaps) {
+ problems.push(`${name} is listed as a gap but is not a field any more — drop the entry`);
+}
+
+if (problems.length) {
+ console.error('check-component-fields: a declared field has no reader.\n');
+ for (const p of problems) console.error(` ${p}`);
+ console.error('\nGive it one, remove the field, or record it in DECLARED_GAPS with what is missing.');
+ process.exit(1);
+}
+
+const fields = components.reduce((n, c) => n + (c.fields?.length ?? 0), 0);
+console.log(`check-component-fields: ${fields} field(s) across ${components.length} components`
+ + ` all have a reader; ${Object.keys(DECLARED_GAPS).length} declared gap(s).`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index e408864d5..71b387fc9 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -73,6 +73,7 @@ export const GATES = [
{ id: 'tool-calls', run: 'node tools/check-tool-calls.mjs' },
{ id: 'capabilities', run: 'node tools/check-capabilities.mjs' },
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs' },
+ { id: 'component-fields', run: 'node tools/check-component-fields.mjs' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },
{ id: 'key-codes', run: 'node tools/check-key-codes.mjs' },