condor-pathfinding-navmesh 0.4.0

Navmesh pathfinding algorithms and prepared routing structures for Condor.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

//! Owner crate for Condor's **navmesh domain**: convex-cell substrate, prepared
//! snapshots, dynamic availability, and online routing solvers.
//!
//! # Ownership vs facade
//!
//! This package (`condor-pathfinding-navmesh`, lib name `condor_navmesh`) is the
//! **implementation owner**. Runtime algorithms, mesh validation, walkability,
//! corridor/funnel geometry helpers, TRA* prepared builders, and the optional
//! Polyanya adapter all live here.
//!
//! The root facade crate (`condor` / package `condor-for-games`) only
//! re-exports these types under `navmesh` / algorithm modules for consumer
//! compatibility. Prefer importing from this crate in domain work; consumers of
//! the published product surface use the facade alias. Do not treat the facade
//! as a second implementation home.
//!
//! The implementation layer depends on core and geometry, never on grid or the
//! public facade. Corpus conformance and capture evidence remain in private
//! developer packages.
//!
//! Continuous polygonal scene primitives ([`PolygonScene`], [`PolygonPath`], …)
//! are owned by the geometry crate and re-exported here so navmesh pathfinders
//! share one continuous polyline / substrate vocabulary without a second path
//! type.
//!
//! # Surfaces
//!
//! | Surface | When to use | Entry points |
//! | --- | --- | --- |
//! | **Static mesh** | One-shot or caller-owned immutable geometry | [`Navmesh`], [`NavmeshPathfinder`] (`ChannelSearch`, `TAStar`, optional `Polyanya`) |
//! | **Prepared** | Build once, many neighbor/portal lookups or TRA* queries | [`PreparedNavmeshBuilder`] → [`PreparedNavmesh`] / TRA* prepared maps |
//! | **Dynamic availability** | Enable/disable cells or portals without carving geometry | [`DynamicNavmeshState`] → [`materialize`](DynamicNavmeshState::materialize) → rebuild prepared (e.g. [`DynamicPreparedNavmeshQuery`]) |
//!
//! Prepared maps are **immutable snapshots**. Availability updates never patch a
//! prepared map in place: materialize a new static mesh and re-run preprocess.
//!
//! # Module map
//!
//! - [`navmesh`] — cells, portals, walkability, pathfinder trait, dynamic overlay, prepared adjacency
//! - [`algorithms`] — channel search, TA* (static), TRA* prepared builders and waypoint-DB policies
//! - [`polyanya`] (`feature = "polyanya"`) — external Polyanya-backed [`NavmeshPathfinder`]
//!
//! # Outcomes
//!
//! Connectivity uses [`NavmeshQueryResult`]. Geometric routes return
//! [`NavmeshSearchResult`] = `Result<SearchOutcome<…>, NavmeshSearchError>`:
//! validation / adapter failures are `Err`; found vs no-path are both `Ok` with
//! stats. Mesh construction failures use [`NavmeshValidationError`]; dynamic
//! overlay failures use [`DynamicNavmeshError`].
//!
//! # Example: prepare once
//!
//! A prepared map is the right starting point when many queries share one
//! validated mesh. It is an immutable snapshot: rebuild it after changing mesh
//! geometry or dynamic availability.
//!
//! ```
//! use condor_navmesh::{
//!     Navmesh, NavmeshCell, Point2, PreparedNavmesh, PreparedNavmeshBuilder, TRAStarBuilder,
//! };
//!
//! let navmesh = Navmesh::new(
//!     vec![NavmeshCell::new(
//!         "cell-0",
//!         vec![
//!             Point2::new(0.0, 0.0),
//!             Point2::new(2.0, 0.0),
//!             Point2::new(0.0, 2.0),
//!         ],
//!     )],
//!     vec![],
//! );
//! let prepared = TRAStarBuilder
//!     .preprocess(&navmesh)
//!     .expect("the single convex cell is valid");
//! assert_eq!(prepared.name(), "tra-star");
//! ```

#![forbid(unsafe_code)]

/// Online and prepared navmesh solvers (channel search, TA*, TRA* builders).
pub mod algorithms;
/// Convex-cell mesh substrate, walkability, prepared adjacency, dynamic availability.
pub mod navmesh;
/// Optional external Polyanya-backed [`NavmeshPathfinder`] adapter.
#[cfg(feature = "polyanya")]
pub mod polyanya;

pub use algorithms::{channel_search::ChannelSearch, ta_star::TAStar, tra_star::*};
pub use condor_core::{Point2, SearchOutcome, SearchPathCost, SearchVisitStats};
pub use condor_geometry::{
    continuous::{
        PolygonPath, PolygonPathBuildError, PolygonPathfinder, PolygonSearchError,
        PolygonSearchResult, PolygonSearchStats,
    },
    polygonal::{
        Polygon, PolygonEndpoint, PolygonScene, PolygonSearchRequest, PolygonValidationError,
        WorldBounds,
    },
};
pub use navmesh::{
    DynamicNavmeshError, DynamicNavmeshPortalKey, DynamicNavmeshState, DynamicNavmeshUpdate,
    DynamicPreparedNavmeshQuery, DynamicPreparedNavmeshQueryMetadata,
    DynamicPreparedNavmeshQueryResult, DynamicPreparedNavmeshRebuildStatus, Navmesh, NavmeshCell,
    NavmeshPath, NavmeshPathfinder, NavmeshPortal, NavmeshQuery, NavmeshQueryResult,
    NavmeshSearchError, NavmeshSearchResult, NavmeshSearchStats, NavmeshValidationError,
    PreparedNavmesh, PreparedNavmeshBuildError, PreparedNavmeshBuilder, StaticPreparedNavmesh,
    StaticPreparedNavmeshBuilder,
};
/// Compatibility re-export of geometry polygonal primitives (`PolygonScene`, …).
///
/// Prefer `condor_geometry::polygonal` (or the facade `polygonal` feature) for new
/// code; this module exists so navmesh-side callers can share one continuous
/// free-space vocabulary without a second path type.
pub mod polygonal {
    pub use condor_geometry::polygonal::*;
}

#[cfg(feature = "polyanya")]
pub use polyanya::Polyanya;