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): bake a walkable grid out of the 3D solver

esengineb8539e302042
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b816f6805..18545d712 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,18 @@ published separately; it ships inside the editor.
### Fixed
+- **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
+ steeper than `maxSlopeDegrees` is a wall, and a ceiling closer than
+ `agentHeight` is a crawlspace. The bodies a scene already collides against are
+ the source, so the walkable surface cannot disagree with the one an agent
+ stands on. It takes a `GroundProbe` — an interface small enough that
+ `Physics3DQueries` satisfies it unchanged, and a test satisfies it with a
+ function. One surface per column: a bridge and the road under it collapse into
+ whichever the ray meets first, which is the whole of what a heightfield can
+ honestly answer.
+
- **Navigation plans and walks in three dimensions.** `NavGrid` now knows which
world plane its cells lie in — `xy` (a flat scene, the default and unchanged) or
`xz`, the ground of a spatial one, where each cell also carries the height of
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 9031fc291..2c549640e 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4671,6 +4671,7 @@ targetZ: number
## NavGrid — class @experimental
```
+baseHeight: number
canStep: (fromX: number, fromY: number, toX: number, toY: number) => boolean
cellSize: number
cellToWorld: (gx: number, gy: number) => Vec3
@@ -4680,9 +4681,8 @@ inBounds: (gx: number, gy: number) => boolean
index: (gx: number, gy: number) => number
isWalkable: (gx: number, gy: number) => boolean
nearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null
-originX: number
-originY: number
-originZ: number
+originU: number
+originV: number
plane: NavPlane
setWalkable: (gx: number, gy: number, walkable: boolean) => void
stepHeight: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 0b7ccd8f6..74437c21c 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -4849,6 +4849,7 @@ targetZ: number
## NavGrid — class @experimental
```
+baseHeight: number
canStep: (fromX: number, fromY: number, toX: number, toY: number) => boolean
cellSize: number
cellToWorld: (gx: number, gy: number) => Vec3
@@ -4858,9 +4859,8 @@ inBounds: (gx: number, gy: number) => boolean
index: (gx: number, gy: number) => number
isWalkable: (gx: number, gy: number) => boolean
nearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null
-originX: number
-originY: number
-originZ: number
+originU: number
+originV: number
plane: NavPlane
setWalkable: (gx: number, gy: number, walkable: boolean) => void
stepHeight: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 65eb458f1..3f8bc8f49 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4666,6 +4666,7 @@ targetZ: number
## NavGrid — class @experimental
```
+baseHeight: number
canStep: (fromX: number, fromY: number, toX: number, toY: number) => boolean
cellSize: number
cellToWorld: (gx: number, gy: number) => Vec3
@@ -4675,9 +4676,8 @@ inBounds: (gx: number, gy: number) => boolean
index: (gx: number, gy: number) => number
isWalkable: (gx: number, gy: number) => boolean
nearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null
-originX: number
-originY: number
-originZ: number
+originU: number
+originV: number
plane: NavPlane
setWalkable: (gx: number, gy: number, walkable: boolean) => void
stepHeight: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 7d880e034..d4335af7f 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -4911,6 +4911,7 @@ targetZ: number
## NavGrid — class @experimental
```
+baseHeight: number
canStep: (fromX: number, fromY: number, toX: number, toY: number) => boolean
cellSize: number
cellToWorld: (gx: number, gy: number) => Vec3
@@ -4920,9 +4921,8 @@ inBounds: (gx: number, gy: number) => boolean
index: (gx: number, gy: number) => number
isWalkable: (gx: number, gy: number) => boolean
nearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null
-originX: number
-originY: number
-originZ: number
+originU: number
+originV: number
plane: NavPlane
setWalkable: (gx: number, gy: number, walkable: boolean) => void
stepHeight: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 5f4783dcb..2bc9cc26a 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4673,6 +4673,7 @@ targetZ: number
## NavGrid — class @experimental
```
+baseHeight: number
canStep: (fromX: number, fromY: number, toX: number, toY: number) => boolean
cellSize: number
cellToWorld: (gx: number, gy: number) => Vec3
@@ -4682,9 +4683,8 @@ inBounds: (gx: number, gy: number) => boolean
index: (gx: number, gy: number) => number
isWalkable: (gx: number, gy: number) => boolean
nearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null
-originX: number
-originY: number
-originZ: number
+originU: number
+originV: number
plane: NavPlane
setWalkable: (gx: number, gy: number, walkable: boolean) => void
stepHeight: number
diff --git a/sdk/src/ai/nav/NavGrid.ts b/sdk/src/ai/nav/NavGrid.ts
index c980a0773..c9e5de55d 100644
--- a/sdk/src/ai/nav/NavGrid.ts
+++ b/sdk/src/ai/nav/NavGrid.ts
@@ -40,7 +40,8 @@ export interface NavGridOptions {
height: number;
/** World pixels per cell (square). */
cellSize: number;
- /** World position of cell (0,0)'s center. Defaults to the world origin. */
+ /** WORLD position of cell (0,0)'s centre; the plane decides which of its axes
+ * the cells run along. Defaults to the world origin. */
origin?: { x: number; y: number; z?: number };
/**
* Walkability, row-major `width * height`, 1 = walkable / 0 = blocked.
@@ -73,26 +74,32 @@ export class NavGrid {
readonly width: number;
readonly height: number;
readonly cellSize: number;
- /** Cell (0,0)'s centre, on the plane's two axes. */
- readonly originX: number;
- readonly originY: number;
- /** Where the plane itself sits on the axis it leaves out. */
- readonly originZ: number;
+ /** Cell (0,0)'s centre along the plane's first and second axes — x and y for
+ * an `xy` grid, x and z for an `xz` one. Named for the plane, not the world,
+ * because which world axis `v` is depends on the plane. */
+ readonly originU: number;
+ readonly originV: number;
+ /** Where the ground sits on the axis the plane leaves out, for cells whose
+ * own height is not given. */
+ readonly baseHeight: number;
readonly plane: NavPlane;
readonly stepHeight: number;
/** Row-major walkability, 1 = walkable. Mutable via {@link setWalkable}. */
readonly walkable: Uint8Array;
- /** Row-major ground height, or null when every cell sits at `originZ`. */
+ /** Row-major ground height, or null when every cell sits at `baseHeight`. */
readonly surface: Float32Array | null;
constructor(opts: NavGridOptions) {
this.width = opts.width;
this.height = opts.height;
this.cellSize = opts.cellSize;
- this.originX = opts.origin?.x ?? 0;
- this.originY = opts.origin?.y ?? 0;
- this.originZ = opts.origin?.z ?? 0;
this.plane = opts.plane ?? 'xy';
+ // The origin is a WORLD point; which of its axes the cells run along is
+ // the plane's business, so it is taken apart here rather than by callers.
+ const o = opts.origin;
+ this.originU = o?.x ?? 0;
+ this.originV = (this.plane === 'xy' ? o?.y : o?.z) ?? 0;
+ this.baseHeight = (this.plane === 'xy' ? o?.z : o?.y) ?? 0;
this.stepHeight = opts.stepHeight ?? 0;
const n = this.width * this.height;
@@ -139,7 +146,7 @@ export class NavGrid {
/** Height of the ground in cell `(gx, gy)`, on the axis the plane leaves out. */
surfaceAt(gx: number, gy: number): number {
- if (!this.surface || !this.inBounds(gx, gy)) return this.originZ;
+ if (!this.surface || !this.inBounds(gx, gy)) return this.baseHeight;
return this.surface[gy * this.width + gx];
}
@@ -157,10 +164,10 @@ export class NavGrid {
/** Centre of cell `(gx, gy)` in world space, on the grid's own plane. */
cellToWorld(gx: number, gy: number): Vec3 {
- const u = this.originX + gx * this.cellSize;
- const v = this.originY + gy * this.cellSize;
+ const u = this.originU + gx * this.cellSize;
+ const v = this.originV + gy * this.cellSize;
return this.plane === 'xy'
- ? { x: u, y: v, z: this.originZ }
+ ? { x: u, y: v, z: this.baseHeight }
: { x: u, y: this.surfaceAt(gx, gy), z: v };
}
@@ -169,8 +176,8 @@ export class NavGrid {
const u = p.x;
const v = this.plane === 'xy' ? p.y : (p.z ?? 0);
return {
- x: Math.round((u - this.originX) / this.cellSize),
- y: Math.round((v - this.originY) / this.cellSize),
+ x: Math.round((u - this.originU) / this.cellSize),
+ y: Math.round((v - this.originV) / this.cellSize),
};
}
diff --git a/sdk/src/ai/nav/bakeNavGrid.ts b/sdk/src/ai/nav/bakeNavGrid.ts
new file mode 100644
index 000000000..fcbb192e5
--- /dev/null
+++ b/sdk/src/ai/nav/bakeNavGrid.ts
@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file bakeNavGrid.ts
+ * @brief Build a ground-plane {@link NavGrid} by asking the 3D solver what is
+ * under each cell.
+ *
+ * The bodies a scene already collides against ARE its walkable surface, so this
+ * takes them as the source rather than a second authored description that can
+ * disagree with them. One ray straight down per cell answers three questions at
+ * once: whether there is ground, how high it is, and how steeply it is tilted.
+ *
+ * What this is NOT: it samples ONE surface per column, so a bridge and the road
+ * under it collapse into whichever the ray meets first. Multi-level navigation
+ * wants a real navmesh (voxelise → regions → contours), which this deliberately
+ * is not — it is the whole of what a heightfield can honestly answer.
+ */
+
+import type { Vec3 } from '../../types';
+import { NavGrid } from './NavGrid';
+
+/** One downward hit: the height of the ground and how it is tilted. */
+export interface GroundHit {
+ /** World height of the point hit. */
+ y: number;
+ /** The surface normal's up component, 1 = level, 0 = a vertical wall. */
+ normalY: number;
+}
+
+/**
+ * What the baker needs from a solver — a ray, and what it hit. `Physics3DQueries`
+ * satisfies it as it stands; a test satisfies it with a function.
+ */
+export interface GroundProbe {
+ raycast(origin: Vec3, direction: Vec3, layerMask?: number): GroundHit | null;
+}
+
+export interface BakeNavGridOptions {
+ /** The box of world to sample, in world pixels. */
+ min: Vec3;
+ max: Vec3;
+ /** World pixels per cell (square, in the x/z plane). */
+ cellSize: number;
+ /**
+ * Steepest ground an agent can stand on, in degrees from level. Anything
+ * steeper is a wall it walks past, not a slope it walks up.
+ */
+ maxSlopeDegrees?: number;
+ /**
+ * How much room an agent needs above the ground. A cell whose ceiling is
+ * lower than this is not walkable however flat its floor is — a crawlspace
+ * is not a corridor. 0 skips the check (and its second ray per cell).
+ */
+ agentHeight?: number;
+ /** Height difference between neighbours an agent can cross — see NavGrid. */
+ stepHeight?: number;
+ /** Physics layers the ground is on; 0 (default) = every layer. */
+ layers?: number;
+}
+
+/**
+ * Sample the solver into a walkable grid over the x/z plane. Every cell centre
+ * gets one ray straight down: no hit is a hole, too steep a hit is a wall, too
+ * low a ceiling is a crawlspace. What survives is walkable at the height the ray
+ * found, which is the surface the agent then walks along.
+ */
+export function bakeNavGrid(probe: GroundProbe, opts: BakeNavGridOptions): NavGrid {
+ const { min, max, cellSize } = opts;
+ const layers = opts.layers ?? 0;
+ const agentHeight = opts.agentHeight ?? 0;
+ const cosMaxSlope = Math.cos(((opts.maxSlopeDegrees ?? 45) * Math.PI) / 180);
+ const depth = max.y - min.y;
+
+ const width = Math.max(1, Math.floor((max.x - min.x) / cellSize) + 1);
+ const height = Math.max(1, Math.floor((max.z - min.z) / cellSize) + 1);
+ const walkable = new Uint8Array(width * height);
+ const surface = new Float32Array(width * height);
+
+ for (let gy = 0; gy < height; gy++) {
+ for (let gx = 0; gx < width; gx++) {
+ const i = gy * width + gx;
+ const x = min.x + gx * cellSize;
+ const z = min.z + gy * cellSize;
+ surface[i] = min.y;
+
+ const ground = probe.raycast({ x, y: max.y, z }, { x: 0, y: -depth, z: 0 }, layers);
+ if (!ground) continue;
+ surface[i] = ground.y;
+ // Level ground has a normal pointing straight up; the steeper it is,
+ // the smaller that component, which is the cosine of the slope.
+ if (ground.normalY < cosMaxSlope) continue;
+ if (agentHeight > 0) {
+ // From just above the floor, so the floor itself is not the ceiling.
+ const from = { x, y: ground.y + CEILING_EPSILON, z };
+ if (probe.raycast(from, { x: 0, y: agentHeight, z: 0 }, layers)) continue;
+ }
+ walkable[i] = 1;
+ }
+ }
+
+ return new NavGrid({
+ width, height, cellSize,
+ origin: { x: min.x, y: min.y, z: min.z },
+ plane: 'xz',
+ walkable, surface,
+ stepHeight: opts.stepHeight ?? 0,
+ });
+}
+
+/** How far off the floor the headroom ray starts — enough to leave the surface
+ * it was just cast onto, small next to any agent worth the check. */
+const CEILING_EPSILON = 1;
diff --git a/sdk/src/ai/nav/index.ts b/sdk/src/ai/nav/index.ts
index e271ae614..146a84d6b 100644
--- a/sdk/src/ai/nav/index.ts
+++ b/sdk/src/ai/nav/index.ts
@@ -5,13 +5,19 @@
* @brief Navigation barrel — grid, A*, tilemap builder, agent, plugin.
*/
-export { NavGrid, type NavGridOptions, type Cell } from './NavGrid';
+export { NavGrid, type NavGridOptions, type NavPlane, type Cell } from './NavGrid';
export { findPath, pathToWorld, type PathfindOptions } from './pathfind';
export {
navGridFromTiles,
navGridFromTilemapLayer,
type BuildNavGridOptions,
} from './navGridFromTilemap';
+export {
+ bakeNavGrid,
+ type BakeNavGridOptions,
+ type GroundProbe,
+ type GroundHit,
+} from './bakeNavGrid';
export { Navigation, Nav } from './Navigation';
export { NavAgent, type NavAgentData, setNavDestination, stopNavAgent } from './NavAgent';
export { NavPlugin, navPlugin } from './NavPlugin';
diff --git a/sdk/tests/nav-bake.test.ts b/sdk/tests/nav-bake.test.ts
new file mode 100644
index 000000000..5070cd9b8
--- /dev/null
+++ b/sdk/tests/nav-bake.test.ts
@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Baking a walkable grid out of what the 3D solver can see.
+ *
+ * The claims are about what makes a cell UNwalkable — a hole, a wall, a ceiling
+ * too low — and about the height it reports for the ones that survive, because
+ * that height is what the agent then walks along.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { bakeNavGrid, type GroundHit, type GroundProbe } from '../src/ai/nav/bakeNavGrid';
+import type { Physics3DQueries } from '../src/physics3d/Physics3DQueries';
+import type { Vec3 } from '../src/types';
+
+// The engine's own solver satisfies the probe as it stands — the reason the
+// interface is this small. A type-level check, so it costs nothing at runtime
+// and fails at compile time if the two ever drift apart.
+type SolverIsAProbe = Physics3DQueries extends GroundProbe ? true : false;
+const _solverIsAProbe: SolverIsAProbe = true;
+void _solverIsAProbe;
+
+/** A solver that answers by the world position of the ray, not by its own state. */
+function probeOf(
+ ground: (x: number, z: number) => GroundHit | null,
+ ceiling: (x: number, z: number) => boolean = () => false,
+): GroundProbe {
+ return {
+ raycast(origin: Vec3, direction: Vec3): GroundHit | null {
+ // Down is the ground query; up is the headroom one.
+ if (direction.y < 0) return ground(origin.x, origin.z);
+ return ceiling(origin.x, origin.z) ? { y: origin.y + 1, normalY: -1 } : null;
+ },
+ };
+}
+
+const LEVEL = (y: number): GroundHit => ({ y, normalY: 1 });
+const BOX = { min: { x: 0, y: -100, z: 0 }, max: { x: 20, y: 100, z: 20 }, cellSize: 10 };
+
+describe('bakeNavGrid', () => {
+ it('covers the box in cells and lies in the ground plane', () => {
+ const grid = bakeNavGrid(probeOf(() => LEVEL(0)), BOX);
+ expect(grid.width).toBe(3); // 0, 10, 20
+ expect(grid.height).toBe(3);
+ expect(grid.plane).toBe('xz');
+ expect(grid.isWalkable(1, 1)).toBe(true);
+ // Cell (2,1) is at x=20, z=10 — the grid's own two axes are x and z.
+ expect(grid.cellToWorld(2, 1)).toEqual({ x: 20, y: 0, z: 10 });
+ });
+
+ it('reports the height of the ground it found, per cell', () => {
+ const grid = bakeNavGrid(probeOf((x) => LEVEL(x === 10 ? 35 : 0)), BOX);
+ expect(grid.surfaceAt(0, 0)).toBe(0);
+ expect(grid.surfaceAt(1, 0)).toBe(35);
+ expect(grid.cellToWorld(1, 0).y).toBe(35);
+ });
+
+ // Three ways a cell fails, and each has to fail on its OWN account: a hole is
+ // not a wall and neither is a low ceiling.
+ it('a cell with no ground under it is a hole', () => {
+ const grid = bakeNavGrid(probeOf((x) => (x === 10 ? null : LEVEL(0))), BOX);
+ expect(grid.isWalkable(1, 0)).toBe(false);
+ expect(grid.isWalkable(0, 0)).toBe(true);
+ });
+
+ it('ground steeper than the agent can stand on is a wall', () => {
+ // ~60° from level: normalY = cos(60°) = 0.5.
+ const steep = { y: 0, normalY: 0.5 };
+ const grid = bakeNavGrid(probeOf((x) => (x === 10 ? steep : LEVEL(0))),
+ { ...BOX, maxSlopeDegrees: 45 });
+ expect(grid.isWalkable(1, 0)).toBe(false);
+ // The same ground, an agent that can stand on it.
+ const lenient = bakeNavGrid(probeOf((x) => (x === 10 ? steep : LEVEL(0))),
+ { ...BOX, maxSlopeDegrees: 70 });
+ expect(lenient.isWalkable(1, 0)).toBe(true);
+ });
+
+ it('a ceiling lower than the agent is a crawlspace, not a corridor', () => {
+ const grid = bakeNavGrid(probeOf(() => LEVEL(0), (x) => x === 10),
+ { ...BOX, agentHeight: 180 });
+ expect(grid.isWalkable(1, 0)).toBe(false);
+ expect(grid.isWalkable(0, 0)).toBe(true);
+ });
+
+ it('skips the headroom ray entirely when no agent height was given', () => {
+ const raycast = vi.fn((_o: Vec3, d: Vec3) => (d.y < 0 ? LEVEL(0) : null));
+ bakeNavGrid({ raycast }, BOX);
+ expect(raycast).toHaveBeenCalledTimes(9); // one per cell, none upward
+ });
+
+ // A cell that failed still reports the height it found, so a route planned
+ // past it (and an agent snapped onto it) is at the height of the floor there.
+ it('keeps the height of a cell it refused to make walkable', () => {
+ const grid = bakeNavGrid(probeOf((x) => (x === 10 ? { y: 42, normalY: 0.1 } : LEVEL(0))), BOX);
+ expect(grid.isWalkable(1, 0)).toBe(false);
+ expect(grid.surfaceAt(1, 0)).toBe(42);
+ });
+
+ it('carries the step limit onto the grid it builds', () => {
+ const grid = bakeNavGrid(probeOf((x) => LEVEL(x === 10 ? 90 : 0)),
+ { ...BOX, stepHeight: 30 });
+ expect(grid.stepHeight).toBe(30);
+ expect(grid.canStep(0, 0, 1, 0)).toBe(false);
+ });
+
+ it('casts the ground ray through the whole box, from its top', () => {
+ const raycast = vi.fn(() => null);
+ bakeNavGrid({ raycast }, BOX);
+ expect(raycast).toHaveBeenCalledWith({ x: 0, y: 100, z: 0 }, { x: 0, y: -200, z: 0 }, 0);
+ });
+
+ it('casts against the layers it was given', () => {
+ const raycast = vi.fn(() => null);
+ bakeNavGrid({ raycast }, { ...BOX, layers: 0b101 });
+ expect(raycast).toHaveBeenCalledWith(expect.anything(), expect.anything(), 0b101);
+ });
+});
diff --git a/sdk/tests/physics3d-smoke.mjs b/sdk/tests/physics3d-smoke.mjs
index 530d4af3e..735ab7722 100644
--- a/sdk/tests/physics3d-smoke.mjs
+++ b/sdk/tests/physics3d-smoke.mjs
@@ -351,6 +351,13 @@ check('a ray meets the ramp where it slopes', onRamp != null && onRamp.entity ==
&& near(onRamp.fraction, 0.3375, 0.02),
`entity=${onRamp?.entity} fraction=${onRamp?.fraction?.toFixed(4)} want 0.3375`);
+// And it says HOW steep, not just how far: the up component of a hit normal is
+// the cosine of the slope, which is what a nav bake reads to tell ground from
+// wall. This ramp rises 1 over 4, so 4/sqrt(17).
+check('and reports the tilt in the normal it returns',
+ onRamp != null && near(onRamp.ny, 4 / Math.sqrt(17), 0.01) && onRamp.ny < 1,
+ `ny=${onRamp?.ny?.toFixed(4)} want ${(4 / Math.sqrt(17)).toFixed(4)}`);
+
// Over x=32 the surface is at 3.5, so a half-metre box settles near 4; the floor
// is at 0. A BOX, not a sphere — a sphere rolls off any slope, however shallow.
const CRATE = 31;