Crate bevy_landmass

Expand description

§bevy_landmass

A plugin for Bevy to allow using landmass conveniently.

§Overview

bevy_landmass allows using a navigation mesh to determine the desired move direction for characters using pathfinding.

To use bevy_landmass:

Add LandmassPlugin to your app.
Spawn an entity with an Archipelago component.
Spawn an entity with an IslandBundle, a TransformBundle (or any other bundle which includes a Transform and GlobalTransform), and an IslandNavMesh component.
Spawn entities with the AgentBundle and a TransformBundle (or any other bundle which includes a Transform and GlobalTransform).

Note the Archipelago can be created later, even if the agents/islands already have an ArchipelagoRef to it. Agents/islands will be added once the Archipelago exists.

§Example

use std::sync::Arc;

use bevy::{app::AppExit, prelude::*};
use bevy_landmass::{prelude::*, NavMeshHandle};

fn main() {
  App::new()
    .add_plugins(MinimalPlugins)
    .add_plugins(AssetPlugin::default())
    .add_plugins(TransformPlugin)
    .add_plugins(Landmass2dPlugin::default())
    .add_systems(Startup, set_up_scene)
    .add_systems(Update, print_desired_velocity.after(LandmassSystemSet::Output))
    .add_systems(Update, quit.after(print_desired_velocity))
    .run();
}

fn set_up_scene(
  mut commands: Commands,
  mut nav_meshes: ResMut<Assets<NavMesh2d>>,
) {
  let archipelago_id = commands
    .spawn(Archipelago2d::new(AgentOptions::from_agent_radius(0.5)))
    .id();

  let nav_mesh_handle = nav_meshes.reserve_handle();

  commands
    .spawn((
      Island2dBundle {
        island: Island,
        archipelago_ref: ArchipelagoRef2d::new(archipelago_id),
        nav_mesh: NavMeshHandle(nav_mesh_handle.clone()),
      },
    ));
  
  // The nav mesh can be populated in another system, or even several frames
  // later.
  let nav_mesh = Arc::new(NavigationMesh2d {
      vertices: vec![
        Vec2::new(1.0, 1.0),
        Vec2::new(2.0, 1.0),
        Vec2::new(2.0, 2.0),
        Vec2::new(1.0, 2.0),
        Vec2::new(2.0, 3.0),
        Vec2::new(1.0, 3.0),
        Vec2::new(2.0, 4.0),
        Vec2::new(1.0, 4.0),
      ],
      polygons: vec![
        vec![0, 1, 2, 3],
        vec![3, 2, 4, 5],
        vec![5, 4, 6, 7],
      ],
      polygon_type_indices: vec![0, 0, 0],
    }.validate().expect("is valid"));
  nav_meshes.insert(&nav_mesh_handle, NavMesh2d{
    nav_mesh,
    type_index_to_node_type: Default::default(),
  });

  commands.spawn((
    Transform::from_translation(Vec3::new(1.5, 1.5, 0.0)),
    Agent2dBundle {
      agent: Default::default(),
      settings: AgentSettings {
        radius: 0.5,
        desired_speed: 1.0,
        max_speed: 2.0,
      },
      archipelago_ref: ArchipelagoRef2d::new(archipelago_id),
    },
    AgentTarget2d::Point(Vec2::new(1.5, 3.5)),
  ));
}

fn print_desired_velocity(query: Query<(Entity, &AgentDesiredVelocity2d)>) {
  for (entity, desired_velocity) in query.iter() {
    println!(
      "entity={:?}, desired_velocity={}",
      entity,
      desired_velocity.velocity());
  }
}

fn quit(mut exit: EventWriter<AppExit>) {
  // Quit so doctests pass.
  exit.send(AppExit::Success);
}

§License

License under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

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§

coords
debug
nav_mesh
prelude

Structs§

Agent: A marker component to create all required components for an agent.
AgentBundle: A bundle to create agents. This omits the GlobalTransform component, since this is commonly added in other bundles (which is redundant and can override previous bundles).
AgentDesiredVelocity: The current desired velocity of the agent. This is set by landmass (during crate::LandmassSystemSet::Output).
AgentNodeTypeCostOverrides
AgentOptions: Options that apply to all agents
AgentSettings: The settings for an agent. See crate::AgentBundle for required related components.
Archipelago: An archipelago, holding the internal state of landmass.
ArchipelagoRef: A reference to an archipelago.
Character: A marker component to create all required components for a character.
CharacterBundle: A bundle to create characters. This omits the GlobalTransform component, since this is commonly added in other bundles (which is redundant and can override previous bundles).
CharacterSettings: A character’s settings. See crate::CharacterBundle for required related components.
Island: A marker component that an entity is an island.
IslandBundle: A bundle to create islands. The GlobalTransform component is omitted, since this is commonly added in other bundles (which is redundant and can override previous bundles).
LandmassPlugin
NavMesh: An asset holding a landmass nav mesh.
NavMeshHandle: A handle to a navigation mesh for an Island.
NavigationMesh: A navigation mesh.
NodeType: A unique type of node.
PointSampleDistance3d: A PointSampleDistance type for 3D coordinate systems.
SampledPoint: A point on the navigation meshes.
ValidNavigationMesh: A navigation mesh which has been validated and derived data has been computed.
Velocity: The current velocity of the agent/character. This must be set to match whatever speed the agent/character is going.

Enums§

AgentState: The state of an agent.
AgentTarget: The current target of the entity. Note this can be set by either reinserting the component, or dereferencing:
FindPathError: An error from finding a path between two sampled points.
LandmassSystemSet: System set for landmass systems.
NewNodeTypeError: An error for creating a new node type.
SamplePointError: An error while sampling a point.
SetNodeTypeCostError: An error for settings the cost of an existing node type.
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§

FromAgentRadius: A trait to create a default instance based on an agent’s radius.

Crate bevy_landmassCopy item path