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): bake a walkable grid out of the 3D solver
esengineb8539e302042
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 whichworld 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 ofdiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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: numbercanStep: (fromX: number, fromY: number, toX: number, toY: number) => booleancellSize: numbercellToWorld: (gx: number, gy: number) => Vec3@@ -4680,9 +4681,8 @@ inBounds: (gx: number, gy: number) => booleanindex: (gx: number, gy: number) => numberisWalkable: (gx: number, gy: number) => booleannearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null-originX: number-originY: number-originZ: number+originU: number+originV: numberplane: NavPlanesetWalkable: (gx: number, gy: number, walkable: boolean) => voidstepHeight: numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: numbercanStep: (fromX: number, fromY: number, toX: number, toY: number) => booleancellSize: numbercellToWorld: (gx: number, gy: number) => Vec3@@ -4858,9 +4859,8 @@ inBounds: (gx: number, gy: number) => booleanindex: (gx: number, gy: number) => numberisWalkable: (gx: number, gy: number) => booleannearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null-originX: number-originY: number-originZ: number+originU: number+originV: numberplane: NavPlanesetWalkable: (gx: number, gy: number, walkable: boolean) => voidstepHeight: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: numbercanStep: (fromX: number, fromY: number, toX: number, toY: number) => booleancellSize: numbercellToWorld: (gx: number, gy: number) => Vec3@@ -4675,9 +4676,8 @@ inBounds: (gx: number, gy: number) => booleanindex: (gx: number, gy: number) => numberisWalkable: (gx: number, gy: number) => booleannearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null-originX: number-originY: number-originZ: number+originU: number+originV: numberplane: NavPlanesetWalkable: (gx: number, gy: number, walkable: boolean) => voidstepHeight: numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: numbercanStep: (fromX: number, fromY: number, toX: number, toY: number) => booleancellSize: numbercellToWorld: (gx: number, gy: number) => Vec3@@ -4920,9 +4921,8 @@ inBounds: (gx: number, gy: number) => booleanindex: (gx: number, gy: number) => numberisWalkable: (gx: number, gy: number) => booleannearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null-originX: number-originY: number-originZ: number+originU: number+originV: numberplane: NavPlanesetWalkable: (gx: number, gy: number, walkable: boolean) => voidstepHeight: numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: numbercanStep: (fromX: number, fromY: number, toX: number, toY: number) => booleancellSize: numbercellToWorld: (gx: number, gy: number) => Vec3@@ -4682,9 +4683,8 @@ inBounds: (gx: number, gy: number) => booleanindex: (gx: number, gy: number) => numberisWalkable: (gx: number, gy: number) => booleannearestWalkable: (gx: number, gy: number, maxRadius?: number, clearance?: number) => Cell | null-originX: number-originY: number-originZ: number+originU: number+originV: numberplane: NavPlanesetWalkable: (gx: number, gy: number, walkable: boolean) => voidstepHeight: numberdiff --git a/sdk/src/ai/nav/NavGrid.ts b/sdk/src/ai/nav/NavGrid.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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;