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): the SDK exports what a 3D scene needs to navigate

esengine269e91cc693c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b36f9036f..cccd8abb3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,14 @@ published separately; it ships inside the editor.
### Fixed
+- **A navigation volume is visible while it is being placed.** Nothing renders a
+ `NavVolume` and nothing collides with it, so the box that decides where agents
+ may walk was invisible in the editor — the one thing about it worth checking.
+ It now draws its wireframe, axis-aligned as the bake samples it rather than
+ turned by the entity's rotation, which would draw a volume nothing is sampled
+ from. It joins `gizmo-chrome`, the gate that fails a gizmo which computes a
+ shape and does not draw it.
+
- **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
diff --git a/desktop b/desktop
index 58fcc088e..dd9ca4108 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 58fcc088ead16ef583cc6a7f7566fe88a1e77262
+Subproject commit dd9ca4108e5e2cfdc5208d25ef64de9f24d5c774
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index b05a97ec6..d532d60a4 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 73,
- "experimental": 1596,
+ "experimental": 1603,
"deprecated": 3
},
- "total": 1782,
+ "total": 1789,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 2c549640e..83245a098 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1482 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1489 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1088,6 +1088,17 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BakeNavGridOptions — interface @experimental
+```
+agentHeight: number | undefined
+cellSize: number
+layers: number | undefined
+max: Vec3
+maxSlopeDegrees: number | undefined
+min: Vec3
+stepHeight: number | undefined
+```
+
## BatchBreak — enum @experimental
```
Blend = 4
@@ -3572,6 +3583,17 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## GroundHit — interface @experimental
+```
+normalY: number
+y: number
+```
+
+## GroundProbe — interface @experimental
+```
+raycast: (origin: Vec3, direction: Vec3, layerMask?: number) => GroundHit | null
+```
+
## HeadlessAppOptions — interface @experimental
```
plugins: Plugin[] | undefined
@@ -4707,6 +4729,11 @@ walkable: ArrayLike<number> | undefined
width: number
```
+## NavPlane — type @experimental
+```
+'xy' | 'xz'
+```
+
## NavPlugin — class @experimental
```
build: (app: App) => void
@@ -4715,6 +4742,21 @@ static new (): NavPlugin
static prototype: NavPlugin
```
+## NavVolume — const @experimental
+```
+ComponentDef<NavVolumeData>
+```
+
+## NavVolumeData — interface @experimental
+```
+agentHeight: number
+cellSize: number
+halfExtents: Vec3
+layers: number
+maxSlopeDegrees: number
+stepHeight: number
+```
+
## Navigation — class @experimental
```
findWorldPath: (from: { x: number; y: number; z?: number; }, to: { x: number; y: number; z?: number; }, opts?: PathfindOptions & { radius?: number; }) => Vec3[] | null
@@ -9380,6 +9422,11 @@ AudioPlugin
() => Dimension
```
+## bakeNavGrid — function @experimental
+```
+(probe: GroundProbe, opts: BakeNavGridOptions): NavGrid
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 74437c21c..cbbb19ba5 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 71 beta · 1501 experimental · 3 deprecated
+Symbols: 113 public · 71 beta · 1508 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1088,6 +1088,17 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BakeNavGridOptions — interface @experimental
+```
+agentHeight: number | undefined
+cellSize: number
+layers: number | undefined
+max: Vec3
+maxSlopeDegrees: number | undefined
+min: Vec3
+stepHeight: number | undefined
+```
+
## BatchBreak — enum @experimental
```
Blend = 4
@@ -3580,6 +3591,17 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## GroundHit — interface @experimental
+```
+normalY: number
+y: number
+```
+
+## GroundProbe — interface @experimental
+```
+raycast: (origin: Vec3, direction: Vec3, layerMask?: number) => GroundHit | null
+```
+
## HeadlessAppOptions — interface @experimental
```
plugins: Plugin[] | undefined
@@ -4885,6 +4907,11 @@ walkable: ArrayLike<number> | undefined
width: number
```
+## NavPlane — type @experimental
+```
+'xy' | 'xz'
+```
+
## NavPlugin — class @experimental
```
build: (app: App) => void
@@ -4893,6 +4920,21 @@ static new (): NavPlugin
static prototype: NavPlugin
```
+## NavVolume — const @experimental
+```
+ComponentDef<NavVolumeData>
+```
+
+## NavVolumeData — interface @experimental
+```
+agentHeight: number
+cellSize: number
+halfExtents: Vec3
+layers: number
+maxSlopeDegrees: number
+stepHeight: number
+```
+
## Navigation — class @experimental
```
findWorldPath: (from: { x: number; y: number; z?: number; }, to: { x: number; y: number; z?: number; }, opts?: PathfindOptions & { radius?: number; }) => Vec3[] | null
@@ -9588,6 +9630,11 @@ AudioPlugin
() => Dimension
```
+## bakeNavGrid — function @experimental
+```
+(probe: GroundProbe, opts: BakeNavGridOptions): NavGrid
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 3f8bc8f49..73562cb06 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 68 beta · 1481 experimental · 3 deprecated
+Symbols: 113 public · 68 beta · 1488 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1083,6 +1083,17 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BakeNavGridOptions — interface @experimental
+```
+agentHeight: number | undefined
+cellSize: number
+layers: number | undefined
+max: Vec3
+maxSlopeDegrees: number | undefined
+min: Vec3
+stepHeight: number | undefined
+```
+
## BatchBreak — enum @experimental
```
Blend = 4
@@ -3567,6 +3578,17 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## GroundHit — interface @experimental
+```
+normalY: number
+y: number
+```
+
+## GroundProbe — interface @experimental
+```
+raycast: (origin: Vec3, direction: Vec3, layerMask?: number) => GroundHit | null
+```
+
## HeadlessAppOptions — interface @experimental
```
plugins: Plugin[] | undefined
@@ -4702,6 +4724,11 @@ walkable: ArrayLike<number> | undefined
width: number
```
+## NavPlane — type @experimental
+```
+'xy' | 'xz'
+```
+
## NavPlugin — class @experimental
```
build: (app: App) => void
@@ -4710,6 +4737,21 @@ static new (): NavPlugin
static prototype: NavPlugin
```
+## NavVolume — const @experimental
+```
+ComponentDef<NavVolumeData>
+```
+
+## NavVolumeData — interface @experimental
+```
+agentHeight: number
+cellSize: number
+halfExtents: Vec3
+layers: number
+maxSlopeDegrees: number
+stepHeight: number
+```
+
## Navigation — class @experimental
```
findWorldPath: (from: { x: number; y: number; z?: number; }, to: { x: number; y: number; z?: number; }, opts?: PathfindOptions & { radius?: number; }) => Vec3[] | null
@@ -9375,6 +9417,11 @@ AudioPlugin
() => Dimension
```
+## bakeNavGrid — function @experimental
+```
+(probe: GroundProbe, opts: BakeNavGridOptions): NavGrid
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index d4335af7f..8d2bc1db5 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1502 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1509 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1083,6 +1083,17 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BakeNavGridOptions — interface @experimental
+```
+agentHeight: number | undefined
+cellSize: number
+layers: number | undefined
+max: Vec3
+maxSlopeDegrees: number | undefined
+min: Vec3
+stepHeight: number | undefined
+```
+
## BatchBreak — enum @experimental
```
Blend = 4
@@ -3567,6 +3578,17 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## GroundHit — interface @experimental
+```
+normalY: number
+y: number
+```
+
+## GroundProbe — interface @experimental
+```
+raycast: (origin: Vec3, direction: Vec3, layerMask?: number) => GroundHit | null
+```
+
## HeadlessAppOptions — interface @experimental
```
plugins: Plugin[] | undefined
@@ -4947,6 +4969,11 @@ walkable: ArrayLike<number> | undefined
width: number
```
+## NavPlane — type @experimental
+```
+'xy' | 'xz'
+```
+
## NavPlugin — class @experimental
```
build: (app: App) => void
@@ -4955,6 +4982,21 @@ static new (): NavPlugin
static prototype: NavPlugin
```
+## NavVolume — const @experimental
+```
+ComponentDef<NavVolumeData>
+```
+
+## NavVolumeData — interface @experimental
+```
+agentHeight: number
+cellSize: number
+halfExtents: Vec3
+layers: number
+maxSlopeDegrees: number
+stepHeight: number
+```
+
## Navigation — class @experimental
```
findWorldPath: (from: { x: number; y: number; z?: number; }, to: { x: number; y: number; z?: number; }, opts?: PathfindOptions & { radius?: number; }) => Vec3[] | null
@@ -9620,6 +9662,11 @@ AudioPlugin
() => Dimension
```
+## bakeNavGrid — function @experimental
+```
+(probe: GroundProbe, opts: BakeNavGridOptions): NavGrid
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 2bc9cc26a..e0a2f2e3b 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 66 beta · 1492 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1499 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1083,6 +1083,17 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BakeNavGridOptions — interface @experimental
+```
+agentHeight: number | undefined
+cellSize: number
+layers: number | undefined
+max: Vec3
+maxSlopeDegrees: number | undefined
+min: Vec3
+stepHeight: number | undefined
+```
+
## BatchBreak — enum @experimental
```
Blend = 4
@@ -3567,6 +3578,17 @@ static new (opts: GridLayoutOptions): GridLayoutProvider
static prototype: GridLayoutProvider
```
+## GroundHit — interface @experimental
+```
+normalY: number
+y: number
+```
+
+## GroundProbe — interface @experimental
+```
+raycast: (origin: Vec3, direction: Vec3, layerMask?: number) => GroundHit | null
+```
+
## HeadlessAppOptions — interface @experimental
```
plugins: Plugin[] | undefined
@@ -4709,6 +4731,11 @@ walkable: ArrayLike<number> | undefined
width: number
```
+## NavPlane — type @experimental
+```
+'xy' | 'xz'
+```
+
## NavPlugin — class @experimental
```
build: (app: App) => void
@@ -4717,6 +4744,21 @@ static new (): NavPlugin
static prototype: NavPlugin
```
+## NavVolume — const @experimental
+```
+ComponentDef<NavVolumeData>
+```
+
+## NavVolumeData — interface @experimental
+```
+agentHeight: number
+cellSize: number
+halfExtents: Vec3
+layers: number
+maxSlopeDegrees: number
+stepHeight: number
+```
+
## Navigation — class @experimental
```
findWorldPath: (from: { x: number; y: number; z?: number; }, to: { x: number; y: number; z?: number; }, opts?: PathfindOptions & { radius?: number; }) => Vec3[] | null
@@ -9402,6 +9444,11 @@ AudioPlugin
() => Dimension
```
+## bakeNavGrid — function @experimental
+```
+(probe: GroundProbe, opts: BakeNavGridOptions): NavGrid
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 2d0c6ac6e..56df37b84 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -668,15 +668,22 @@ export {
Navigation,
Nav,
NavAgent,
+ NavVolume,
setNavDestination,
stopNavAgent,
NavPlugin,
navPlugin,
+ bakeNavGrid,
type NavGridOptions,
+ type NavPlane,
type Cell,
type PathfindOptions,
type BuildNavGridOptions,
type NavAgentData,
+ type NavVolumeData,
+ type BakeNavGridOptions,
+ type GroundProbe,
+ type GroundHit,
} from './ai';
// =============================================================================