# 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.