Skip to main content

Crate landmass

Crate landmass 

Source
Expand description

§landmass

A Rust crate to provide a navigation system for video game characters to walk around levels.

§What is a navigation system?

A navigation system is essentially the collection of tools needed for robust agent movement in video games. This generally involves 4 things:

  • Path finding (e.g. A-star)
  • Path simplification (e.g. SSFA)
  • Steering (e.g. boids)
  • Local collision avoidance

In addition, managing agents and the navigation meshes they walk on can be cumbersome, so a navigation system ideally will handle that for you.

Generally it is difficult to find a full, free system to handle all of these for you, and the goal is for landmass to work relatively easily with other languages so it can be used anywhere.

§Overview

landmass has five major components: Archipelagos, Islands, Agents, Characters, and AnimationLinks. An Archipelago is composed of several Islands, as well as the Agents and Characters that travel across those Islands. Each Island holds a single navigation mesh. Each game character (controlled by AI) should correspond to one Agent. Player characters or other characters not controlled by AI should correspond to one Character. AnimationLinks (aka off-mesh links) allow connecting areas outside the nav mesh, allowing more flexible navigation. To start using landmass:

  1. Create an Archipelago.
  2. Create an Island.
  3. Add Agents and Characters to the Archipelago.

Each frame of the game:

  1. Set the position and velocity of each game character to its corresponding Agent or Character.
  2. Call update on the Archipelago.
  3. Use the desired move from each Agent to inform the corresponding game character where it should move.

Note: landmass intentionally does not update the Agents position itself. Generally, characters are moved using some other method (like a physics simulation) rather than just moving the character, so moving the Agent would be confusing.

§Example

use glam::Vec3;
use landmass::*;
use std::{sync::Arc, collections::HashMap};

let mut archipelago =
  Archipelago::<XYZ>::new(ArchipelagoOptions::from_agent_radius(0.5));

let nav_mesh = NavigationMesh {
  vertices: vec![
    Vec3::new(0.0, 0.0, 0.0),
    Vec3::new(15.0, 0.0, 0.0),
    Vec3::new(15.0, 15.0, 0.0),
    Vec3::new(0.0, 15.0, 0.0),
  ],
  polygons: vec![vec![0, 1, 2, 3]],
  polygon_type_indices: vec![0],
  height_mesh: None,
};

let valid_nav_mesh = Arc::new(
  nav_mesh.validate().expect("Validation succeeds")
);

let island_id = archipelago
  .add_island(Island::new(
    Transform { translation: Vec3::ZERO, rotation: 0.0 },
    valid_nav_mesh,
  ));

let agent_1 = archipelago.add_agent({
  let mut agent = Agent::create(
    /* position= */ Vec3::new(1.0, 1.0, 0.0),
    /* velocity= */ Vec3::ZERO,
    /* radius= */ 1.0,
    /* desired_speed= */ 1.0,
    /* max_speed= */ 2.0,
  );
  agent.current_target = Some(Vec3::new(11.0, 1.1, 0.0));
  agent.target_reached_condition = TargetReachedCondition::Distance(Some(0.01));
  agent
});
let agent_2 = archipelago.add_agent({
  let mut agent = Agent::create(
    /* position= */ Vec3::new(11.0, 1.1, 0.0),
    /* velocity= */ Vec3::ZERO,
    /* radius= */ 1.0,
    /* desired_speed= */ 1.0,
    /* max_speed= */ 2.0,
  );
  agent.current_target = Some(Vec3::new(1.0, 1.0, 0.0));
  agent.target_reached_condition = TargetReachedCondition::Distance(Some(0.01));
  agent
});

for i in 0..300 {
  let delta_time = 1.0 / 10.0;
  archipelago.update(delta_time);

  for agent_id in archipelago.get_agent_ids().collect::<Vec<_>>() {
    let agent = archipelago.get_agent_mut(agent_id).unwrap();
    agent.velocity = *agent.get_desired_velocity();
    agent.position += agent.velocity * delta_time;
  }
}

assert!(archipelago
  .get_agent(agent_1)
  .unwrap()
  .position
  .abs_diff_eq(Vec3::new(11.0, 1.1, 0.0), 0.1));
assert!(archipelago
  .get_agent(agent_2)
  .unwrap()
  .position
  .abs_diff_eq(Vec3::new(1.0, 1.0, 0.0), 0.1));

§License

License under either of

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules§

debug

Structs§

Agent
An agent in an archipelago.
AgentId
The ID of an agent.
AnimationLink
A link connecting two edges where an agent must perform some action (or animation) to use the link.
AnimationLinkId
The ID of an AnimationLink.
Archipelago
ArchipelagoOptions
Options that apply to the entire archipelago.
Character
A non-agent character. While agents are “managed” by the archipelago, characters are only as obstacles to be avoided by agents.
CharacterId
The ID of a character.
HeightNavigationMesh
An (optional) part of the navigation mesh dedicated to “refining” the height of a point.
HeightPolygon
A polygon specifically for “refining” the height of a point.
Island
An Island in an Archipelago. Each island holds a navigation mesh.
IslandId
The ID of an island.
IslandMut
A mutable borrow to an island.
NavigationMesh
A navigation mesh.
NotReachedAnimationLinkError
PathingResult
The result of path finding.
PointSampleDistance3d
A PointSampleDistance type for 3D coordinate systems.
ReachedAnimationLink
An animation link that an agent has reached (in order to use it).
SampledPoint
A point on the navigation meshes.
Transform
A transform that can be applied to Vec3’s.
ValidNavigationMesh
A navigation mesh which has been validated and derived data has been computed.
Vec3
A 3-dimensional vector.
XY
A 2D coordinate system, where X points right, and Y points forward.
XYZ
The standard coordinate system, where X points right, Y points forward, and Z points up.

Enums§

AgentState
The state of an agent.
FindPathError
An error from finding a path between two sampled points.
PathStep
A single step in a path.
PermittedAnimationLinks
Defines the list of animation links that an agent is allowed to use.
SamplePointError
An error while sampling a point.
SetTypeIndexCostError
An error for settings the cost of a type index.
TargetReachedCondition
The condition to consider the agent as having reached its target. When this condition is satisfied, the agent will stop moving.
ValidationError
An error when validating a navigation mesh.

Traits§

CoordinateSystem
A coordinate system used to convert from a user-facing coordinate system into landmass’s standard coordinate system. The standard coordinate system is crate::coords::XYZ.
FromAgentRadius
A trait to create a default instance based on an agent’s radius.
PointSampleDistance
A configuration of how a type relates to distances when sampling points. See crate::Archipelago::sample_point for more.