condor_navmesh/
lib.rs

1//! Owner crate for Condor's **navmesh domain**: convex-cell substrate, prepared
2//! snapshots, dynamic availability, and online routing solvers.
3//!
4//! # Ownership vs facade
5//!
6//! This package (`condor-pathfinding-navmesh`, lib name `condor_navmesh`) is the
7//! **implementation owner**. Runtime algorithms, mesh validation, walkability,
8//! corridor/funnel geometry helpers, TRA* prepared builders, and the optional
9//! Polyanya adapter all live here.
10//!
11//! The root facade crate (`condor` / package `condor-for-games`) only
12//! re-exports these types under `navmesh` / algorithm modules for consumer
13//! compatibility. Prefer importing from this crate in domain work; consumers of
14//! the published product surface use the facade alias. Do not treat the facade
15//! as a second implementation home.
16//!
17//! The implementation layer depends on core and geometry, never on grid or the
18//! public facade. Corpus conformance and capture evidence remain in private
19//! developer packages.
20//!
21//! Continuous polygonal scene primitives ([`PolygonScene`], [`PolygonPath`], …)
22//! are owned by the geometry crate and re-exported here so navmesh pathfinders
23//! share one continuous polyline / substrate vocabulary without a second path
24//! type.
25//!
26//! # Surfaces
27//!
28//! | Surface | When to use | Entry points |
29//! | --- | --- | --- |
30//! | **Static mesh** | One-shot or caller-owned immutable geometry | [`Navmesh`], [`NavmeshPathfinder`] (`ChannelSearch`, `TAStar`, optional `Polyanya`) |
31//! | **Prepared** | Build once, many neighbor/portal lookups or TRA* queries | [`PreparedNavmeshBuilder`] → [`PreparedNavmesh`] / TRA* prepared maps |
32//! | **Dynamic availability** | Enable/disable cells or portals without carving geometry | [`DynamicNavmeshState`] → [`materialize`](DynamicNavmeshState::materialize) → rebuild prepared (e.g. [`DynamicPreparedNavmeshQuery`]) |
33//!
34//! Prepared maps are **immutable snapshots**. Availability updates never patch a
35//! prepared map in place: materialize a new static mesh and re-run preprocess.
36//!
37//! # Module map
38//!
39//! - [`navmesh`] — cells, portals, walkability, pathfinder trait, dynamic overlay, prepared adjacency
40//! - [`algorithms`] — channel search, TA* (static), TRA* prepared builders and waypoint-DB policies
41//! - [`polyanya`] (`feature = "polyanya"`) — external Polyanya-backed [`NavmeshPathfinder`]
42//!
43//! # Outcomes
44//!
45//! Connectivity uses [`NavmeshQueryResult`]. Geometric routes return
46//! [`NavmeshSearchResult`] = `Result<SearchOutcome<…>, NavmeshSearchError>`:
47//! validation / adapter failures are `Err`; found vs no-path are both `Ok` with
48//! stats. Mesh construction failures use [`NavmeshValidationError`]; dynamic
49//! overlay failures use [`DynamicNavmeshError`].
50//!
51//! # Example: prepare once
52//!
53//! A prepared map is the right starting point when many queries share one
54//! validated mesh. It is an immutable snapshot: rebuild it after changing mesh
55//! geometry or dynamic availability.
56//!
57//! ```
58//! use condor_navmesh::{
59//!     Navmesh, NavmeshCell, Point2, PreparedNavmesh, PreparedNavmeshBuilder, TRAStarBuilder,
60//! };
61//!
62//! let navmesh = Navmesh::new(
63//!     vec![NavmeshCell::new(
64//!         "cell-0",
65//!         vec![
66//!             Point2::new(0.0, 0.0),
67//!             Point2::new(2.0, 0.0),
68//!             Point2::new(0.0, 2.0),
69//!         ],
70//!     )],
71//!     vec![],
72//! );
73//! let prepared = TRAStarBuilder
74//!     .preprocess(&navmesh)
75//!     .expect("the single convex cell is valid");
76//! assert_eq!(prepared.name(), "tra-star");
77//! ```
78
79#![forbid(unsafe_code)]
80
81/// Online and prepared navmesh solvers (channel search, TA*, TRA* builders).
82pub mod algorithms;
83/// Convex-cell mesh substrate, walkability, prepared adjacency, dynamic availability.
84pub mod navmesh;
85/// Optional external Polyanya-backed [`NavmeshPathfinder`] adapter.
86#[cfg(feature = "polyanya")]
87pub mod polyanya;
88
89pub use algorithms::{channel_search::ChannelSearch, ta_star::TAStar, tra_star::*};
90pub use condor_core::{Point2, SearchOutcome, SearchPathCost, SearchVisitStats};
91pub use condor_geometry::{
92    continuous::{
93        PolygonPath, PolygonPathBuildError, PolygonPathfinder, PolygonSearchError,
94        PolygonSearchResult, PolygonSearchStats,
95    },
96    polygonal::{
97        Polygon, PolygonEndpoint, PolygonScene, PolygonSearchRequest, PolygonValidationError,
98        WorldBounds,
99    },
100};
101pub use navmesh::{
102    DynamicNavmeshError, DynamicNavmeshPortalKey, DynamicNavmeshState, DynamicNavmeshUpdate,
103    DynamicPreparedNavmeshQuery, DynamicPreparedNavmeshQueryMetadata,
104    DynamicPreparedNavmeshQueryResult, DynamicPreparedNavmeshRebuildStatus, Navmesh, NavmeshCell,
105    NavmeshPath, NavmeshPathfinder, NavmeshPortal, NavmeshQuery, NavmeshQueryResult,
106    NavmeshSearchError, NavmeshSearchResult, NavmeshSearchStats, NavmeshValidationError,
107    PreparedNavmesh, PreparedNavmeshBuildError, PreparedNavmeshBuilder, StaticPreparedNavmesh,
108    StaticPreparedNavmeshBuilder,
109};
110/// Compatibility re-export of geometry polygonal primitives (`PolygonScene`, …).
111///
112/// Prefer `condor_geometry::polygonal` (or the facade `polygonal` feature) for new
113/// code; this module exists so navmesh-side callers can share one continuous
114/// free-space vocabulary without a second path type.
115pub mod polygonal {
116    pub use condor_geometry::polygonal::*;
117}
118
119#[cfg(feature = "polyanya")]
120pub use polyanya::Polyanya;
condor_navmesh/lib.rs

condor_navmesh/
lib.rs
