condor-for-games 0.4.0

#![forbid(unsafe_code)]
//! # Condor
//!
//! Condor is a pathfinding library with explicit public entrypoints for grids,
//! polygonal scenes, repeated polygonal queries, navmesh routing, and
//! replanning lanes.
//!
//! The published package is `condor-for-games`; the Rust library name is
//! `condor` (`cargo add condor-for-games --rename condor`). This crate is the
//! **public facade**: it curates feature-gated re-exports from owner crates
//! (`core`, `geometry`, `grid`, `navmesh`) and owns a small set of root contracts
//! ([`solver_portfolio`], polygonal pack adapters, artifact error types).
//! Application code should depend on `condor`, not on implementation crates
//! directly.
//!
//! Start with [`SolverPortfolio`] if you want the current recommended surface
//! for a problem model, then move to the concrete solver or workflow type for
//! that model. Project support catalogs, capture reports, and readiness
//! checklists live outside this curated import surface.
//!
//! # Problem models
//!
//! | Model | Build and query with | How it relates to the other lanes |
//! | --- | --- | --- |
//! | Discrete grid | [`Grid`], [`SearchRequest`], [`Pathfinder`] | Cell-based static, any-angle, prepared, replanning, and MAPF work |
//! | Continuous free space | [`PolygonScene`], [`PolygonSearchRequest`], [`PolygonPathfinder`] | Uses world-coordinate [`Point2`] values and Euclidean polyline paths |
//! | Navmesh | [`Navmesh`], [`NavmeshPathfinder`], [`PreparedNavmeshBuilder`] | Reuses the continuous `Point2` / polygon-path vocabulary over convex cells and portals |
//! | Shared outcome | [`SearchOutcome`] | Each lane distinguishes invalid requests (`Err`) from computed found/no-path outcomes with stats |
//! | Search budget | [`SearchBudget`] on each request/query | Optional `max_expansions` / `max_duration`; default unlimited; exhaustion is `Err`, not no-path |
//!
//! The grid and continuous/navmesh lanes deliberately use their own request and
//! path types. Choose the model that matches the caller's world representation;
//! [`SolverPortfolio`] maps that choice to the endorsed public entrypoint.
//!
//! # Features
//!
//! | Feature | Surface |
//! | --- | --- |
//! | `grid` | Grids, static search, any-angle, preprocessed grids, MAPF, replanning |
//! | `polygonal` | Continuous polygon scenes, visibility / SPM / TFS solvers, artifact errors |
//! | `navmesh` | Navmesh substrate and routing (implies `polygonal`) |
//! | `polyanya` | Optional Polyanya router (implies `navmesh`) |
//! | `full` | All of the above (**default**) |
//!
//! # Add Condor to an application
//!
//! Give the dependency the library name so application code can use
//! `condor::{AStar, Grid, ...}` directly:
//!
//! ```bash
//! cargo add condor-for-games --rename condor
//! ```
//!
//! ```toml
//! [dependencies]
//! condor = { package = "condor-for-games", version = "0.4.0", default-features = false, features = ["grid"] }
//! ```
//!
//! Omit the feature settings when you want Condor's complete curated surface;
//! `full` is the default.
//!
//! # Examples
//!
//! Choose an endorsed surface for a problem model:
//!
//! ```
//! use condor::{SolverPortfolio, SolverUseCase};
//!
//! let recommendation = SolverPortfolio::recommend(SolverUseCase::ExactNavmeshRouting);
//! assert_eq!(recommendation.solver(), "TRAStarBuilder");
//! assert_eq!(recommendation.integration_surface(), "PreparedNavmeshBuilder");
//! ```
//!
//! Run a grid-only A* search:
//!
//! ```
//! use condor::{AStar, Cell, Grid, Pathfinder, Point, SearchRequest};
//!
//! let mut grid = Grid::new(5, 5).expect("grid dimensions are valid");
//! grid.set_cell(Point::new(2, 2), Cell::Blocked)
//!     .expect("point is in bounds");
//!
//! let result = AStar.search(
//!     &grid,
//!     SearchRequest::new(Point::new(0, 0), Point::new(4, 4)),
//! ).expect("request is valid");
//!
//! assert!(result.is_found());
//! ```
//!
//! Cap expansions or wall-clock time on any online search request:
//!
//! ```
//! use condor::{AStar, Grid, Pathfinder, Point, SearchBudget, SearchRequest};
//!
//! let grid = Grid::new(20, 20).expect("grid dimensions are valid");
//! let request = SearchRequest::new(Point::new(0, 0), Point::new(19, 19))
//!     .with_budget(SearchBudget::max_expansions(4));
//! let error = AStar.search(&grid, request).expect_err("budget should stop a long path");
//! assert!(matches!(error, condor::GridSearchError::BudgetExhausted(_)));
//! ```

