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

File diff suppressed because it is too large. Load diff
+412 -26
View File
@@ -15,6 +15,7 @@ use shared::{
PostProcessVolumeDesc, PrefabInstance, PrefabRef, RendererMaterialSet, ShaderSchemaAsset,
SkinnedMeshRenderer, StaticMeshRenderer, ANIMATION_MANIFEST_SCHEMA_VERSION,
AUDIO_CLIP_SUB_ASSET_ID, COMPONENT_ANIMATION_CONTROLLER_DESC, COMPONENT_SKINNED_MESH_RENDERER,
NAVIGATION_GENERATED_ARTIFACT_DIRECTORY,
};
use crate::document::{SceneComponentBlob, SceneDocument};
@@ -113,6 +114,8 @@ pub fn validate_project(project_root: &Path) -> ProjectValidationReport {
);
}
validate_navigation_artifact_ownership(&mut report);
report.dependencies.sort_by(|left, right| {
(
&left.owner_path,
@@ -1456,7 +1459,11 @@ fn validate_navigation_document(
document: &SceneDocument,
report: &mut ProjectValidationReport,
) {
let jobs = match crate::navigation::navigation_bake_jobs_from_document(document, source_path) {
let jobs = match crate::navigation::resolve_navigation_bake_jobs(
project_root,
&project_root.join(source_path),
Some(document.normalized_ron()),
) {
Ok(jobs) => jobs,
Err(error) => {
report.findings.push(ProjectValidationFinding {
@@ -1473,19 +1480,66 @@ fn validate_navigation_document(
};
for job in jobs {
let normalized_artifact_path = match shared::navigation_generated_artifact_path(
&job.artifact_path,
) {
Ok(path) => path,
Err(error) => {
push_navigation_finding(
report,
source_path,
&job.input.bounds_actor_id,
"navigation.artifact_outside_generated_directory",
&job.artifact_path,
error,
"Assign a project-relative artifact path under assets/navigation/generated/ and rebake this bounds actor.",
);
continue;
}
};
report.dependencies.push(ProjectDependency {
owner_path: source_path.to_string(),
owner_actor_id: Some(job.input.bounds_actor_id.clone()),
kind: "navigation_artifact".into(),
reference: job.artifact_path.clone(),
reference: normalized_artifact_path.clone(),
});
let Some(path) = resolve_reference(project_root, &job.artifact_path) else {
let fresh_artifact = match crate::navigation::bake_navigation(&job.input) {
Ok(artifact) => artifact,
Err(error) => {
push_navigation_finding(
report,
source_path,
&job.input.bounds_actor_id,
"navigation.bake_failed",
&normalized_artifact_path,
&format!("deterministic navigation bake failed: {error}"),
"Repair the bounds, agent profile, or source geometry named by the bake error, then rebake this actor.",
);
continue;
}
};
if fresh_artifact.diagnostics.effective_component_count > 1 {
report.findings.push(ProjectValidationFinding {
severity: ValidationSeverity::Warning,
code: "navigation.isolated_regions".into(),
source_path: source_path.into(),
owner_actor_id: Some(job.input.bounds_actor_id.clone()),
reference: Some(normalized_artifact_path.clone()),
message: format!(
"navigation bake has {} raw walkable islands and {} disconnected traversable components after valid links",
fresh_artifact.diagnostics.island_count,
fresh_artifact.diagnostics.effective_component_count
),
repair: "Add explicit Navigation Links between regions that agents must traverse, or confirm the isolation is intentional.".into(),
});
}
let Some(path) = resolve_reference(project_root, &normalized_artifact_path) else {
push_navigation_finding(
report,
source_path,
&job.input.bounds_actor_id,
"navigation.artifact_unsafe_path",
&job.artifact_path,
&normalized_artifact_path,
"navigation artifact path escapes the project",
"Choose an artifact path under assets/navigation/generated/.",
);
@@ -1497,7 +1551,7 @@ fn validate_navigation_document(
source_path,
&job.input.bounds_actor_id,
"navigation.artifact_missing",
&job.artifact_path,
&normalized_artifact_path,
"navigation bounds has no baked artifact",
"Select the bounds actor and run Scene > Navigation > Bake Selected Bounds.",
);
@@ -1511,47 +1565,141 @@ fn validate_navigation_document(
source_path,
&job.input.bounds_actor_id,
"navigation.artifact_invalid",
&job.artifact_path,
&normalized_artifact_path,
&error,
"Delete the invalid generated artifact and rebake the bounds actor.",
);
continue;
}
};
if artifact.is_stale_for(&job.input) {
let stale = artifact.is_stale_for(&job.input);
if stale {
push_navigation_finding(
report,
source_path,
&job.input.bounds_actor_id,
"navigation.artifact_stale",
&job.artifact_path,
&normalized_artifact_path,
"navigation artifact fingerprint does not match authored navigation data",
"Rebake navigation after the authored geometry or agent-profile change.",
);
}
let mesh = artifact.runtime_mesh();
for link in artifact.links.iter().filter(|link| link.enabled) {
for (label, endpoint) in [("start", link.start), ("end", link.end)] {
let point = nav_glam::Vec2::new(endpoint[0], endpoint[2]);
let valid = mesh.get_closest_point(point).is_some_and(|closest| {
closest.position().distance(point) <= artifact.agent.radius * 2.0
});
if !valid {
} else {
let stored_hash = crate::navigation::navigation_artifact_content_hash(&artifact);
let fresh_hash = crate::navigation::navigation_artifact_content_hash(&fresh_artifact);
match (stored_hash, fresh_hash) {
(Ok(stored_hash), Ok(fresh_hash)) if stored_hash != fresh_hash => {
push_navigation_finding(
report,
source_path,
&link.actor_id,
"navigation.link_unreachable",
&job.artifact_path,
&format!(
"navigation link {label} endpoint is farther than two agent radii from the baked mesh"
),
"Move the endpoint onto a visible navigation polygon and rebake.",
&job.input.bounds_actor_id,
"navigation.artifact_content_mismatch",
&normalized_artifact_path,
"stored navigation artifact differs from a deterministic fresh bake despite a current source fingerprint",
"Rebake this bounds actor and commit the regenerated artifact.",
);
}
(Err(error), _) | (_, Err(error)) => push_navigation_finding(
report,
source_path,
&job.input.bounds_actor_id,
"navigation.artifact_hash_failed",
&normalized_artifact_path,
&error,
"Rebake this bounds actor; if hashing still fails, repair the generated artifact serializer.",
),
_ => {}
}
}
let runtime = match crate::navigation::NavigationQueryRuntime::from_artifact(
fresh_artifact.clone(),
) {
Ok(runtime) => runtime,
Err(error) => {
push_navigation_finding(
report,
source_path,
&job.input.bounds_actor_id,
"navigation.runtime_invalid",
&normalized_artifact_path,
&error,
"Repair the bake inputs and rebake this bounds actor.",
);
continue;
}
};
for finding in runtime.validate_link_findings() {
push_navigation_finding(
report,
source_path,
&finding.actor_id,
"navigation.link_unreachable",
&normalized_artifact_path,
&finding.message,
"Move the endpoint onto a visible navigation polygon and rebake.",
);
}
for sample in fresh_artifact
.samples
.iter()
.filter(|sample| sample.enabled)
{
if let Err(error) = runtime.query(sample.start, sample.end) {
push_navigation_finding(
report,
source_path,
&job.input.bounds_actor_id,
"navigation.sample_unreachable",
&sample.id,
&format!("navigation validation sample `{}` failed: {error}", sample.id),
"Move the sample endpoints onto connected visible navigation polygons, add the required links, and rebake.",
);
}
}
}
}
fn validate_navigation_artifact_ownership(report: &mut ProjectValidationReport) {
let mut owners_by_artifact = BTreeMap::<String, Vec<(String, String)>>::new();
for dependency in report
.dependencies
.iter()
.filter(|dependency| dependency.kind == "navigation_artifact")
{
let Some(actor_id) = dependency.owner_actor_id.as_ref() else {
continue;
};
owners_by_artifact
.entry(dependency.reference.clone())
.or_default()
.push((dependency.owner_path.clone(), actor_id.clone()));
}
for (artifact_path, owners) in owners_by_artifact {
let owners = owners.into_iter().collect::<BTreeSet<_>>();
if owners.len() < 2 {
continue;
}
let owner_list = owners
.iter()
.map(|(source_path, actor_id)| format!("actor `{actor_id}` in {source_path}"))
.collect::<Vec<_>>()
.join(", ");
for (source_path, actor_id) in owners {
push_navigation_finding(
report,
&source_path,
&actor_id,
"navigation.artifact_duplicate_owner",
&artifact_path,
&format!(
"navigation artifact is claimed by multiple bounds actors: {owner_list}"
),
&format!(
"Keep one owner; give every other bounds actor a unique path under {NAVIGATION_GENERATED_ARTIFACT_DIRECTORY} (or remove and re-add Navigation Bounds), then rebake all affected actors."
),
);
}
}
}
@@ -3010,7 +3158,7 @@ mod tests {
bounds.artifact_path = "assets/navigation/generated/main_humanoid.nav.ron".to_string();
let bounds_ron = ron::to_string(&bounds).unwrap();
let scene = format!(
"(schema_version:2,resources:{{}},entities:{{1:(components:{{\"shared::components::ActorId\":(\"nav-bounds\"),\"shared::navigation::NavigationBounds\":{bounds_ron},}})}})"
"(schema_version:2,resources:{{}},entities:{{1:(components:{{\"shared::components::ActorId\":(\"nav-bounds\"),\"shared::navigation::NavigationBounds\":{bounds_ron},}}),2:(components:{{\"shared::components::ActorId\":(\"nav-floor\"),\"shared::components::Primitive\":(shape:Box,size:(10.0,0.2,10.0)),}})}})"
);
std::fs::write(root.join("assets/levels/main.scn.ron"), &scene).unwrap();
if write_artifact {
@@ -3028,6 +3176,42 @@ mod tests {
}
}
fn navigation_scene_with_artifact_path(
bounds_actor_id: &str,
artifact_path: &str,
include_floor: bool,
link_height: Option<f32>,
) -> String {
let mut bounds = shared::NavigationBounds::for_actor(bounds_actor_id);
bounds.half_extents = [5.0, link_height.unwrap_or(0.0).abs() + 2.0, 5.0].into();
bounds.agent.min_region_size = 1;
bounds.agent.merge_region_size = 2;
bounds.artifact_path = artifact_path.to_string();
let bounds = ron::to_string(&bounds).unwrap();
let mut entities = format!(
"1:(components:{{\"shared::components::ActorId\":({bounds_actor_id:?}),\"shared::navigation::NavigationBounds\":{bounds},}})"
);
if include_floor {
entities.push_str(&format!(
",2:(components:{{\"shared::components::ActorId\":({:?}),\"shared::components::Primitive\":(shape:Box,size:(10.0,0.2,10.0)),}})",
format!("{bounds_actor_id}-floor")
));
}
if let Some(height) = link_height {
let link = shared::NavigationLink {
start: [-1.0, height, 0.0].into(),
end: [1.0, height, 0.0].into(),
..Default::default()
};
let link = ron::to_string(&link).unwrap();
entities.push_str(&format!(
",3:(components:{{\"shared::components::ActorId\":({:?}),\"shared::navigation::NavigationLink\":{link},}})",
format!("{bounds_actor_id}-link")
));
}
format!("(schema_version:2,resources:{{}},entities:{{{entities}}})")
}
#[test]
fn missing_navigation_artifact_blocks_release_with_bounds_owner() {
let root = fixture_root();
@@ -3057,6 +3241,208 @@ mod tests {
.any(|finding| finding.code == "navigation.artifact_stale"));
}
#[test]
fn navigation_artifacts_must_stay_in_generated_directory() {
let root = fixture_root();
let scene = navigation_scene_with_artifact_path(
"outside-bounds",
"assets/navigation/manual.nav.ron",
true,
None,
);
std::fs::write(root.join("assets/levels/main.scn.ron"), scene).unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "navigation.artifact_outside_generated_directory")
.expect("outside artifact path should be rejected");
assert_eq!(finding.owner_actor_id.as_deref(), Some("outside-bounds"));
assert!(finding.repair.contains("assets/navigation/generated/"));
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn duplicate_navigation_artifact_owners_name_every_bounds_actor() {
let root = fixture_root();
let artifact_path = "assets/navigation/generated/shared.nav.ron";
std::fs::write(
root.join("assets/levels/main.scn.ron"),
navigation_scene_with_artifact_path("first-bounds", artifact_path, true, None),
)
.unwrap();
std::fs::write(
root.join("assets/levels/secondary.scn.ron"),
navigation_scene_with_artifact_path("second-bounds", artifact_path, true, None),
)
.unwrap();
let report = validate_project(&root);
let findings = report
.findings
.iter()
.filter(|finding| finding.code == "navigation.artifact_duplicate_owner")
.collect::<Vec<_>>();
assert_eq!(findings.len(), 2, "{:?}", report.findings);
assert!(findings.iter().any(|finding| {
finding.owner_actor_id.as_deref() == Some("first-bounds")
&& finding.message.contains("second-bounds")
}));
assert!(findings.iter().all(|finding| {
finding.repair.contains("unique path") && finding.repair.contains("rebake")
}));
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn deterministic_bake_failures_are_attributed_to_bounds_actor() {
let root = fixture_root();
let scene = navigation_scene_with_artifact_path(
"empty-bounds",
"assets/navigation/generated/empty.nav.ron",
false,
None,
);
std::fs::write(root.join("assets/levels/main.scn.ron"), scene).unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "navigation.bake_failed")
.expect("empty bounds should fail a fresh validation bake");
assert_eq!(finding.owner_actor_id.as_deref(), Some("empty-bounds"));
assert!(finding.message.contains("no primitive or additive-brush"));
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn link_validation_uses_endpoint_height_not_only_xz() {
let root = fixture_root();
let artifact_path = "assets/navigation/generated/high-link.nav.ron";
let scene = navigation_scene_with_artifact_path(
"high-link-bounds",
artifact_path,
true,
Some(10.0),
);
std::fs::write(root.join("assets/levels/main.scn.ron"), &scene).unwrap();
let document = SceneDocument::from_ron_text(&scene).unwrap();
let job = crate::navigation::navigation_bake_jobs_from_document(
&document,
"assets/levels/main.scn.ron",
)
.unwrap()
.pop()
.unwrap();
let artifact = crate::navigation::bake_navigation(&job.input).unwrap();
crate::navigation::write_navigation_artifact(&root.join(artifact_path), &artifact).unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "navigation.link_unreachable")
.expect("vertically distant link should be rejected");
assert_eq!(
finding.owner_actor_id.as_deref(),
Some("high-link-bounds-link")
);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn unreachable_navigation_sample_blocks_release_with_bounds_owner() {
let root = fixture_root();
let artifact_path = "assets/navigation/generated/sample.nav.ron";
let mut bounds = shared::NavigationBounds::for_actor("sample-bounds");
bounds.half_extents = [5.0, 2.0, 5.0].into();
bounds.agent.min_region_size = 1;
bounds.agent.merge_region_size = 2;
bounds.artifact_path = artifact_path.into();
bounds
.validation_samples
.push(shared::NavigationPathSample {
id: "outside-mesh".into(),
start: [100.0, 0.0, 100.0].into(),
end: [101.0, 0.0, 100.0].into(),
enabled: true,
});
let bounds = ron::to_string(&bounds).unwrap();
let scene = format!(
r#"(schema_version:2,resources:{{}},entities:{{
1:(components:{{"shared::components::ActorId":("sample-bounds"),"shared::navigation::NavigationBounds":{bounds},}}),
2:(components:{{"shared::components::ActorId":("sample-floor"),"shared::components::Primitive":(shape:Box,size:(10.0,0.2,10.0)),}}),
}})"#
);
std::fs::write(root.join("assets/levels/main.scn.ron"), &scene).unwrap();
let document = SceneDocument::from_ron_text(&scene).unwrap();
let job = crate::navigation::navigation_bake_jobs_from_document(
&document,
"assets/levels/main.scn.ron",
)
.unwrap()
.pop()
.unwrap();
let artifact = crate::navigation::bake_navigation(&job.input).unwrap();
crate::navigation::write_navigation_artifact(&root.join(artifact_path), &artifact).unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "navigation.sample_unreachable")
.expect("unreachable sample should block release");
assert_eq!(finding.owner_actor_id.as_deref(), Some("sample-bounds"));
assert_eq!(finding.reference.as_deref(), Some("outside-mesh"));
assert_eq!(finding.severity, ValidationSeverity::Error);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn disconnected_navigation_islands_emit_owner_warning() {
let root = fixture_root();
let artifact_path = "assets/navigation/generated/islands.nav.ron";
let mut bounds = shared::NavigationBounds::for_actor("island-bounds");
bounds.half_extents = [6.0, 2.0, 5.0].into();
bounds.agent.min_region_size = 1;
bounds.agent.merge_region_size = 2;
bounds.artifact_path = artifact_path.into();
let bounds = ron::to_string(&bounds).unwrap();
let scene = format!(
r#"(schema_version:2,resources:{{}},entities:{{
1:(components:{{"shared::components::ActorId":("island-bounds"),"shared::navigation::NavigationBounds":{bounds},}}),
2:(components:{{"shared::components::ActorId":("left-floor"),"bevy_transform::components::transform::Transform":(translation:(-3.5,0.0,0.0),rotation:(0.0,0.0,0.0,1.0),scale:(1.0,1.0,1.0)),"shared::components::Primitive":(shape:Box,size:(4.0,0.2,8.0)),}}),
3:(components:{{"shared::components::ActorId":("right-floor"),"bevy_transform::components::transform::Transform":(translation:(3.5,0.0,0.0),rotation:(0.0,0.0,0.0,1.0),scale:(1.0,1.0,1.0)),"shared::components::Primitive":(shape:Box,size:(4.0,0.2,8.0)),}}),
}})"#
);
std::fs::write(root.join("assets/levels/main.scn.ron"), &scene).unwrap();
let document = SceneDocument::from_ron_text(&scene).unwrap();
let job = crate::navigation::navigation_bake_jobs_from_document(
&document,
"assets/levels/main.scn.ron",
)
.unwrap()
.pop()
.unwrap();
let artifact = crate::navigation::bake_navigation(&job.input).unwrap();
assert!(artifact.diagnostics.effective_component_count > 1);
crate::navigation::write_navigation_artifact(&root.join(artifact_path), &artifact).unwrap();
let report = validate_project(&root);
let finding = report
.findings
.iter()
.find(|finding| finding.code == "navigation.isolated_regions")
.expect("multiple islands should produce an authoring warning");
assert_eq!(finding.severity, ValidationSeverity::Warning);
assert_eq!(finding.owner_actor_id.as_deref(), Some("island-bounds"));
assert!(finding.message.contains("2 disconnected"));
assert!(finding.repair.contains("Navigation Links"));
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn valid_animation_controller_collects_stable_artifact_dependencies() {
let root = fixture_root();