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
feat(editor): inspect live agent route failures on demand
yhhff1c37a00ced
diff --git a/.github/workflows/editor-spatial.yml b/.github/workflows/editor-spatial.ymlindex 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: regressionartifact: gizmo-regression-editor-checks+ - suite: navigation+ artifact: navigation-inspector-editor-checksenv:ESTELLA_WIN_W: '1480'ESTELLA_WIN_H: '920'@@ -61,6 +63,9 @@ jobs:mkdir -p desktop/public/wasmcp 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 undoif: matrix.suite == 'spatial'run: node tools/verify-gizmo-planes.mjs@@ -99,5 +104,6 @@ jobs:output/gizmo-origins-cioutput/gizmo-legacy-2d-cioutput/gizmo-regression-ci+ output/navigation-inspector-ciif-no-files-found: warnretention-days: 3diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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/desktopindex 918f30436..af5b633f9 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 918f304361890270dba66aafbdf256c4b39cdf72+Subproject commit af5b633f9739abd1dcf4bbae555727b008529823diff --git a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/gameplay/ai/navigation.mdxindex 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 buildingchanges 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.mdxindex 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.mjsindex 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.mjsnew file mode 100644index 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.');