Crate bevy_landmass

Crate bevy_landmass 

Source
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:

  1. Add LandmassPlugin to your app.
  2. Spawn an entity with an Archipelago component.
  3. Spawn an entity with an IslandBundle, a TransformBundle (or any other bundle which includes a Transform and GlobalTransform), and an IslandNavMesh component.
  4. 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)
    .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(ArchipelagoOptions::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],
      height_mesh: None,
    }.validate().expect("is valid"));
  nav_meshes.insert(&nav_mesh_handle, NavMesh2d { nav_mesh });

  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: MessageWriter<AppExit>) {
  // Quit so doctests pass.
  exit.write(AppExit::Success);
}

§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§

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]).
AgentSettings
The settings for an agent. See crate::AgentBundle for required related components.
AgentTypeIndexCostOverrides
AnimationLink
A link connecting two edges where an agent must perform some action (or animation) to use the link.
AnimationLinkBundle
A bundle to create animation links.
AnimationLinkReachedDistance
The distance at which an animation link can be used.
Archipelago
An archipelago, holding the internal state of landmass.
ArchipelagoOptions
Options that apply to the entire archipelago.
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.
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
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.
PauseAgent
A marker component to indicate that an agent should be paused.
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.
UsingAnimationLink
A marker component to indicate that an agent is currently using an animation link and should behave as though it is paused (see PauseAgent for details).
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.
LandmassSystems
System set for landmass systems.
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§

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

Type Aliases§

Agent2d
Agent2dBundle
Agent3d
Agent3dBundle
AgentDesiredVelocity2d
AgentDesiredVelocity3d
AgentTarget2d
AgentTarget3d
AnimationLink2d
AnimationLink2dBundle
AnimationLink3d
AnimationLink3dBundle
Archipelago2d
Archipelago3d
ArchipelagoRef2d
ArchipelagoRef3d
Character2dBundle
Character3dBundle
HeightNavigationMesh2d
HeightNavigationMesh3d
Island2dBundle
Island3dBundle
Landmass2dPlugin
Landmass3dPlugin
NavMesh2d
NavMesh3d
NavMeshHandle2d
NavMeshHandle3d
NavigationMesh2d
NavigationMesh using 2D Bevy coordinates. That means that the mesh expects vertices to be on the XY plane.
NavigationMesh3d
NavigationMesh using 3D Bevy coordinates. That means that the mesh expects vertices to be in
ReachedAnimationLink2d
ReachedAnimationLink3d
ValidNavigationMesh2d
ValidNavigationMesh3d
Velocity2d
Velocity3d