Blacksite/docs/editor/navigation-authoring.md

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/:

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:

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 for dependency and ownership decisions and the implementation plan for acceptance gates.