Ship production navigation authoring workflow

This commit is contained in:
Rbanh committed 2026-07-12 02:53:43 -04:00
1 parent 0798aa5d57
commit b4aa61e394
35 files changed
+3898 -602

No files matched your search

+1
View File
@@ -76,6 +76,7 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [editor/extensibility.md](editor/extensibility.md) | Static authoring component registration, lifecycle, composition, and history contract |
| [editor/material-system.md](editor/material-system.md) | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
## Working plans (not canonical long-term)
@@ -16,19 +16,36 @@ packaged games and headless validation must consume the same data and behavior.
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, agent profile, baked mesh, links, bounds, and diagnostics.
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, and validation. The game crate owns artifact
loading and path queries. Editor bake controls, overlays, and path preview call those shared/game
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 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
+1
View File
@@ -24,6 +24,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| [extensibility.md](extensibility.md) | Static authoring component lifecycle registration, stable IDs, composition, and generic history |
| [material-system.md](material-system.md) | Shared Material/Material Instance assets, static/skinned renderer slots, Surface ABI, Solari scope, and migration |
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
## Subsystems (code → doc)
@@ -0,0 +1,64 @@
# Navigation Authoring Evaluation
Date: 2026-07-12
Branch: `codex/renderer-material-component-foundation`
This record captures implementation evidence for deterministic navigation authoring, composed
source resolution, persisted path samples, bake diagnostics, and shared editor/game/headless path
queries. The permanent contract lives in [ADR 0032](../../../adr/0032-versioned-navigation-bake-and-runtime-query.md),
and the user workflow lives in the [navigation authoring guide](../../navigation-authoring.md).
## Live editor evidence
The images below are native Wayland captures from the debug editor running the isolated
`Blacksite Navigation QA` project. The QA project is temporary; no acceptance interaction changes
the repository scene.
### Bounds, sources, diagnostics, and validation samples
![Selected Navigation Bounds with the truthful world-space overlay and complete authoring controls](navigation-authoring-overview.png)
The selected bounds owns its generated artifact, exposes the complete agent profile, reports
current/stale state, and shows its persisted validation sample. Bounds, obstacle, area, and link
visualizers match the world-axis-aligned volumes and endpoints consumed by the bake.
### Shared runtime path preview
![Polyanya path preview crossing the authored off-mesh link](navigation-path-preview.png)
**Test Path** uses the same height-aware, multi-link query core as project validation and the game
adapter. The live query returned an 8.20 m, six-waypoint route through
`navigation-link-center`; a subsequent editor bake regenerated 26 polygons and the same query
remained valid. Pinning a second sample immediately marked the artifact stale and disabled path
testing; undo restored the current one-sample state. The transient route, endpoints, baked mesh,
and visualizers do not enter scene serialization.
## Acceptance results
| Area | Result | Evidence |
|------|--------|----------|
| Designer workflow | Pass | Typed bounds/obstacle/area/link actors, Bake, overlay, Test Path, and persisted sample controls |
| Source fidelity | Pass | Active unsaved snapshot plus visible subscene and recursive prefab resolution; exact affine transforms; no synthetic floor |
| Stale-state scope | Pass | Each bounds fingerprint includes only overlapping geometry/volumes and relevant links/samples; external artifact replacement is polled |
| Diagnostics | Pass | Invalid agents, grid budgets, links, duplicate artifact owners, prefab drift/structure, empty bakes, and unreachable named samples identify owners and repairs |
| Runtime parity | Pass | One scene-owned Polyanya query core drives editor preview, game `Vec3` adapter, link/sample validation, and the renderer-free validation CLI |
| Artifact integrity | Pass | Schema 2, exact generator identity, deterministic fresh-bake comparison, self-verifying payload hash, and atomic replacement |
| Serialization boundary | Pass | Viewport meshes, lines, markers, routes, and cache state remain transient |
| Packaged/release acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged test is claimed in this record |
## Automated verification
| Command/suite | Result |
|---------------|--------|
| Affected source test matrix (`shared`, `scene`, `game`, `editor`, `blacksite_surface`, `xtask`) | 390 passed; 1 intentional manual migration test ignored |
| `cargo clippy -p shared -p scene -p game -p editor -p xtask --all-targets -- -D warnings` | Pass |
| `cargo bake-navigation --project . --check` | 1 deterministic artifact current |
| `cargo validate-levels` | 59 dependencies, 5 non-blocking findings, 0 blocking errors |
| `cargo fmt --all` / `git diff --check` | Pass |
## Deliberate boundaries
V1 applies blocked areas and retains walkable cost metadata until Polyanya exposes a suitable
per-polygon cost callback. Imported static-mesh manifests do not yet contain normalized navigation
triangles. Runtime obstacle carving, crowd avoidance, and partial tile rebuilds remain future work;
V1 uses a debounced deterministic rebuild scoped by each bounds fingerprint.
+55 -14
View File
@@ -1,15 +1,16 @@
# Navigation Authoring
Blacksite navigation v1 uses authored bounds, obstacles, areas, and links to produce a deterministic
Rerecast bake artifact. Editor preview and packaged gameplay query that artifact through the same
`game::navigation::NavigationRuntime` Polyanya path API.
Blacksite navigation v1 uses authored bounds, obstacles, areas, links, and validation samples to
produce a deterministic Rerecast bake artifact. The scene crate owns one height-aware Polyanya
query core; editor preview, project validation, and `game::navigation::NavigationRuntime` use that
same implementation.
## Authoring
Use **Scene > Navigation** or the path icon in the existing top toolbar to create navigation actors:
Use **Scene > Navigation** or the path icon in the existing viewport toolbar to create navigation actors:
- **Navigation Bounds** defines an axis-aligned bake region, agent profile, generated artifact path,
and optional debounced auto-bake.
optional debounced auto-bake, and named start/end validation samples.
- **Navigation Obstacle** carves a blocked volume from overlapping bounds.
- **Navigation Area** records a named walkable/blocked volume and traversal cost. V1 applies blocked
areas during bake and retains walkable cost metadata for a future per-polygon cost callback.
@@ -18,10 +19,26 @@ Use **Scene > Navigation** or the path icon in the existing top toolbar to creat
V1 source geometry includes primitives and additive brushes. Imported static-mesh manifests do not
yet contain normalized collision triangles, so imported objects require authored navigation
obstacles until that artifact contract is extended.
obstacles until that artifact contract is extended. Bounds never synthesize a walkable floor:
at least one overlapping primitive or additive brush must provide real source triangles, so gaps,
voids, and separated platforms remain non-navigable unless explicitly linked.
Each navigation actor must own exactly one navigation component. Inspector changes are undoable and
save-time validation rejects invalid extents, profiles, area IDs/costs, and link endpoints.
save-time validation rejects invalid extents, profiles, area IDs/costs, and link endpoints. New and
duplicated bounds receive an actor-ID-derived artifact path; headless bake and project validation
reject legacy or manually edited paths claimed by more than one bounds actor before any file is
written.
The authoritative bake resolver starts from the active scene's authored snapshot, expands visible
composed subscenes, and expands linked prefab sources recursively. Contributor IDs include their
subscene/prefab chain so repeated source actors remain unambiguous. Prefab transform, primitive,
brush, navigation-component, and nested-instance overrides use their serialized values. Independent
property paths on one component merge with the same reflected semantics as runtime hydration, while
every override must still match the source component base it was authored against. Drifted property
layers and structural overrides are blocked with a rebase/apply/unpack repair action because
silently guessing would produce a different mesh from the hydrated editor world. Prefabs may
contribute geometry, obstacles, areas, and links, but Navigation Bounds remain owned by level
scenes.
## Bake And Preview
@@ -34,8 +51,17 @@ stale; auto-bake waits 0.75 seconds after the latest change before rebuilding. A
reports once and waits for another authored change before retrying.
The viewport overlay draws authored volumes, baked polygon edges, link endpoints, and the current
path test. Set **Path start** and **Path end** on the bounds card and choose **Test Path**. Green/red
endpoint markers and an amber route show the exact result returned by the game runtime API.
path test. Bounds, obstacles, and areas are shown as the same scaled, rotated world-axis-aligned
volumes consumed by the bake, so the overlay remains truthful for transformed or parented actors.
Set **Path start** and **Path end** on the bounds card and choose **Test Path**. Green/red endpoint
markers and an amber route show the exact result returned by the game runtime API. The editor also
tracks the selected artifact path on disk: external deletion, replacement, or rebaking invalidates
the previous preview and reloads the new artifact before another path query can run.
Choose **Pin Current Path** to store the current local-space endpoints as a named validation sample.
Samples can be enabled, edited, loaded back into the preview, or removed from the same bounds card.
Enabled samples are embedded in the artifact and must resolve through the shared multi-link runtime
query during project validation.
## Headless And Runtime
@@ -47,9 +73,14 @@ cargo bake-navigation --project .
cargo bake-navigation --project . --check
```
`--check` never writes. It fails when an artifact is missing, malformed, or stale, making it suitable
for CI. `cargo validate-levels` applies the same fingerprint policy, validates link proximity, and
adds current navigation artifacts to package dependencies.
`--check` never writes. It fails when an artifact is missing, malformed, stale, generated by a
different exact navigation toolchain, or differs from a fresh deterministic bake, making it
suitable for CI. Bake requests are rejected before allocation when their voxel grid exceeds the
production budget (8,192 cells per X/Z axis and 4,194,304 XZ cells total). `cargo validate-levels`
applies the same composed-scene/prefab resolver, validates link proximity and enabled samples,
reports effective disconnected components after valid links, and adds current navigation artifacts
to package dependencies. Artifacts use schema 2, an exact Rerecast/Polyanya/glam generator ID, and a
self-verifying payload hash; incompatible or parseable-tampered artifacts must be rebaked.
Gameplay loads and queries an artifact without editor dependencies:
@@ -58,8 +89,18 @@ let navigation = game::navigation::NavigationRuntime::load(path)?;
let path = navigation.query(start, destination)?;
```
The returned path contains world-space points, total length, and the optional stable actor ID of an
off-mesh link used by the route.
The returned path contains height-resolved world-space points, 3D total length, and the ordered
stable actor IDs of every off-mesh link used by the route. Routes may traverse multiple directed or
bidirectional links across disconnected islands.
The game binary also exposes a renderer-free artifact check for build or deployment tooling:
```bash
cargo run -p game -- --validate-navigation assets/navigation/generated/example.nav.ron
```
It validates link placement and every enabled embedded sample, then exits nonzero with the named
failure instead of opening a window.
See [ADR 0032](../adr/0032-versioned-navigation-bake-and-runtime-query.md) for dependency and
ownership decisions and [the implementation plan](../../.cursor/plans/navigation_authoring_2026-07-11.plan.md)
+1 -1
View File
@@ -147,7 +147,7 @@ with implementation sequencing in
| Milestone | Exit condition | Status |
|-----------|----------------|--------|
| M6 Reliability, recovery, and project workflow | Transactional save/recovery, stable sessions, project launcher, hardened hierarchy/prefabs, multi-scene composition | Implementation complete; all six scoped issues are closed after prefab #43 passed workspace, headless, packaged-runtime, and live editor acceptance |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44, #45, #46, and #47 are complete. Navigation #48 is in implementation; source-control safety #49 and final readiness gate #50 remain. |
| M7 Content production and shipping | Build/package profiles, content release gate, animation, audio, navigation, collaborative safety | Active; #44-#48 are complete. Source-control safety #49 and final readiness gate #50 remain; packaged acceptance is deferred until requested by the project owner. |
Production readiness is not inferred from feature count. Gitea
[`#50`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/50)