# Navigation Mesh Authoring, Bake Diagnostics, And Path Preview

> **Historical plan — not current implementation guidance.** Use the [documentation index](../../docs/README.md) for current behavior and architecture.

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, dependency compatibility, composed-source resolution, persisted path samples,
corrective source-level QA, and live debug-editor acceptance are complete. Packaged/release
acceptance remains explicitly deferred until the project owner requests another packaged pass.

## 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 composed-source resolution, source fingerprinting, bake
  artifact IO, the engine-independent query core, 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. No synthetic bounds
  floor is added.
- The game crate adapts the shared query core to Bevy types and exposes renderer-free artifact
  validation. Editor preview and project validation do not implement separate pathfinders.
- 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, and live debug-editor
   acceptance. PIE and packaged runtime acceptance remain deferred by project-owner direction.

## 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.
- Visible subscenes and nested prefab contributors resolve identically from editor snapshots and
  headless tooling; unsupported structural overrides block with an apply/unpack repair action.

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