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(nav): a 3D scene authors where its agents may walk
esengine05a1da8f895e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 18545d712..b36f9036f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -54,6 +54,17 @@ published separately; it ships inside the editor.### Fixed+- **A 3D scene authors where its agents may walk.** `NavVolume` is a box on an+ entity; the nav plugin bakes the grid inside it out of the running 3D world and+ installs it, so navigation is authored in the scene rather than written by every+ game. It waits for the solver to create its bodies first — the queries resource+ exists as soon as the module loads, and a bake against a world with no bodies in+ it returns a grid of holes that one-bake-per-volume would never revisit. A volume+ that finds no walkable ground says so in the log instead of leaving agents+ standing still for no stated reason. New editor check `nav3d-play` walks an agent+ round a wall in the running game, which is the only place the side module, the+ plugin and the bodies all exist at once.+- **A navigation grid can be baked out of the 3D solver.** `bakeNavGrid` casts oneray straight down per cell and reads three answers off it: whether there isground, how high it is, and how steeply it is tilted. No hit is a hole, grounddiff --git a/desktop b/desktopindex 7316ca021..58fcc088e 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 7316ca0214a9a3838000ff15eab7e06cbfaa5373+Subproject commit 58fcc088ead16ef583cc6a7f7566fe88a1e77262diff --git a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/gameplay/ai/navigation.mdxindex 61df315dc..b0861ac7a 100644--- a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx+++ b/docs/astro/src/content/docs/gameplay/ai/navigation.mdx@@ -33,11 +33,44 @@ export const setupNav = defineSystem([Res(Nav)], (nav) => {| `cellSize` | number | World pixels per cell (square). || `origin` | `Vec2` | World position of cell `(0,0)`'s center. Defaults to `(0,0)`. || `walkable` | `Uint8Array` | Optional row-major `width*height` mask, `1` = walkable, `0` = blocked. Omitted → all walkable. |+| `plane` | `'xy' \| 'xz'` | Which world plane the cells lie in. `xy` (the default) is a flat scene's own plane; `xz` is the ground of a 3D one. |+| `surface` | `Float32Array` | Ground height per cell, on the axis the plane leaves out. Omitted → every cell sits at the origin's third axis. |+| `stepHeight` | number | Height difference between neighbours an agent can climb. `0` (the default) lets any difference through. |To derive a grid from a painted tilemap instead of hand-authoring the mask, use`navGridFromTilemapLayer` (which cells a layer's solid tiles block) or`navGridFromTiles`.+### A grid for a 3D scene++A 3D scene has geometry rather than a tile mask, so its grid is **baked** from the+bodies it already collides against — put a **`NavVolume`** on an entity and the nav+plugin fills the box it describes:++| `NavVolume` field | Description |+|---|---|+| `halfExtents` | Half the box to sample, in world pixels; the entity's Transform is its centre. |+| `cellSize` | World pixels per cell. Smaller is a finer route and a slower bake. |+| `maxSlopeDegrees` | Steepest ground an agent can stand on. Anything steeper is a wall. |+| `agentHeight` | Headroom an agent needs — a cell with less is a crawlspace, not a corridor. `0` skips the check. |+| `stepHeight` | How high a step the agent can climb between neighbouring cells. |+| `layers` | Physics layers the ground rays are cast against; `0` = every layer. |++One ray straight down per cell answers all of it: no hit is a hole, a tilted hit is+a slope or a wall, and a hit with a ceiling too close above it is unwalkable. The+bake waits for the 3D solver to create its bodies, so the grid appears a frame or+two into play, not at load.++<Aside type="caution">+ **One surface per column.** A bridge and the road under it collapse into whichever+ the ray meets first — the top of a wall becomes perfectly good ground two metres+ up, and it is `stepHeight` (not walkability) that keeps agents off it. Multi-level+ routing needs a real navmesh, which this is not.+</Aside>++`bakeNavGrid` is also callable directly if a game wants to bake on its own terms;+it takes any object with a `raycast`, which the `Physics3D` resource already is.+<Aside type="tip">The `Nav` resource also answers one-off queries directly:`nav.findWorldPath(from, to)` returns an array of world-space waypoints (ordiff --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 3048a2d55..77adf3802 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@@ -32,10 +32,39 @@ export const setupNav = defineSystem([Res(Nav)], (nav) => {| `cellSize` | number | 每格的世界像素(正方形)。 || `origin` | `Vec2` | 格子 `(0,0)` 中心的世界坐标。默认 `(0,0)`。 || `walkable` | `Uint8Array` | 可选的行主序 `width*height` 掩码,`1` = 可走,`0` = 阻挡。省略则全部可走。 |+| `plane` | `'xy' \| 'xz'` | 格子躺在哪个世界平面上。`xy`(默认)是平面场景自己的平面;`xz` 是 3D 场景的地面。 |+| `surface` | `Float32Array` | 每格地面的高度,在平面留出的那个轴上。省略则每格都位于原点的第三轴。 |+| `stepHeight` | number | 相邻格之间 agent 能爬上去的高度差。`0`(默认)表示任何高差都放行。 |若想从已绘制的瓦片地图推导网格,而不是手写掩码,用 `navGridFromTilemapLayer`(把某图层的实心瓦片视作阻挡)或 `navGridFromTiles`。+### 3D 场景的网格++3D 场景有的是几何而不是瓦片掩码,所以它的网格是从**它本来就在碰撞的那些刚体**上**烘焙**出来的+——在一个实体上放 **`NavVolume`**,导航插件就会把它描述的那个盒子填满:++| `NavVolume` 字段 | 说明 |+|---|---|+| `halfExtents` | 要采样的盒子半尺寸,单位世界像素;实体的 Transform 是盒子中心。 |+| `cellSize` | 每格的世界像素。越小路线越细、烘焙越慢。 |+| `maxSlopeDegrees` | agent 能站住的最陡地面。比这更陡的就是墙。 |+| `agentHeight` | agent 需要的头顶空间——不够的格子是爬行空间不是走廊。`0` 跳过这项检查。 |+| `stepHeight` | 相邻格之间 agent 能爬上去的台阶高度。 |+| `layers` | 地面射线投射的物理层;`0` = 所有层。 |++每格一条向下的射线就回答了全部:没命中是洞,命中面倾斜就是坡或墙,命中点上方净空不够就不可走。+烘焙会等 3D 求解器把刚体建出来,所以网格是在开始运行后一两帧出现的,不是加载时。++<Aside type="caution">+ **每一列只有一个面。**桥和桥下的路会塌成射线先碰到的那一个——墙顶会变成两米高处一块+ 完全可站的地面,把 agent 挡在墙外的是 `stepHeight` 而不是可走性。多层路网需要真正的+ navmesh,这里不是。+</Aside>++`bakeNavGrid` 也可以直接调用,让游戏按自己的方式烘焙;它只要一个带 `raycast` 的对象,+而 `Physics3D` 资源本身就是。+<Aside type="tip">`Nav` 资源也能直接回答一次性查询:`nav.findWorldPath(from, to)` 返回一组世界空间路点(没有路线时返回 `null`),无需 `NavAgent`。diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.tsindex ee99ef7bb..91cad5960 100644--- a/docs/astro/src/data/componentDocs.ts+++ b/docs/astro/src/data/componentDocs.ts@@ -144,6 +144,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {// ── Gameplay ───────────────────────────────────────────────────────────────NavAgent: { category: 'gameplay', summary: 'Steers an entity along a path found on the navigation grid.', doc: 'gameplay/ai/navigation' },+ NavVolume: { category: 'gameplay', summary: 'The box a navigation grid is baked over, sampled out of the 3D world.', doc: 'gameplay/ai/navigation' },Perceiver: { category: 'gameplay', summary: 'Senses nearby perception targets within a sight cone and range.', doc: 'gameplay/ai/perception' },Perception: { category: 'gameplay', summary: "What a perceiver currently sees — written each frame for the entity's own logic to read.", doc: 'gameplay/ai/perception' },PerceptionTarget: { category: 'gameplay', summary: 'Tag: perceivers can see this entity.', doc: 'gameplay/ai/perception' },diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex aee28d5cd..a0e604884 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -1989,6 +1989,60 @@"targetZ"]},+ {+ "name": "NavVolume",+ "source": "ts",+ "fields": [+ {+ "key": "halfExtents",+ "type": "Vec3",+ "default": "(1000, 500, 1000)"+ },+ {+ "key": "cellSize",+ "type": "number",+ "default": "50",+ "range": "≥ 1"+ },+ {+ "key": "maxSlopeDegrees",+ "type": "number",+ "default": "45",+ "range": "0–89"+ },+ {+ "key": "agentHeight",+ "type": "number",+ "default": "180",+ "doc": "Headroom an agent needs; 0 skips the ceiling check.",+ "range": "≥ 0"+ },+ {+ "key": "stepHeight",+ "type": "number",+ "default": "40",+ "range": "≥ 0"+ },+ {+ "key": "layers",+ "type": "number",+ "default": "0",+ "doc": "Layer mask the ground rays are cast against; 0 = every layer.",+ "range": "≥ 0",+ "advanced": true+ }+ ],+ "animatable": [+ "halfExtents.x",+ "halfExtents.y",+ "halfExtents.z",+ "cellSize",+ "maxSlopeDegrees",+ "agentHeight",+ "stepHeight",+ "layers"+ ]+ },{"name": "NetGhost","source": "ts",diff --git a/sdk/src/ai/nav/NavPlugin.ts b/sdk/src/ai/nav/NavPlugin.tsindex 28c78d44b..c37c0ca6f 100644--- a/sdk/src/ai/nav/NavPlugin.ts+++ b/sdk/src/ai/nav/NavPlugin.ts@@ -22,8 +22,14 @@ import {type ComponentData,} from '../../ecs/component';import { playModeOnly } from '../../ecs/env';+import {+ Physics3D, Physics3DRuntime, type Physics3DRuntime as Physics3DRuntimeData,+} from '../../physics3d/Physics3DPlugin';+import { log } from '../../util/logger';import { Navigation, Nav } from './Navigation';import { NavAgent } from './NavAgent';+import { NavVolume } from './NavVolume';+import { bakeNavGrid, type GroundProbe } from './bakeNavGrid';import { advanceAlongPath } from './follow';/** Per-entity runtime path state, owned by the driving system (not serialized). */@@ -37,6 +43,47 @@ export interface AgentRuntime {reachable: boolean;}+/**+ * Bake the first NavVolume that has not been baked yet, and install its grid.+ * `probe` is null until the caller has a world worth sampling (see the plugin):+ * a bake against a solver with no bodies yet returns a grid of holes, and one+ * bake per volume means it would stay that way.+ */+export function bakeVolumes(+ world: NavWorldView,+ nav: Navigation,+ probe: GroundProbe | null,+ baked: Set<Entity>,+): void {+ if (!probe) return;+ for (const entity of world.getEntitiesWithComponents([NavVolume, Transform])) {+ if (baked.has(entity)) continue;+ const volume = world.get(entity, NavVolume);+ const at = world.get(entity, Transform).position;+ const h = volume.halfExtents;+ nav.setGrid(bakeNavGrid(probe, {+ min: { x: at.x - h.x, y: at.y - h.y, z: at.z - h.z },+ max: { x: at.x + h.x, y: at.y + h.y, z: at.z + h.z },+ cellSize: volume.cellSize,+ maxSlopeDegrees: volume.maxSlopeDegrees,+ agentHeight: volume.agentHeight,+ stepHeight: volume.stepHeight,+ layers: volume.layers,+ }));+ baked.add(entity);+ // Baked once, so a volume that found nothing stays empty: say so rather+ // than leave a scene with agents that never move and no reason given.+ if (!nav.grid?.walkable.some(w => w === 1)) {+ log.warn('nav', `NavVolume on entity ${entity} baked no walkable ground —`+ + ' check that it covers the floor and that `layers` includes it');+ }+ // One grid is installed at a time, so a scene with two volumes would have+ // the last one win. Bake one per frame and let the newest be the active+ // one rather than silently merging boxes that may not touch.+ return;+ }+}+/** The slice of `World` the nav step needs — lets tests inject a fake. */export interface NavWorldView {getEntitiesWithComponents(components: readonly AnyComponentDef[]): readonly Entity[];@@ -122,18 +169,34 @@ export class NavPlugin implements Plugin {app.insertResource(Nav, new Navigation());const runtimes = new Map<Entity, AgentRuntime>();- app.world.onDespawn((entity: Entity) => runtimes.delete(entity));+ const baked = new Set<Entity>();+ app.world.onDespawn((entity: Entity) => {+ runtimes.delete(entity);+ baked.delete(entity);+ });app.addSystemToSchedule(Schedule.Update,defineSystem([Res(Nav), Res(Time), GetWorld()],(nav: Navigation, time: TimeData, world) => {+ // A NavVolume takes its grid from the 3D solver. Waiting for a+ // BODY, not for the queries resource: that appears when the+ // module loads, bodies only when it first steps.+ const runtime = app.hasResource(Physics3DRuntime)+ ? app.getResource<Physics3DRuntimeData>(Physics3DRuntime) : null;+ const populated = (runtime?.bodies.size ?? 0) > 0;+ const probe = populated && app.hasResource(Physics3D)+ ? app.getResource<GroundProbe | null>(Physics3D) : null;+ bakeVolumes(world as NavWorldView, nav, probe, baked);stepNavigation(world as NavWorldView, nav, time.delta, runtimes);},{name: 'NavAgentSystem',- touches: { writes: [NavAgent._name, Transform._name] },+ touches: {+ reads: [NavVolume._name],+ writes: [NavAgent._name, Transform._name],+ },// Both move an entity; for one carrying both, the path is the// intent and the drift is not, so the follow lands last. The// order registration already produced — declared, not changed.diff --git a/sdk/src/ai/nav/NavVolume.ts b/sdk/src/ai/nav/NavVolume.tsnew file mode 100644index 000000000..9b083dd25--- /dev/null+++ b/sdk/src/ai/nav/NavVolume.ts@@ -0,0 +1,48 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file NavVolume.ts+ * @brief The box a navigation grid is baked over — where a scene SAYS its+ * agents may walk.+ *+ * Authored, not coded. A flat scene builds its grid from a tilemap, which is+ * already data; a spatial one has only geometry, and asking every game to write+ * the bake by hand would put the one thing agents depend on outside the scene+ * that describes them.+ */++import { defineComponent } from '../../ecs/component';+import type { Vec3 } from '../../types';++export interface NavVolumeData {+ /** Half-extents of the box, in world pixels; the entity's Transform is its centre. */+ halfExtents: Vec3;+ /** World pixels per cell. Smaller is a finer route and a slower bake. */+ cellSize: number;+ /** Steepest ground an agent can stand on, in degrees from level. */+ maxSlopeDegrees: number;+ /** Headroom an agent needs; a cell with less is not walkable. 0 skips the check. */+ agentHeight: number;+ /** Height difference between neighbouring cells an agent can climb. */+ stepHeight: number;+ /** Physics layers the ground is on; 0 = every layer. */+ layers: number;+}++export const NavVolume = defineComponent<NavVolumeData>('NavVolume', {+ halfExtents: { x: 1000, y: 500, z: 1000 },+ cellSize: 50,+ maxSlopeDegrees: 45,+ agentHeight: 180,+ stepHeight: 40,+ layers: 0,+}, {+ fields: {+ halfExtents: { unit: 'px', category: 'Navigation' },+ cellSize: { min: 1, unit: 'px', category: 'Navigation' },+ maxSlopeDegrees: { min: 0, max: 89, unit: '°', category: 'Navigation' },+ agentHeight: { min: 0, unit: 'px', category: 'Navigation', tooltip: 'Headroom an agent needs; 0 skips the ceiling check.' },+ stepHeight: { min: 0, unit: 'px', category: 'Navigation' },+ layers: { min: 0, category: 'Navigation', advanced: true, tooltip: 'Layer mask the ground rays are cast against; 0 = every layer.' },+ },+});diff --git a/sdk/src/ai/nav/index.ts b/sdk/src/ai/nav/index.tsindex 146a84d6b..6873b39b7 100644--- a/sdk/src/ai/nav/index.ts+++ b/sdk/src/ai/nav/index.ts@@ -20,4 +20,5 @@ export {} from './bakeNavGrid';export { Navigation, Nav } from './Navigation';export { NavAgent, type NavAgentData, setNavDestination, stopNavAgent } from './NavAgent';+export { NavVolume, type NavVolumeData } from './NavVolume';export { NavPlugin, navPlugin } from './NavPlugin';diff --git a/sdk/tests/nav-bake.test.ts b/sdk/tests/nav-bake.test.tsindex 5070cd9b8..dd78a5597 100644--- a/sdk/tests/nav-bake.test.ts+++ b/sdk/tests/nav-bake.test.ts@@ -9,6 +9,10 @@*/import { describe, it, expect, vi } from 'vitest';import { bakeNavGrid, type GroundHit, type GroundProbe } from '../src/ai/nav/bakeNavGrid';+import { bakeVolumes } from '../src/ai/nav/NavPlugin';+import { NavVolume, type NavVolumeData } from '../src/ai/nav/NavVolume';+import { Navigation } from '../src/ai/nav/Navigation';+import { Transform } from '../src/ecs/component';import type { Physics3DQueries } from '../src/physics3d/Physics3DQueries';import type { Vec3 } from '../src/types';@@ -114,3 +118,70 @@ describe('bakeNavGrid', () => {expect(raycast).toHaveBeenCalledWith(expect.anything(), expect.anything(), 0b101);});});++/** The narrow world view `bakeVolumes` walks, with just enough store to answer. */+class VolumeWorld {+ private store = new Map<string, unknown>();+ private ids: number[] = [];+ spawn(comps: Array<[{ _name: string }, unknown]>): number {+ const e = this.ids.length + 1;+ for (const [def, data] of comps) this.store.set(`${e}:${def._name}`, data);+ this.ids.push(e);+ return e;+ }+ getEntitiesWithComponents(defs: readonly { _name: string }[]): number[] {+ return this.ids.filter(e => defs.every(d => this.store.has(`${e}:${d._name}`)));+ }+ get(e: number, def: { _name: string }): never {+ return this.store.get(`${e}:${def._name}`) as never;+ }+ set(): void { /* the bake writes nothing back */ }+}++describe('bakeVolumes', () => {+ const spawnVolume = (w: VolumeWorld, over: Partial<NavVolumeData> = {}) => w.spawn([+ [NavVolume, NavVolume.create({ halfExtents: { x: 20, y: 100, z: 20 }, cellSize: 10, ...over })],+ [Transform, { position: { x: 0, y: 0, z: 0 }, rotation: { x: 0, y: 0, z: 0, w: 1 } }],+ ]);++ it('bakes an authored volume into the active grid, centred on its Transform', () => {+ const w = new VolumeWorld();+ spawnVolume(w);+ const nav = new Navigation();+ bakeVolumes(w as never, nav, probeOf(() => LEVEL(7)), new Set());+ expect(nav.grid).not.toBeNull();+ expect(nav.grid!.plane).toBe('xz');+ expect(nav.grid!.width).toBe(5); // 40 across at 10 a cell, inclusive+ expect(nav.grid!.surfaceAt(0, 0)).toBe(7);+ });++ // Bodies are created by the physics system on its first step; a bake that ran+ // before it would sample an empty world and produce a grid of holes.+ it('does nothing at all without a solver to ask', () => {+ const w = new VolumeWorld();+ spawnVolume(w);+ const nav = new Navigation();+ bakeVolumes(w as never, nav, null, new Set());+ expect(nav.grid).toBeNull();+ });++ it('bakes each volume once, however many frames run', () => {+ const w = new VolumeWorld();+ spawnVolume(w);+ const raycast = vi.fn((_o: Vec3, d: Vec3) => (d.y < 0 ? LEVEL(0) : null));+ const baked = new Set<number>();+ const nav = new Navigation();+ bakeVolumes(w as never, nav, { raycast }, baked as never);+ const afterFirst = raycast.mock.calls.length;+ bakeVolumes(w as never, nav, { raycast }, baked as never);+ expect(raycast.mock.calls.length).toBe(afterFirst);+ });++ it('carries the volume own settings into the grid', () => {+ const w = new VolumeWorld();+ spawnVolume(w, { stepHeight: 25 });+ const nav = new Navigation();+ bakeVolumes(w as never, nav, probeOf(() => LEVEL(0)), new Set());+ expect(nav.grid!.stepHeight).toBe(25);+ });+});