# Navigation Mesh Authoring, Bake Diagnostics, And Path Preview

Working implementation plan for Gitea issue
[`#48`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/48).
This is the navigation production loop required by the M7 content-production milestone.

## Status

Architecture and dependency compatibility are established. Implementation and production
acceptance are in progress.

## Outcome

A level designer can author navigation bounds, obstacles, areas, links, and agent profiles; bake a
deterministic versioned artifact; inspect stale or invalid data; preview a path in the viewport; and
use the same artifact through a game-owned runtime query API and headless release validation.

## Architecture

- Shared reflected components own bounds, obstacles, area volumes, links, and scene bake settings.
- The scene crate owns deterministic source fingerprinting, bake artifact IO, and validation.
- Rerecast performs the 3D walkable-surface bake without coupling navigation to a Bevy plugin
  release. Polyanya performs proven any-angle runtime and editor-preview path queries.
- Overlapping primitive and additive-brush triangles enter the deterministic bake source; distant
  geometry and navigation authoring are excluded from each bounds fingerprint.
- The game crate owns loading and querying baked artifacts. Editor UI calls that public API for
  preview rather than implementing a second pathfinder.
- Generated artifacts live under `assets/navigation/generated/`, are project-relative runtime
  dependencies, and never serialize viewport helpers into authored scenes.

## Implementation Sequence

1. Add reflected authoring schema, versioned bake artifact, source fingerprint, validation, and
   exact agent-profile settings.
2. Add deterministic Rerecast bake input extraction for authored bounds/obstacles and headless bake
   command coverage.
3. Add game-owned artifact loading and Polyanya path-query API, including authored off-mesh links.
4. Add typed inspectors, create commands, bake/stale status, viewport overlay, and start/end path
   preview.
5. Add owner-attributed project validation for invalid links, missing/stale artifacts, unreachable
   preview samples, and bake failures.
6. Commit a small sample scene/artifact and run automated, headless, live editor, PIE, and packaged
   runtime acceptance.

## Acceptance Gates

- A designer can create bounds and obstacles, bake, view the resulting mesh, and preview a valid
  start-to-end path.
- Agent radius, height, climb, and slope settings deterministically affect the bake fingerprint.
- Relevant geometry or navigation-authoring changes mark the artifact stale; unrelated scene
  metadata does not.
- Invalid or dangling links, samples outside the mesh, isolated regions, and bake failures identify
  the owning actor or setting and provide a repair action.
- Runtime path queries and editor preview use the same game-owned API and versioned artifact.
- Helper meshes, lines, endpoints, and bake state are transient and never serialize.
- Headless bake and project validation pass for the committed sample fixture, and package dependency
  collection includes the current artifact.

## Deliberate Boundaries

- V1 supports static baked navigation plus explicit links. Dynamic crowd avoidance and runtime tile
  carving are separate work.
- Full partial-tile regeneration waits for upstream Rerecast tiling support. V1 records affected
  source bounds and debounces a deterministic full bake while reporting the dirty region.
- Area costs are authored and validated in V1; path-cost weighting beyond walkable/blocked areas is
  deferred until the runtime exposes per-polygon cost callbacks.
- Imported static meshes remain obstacle-authored in V1 because their normalized manifests do not
  yet expose deterministic collision triangles to the headless scene crate.