54 lines
3.4 KiB
Markdown
54 lines
3.4 KiB
Markdown
# ADR 0032: Versioned Navigation Bake And Runtime Query
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
Blacksite needs a production navigation workflow on Bevy 0.19. Current high-level Bevy navigation
|
|
plugins target older Bevy releases, while baking and pathfinding are difficult, established domains
|
|
that should not be reimplemented locally. The editor also cannot own the runtime query contract:
|
|
packaged games and headless validation must consume the same data and behavior.
|
|
|
|
## Decision
|
|
|
|
Use the engine-independent Rerecast crate for deterministic 3D walkable-surface generation and
|
|
Polyanya for any-angle path queries. Blacksite owns reflected authoring components and a versioned
|
|
generated artifact under `assets/navigation/generated/`. The artifact records the source scene,
|
|
source fingerprint, exact generator/toolchain ID, agent profile, baked mesh, links, bounds, polygon
|
|
count, authored validation samples, a self-verifying payload hash, and raw/effective
|
|
disconnected-island diagnostics. Bounds do not inject fallback geometry.
|
|
Each bounds actor owns one artifact path derived from its stable `ActorId` when created or
|
|
duplicated. Artifact paths remain inside `assets/navigation/generated/`; duplicate ownership is a
|
|
blocking authoring error rather than last-writer-wins bake behavior.
|
|
|
|
The scene crate owns fingerprinting, bake artifact IO, the engine-independent query runtime, and
|
|
validation. The game crate provides the Bevy `Vec3` adapter and renderer-free validation CLI.
|
|
Editor bake controls, overlays, path preview, headless baking, and project validation call the same
|
|
resolver/query contracts and keep all visual helpers transient. Relevant authored geometry changes
|
|
mark the artifact stale; V1 debounces a full deterministic rebuild and reports the affected region
|
|
until Rerecast provides production-ready tiled regeneration.
|
|
|
|
The authoritative resolver expands visible scene composition and recursively linked prefab sources
|
|
from the project root. Repeated contributors receive qualified source identities. Full-value
|
|
navigation-relevant prefab component overrides are applied deterministically. Property overrides
|
|
apply only while their serialized source base remains current; drifted property layers and
|
|
structural overrides are rejected with a rebase/apply/unpack repair action. Bounds inside prefabs
|
|
are rejected so one level-scene actor remains the unambiguous artifact owner.
|
|
|
|
## Consequences
|
|
|
|
- Navigation remains usable on Bevy 0.19 without forking an older Bevy integration crate.
|
|
- Rerecast and Polyanya versions become explicit serialized-artifact compatibility inputs; schema
|
|
migration or rebaking is required when their representation changes.
|
|
- Runtime queries resolve vertically overlapping surfaces by endpoint height and may traverse an
|
|
ordered graph of multiple explicit links; reported distance is measured along the 3D route.
|
|
- Enabled named path samples become deterministic release assertions evaluated by the same query
|
|
core used by the editor and game.
|
|
- Static navigation and explicit links ship first. Runtime obstacle carving, crowd avoidance, and
|
|
partial tile rebuilding remain future work.
|
|
- Primitive and additive-brush triangles are deterministic source geometry. Imported static meshes
|
|
use authored navigation obstacles until their normalized artifacts expose collision triangles.
|
|
- Runtime code never depends on editor UI state, and authored scenes never contain bake visualizers.
|