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

+27
View File
@@ -2,6 +2,33 @@ use bevy::prelude::*;
use game::{launch, GamePlugin};
fn main() {
let arguments = std::env::args().skip(1).collect::<Vec<_>>();
match game::navigation::navigation_validation_argument(&arguments) {
Ok(Some(path)) => match game::navigation::validate_navigation_artifact(&path) {
Ok(summary) => {
println!(
"navigation validation passed: {} sample(s), {} link(s), {}",
summary.enabled_sample_count,
summary.enabled_link_count,
summary.artifact_path.display()
);
return;
}
Err(error) => {
eprintln!(
"navigation validation failed for {}:\n{error}",
path.display()
);
std::process::exit(1);
}
},
Ok(None) => {}
Err(error) => {
eprintln!("{error}");
std::process::exit(2);
}
}
App::new()
.add_plugins(launch::default_plugins("Bevy FPS Foundation"))
.add_plugins(GamePlugin)
+181 -144
View File
@@ -1,172 +1,63 @@
use std::path::Path;
use std::path::{Path, PathBuf};
use bevy::prelude::Vec3;
use nav_glam::{Vec2 as NavVec2, Vec3 as NavVec3};
use polyanya::Mesh;
use scene::navigation::{read_navigation_artifact, NavigationBakeArtifact, NavigationLinkInput};
use scene::navigation::{NavigationBakeArtifact, NavigationQueryPath, NavigationQueryRuntime};
/// Loaded navigation artifact and its baked Polyanya acceleration data.
/// Loaded navigation artifact and its shared Polyanya query runtime.
#[derive(Debug, Clone)]
pub struct NavigationRuntime {
artifact: NavigationBakeArtifact,
mesh: Mesh,
query: NavigationQueryRuntime,
}
#[derive(Debug, Clone, PartialEq)]
pub struct NavigationPath {
pub points: Vec<Vec3>,
pub length: f32,
pub used_link_actor_id: Option<String>,
pub used_link_actor_ids: Vec<String>,
}
impl NavigationPath {
pub fn used_link_actor_id(&self) -> Option<&str> {
self.used_link_actor_ids.first().map(String::as_str)
}
}
impl From<NavigationQueryPath> for NavigationPath {
fn from(path: NavigationQueryPath) -> Self {
Self {
points: path.points.into_iter().map(Vec3::from_array).collect(),
length: path.length,
used_link_actor_ids: path.used_link_actor_ids,
}
}
}
impl NavigationRuntime {
pub fn from_artifact(artifact: NavigationBakeArtifact) -> Result<Self, String> {
if artifact.mesh.layers.is_empty()
|| artifact
.mesh
.layers
.iter()
.all(|layer| layer.polygons.is_empty())
{
return Err("navigation artifact contains no walkable polygons; rebake it".into());
}
let mesh = artifact.runtime_mesh();
Ok(Self { artifact, mesh })
Ok(Self {
query: NavigationQueryRuntime::from_artifact(artifact)?,
})
}
pub fn load(path: &Path) -> Result<Self, String> {
Self::from_artifact(read_navigation_artifact(path)?)
Ok(Self {
query: NavigationQueryRuntime::load(path)?,
})
}
pub fn artifact(&self) -> &NavigationBakeArtifact {
&self.artifact
self.query.artifact()
}
pub fn query(&self, start: Vec3, end: Vec3) -> Result<NavigationPath, String> {
if !start.is_finite() || !end.is_finite() {
return Err("navigation query endpoints must be finite".into());
}
let mut best = self.direct_path(start, end).ok().map(|path| Candidate {
path,
weighted_cost: 0.0,
});
if let Some(candidate) = best.as_mut() {
candidate.weighted_cost = candidate.path.length;
}
for link in self.artifact.links.iter().filter(|link| link.enabled) {
self.consider_link(start, end, link, false, &mut best);
if link.bidirectional {
self.consider_link(start, end, link, true, &mut best);
}
}
best.map(|candidate| candidate.path).ok_or_else(|| {
"no navigation path connects the requested endpoints; inspect islands or add a link"
.into()
})
self.query
.query(start.to_array(), end.to_array())
.map(NavigationPath::from)
}
pub fn validate_links(&self) -> Vec<String> {
let mut findings = Vec::new();
for link in self.artifact.links.iter().filter(|link| link.enabled) {
for (label, endpoint) in [("start", link.start), ("end", link.end)] {
let point = NavVec2::new(endpoint[0], endpoint[2]);
let Some(closest) = self.mesh.get_closest_point(point) else {
findings.push(format!(
"navigation link {} {label} endpoint is not near a walkable polygon",
link.actor_id
));
continue;
};
if closest.position().distance(point) > self.artifact.agent.radius * 2.0 {
findings.push(format!(
"navigation link {} {label} endpoint is farther than two agent radii from the mesh",
link.actor_id
));
}
}
}
findings
self.query.validate_links()
}
fn consider_link(
&self,
start: Vec3,
end: Vec3,
link: &NavigationLinkInput,
reverse: bool,
best: &mut Option<Candidate>,
) {
let (entry, exit) = if reverse {
(vec3(link.end), vec3(link.start))
} else {
(vec3(link.start), vec3(link.end))
};
let (Ok(mut first), Ok(second)) =
(self.direct_path(start, entry), self.direct_path(exit, end))
else {
return;
};
append_distinct(&mut first.points, entry);
append_distinct(&mut first.points, exit);
for point in second.points.into_iter().skip(1) {
append_distinct(&mut first.points, point);
}
let link_length = entry.distance(exit);
first.length += link_length + second.length;
first.used_link_actor_id = Some(link.actor_id.clone());
let weighted_cost = first.length + link_length * (link.cost - 1.0);
if best
.as_ref()
.is_none_or(|candidate| weighted_cost < candidate.weighted_cost)
{
*best = Some(Candidate {
path: first,
weighted_cost,
});
}
}
fn direct_path(&self, start: Vec3, end: Vec3) -> Result<NavigationPath, String> {
let start2 = NavVec2::new(start.x, start.z);
let end2 = NavVec2::new(end.x, end.z);
let path = self.mesh.path(start2, end2).ok_or_else(|| {
"navigation endpoints are outside the same reachable mesh island".to_string()
})?;
let length = path.length;
let nav_start = NavVec3::new(start.x, start.y, start.z);
let nav_end = NavVec3::new(end.x, end.y, end.z);
let mut points = vec![start];
for point in path.path_with_height(nav_start, nav_end, &self.mesh) {
append_distinct(&mut points, Vec3::new(point.x, point.y, point.z));
}
append_distinct(&mut points, end);
Ok(NavigationPath {
points,
length,
used_link_actor_id: None,
})
}
}
struct Candidate {
path: NavigationPath,
weighted_cost: f32,
}
fn append_distinct(points: &mut Vec<Vec3>, point: Vec3) {
if points
.last()
.is_none_or(|last| last.distance_squared(point) > 1.0e-8)
{
points.push(point);
}
}
fn vec3(value: [f32; 3]) -> Vec3 {
Vec3::from_array(value)
}
pub fn query_navigation_path(
@@ -177,15 +68,85 @@ pub fn query_navigation_path(
NavigationRuntime::load(artifact_path)?.query(start, end)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NavigationValidationSummary {
pub artifact_path: PathBuf,
pub enabled_link_count: usize,
pub enabled_sample_count: usize,
}
pub fn validate_navigation_artifact(
artifact_path: &Path,
) -> Result<NavigationValidationSummary, String> {
let runtime = NavigationQueryRuntime::load(artifact_path)?;
let mut findings = runtime.validate_links();
findings.extend(runtime.validate_samples());
if !findings.is_empty() {
return Err(findings.join("\n"));
}
Ok(NavigationValidationSummary {
artifact_path: artifact_path.to_path_buf(),
enabled_link_count: runtime
.artifact()
.links
.iter()
.filter(|link| link.enabled)
.count(),
enabled_sample_count: runtime
.artifact()
.samples
.iter()
.filter(|sample| sample.enabled)
.count(),
})
}
pub fn navigation_validation_argument(args: &[String]) -> Result<Option<PathBuf>, String> {
let Some(index) = args
.iter()
.position(|argument| argument == "--validate-navigation")
else {
return Ok(None);
};
if args.len() != 2 || index != 0 {
return Err(
"usage: game --validate-navigation <project-relative-or-absolute-artifact-path>".into(),
);
}
let path = args[1].trim();
if path.is_empty() {
return Err("navigation validation artifact path must not be empty".into());
}
Ok(Some(PathBuf::from(path)))
}
#[cfg(test)]
mod tests {
use scene::navigation::{
bake_navigation, NavigationBakeInput, NavigationLinkInput, NavigationVolumeInput,
bake_navigation, NavigationBakeInput, NavigationGeometryInput, NavigationLinkInput,
NavigationVolumeInput,
};
use shared::NavigationAgentProfile;
use super::*;
fn floor_geometry(
actor_id: &str,
min_x: f32,
max_x: f32,
min_z: f32,
max_z: f32,
y: f32,
) -> NavigationGeometryInput {
NavigationGeometryInput {
actor_id: actor_id.into(),
triangles: vec![
[[min_x, y, min_z], [max_x, y, max_z], [max_x, y, min_z]],
[[min_x, y, min_z], [min_x, y, max_z], [max_x, y, max_z]],
],
}
}
fn input() -> NavigationBakeInput {
NavigationBakeInput {
source_scene: "assets/levels/navigation_showcase.scn.ron".into(),
@@ -197,7 +158,7 @@ mod tests {
merge_region_size: 2,
..Default::default()
},
geometry: Vec::new(),
geometry: vec![floor_geometry("floor", -6.0, 6.0, -6.0, 6.0, 0.0)],
obstacles: vec![NavigationVolumeInput {
actor_id: "wall".into(),
center: [0.0, 0.5, 0.0],
@@ -205,6 +166,7 @@ mod tests {
}],
areas: Vec::new(),
links: Vec::new(),
samples: Vec::new(),
}
}
@@ -234,7 +196,65 @@ mod tests {
let path = runtime
.query(Vec3::new(-4.0, 0.0, 0.0), Vec3::new(4.0, 0.0, 0.0))
.unwrap();
assert_eq!(path.used_link_actor_id.as_deref(), Some("door-link"));
assert_eq!(path.used_link_actor_id(), Some("door-link"));
assert_eq!(path.used_link_actor_ids, ["door-link"]);
}
#[test]
fn route_can_traverse_multiple_explicit_links() {
let mut input = input();
input.geometry = vec![
floor_geometry("island-a", -6.0, -3.0, -2.0, 2.0, 0.0),
floor_geometry("island-b", -1.5, 1.5, -2.0, 2.0, 0.0),
floor_geometry("island-c", 3.0, 6.0, -2.0, 2.0, 0.0),
];
input.obstacles.clear();
input.links = vec![
NavigationLinkInput {
actor_id: "link-a-b".into(),
start: [-3.6, 0.0, 0.0],
end: [-1.0, 0.0, 0.0],
bidirectional: true,
cost: 1.0,
enabled: true,
},
NavigationLinkInput {
actor_id: "link-b-c".into(),
start: [1.0, 0.0, 0.0],
end: [3.6, 0.0, 0.0],
bidirectional: true,
cost: 1.0,
enabled: true,
},
];
let runtime = NavigationRuntime::from_artifact(bake_navigation(&input).unwrap()).unwrap();
let path = runtime
.query(Vec3::new(-5.0, 0.0, 0.0), Vec3::new(5.0, 0.0, 0.0))
.unwrap();
assert_eq!(path.used_link_actor_ids, ["link-a-b", "link-b-c"]);
assert!(path.length >= 10.0);
}
#[test]
fn query_selects_vertically_nearest_walkable_surface() {
let mut input = input();
input.center = [0.0, 2.0, 0.0];
input.half_extents = [6.0, 3.0, 6.0];
input.geometry = vec![
floor_geometry("lower-floor", -5.0, 5.0, -5.0, 5.0, 0.0),
floor_geometry("upper-floor", -5.0, 5.0, -5.0, 5.0, 4.0),
];
input.obstacles.clear();
let runtime = NavigationRuntime::from_artifact(bake_navigation(&input).unwrap()).unwrap();
let lower = runtime
.query(Vec3::new(-3.0, 0.1, 0.0), Vec3::new(3.0, 0.1, 0.0))
.unwrap();
let upper = runtime
.query(Vec3::new(-3.0, 3.9, 0.0), Vec3::new(3.0, 3.9, 0.0))
.unwrap();
assert!(lower.points.iter().all(|point| point.y < 1.0));
assert!(upper.points.iter().all(|point| point.y > 3.0));
}
#[test]
@@ -254,4 +274,21 @@ mod tests {
.iter()
.any(|finding| finding.contains("bad-link start")));
}
#[test]
fn validation_cli_argument_is_strict_and_window_free() {
assert_eq!(
navigation_validation_argument(&[
"--validate-navigation".into(),
"assets/navigation/generated/main.nav.ron".into(),
])
.unwrap(),
Some(PathBuf::from("assets/navigation/generated/main.nav.ron"))
);
assert!(navigation_validation_argument(&["--validate-navigation".into()]).is_err());
assert_eq!(
navigation_validation_argument(&["--project".into(), ".".into()]).unwrap(),
None
);
}
}