/// Shared search-budget types used across problem models (owner: core).
pub use condor_core::{BudgetExhausted, BudgetWatch, SearchBudget};

/// Algorithm taxonomy re-exports grouped by search contract (owner crates hold bodies).
#[cfg(any(feature = "grid", feature = "navmesh"))]
pub mod algorithms;
/// Any-angle grid pathfinder trait and continuous-on-grid request surface (owner: grid).
#[cfg(feature = "grid")]
pub mod any_angle;
/// Continuous free-space geometry substrate and walkability primitives (owner: geometry).
#[cfg(feature = "polygonal")]
pub use condor_geometry::continuous;
/// Artifact and pack-boundary error types owned by the facade.
#[cfg(feature = "polygonal")]
pub mod error;
/// Multi-agent same-goal flow-field amortization (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::flow_field;
/// Discrete grid storage and cell model (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::grid;
/// Hierarchical abstract-grid layers for multi-level search (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::hierarchical;
/// Multi-agent pathfinding starter surface (owner: grid).
#[cfg(feature = "grid")]
pub mod mapf;
/// Navmesh substrate and pathfinder re-exports (owner: navmesh).
#[cfg(feature = "navmesh")]
pub mod navmesh;
/// Grid path reconstruction and cost types (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::path;
/// Integer grid coordinates (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::point;
/// Optional Polyanya-backed navmesh pathfinder (owner: navmesh, feature-gated).
#[cfg(feature = "polyanya")]
pub mod polyanya;
/// Continuous polygonal pack adapters and scene pathfinder surface (owner: geometry + facade packs).
#[cfg(feature = "polygonal")]
pub mod polygonal;
/// Prepared any-angle visibility graphs over grids (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::prepared_any_angle;
/// Preprocessed static grid search substrates (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::preprocessed_grid;
/// Incremental and interpolated grid replanning contracts (owner: grid).
#[cfg(feature = "grid")]
pub mod replanning;
/// Continuous shortest-path maps for fixed-source polygonal queries (owner: geometry).
#[cfg(feature = "polygonal")]
pub use condor_geometry::shortest_path_map;
/// Online grid search traits and request/result contracts (owner: grid).
#[cfg(feature = "grid")]
pub use condor_grid::search;
/// Endorsed solver recommendations keyed by problem model / use case.
pub mod solver_portfolio;
/// Topological fracture search for continuous free space (owner: geometry).
#[cfg(feature = "polygonal")]
pub use condor_geometry::topological_fracture_search;
/// Visibility-graph exact polygonal shortest paths (owner: geometry).
#[cfg(feature = "polygonal")]
pub use condor_geometry::visibility_graph;

