Getting Started
Installation
Add the crates you need to your Cargo.toml:
[dependencies]
landmark = "0.1"
waymark = "0.1"
Optional crates:
[dependencies]
waymark-crowd = "0.1" # Multi-agent crowd simulation
waymark-tilecache = "0.1" # Dynamic obstacle management
waymark-dynamic = "0.1" # Dynamic navmesh generation
Feature Flags
| Crate | Feature | Dependencies | Default |
|---|---|---|---|
| landmark-common | std | standard library | Yes |
| waymark | serialization | serde, serde_json, postcard, byteorder | No |
| waymark-tilecache | serialization | serde, serde_json, postcard | No |
| waymark-dynamic | tokio | tokio (spawn_blocking) | No |
Enable features in Cargo.toml:
[dependencies]
waymark = { version = "0.1", features = ["serialization"] }
Basic Usage
The typical workflow is:
- Load or define input geometry (triangle mesh)
- Generate a navigation mesh with Recast
- Query paths with Detour
use landmark::{RecastBuilder, RecastConfig};
use waymark::{NavMesh, NavMeshFlags, NavMeshParams, NavMeshQuery, QueryFilter};
use glam::Vec3;
// Configure and build the navigation mesh
let mut config = RecastConfig::default();
config.calculate_grid_size(bounds_min, bounds_max);
let builder = RecastBuilder::new(config);
// Build from triangle data (flat f32 arrays: [x,y,z, x,y,z, ...])
let (poly_mesh, detail_mesh) = builder.build_mesh(&vertices, &indices)?;
// Create a NavMesh for pathfinding
let params = NavMeshParams::default();
let nav_mesh = NavMesh::build_from_recast(params, &poly_mesh, &detail_mesh, NavMeshFlags::empty())?;
// Find a path
let mut query = NavMeshQuery::new(&nav_mesh);
let filter = QueryFilter::default();
let extents = Vec3::new(2.0, 4.0, 2.0);
let (start_ref, _) = query.find_nearest_poly(start_pos, extents, &filter)?;
let (end_ref, _) = query.find_nearest_poly(end_pos, extents, &filter)?;
let path = query.find_path(start_ref, end_ref, start_pos, end_pos, &filter)?;RecastConfig Parameters
The RecastConfig struct controls the navigation mesh generation. Key parameters:
| Parameter | Default | Description |
|---|---|---|
cs | 0.3 | Cell size (horizontal voxel resolution) |
ch | 0.2 | Cell height (vertical voxel resolution) |
walkable_slope_angle | 45.0 | Maximum walkable slope in degrees |
walkable_height | 2 | Minimum ceiling height (in voxels) |
walkable_climb | 1 | Maximum step height (in voxels) |
walkable_radius | 1 | Agent radius for erosion (in voxels) |
max_edge_len | 12 | Maximum contour edge length |
max_simplification_error | 1.3 | Maximum contour simplification error |
min_region_area | 8 | Minimum region size (in voxels) |
merge_region_area | 20 | Region merge threshold |
max_vertices_per_polygon | 6 | Maximum vertices per polygon |
detail_sample_dist | 6.0 | Detail mesh sampling distance |
detail_sample_max_error | 1.0 | Detail mesh max height error |
Smaller cs and ch values produce more accurate meshes but increase memory
usage and build time. walkable_height, walkable_climb, and walkable_radius
define the agent’s physical properties in voxel units.
Platform Support
- Linux: x86_64 (glibc, musl), aarch64 (glibc, musl), armv7 (glibc, musl)
- macOS: aarch64, x86_64
- Windows: x86_64 (MSVC, GNU)
- WebAssembly: wasm32-unknown-unknown (library crates only)
See the WebAssembly guide for WASM-specific instructions.