condor-pathfinding-navmesh 0.4.0

Navmesh pathfinding algorithms and prepared routing structures for Condor.
Documentation

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 → 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");