Struct NavMeshQuery 

pub struct NavMeshQuery<'a> { /* private fields */ }

Navigation mesh query structure

Implementations

impl<'a> NavMeshQuery<'a>

pub fn new(nav_mesh: &'a NavMesh) -> Self

Creates a new navigation mesh query

pub fn set_query_extent(&mut self, extent: Vec3)

pub fn get_query_extent(&self) -> Vec3

pub fn set_random_seed(&mut self, seed: u32)

pub fn nav_mesh(&self) -> &NavMesh

Gets a reference to the navigation mesh

pub fn find_nearest_poly( &self, center: Vec3, half_extents: Vec3, filter: &QueryFilter, ) -> Result<(PolyRef, Vec3), DetourError>

Finds the polygon nearest to the specified center point

pub fn find_nearest_poly_extended( &self, center: Vec3, half_extents: Vec3, filter: &QueryFilter, ) -> Result<(PolyRef, Vec3, bool), DetourError>

Finds the polygon nearest to the specified center point (with is_over_poly flag)

This overload also returns whether the nearest point lies directly over the polygon.

Arguments

• center - The center of the search box
• half_extents - The search distance along each axis
• filter - The polygon filter to apply to the query

Returns

A tuple containing:

• The polygon reference of the nearest polygon
• The nearest point on the polygon
• Whether the point’s X/Z coordinate lies inside the polygon

pub fn find_path( &mut self, start_ref: PolyRef, end_ref: PolyRef, start_pos: Vec3, end_pos: Vec3, filter: &QueryFilter, ) -> Result<Vec<PolyRef>, DetourError>

Finds a path from start to end position

pub fn get_poly_center(&self, poly_ref: PolyRef) -> Result<Vec3, DetourError>

pub fn closest_point_on_poly( &self, poly_ref: PolyRef, pos: Vec3, ) -> Result<(Vec3, bool), DetourError>

Finds the closest point on a polygon

pub fn get_off_mesh_connection_endpoint( &self, connection_ref: PolyRef, start_pos: Vec3, ) -> Result<Vec3, DetourError>

pub fn get_off_mesh_connection_poly_end_points( &self, prev_ref: PolyRef, connection_ref: PolyRef, ) -> Result<(Vec3, Vec3), DetourError>

Gets the ordered endpoints of an off-mesh connection based on the previous polygon. This method determines the travel direction through the off-mesh connection by looking at which polygon was used to reach the connection.

Arguments

• prev_ref - Reference to the polygon we came from (used to determine direction)
• connection_ref - Reference to the off-mesh connection polygon

Returns

A tuple of (start_pos, end_pos) ordered for the travel direction. If prev_ref is invalid, returns the connection’s natural start->end order.

pub fn move_along_surface( &self, start_ref: PolyRef, start_pos: Vec3, end_pos: Vec3, filter: &QueryFilter, ) -> Result<MoveAlongSurfaceResult, DetourError>

Moves from the start to the end position constrained to the navigation mesh surface

This uses the same algorithm as the C++ version: a breadth-first search with a search radius constraint to find the best path.

Algorithm

Uses breadth-first search (BFS) to explore neighboring polygons within a search radius. The search radius is calculated as quarter distance between start and end positions plus a small epsilon to ensure numeric stability.

Performance

Time complexity: O(n) where n is the number of polygons within search radius (max 16) Space complexity: O(n) for the node storage and traversal queue

Uses VecDeque for efficient O(1) front operations during BFS traversal.

pub fn raycast( &self, start_ref: PolyRef, start_pos: Vec3, dir: Vec3, max_dist: f32, filter: &QueryFilter, ) -> Result<(PolyRef, Vec3, f32), DetourError>

Casts a ray along the navigation mesh

pub fn raycast_enhanced( &self, start_ref: PolyRef, start_pos: Vec3, end_pos: Vec3, filter: &QueryFilter, options: &RaycastOptions, prev_ref: Option<PolyRef>, ) -> Result<RaycastResult, DetourError>

Enhanced raycast method that returns detailed hit information Matches C++ API: raycast(…, dtRaycastHit*, …)

pub fn get_path_from_dijkstra_search( &self, end_ref: PolyRef, max_path: usize, ) -> Result<Vec<PolyRef>, DetourError>

Gets a path from the explored nodes in the previous Dijkstra search Matches C++ API: getPathFromDijkstraSearch

pub fn find_straight_path( &self, start_pos: Vec3, end_pos: Vec3, path: &[PolyRef], ) -> Result<Path, DetourError>

Finds a straight path from start to end

pub fn find_straight_path_with_options( &self, start_pos: Vec3, end_pos: Vec3, path: &[PolyRef], options: u32, ) -> Result<Path, DetourError>

Finds the straight path from start to end position with options

This overload accepts additional options for path computation.

Arguments

• start_pos - Path start position
• end_pos - Path end position
• path - An array of polygon references that represent the path corridor
• options - Options for straight path computation (0 = default behavior)

Returns

The straight path with waypoints and polygon references

pub fn get_portal_points( &self, from_ref: PolyRef, to_ref: PolyRef, ) -> Result<(Vec3, Vec3), DetourError>

Gets portal points between two adjacent polygons

Arguments

• from_ref - The reference of the polygon to traverse from
• to_ref - The reference of the polygon to traverse to

Returns

A tuple containing the left and right portal points

pub fn find_polys_around_circle( &self, center_ref: PolyRef, center_pos: Vec3, radius: f32, filter: &QueryFilter, ) -> Result<Vec<PolyRef>, DetourError>

Finds all polygons within a circular area around a center point

pub fn find_distance_to_wall( &self, start_ref: PolyRef, center_pos: Vec3, radius: f32, filter: &QueryFilter, ) -> Result<(f32, Vec3, Vec3), DetourError>

Finds the distance to the nearest wall or obstacle from a given position

pub fn find_random_point( &mut self, filter: &QueryFilter, ) -> Result<(PolyRef, Vec3), DetourError>

Finds a random point on the navigation mesh

pub fn find_random_point_with_custom_rand<F>( &mut self, filter: &QueryFilter, frand: F, ) -> Result<(PolyRef, Vec3), DetourError>

where F: FnMut() -> f32,

Finds a random point on the navigation mesh using custom random function

This method matches the C++ API that accepts a function pointer for random number generation.

Arguments

• filter - The polygon filter to apply to the query
• frand - Function returning a random number [0..1)

Returns

• A tuple containing the polygon reference and the random point position

pub fn get_poly_height( &self, poly_ref: PolyRef, pos: Vec3, ) -> Result<Option<f32>, DetourError>

Gets the height of the polygon at the provided position

This method provides accurate height interpolation using the detail mesh.

Arguments

• ref - The reference id of the polygon
• pos - A position within the xz-bounds of the polygon

Returns

• The height at the surface of the polygon, or None if the position is outside the polygon

pub fn find_random_point_around_circle<F>( &mut self, center_ref: PolyRef, center_pos: Vec3, radius: f32, filter: &QueryFilter, frand: F, ) -> Result<(PolyRef, Vec3), DetourError>

where F: FnMut() -> f32,

Finds a random point within a given radius of a center point using custom random function

This method matches the C++ API that accepts a function pointer for random number generation.

Arguments

• center_ref - The reference id of the polygon where the search starts
• center_pos - The center of the search circle
• radius - The radius of the search circle
• filter - The polygon filter to apply to the query
• frand - Function returning a random number [0..1)

Returns

• A tuple containing the polygon reference and the random point position

pub fn find_random_point_around( &mut self, center_ref: PolyRef, center_pos: Vec3, radius: f32, filter: &QueryFilter, ) -> Result<(PolyRef, Vec3), DetourError>

Finds a random point within a given radius of a center point

pub fn find_local_neighbourhood( &self, start_ref: PolyRef, center_pos: Vec3, radius: f32, filter: &QueryFilter, max_result: usize, ) -> Result<(Vec<PolyRef>, Vec<PolyRef>), DetourError>

Finds the non-overlapping navigation polygons in the local neighbourhood around the center position

pub fn init_sliced_find_path( &mut self, start_ref: PolyRef, end_ref: PolyRef, start_pos: Vec3, end_pos: Vec3, filter: &QueryFilter, options: u32, ) -> Result<(), DetourError>

Initializes a sliced pathfinding query for large-scale pathfinding

This method starts a pathfinding request that can be processed over multiple frames to avoid performance hitches with very long paths.

Arguments

• start_ref - Start polygon reference
• end_ref - End polygon reference
• start_pos - Start position in world coordinates
• end_pos - End position in world coordinates
• filter - Query filter for polygon selection

Returns

Result indicating success or failure of initialization

pub fn init_sliced_find_path_default( &mut self, start_ref: PolyRef, end_ref: PolyRef, start_pos: Vec3, end_pos: Vec3, filter: &QueryFilter, ) -> Result<(), DetourError>

Initializes a sliced path query with default options

This is a convenience method that calls init_sliced_find_path with options = 0 to match the C++ API default parameter behavior.

Arguments

• start_ref - The reference id of the start polygon
• end_ref - The reference id of the end polygon
• start_pos - A position within the start polygon
• end_pos - A position within the end polygon
• filter - The polygon filter to apply to the query

pub fn update_sliced_find_path( &mut self, max_iter: i32, ) -> Result<(i32, SlicedPathState), DetourError>

Updates the sliced pathfinding query for a limited number of iterations

This method continues processing the pathfinding request. It should be called each frame until it returns a state other than InProgress.

Arguments

• max_iterations - Maximum number of iterations to process this frame

Returns

The current state of the pathfinding (InProgress, Success, Failed, PartialPath)

pub fn finalize_sliced_find_path( &mut self, max_path: usize, ) -> Result<Vec<PolyRef>, DetourError>

Finalizes the sliced pathfinding and returns the computed path

This method should be called after update_sliced_find_path returns Success or PartialPath to retrieve the final path result.

Returns

The computed path as a vector of polygon references

pub fn finalize_sliced_find_path_partial( &mut self, existing: &[PolyRef], max_path: usize, ) -> Result<Vec<PolyRef>, DetourError>

Finalizes a sliced pathfinding query with a partial path

This method is used to retrieve a partial path when the pathfinding cannot reach the goal but has explored some nodes. It attempts to find the furthest node along the existing path that was visited.

Arguments

• existing - An existing path to try to extend from
• max_path - Maximum number of polygons in the result path

Returns

The computed partial path as a vector of polygon references

pub fn get_sliced_path_state(&self) -> Option<SlicedPathState>

Gets the current state of the sliced pathfinding query

Returns

The current pathfinding state, or None if no sliced query is active

pub fn cancel_sliced_find_path(&mut self)

Cancels the current sliced pathfinding query

pub fn find_polys_around_shape( &mut self, start_ref: PolyRef, verts: &[Vec3], filter: &QueryFilter, ) -> Result<Vec<(PolyRef, Option<PolyRef>, f32)>, DetourError>

Gets the wall segments of a polygon

Wall segments are edges of the polygon that don’t connect to other walkable polygons. Each segment is represented by two 3D points [start_x, start_y, start_z, end_x, end_y, end_z].

Arguments

• poly_ref - The polygon reference to get wall segments for
• filter - Query filter to determine which polygons are walkable
• max_segments - Maximum number of segments to return

Returns

Vector of wall segments, where each segment is [start_x, start_y, start_z, end_x, end_y, end_z] Finds polygons that overlap the search box

Arguments

• center - The center of the search box
• half_extents - The search distance along each axis
• filter - The polygon filter to apply to the query

Returns

A vector of polygon references that overlap the query box

Finds the polygons along the navigation graph that touch the specified convex polygon

Arguments

• start_ref - The reference id of the polygon where the search starts
• verts - The vertices describing the convex polygon (CCW). [(x, y, z) * nverts]
• filter - The polygon filter to apply to the query

Returns

A vector of tuples containing:

• The polygon reference
• The parent polygon reference (None if it’s the start polygon)
• The search cost from the centroid to the polygon

pub fn closest_point_on_poly_boundary( &self, poly_ref: PolyRef, pos: Vec3, ) -> Result<Vec3, DetourError>

Returns a point on the boundary closest to the source point if the source point is outside the polygon’s xz-bounds

Arguments

• poly_ref - The reference id to the polygon
• pos - The position to check

Returns

The closest point on the polygon boundary

pub fn get_edge_mid_point( &self, from_ref: PolyRef, to_ref: PolyRef, ) -> Result<Vec3, DetourError>

Returns edge mid point between two polygons

Arguments

• from_ref - The reference of the polygon to traverse from
• to_ref - The reference of the polygon to traverse to

Returns

The midpoint of the edge between the two polygons

pub fn query_polygons( &self, center: Vec3, half_extents: Vec3, filter: &QueryFilter, max_polys: usize, ) -> Result<Vec<PolyRef>, DetourError>

Gets a path from the explored nodes in the previous search

This method depends on the state from a previous Dijkstra search (findPolysAroundCircle or findPolysAroundShape). It should only be used immediately after one of these searches.

Arguments

• end_ref - The reference id of the end polygon

Returns

An ordered list of polygon references representing the path (start to end) Finds polygons that overlap the search box.

This method matches the C++ API: dtNavMeshQuery::queryPolygons

pub fn query_polygons_with_query( &self, center: Vec3, half_extents: Vec3, filter: &QueryFilter, query: &mut dyn PolyQuery, ) -> Result<(), DetourError>

Finds polygons that overlap the search box and processes them with a custom query.

This method matches the C++ API: dtNavMeshQuery::queryPolygons with dtPolyQuery

pub fn get_poly_wall_segments( &self, poly_ref: PolyRef, filter: &QueryFilter, max_segments: usize, ) -> Result<Vec<(Vec3, Vec3)>, DetourError>

pub fn is_valid_poly_ref(&self, poly_ref: PolyRef, filter: &QueryFilter) -> bool

Checks if a polygon reference is valid and passes the filter restrictions

pub fn is_in_closed_list(&self, poly_ref: PolyRef) -> bool

Checks if a polygon reference is in the closed list

pub fn query_polygons_custom<Q: PolyQuery>( &self, center: Vec3, extents: Vec3, filter: &QueryFilter, query: &mut Q, ) -> Result<(), DetourError>

Queries polygons with a custom query implementation

This is an alias for query_polygons_with_query with a more intuitive name. It allows custom processing of polygons during spatial queries.

Example

use waymark::{PolyQuery, NavMesh, NavMeshQuery, PolyRef, MeshTile, Poly, QueryFilter};
use glam::Vec3;

struct MyCustomQuery {
    count: usize,
}

impl PolyQuery for MyCustomQuery {
    fn process(&mut self, tile: &MeshTile, polys: &[&Poly], refs: &[PolyRef]) {
        self.count += polys.len();
    }
}

let filter = QueryFilter::default();
let mut custom_query = MyCustomQuery { count: 0 };
query.query_polygons_custom(
    Vec3::new(0.0, 0.0, 0.0),
    Vec3::new(10.0, 10.0, 10.0),
    &filter,
    &mut custom_query,
)?;
println!("Found {} polygons", custom_query.count);

pub fn get_node_pool(&self) -> &[Node]

Gets the internal node pool (for debugging and advanced use)

Note: The returned nodes are only valid during the current query. The node pool is reused between queries.

pub fn get_attached_nav_mesh(&self) -> &NavMesh

Gets the attached navigation mesh

Trait Implementations

impl<'a> Debug for NavMeshQuery<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.