diff --git a/crates/bevy_landmass/README.md b/crates/bevy_landmass/README.md index b66d75d..7a8ee02 100644 --- a/crates/bevy_landmass/README.md +++ b/crates/bevy_landmass/README.md @@ -22,6 +22,18 @@ 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. +## ⚠️ Important: Mesh Orientation and Normals + +When converting a mesh to a `NavigationMesh`, **ensure that**: +- The mesh is defined in **clockwise** vertex order. +- Normals are facing **inward** (towards the interior of the mesh). + +#### Why does this matter? +- Most 3D editors default to **counter-clockwise** mesh orientation (normals facing outward). +- Incorrect orientation can cause navigation algorithms to fail (e.g., agents may get stuck or choose invalid paths). + +#### How to Check/Fix Orientation? +- **Blender**: Enable normal display (`Overlay -> Normals`). Red normals indicate inward-facing direction. ## Example ```rust diff --git a/crates/bevy_landmass/src/nav_mesh.rs b/crates/bevy_landmass/src/nav_mesh.rs index 17bc346..3f44adb 100644 --- a/crates/bevy_landmass/src/nav_mesh.rs +++ b/crates/bevy_landmass/src/nav_mesh.rs @@ -20,6 +20,10 @@ pub enum ConvertMeshError { /// Converts a Bevy Mesh to a landmass NavigationMesh. This is done naively - /// each triangle forms a single polygon in the navigation mesh, which can cause /// strange paths to form (agents may take turns inside if wide open regions). +/// +/// ## Note: The input mesh must be in **clockwise** orientation, +/// ## with normals facing **inward** (towards the interior of the mesh). +/// /// This function is provided as a convenience, and a better method for /// generating navigation meshes should be used. pub fn bevy_mesh_to_landmass_nav_mesh(