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, bevy_xpbd_3d, or custom parry3d based colliders) and enable the relevant crate features (“rapier” or “xpbd” 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 bevy_xpbd_3d.
  3. Add OxidizedNavigationPlugin as a plugin. (eg. for xpbd OxidizedNavigationPlugin::<Collider>::new(NavMeshSettings {...})
  4. Attach a NavMeshAffector component and a collider that implements the OxidizedCollider trait (already implemented for bevy_rapier3d and bevy_xpbd_3D) 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 xpbd 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 Xpbd/Parry3d colliders scaled properly?

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

Modules§

Structs§

Enums§

Functions§