76 lines
4.5 KiB
Markdown
76 lines
4.5 KiB
Markdown
# 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.
|