Crate oxidized_navigation

Source
Expand description

Tiled Runtime Nav-mesh Generation for 3D worlds in Bevy.

Takes in colliders that implement the OxidizedCollider trait from entities with the NavMeshAffector component and asynchronously generates tiles of navigation meshes based on NavMeshSettings. Nav-meshes can then be queried using query::find_path.

§Quick-start:

Nav-mesh generation:

  1. Choose which backend you’re going to use (bevy_rapier3d, avian3d, or custom parry3d based colliders) and enable the relevant crate features (“rapier” or “avian” features, custom parry3d colliders don’t require enabling any features).
  2. If you opted for custom parry3d colliders, implement the OxidizedCollider trait for your collider component that wraps a parry3d::shape::SharedShape. This is already done for bevy_rapier3d and avian3d.
  3. Add OxidizedNavigationPlugin as a plugin. (eg. for avian OxidizedNavigationPlugin::<Collider>::new(NavMeshSettings {...})
  4. Attach a NavMeshAffector component and a collider that implements the OxidizedCollider trait (already implemented for bevy_rapier3d and avian3d) to any entity you want to affect the nav-mesh.

At this point nav-meshes will be automatically generated whenever the collider or GlobalTransform of any entity with a NavMeshAffector is changed.

Querying the nav-mesh / Pathfinding:

  1. Your system needs to take in the NavMesh resource.
  2. Get the underlying data from the nav-mesh using NavMesh::get. This data is wrapped in an RwLock.
  3. To access the data call RwLock::read. This will block until you get read acces on the lock. If a task is already writing to the lock it may take time.
  4. Call query::find_path with the NavMeshTiles returned from the RwLock.

Also see the examples for how to run pathfinding in an async task which may be preferable.

§FAQ

I added the OxidizedNavigationPlugin to my app and now it won’t compile.

You need to use OxidizedNavigationPlugin::<Collider>::new(NavMeshSettings {...}, where Collider is either a rapier or avian Collider, or your own custom collider that implements the OxidizedCollider trait. This is necessary to allow us to be generic over different Collider components.

I don’t want to use the Rapier3d or XPBD3d physics engines just to generate a navmesh. How do I create my own parry3d wrapper component?

You need to create a component that contains a parry3d SharedShape, then implement the OxidizedCollider trait. See the parry3d example for a basic example.

Can I use this with the builtin bevy shapes, or my own custom shapes?

Currently only parry3d colliders are supported, or crates using parry3d colliders. You’d have to write a function to convert your shapes/bevy shapes into parry3d colliders.

Why aren’t my Parry3d colliders scaled properly?

You need to manually apply your transform’s scale to the Parry3d collider’s shape.

Modules§

colliders
conversion
debug_draw
Module for debug draws.
query
Module for querying the nav-mesh.
tiles

Structs§

ActiveGenerationTasks
Area
NavMesh
Wrapper around the nav-mesh data.
NavMeshAffector
Component for entities that should affect the nav-mesh.
NavMeshAreaType
Optional component to define the area type of an entity. Setting this to None means that the entity isn’t walkable.
NavMeshSettings
Settings for nav-mesh generation.
OxidizedNavigationPlugin
TileGenerated
Event containing the tile coordinate of a generated/regenerated tile.

Enums§

OxidizedNavigation
System sets containing the crate’s systems.

Functions§

build_tile_sync