#[cfg(feature = "grid")]
pub use algorithms::anya::{Anya, AnyaDiagnostics, AnyaInspection};
#[cfg(feature = "grid")]
pub use algorithms::astar::AStar;
#[cfg(feature = "grid")]
pub use algorithms::bfs::Bfs;
#[cfg(feature = "grid")]
pub use algorithms::bidirectional_bfs::BidirectionalBfs;
#[cfg(feature = "navmesh")]
pub use algorithms::channel_search::ChannelSearch;
#[cfg(feature = "grid")]
pub use algorithms::d_star_lite::DStarLite;
#[cfg(feature = "grid")]
pub use algorithms::dijkstra::Dijkstra;
#[cfg(feature = "grid")]
pub use algorithms::field_d_star::FieldDStar;
#[cfg(feature = "grid")]
pub use algorithms::hpastar::{HPAStarBuilder, PreparedHPAStar};
#[cfg(feature = "grid")]
pub use algorithms::jps_plus::{JpsPlusBuilder, PreparedJpsPlus};
#[cfg(feature = "grid")]
pub use algorithms::jump_point_search::JumpPointSearch;
#[cfg(feature = "grid")]
pub use algorithms::lazy_theta_star::LazyThetaStar;
#[cfg(feature = "grid")]
pub use algorithms::lifelong_planning_astar::LifelongPlanningAStar;
#[cfg(feature = "grid")]
pub use algorithms::rectangular_symmetry_reduction::RectangularSymmetryReduction;
#[cfg(feature = "grid")]
pub use algorithms::subgoal_graph::{PreparedSubgoalGraph, SubgoalGraphBuilder};
#[cfg(feature = "navmesh")]
pub use algorithms::ta_star::TAStar;
#[cfg(feature = "grid")]
pub use algorithms::theta_star::ThetaStar;
#[cfg(feature = "navmesh")]
pub use algorithms::tra_star::{
    PreparedTRAStar, PreparedTRAStarPortalTransitionCache,
    PreparedTRAStarWaypointDatabaseAdaptiveLru, PreparedTRAStarWaypointDatabaseCostAwareEviction,
    PreparedTRAStarWaypointDatabaseFixedAdmissionThreshold,
    PreparedTRAStarWaypointDatabaseFixedDemotionRule,
    PreparedTRAStarWaypointDatabaseFixedPromotionRule, PreparedTRAStarWaypointDatabaseLazyQuery,
    PreparedTRAStarWaypointDatabasePolicyProfile, PreparedTRAStarWaypointDatabaseStatic,
    PreparedTRAStarWaypointDatabaseTwoTierLru, TRAStarBuilder, TRAStarPortalTransitionCacheBuilder,
    TRAStarWaypointDatabaseAdaptiveLruBuilder, TRAStarWaypointDatabaseCostAwareEvictionBuilder,
    TRAStarWaypointDatabaseFixedAdmissionThresholdBuilder,
    TRAStarWaypointDatabaseFixedDemotionRuleBuilder,
    TRAStarWaypointDatabaseFixedPromotionRuleBuilder, TRAStarWaypointDatabaseLazyQueryBuilder,
    TRAStarWaypointDatabasePolicyProfile, TRAStarWaypointDatabasePolicyProfileBuilder,
    TRAStarWaypointDatabaseStaticBuilder, TRAStarWaypointDatabaseTwoTierLruBuilder,
};
#[cfg(feature = "grid")]
pub use any_angle::{
    AnyAnglePath, AnyAnglePathBuildError, AnyAnglePathfinder, AnyAngleSearchError,
    AnyAngleSearchRequest, AnyAngleSearchResult, AnyAngleSearchStats,
};
#[cfg(feature = "grid")]
pub use condor_grid::flow_field::{
    FlowDirection, FlowFieldBuildError, FlowFieldBuilder, PreparedFlowField,
};
#[cfg(feature = "grid")]
pub use condor_grid::mapf::*;
#[cfg(feature = "grid")]
pub use condor_grid::replanning::*;
#[cfg(feature = "polygonal")]
pub use continuous::{
    PolygonPath, PolygonPathBuildError, PolygonPathfinder, PolygonSearchError, PolygonSearchResult,
    PolygonSearchStats,
};
#[cfg(feature = "polygonal")]
pub use error::{
    ArtifactContractError, ArtifactContractKind, ArtifactContractLocation, ArtifactDataError,
    ArtifactLoadError,
};
#[cfg(feature = "grid")]
pub use grid::{Cell, Grid, GridBuildError, GridBuilder, GridEditError, GridStorage};
#[cfg(feature = "grid")]
pub use hierarchical::{
    HierarchicalGridBuildError, HierarchicalGridBuilder, PreparedHierarchicalGrid,
};
#[cfg(feature = "navmesh")]
pub use navmesh::{
    DynamicNavmeshPortalKey, DynamicNavmeshState, DynamicNavmeshUpdate,
    DynamicPreparedNavmeshQuery, DynamicPreparedNavmeshQueryMetadata,
    DynamicPreparedNavmeshQueryResult, DynamicPreparedNavmeshRebuildStatus, Navmesh, NavmeshCell,
    NavmeshPath, NavmeshPathfinder, NavmeshPortal, NavmeshQuery, NavmeshQueryResult,
    NavmeshSearchError, NavmeshSearchResult, NavmeshSearchStats, PreparedNavmesh,
    PreparedNavmeshBuildError, PreparedNavmeshBuilder, StaticPreparedNavmesh,
    StaticPreparedNavmeshBuilder,
};
#[cfg(feature = "grid")]
pub use path::{Path, PathBuildError};
#[cfg(feature = "grid")]
pub use point::Point;
#[cfg(feature = "polyanya")]
pub use polyanya::Polyanya;
#[cfg(feature = "polygonal")]
pub use polygonal::{
    NoPathProof, Point2, Polygon, PolygonEndpoint, PolygonScene, PolygonScenePack,
    PolygonScenePackKind, PolygonSearchRequest, PolygonValidationError, SeparationAxis,
    WorldBounds, load_polygon_scene_pack, load_polygon_scene_stress_pack,
};
#[cfg(feature = "grid")]
pub use prepared_any_angle::{
    PREPARED_ANY_ANGLE_CSR_U32_INDEX_LIMIT, PREPARED_ANY_ANGLE_DEFAULT_BENCHMARK_NODE_BUDGET,
    PREPARED_ANY_ANGLE_DIRECTED_EDGE_BUDGET, PREPARED_ANY_ANGLE_NODE_BUDGET,
    PREPARED_ANY_ANGLE_RETAINED_BYTES_BUDGET, PreparedAnyAngleBenchmarkAdmission,
    PreparedAnyAngleBuildDiagnostics, PreparedAnyAngleGrid, PreparedAnyAngleGridBuildError,
    PreparedAnyAngleGridBuilder, PreparedAnyAngleQueryDiagnostics,
};
#[cfg(feature = "grid")]
pub use preprocessed_grid::{
    PreparedGridSearch, PreprocessedGridBuildError, PreprocessedGridBuilder,
    PreprocessedGridMetadata, StaticPreparedGrid, StaticPreparedGridBuilder,
};
#[cfg(feature = "grid")]
pub use search::{
    GridSearchError, Pathfinder, SearchOutcome, SearchPathCost, SearchRequest, SearchResult,
    SearchStats, SearchVisitStats,
};
// SearchBudget / BudgetExhausted / BudgetWatch are re-exported unconditionally above.
#[cfg(feature = "polygonal")]
pub use shortest_path_map::{
    ContinuousShortestPathMap, PolygonShortestPathMap, PolygonShortestPathMapBuildError,
    PolygonShortestPathMapBuilder, PreparedContinuousShortestPathMap,
};
#[doc(inline)]
pub use solver_portfolio::{
    SolverPortfolio, SolverPortfolioRecommendation, SolverRecommendationStatus, SolverSurface,
    SolverUseCase,
};
#[cfg(feature = "polygonal")]
pub use topological_fracture_search::{TfsDiagnostics, TfsInspection, TopologicalFractureSearch};
#[cfg(feature = "polygonal")]
pub use visibility_graph::VisibilityGraph;