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(editor): inspect live agent route failures on demand

yhhff1c37a00ced
diff --git a/.github/workflows/editor-spatial.yml b/.github/workflows/editor-spatial.yml
index 27e6d32dd..60bfef89c 100644
--- a/.github/workflows/editor-spatial.yml
+++ b/.github/workflows/editor-spatial.yml
@@ -28,6 +28,8 @@ jobs:
artifact: gizmo-legacy-2d-editor-checks
- suite: regression
artifact: gizmo-regression-editor-checks
+ - suite: navigation
+ artifact: navigation-inspector-editor-checks
env:
ESTELLA_WIN_W: '1480'
ESTELLA_WIN_H: '920'
@@ -61,6 +63,9 @@ jobs:
mkdir -p desktop/public/wasm
cp build/wasm/web/* desktop/public/wasm/
pnpm --dir desktop exec vite build
+ - name: Check live agent route inspection
+ if: matrix.suite == 'navigation'
+ run: node tools/verify-navigation-inspector.mjs
- name: Check trusted spatial gestures and undo
if: matrix.suite == 'spatial'
run: node tools/verify-gizmo-planes.mjs
@@ -99,5 +104,6 @@ jobs:
output/gizmo-origins-ci
output/gizmo-legacy-2d-ci
output/gizmo-regression-ci
+ output/navigation-inspector-ci
if-no-files-found: warn
retention-days: 3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 757db40fc..ebb1fc3e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,8 @@ published separately; it ships inside the editor.
### Added
+- **Inspect a live agent's current route on demand.** The Play inspector reports partial routes, disconnected regions, insufficient clearance and baked-radius mismatches, with sampled world endpoints, radius and query cost. It queries only on request, discards results across selection/session changes, and identifies unsupported device sessions or custom implementations explicitly.
+
- **Navigation queries distinguish complete routes from best-effort paths.** `queryWorldPath` reports missing surfaces or endpoints, disconnected regions, grid clearance failures and mesh radius mismatches; custom surfaces without diagnostics report unknown. Grid searches reuse revision-scoped connectivity after a failed search, while walkability and dynamic obstacles invalidate it. Dynamic blockers now contribute to body clearance; the legacy path API keeps returning partial approaches.
- **Spatial transform handles fade behind scene geometry.** A persistent Viewport setting can restore always-visible handles; flat 2D widgets retain their appearance. Scoped immediate-draw depth state disables overlay depth writes and restores the previous state, including when drawing throws. Older cores keep their existing overlay fallback.
diff --git a/desktop b/desktop
index 918f30436..af5b633f9 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 918f304361890270dba66aafbdf256c4b39cdf72
+Subproject commit af5b633f9739abd1dcf4bbae555727b008529823
diff --git a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/gameplay/ai/navigation.mdx
index afb650157..3b29e2389 100644
--- a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx
+++ b/docs/astro/src/content/docs/gameplay/ai/navigation.mdx
@@ -264,6 +264,15 @@ Repeated grid queries reuse working memory. Returned routes remain independent,
so callers may retain or edit them without changing a later search. Route costs,
endpoint snapping and best-effort partial paths retain their existing behavior.
+In the editor, select a `NavAgent` during **Play** and expand its component in
+Details. **Inspect current route** queries once from its current world position
+to its stored target with the agent's radius. It shows the reason, sampled world
+endpoints, waypoint count and query time. Results are snapshots; click again after
+changing doors, obstacles or targets. No search runs during recurring inspector
+refreshes. This requires a ready local Play session; connected device inspection
+does not yet support this query. It describes the installed surface, not pending
+rebuilds or the agent's cached movement route.
+
The reproducible CPU corpus runs in headless Chromium with door and building
changes on 32/64/128-cell maps and 64 simultaneous replans:
diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx
index 38f41c931..b23199dc1 100644
--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx
+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai/navigation.mdx
@@ -225,6 +225,12 @@ if (result.status !== 'complete') console.info(result.reason);
重复格子查询会复用工作内存;返回的路线仍各自独立,可保留或修改,不会影响后续查询。
路线代价、端点吸附和尽量靠近的部分路径行为保持一致。
+编辑器中,在**运行**时选择 `NavAgent`,展开详情里的该组件,点击**诊断当前路线**。
+它按代理半径,从当前世界位置到已存目标查询一次,显示原因、查询端点、路径点数与耗时。
+结果为快照,门、障碍或目标变化后需要重新点击;详情面板定期刷新不会触发寻路。
+该功能需要已就绪的本地运行会话,暂不支持连接设备的诊断。它描述当前安装的导航表面,
+不代表尚未提交的重建状态或代理缓存的移动路线。
+
可复现的 CPU 语料使用无头 Chromium,在 32/64/128 格地图中开关门、放置建筑并同时重算
64 个代理的路径:
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 03bc41249..c9bec1890 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,12 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(editor): inspect live agent route failures on demand':
+ { note: "Inspect a live agent's current route on demand." },
+ 'feat(inspector): inspect live agent route failures on demand':
+ { note: "Inspect a live agent's current route on demand." },
+ 'fix(inspector): use shared controls for navigation diagnostics':
+ { note: "Inspect a live agent's current route on demand." },
'perf(nav): reuse grid search workspaces across queries':
{ note: 'Grid path searches reuse their working memory.' },
'feat(nav): diagnose partial routes and reuse disconnected grid topology':
diff --git a/tools/verify-navigation-inspector.mjs b/tools/verify-navigation-inspector.mjs
new file mode 100644
index 000000000..a6ca2b601
--- /dev/null
+++ b/tools/verify-navigation-inspector.mjs
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+import fs from 'node:fs';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { runElectron } from './lib/electronRun.mjs';
+if (!process.env.CI) throw Error('Editor acceptance runs only in CI. Do not launch the local editor.');
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const out = path.join(root, 'output/navigation-inspector-ci');
+fs.mkdirSync(out, { recursive: true });
+const records = [];
+for (const state of ['complete', 'disconnected', 'insufficient-clearance', 'no-target']) {
+ const project = fs.mkdtempSync(path.join(out, 'project-'));
+ fs.mkdirSync(path.join(project, 'assets/scenes'), { recursive: true });
+ fs.mkdirSync(path.join(project, 'src'));
+ fs.writeFileSync(path.join(project, 'project.esproject'), JSON.stringify({ formatVersion: '1', name: 'Navigation inspector acceptance', defaultScene: 'assets/scenes/main.esscene', spineVersion: 'none' }));
+ fs.writeFileSync(path.join(project, 'assets/scenes/main.esscene'), JSON.stringify({ version: '1.0', name: 'Main', entities: [
+ { id: 1, name: 'Route subject', parent: null, children: [], components: [
+ { type: 'Transform', data: { position: { x: 2, y: 4, z: 0 } } },
+ { type: 'NavAgent', data: { hasTarget: state !== 'no-target', targetX: 8, targetY: 4, targetZ: 0, radius: state === 'insufficient-clearance' ? 2 : 0 } },
+ ] },
+ ] }));
+ fs.writeFileSync(path.join(project, 'src/components.ts'), "export { NavAgent } from 'esengine/ai';");
+ fs.writeFileSync(path.join(project, 'src/main.ts'), `
+import { addPlugin } from 'esengine';
+import { Nav, Navigation, NavGrid } from 'esengine/ai';
+addPlugin({name:'navigation-inspection-fixture',build(app){
+ const nav=new Navigation(),grid=new NavGrid({width:11,height:9,cellSize:1});
+ ${state === 'disconnected' || state === 'insufficient-clearance' ? `for(let y=0;y<9;y++) if(${state === 'insufficient-clearance' ? 'y!==4' : 'true'}) grid.setWalkable(5,y,false);` : ''}
+ nav.setSurface(grid);app.insertResource(Nav,nav);
+}});`);
+ const script = `(async()=>{
+ const e=window.__estellaEditor;
+ e.surface.select(1);
+ const wait=async(f)=>{for(let i=0;i<300;i++){const v=f();if(v)return v;await new Promise(r=>setTimeout(r,20));}throw Error('Navigation inspector did not settle');};
+ const head=await wait(()=>[...document.querySelectorAll('.comp-head')].find(h=>h.textContent.includes('Nav')));
+ if(!document.querySelector('.nav-diagnostic'))head.click();
+ const panel=await wait(()=>document.querySelector('.nav-diagnostic'));
+ const button=panel.querySelector('button');
+ if(button.disabled)throw Error('Route inspection disabled in ready Play');
+ if(panel.querySelector('[role=status]').textContent.trim())throw Error('Route queried without clicking');
+ button.click();
+ await wait(()=>!button.disabled&&panel.querySelector('[role=status]').textContent.trim());
+ return {state:${JSON.stringify(state)},text:panel.textContent,status:panel.querySelector('[role=status]').textContent};
+ })()`;
+ const run = runElectron(['.'], { via: 'npx', encoding: 'utf8', cwd: path.join(root, 'desktop'), timeout: 180000, env: {
+ ESTELLA_SHOT: path.join(out, state + '.png'), ESTELLA_SHOT_PROJECT: project,
+ ESTELLA_SHOT_SCENE: 'assets/scenes/main.esscene', ESTELLA_SHOT_PLAY: '1',
+ ESTELLA_SHOT_LOCALE: 'en', ESTELLA_SHOT_EVAL: script,
+ } });
+ fs.writeFileSync(path.join(out, state + '.log'), run.stdout + '\n' + run.stderr);
+ assert.equal(run.status, 0, run.stderr);
+ const line = run.stdout.split('\n').find(line => line.startsWith('[eval] '));
+ assert(line, 'Missing inspector observation');
+ const result = JSON.parse(line.slice('[eval] '.length));
+ const expected = { complete: 'Route reaches the resolved destination', disconnected: 'Start and target are disconnected', 'insufficient-clearance': 'this agent cannot fit', 'no-target': 'No active destination' }[state];
+ assert(result.status.includes(expected), JSON.stringify(result));
+ assert(fs.existsSync(path.join(out, state + '.png')), 'Missing editor screenshot');
+ records.push(result);
+ fs.writeFileSync(path.join(out, 'observations.json'), JSON.stringify({ records }, null, 2));
+}
+console.log('Navigation inspector: 4 live Play scenarios passed.');