Blacksite/.cursor/plans/navigation_authoring_2026-07-11.plan.md

Navigation Mesh Authoring, Bake Diagnostics, And Path Preview

Working implementation plan for Gitea issue #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.