Ship production navigation authoring workflow
This commit is contained in:
1 parent
0798aa5d57
commit
b4aa61e394
35 files changed
+3898
-602
No files matched your search
@@ -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
|
||||
|
||||

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

|
||||
|
||||
**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.
|
||||
Binary file not shown.
Binary file not shown.
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in new issue
Block a user