Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
codex/terrain-foundation
Blacksite/.cursor/plans/navigation_authoring_2026-07-11.plan.md

4.3 KiB
Raw Permalink Blame History

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