diff --git a/Cargo.toml b/Cargo.toml
index c24d89b64e69b01cb2e4fc37940a9667194b810b..3aeea0fc45d0c04f3eaca1a79d53d5b9be0fb164 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "micro_bevy_world_utils"
-version = "0.2.0"
+version = "0.2.1"
edition = "2021"
license = "Apache-2.0"
description = "Handy, reusable utilities for working with direct world access in a Bevy exclusive system"
diff --git a/README.md b/README.md
index 05dad5375e523e054c98f5a92942b65fef00a7f2..bb1fd31d16f66bd243e8afa5e0509fb61f5ab8fa 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,8 @@
# Bevy World Utils
+[](https://crates.io/crates/micro_bevy_world_utils)
+[](https://docs.rs/micro_bevy_world_utils)
+
Handy, reusable utilities for working with direct world access in a Bevy exclusive system
## Installation
@@ -8,7 +11,7 @@ Handy, reusable utilities for working with direct world access in a Bevy exclusi
## Usage
-Check out the docs [{link pending}]() to get a full list of functions. Each function will take at least
+Check out [the docs](https://docs.rs/micro_bevy_world_utils) to get a full list of functions. Each function will take at least
an `&mut World`, as well as whatever parameters it is working on.
### Sending events
diff --git a/src/lib.rs b/src/lib.rs
index 3d9a02ff87c0b917eef33d2e43eaca5f690f7886..15637943a17f49297b07f46e3fddec31665640a7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,34 +1,34 @@
-/// `micro_bevy_world_utils` packages some common functions used to interrogate the world state from
-/// exclusive bevy systems. One frequent use case for these functions is in implementing a monolithic
-/// physics collisions processor.
-///
-/// ## World Interrogation
-///
-/// ## World Mutation
-///
-/// - `send_event`: Send an event
-///
-/// ## Entity Sorting
-///
-/// There are several functions that take the form "get_{specifier}_{specifier}_entities", such as
-/// `get_left_right_entities`. These are used to sort two entities according to which specified
-/// components they contain, or to fetch the _parent_ of one or both entities matching the criteria.
-///
-/// `{specifier}` takes the following form: `[any_](left|right)[[_any]_parent]`
-///
-/// - `any_` implies that no components need to be matched for that side of the query to be
-/// successful. This would be equivalent to supplying `()` to the version without `any_`
-/// - `_parent` implies that the returned entity for that side will, if a match is found, be the
-/// _parent_ entity of the matching input entity.
-///
-/// **N.B.** The left component will always be queried first
-///
-/// ### Examples
-///
-/// - `get_left_right_entities`: Match entities to the left and right components
-/// - `get_left_any_right_parent`: Match against the left component, and match the parent of the second entity against the right component
-/// - `get_left_right_any_parent`: Match entities to the left and right components, but return the _parent_ entity of the right entity
-///
+//! `micro_bevy_world_utils` packages some common functions used to interrogate the world state from
+//! exclusive bevy systems. One frequent use case for these functions is in implementing a monolithic
+//! physics collisions processor.
+//!
+//! ## World Interrogation
+//!
+//! ## World Mutation
+//!
+//! - `send_event`: Send an event
+//!
+//! ## Entity Sorting
+//!
+//! There are several functions that take the form "get_{specifier}_{specifier}_entities", such as
+//! `get_left_right_entities`. These are used to sort two entities according to which specified
+//! components they contain, or to fetch the _parent_ of one or both entities matching the criteria.
+//!
+//! `{specifier}` takes the following form: `[any_](left|right)[[_any]_parent]`
+//!
+//! - `any_` implies that no components need to be matched for that side of the query to be
+//! successful. This would be equivalent to supplying `()` to the version without `any_`
+//! - `_parent` implies that the returned entity for that side will, if a match is found, be the
+//! _parent_ entity of the matching input entity.
+//!
+//! **N.B.** The left component will always be queried first
+//!
+//! ### Examples
+//!
+//! - `get_left_right_entities`: Match entities to the left and right components
+//! - `get_left_any_right_parent`: Match against the left component, and match the parent of the second entity against the right component
+//! - `get_left_right_any_parent`: Match entities to the left and right components, but return the _parent_ entity of the right entity
+//!
use bevy_ecs::{
component::Component,
entity::Entity,
@@ -135,6 +135,13 @@ fn inner_get_left_parent_right_parent_entities<
None
}
+/// Given two entities and two component types, order those entities based on which entity contains
+/// which component.
+///
+/// The generic parameters `LeftSide` and `RightSide` determine the components being queried for,
+/// and will place their matching entity in positions `0` and `1` of the tuple, respectively. If
+/// one of both entities do not match with a distinct component type, this function will return `None`; i.e.
+/// each entity must match exactly one component, and those matches must be unique.
pub fn get_left_right_entities<LeftSide: Component, RightSide: Component>(
world: &mut World,
first: &Entity,
@@ -143,6 +150,16 @@ pub fn get_left_right_entities<LeftSide: Component, RightSide: Component>(
inner_get_left_right_entities::<With<LeftSide>, With<RightSide>>(world, first, second)
}
+/// Given two entities and three component types, order those entities based on which entity contains
+/// the left hand component, and which entity contains the right hand component while having a parent
+/// that contains the right hand component. The resulting tuple will contain the left component and
+/// the parent component, but _not_ the right component.
+///
+/// The generic parameters `LeftSide` and `ParentSide` determine the components being queried for,
+/// and will place their matching entity in positions `0` and `1` of the tuple, respectively. `RightSide`
+/// will be used to determine which entity should have its parent fetched. If one of both entities do not
+/// match with a distinct component type, this function will return `None`; i.e. each entity must match
+/// exactly one component, and those matches must be unique.
pub fn get_left_right_parent_entities<
LeftSide: Component,
RightSide: Component,
@@ -157,6 +174,12 @@ pub fn get_left_right_parent_entities<
)
}
+/// Given two entities and a Component type, order those entities based on which one matches the
+/// Component type.
+///
+/// The first entity to contain `LeftComponent` will be in position `0` of the
+/// resulting tuple, and the other will be in position `1`, regardless of whether they both match
+/// or just one matches. Returns `None` if neither match
pub fn get_left_any_right_entities<LeftComponent: Component>(
world: &mut World,
first: &Entity,