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(nav): a 3D scene authors where its agents may walk

esengine05a1da8f895e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 one
ray straight down per cell and reads three answers off it: whether there is
ground, how high it is, and how steeply it is tilted. No hit is a hole, ground
diff --git a/desktop b/desktop
index 7316ca021..58fcc088e 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 7316ca0214a9a3838000ff15eab7e06cbfaa5373
+Subproject commit 58fcc088ead16ef583cc6a7f7566fe88a1e77262
diff --git a/docs/astro/src/content/docs/gameplay/ai/navigation.mdx b/docs/astro/src/content/docs/gameplay/ai/navigation.mdx
index 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 (or
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 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.ts
index 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.json
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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);
+ });
+});