Rbanh
0798aa5d57
Add dedicated skinned rendering, pose restoration, shared Material and Material Instance slots, registry-driven components, Surface/Solari integration, transactional schema upgrades, navigation authoring, documentation, and evaluation evidence.
67 lines
3.4 KiB
Markdown
67 lines
3.4 KiB
Markdown
# Navigation Authoring
|
|
|
|
Blacksite navigation v1 uses authored bounds, obstacles, areas, and links to produce a deterministic
|
|
Rerecast bake artifact. Editor preview and packaged gameplay query that artifact through the same
|
|
`game::navigation::NavigationRuntime` Polyanya path API.
|
|
|
|
## Authoring
|
|
|
|
Use **Scene > Navigation** or the path icon in the existing top toolbar to create navigation actors:
|
|
|
|
- **Navigation Bounds** defines an axis-aligned bake region, agent profile, generated artifact path,
|
|
and optional debounced auto-bake.
|
|
- **Navigation Obstacle** carves a blocked volume from overlapping bounds.
|
|
- **Navigation Area** records a named walkable/blocked volume and traversal cost. V1 applies blocked
|
|
areas during bake and retains walkable cost metadata for a future per-polygon cost callback.
|
|
- **Navigation Link** connects otherwise isolated regions. Endpoints are local to the actor;
|
|
direction, enabled state, and traversal cost are authored.
|
|
|
|
V1 source geometry includes primitives and additive brushes. Imported static-mesh manifests do not
|
|
yet contain normalized collision triangles, so imported objects require authored navigation
|
|
obstacles until that artifact contract is extended.
|
|
|
|
Each navigation actor must own exactly one navigation component. Inspector changes are undoable and
|
|
save-time validation rejects invalid extents, profiles, area IDs/costs, and link endpoints.
|
|
|
|
## Bake And Preview
|
|
|
|
Select a bounds actor and click **Bake** in its Inspector, use **Scene > Navigation > Bake Selected
|
|
Bounds**, or click the toolbar path icon. The generated artifact must remain under
|
|
`assets/navigation/generated/`. Its fingerprint includes the source scene, bounds, agent settings,
|
|
overlapping primitive/additive-brush triangles, obstacles, areas, and links. Distant authoring is
|
|
excluded so independent bounds do not invalidate one another. Relevant edits immediately mark it
|
|
stale; auto-bake waits 0.75 seconds after the latest change before rebuilding. A failed auto-bake
|
|
reports once and waits for another authored change before retrying.
|
|
|
|
The viewport overlay draws authored volumes, baked polygon edges, link endpoints, and the current
|
|
path test. Set **Path start** and **Path end** on the bounds card and choose **Test Path**. Green/red
|
|
endpoint markers and an amber route show the exact result returned by the game runtime API.
|
|
|
|
## Headless And Runtime
|
|
|
|
Bake one scene or every scene under `assets/levels/`:
|
|
|
|
```bash
|
|
cargo bake-navigation --project . --scene assets/levels/navigation_authoring_showcase.scn.ron
|
|
cargo bake-navigation --project .
|
|
cargo bake-navigation --project . --check
|
|
```
|
|
|
|
`--check` never writes. It fails when an artifact is missing, malformed, or stale, making it suitable
|
|
for CI. `cargo validate-levels` applies the same fingerprint policy, validates link proximity, and
|
|
adds current navigation artifacts to package dependencies.
|
|
|
|
Gameplay loads and queries an artifact without editor dependencies:
|
|
|
|
```rust
|
|
let navigation = game::navigation::NavigationRuntime::load(path)?;
|
|
let path = navigation.query(start, destination)?;
|
|
```
|
|
|
|
The returned path contains world-space points, total length, and the optional stable actor ID of an
|
|
off-mesh link used by the route.
|
|
|
|
See [ADR 0032](../adr/0032-versioned-navigation-bake-and-runtime-query.md) for dependency and
|
|
ownership decisions and [the implementation plan](../../.cursor/plans/navigation_authoring_2026-07-11.plan.md)
|
|
for acceptance gates.
|