Skip to content
Snippets Groups Projects
Verified Commit c0d18d99 authored by Louis's avatar Louis :fire:
Browse files

Improve documentation

parent d78a1eef
No related branches found
No related tags found
No related merge requests found
[package] [package]
name = "micro_bevy_world_utils" name = "micro_bevy_world_utils"
version = "0.2.0" version = "0.2.1"
edition = "2021" edition = "2021"
license = "Apache-2.0" license = "Apache-2.0"
description = "Handy, reusable utilities for working with direct world access in a Bevy exclusive system" description = "Handy, reusable utilities for working with direct world access in a Bevy exclusive system"
......
# Bevy World Utils # Bevy World Utils
[![https://crates.io/crates/micro_bevy_world_utils](https://img.shields.io/crates/v/micro_bevy_world_utils?style=for-the-badge)](https://crates.io/crates/micro_bevy_world_utils)
[![https://docs.rs/micro_bevy_world_utils](https://img.shields.io/docsrs/micro_bevy_world_utils?style=for-the-badge)](https://docs.rs/micro_bevy_world_utils)
Handy, reusable utilities for working with direct world access in a Bevy exclusive system Handy, reusable utilities for working with direct world access in a Bevy exclusive system
## Installation ## Installation
...@@ -8,7 +11,7 @@ Handy, reusable utilities for working with direct world access in a Bevy exclusi ...@@ -8,7 +11,7 @@ Handy, reusable utilities for working with direct world access in a Bevy exclusi
## Usage ## 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. an `&mut World`, as well as whatever parameters it is working on.
### Sending events ### Sending events
......
/// `micro_bevy_world_utils` packages some common functions used to interrogate the world state from //! `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 //! exclusive bevy systems. One frequent use case for these functions is in implementing a monolithic
/// physics collisions processor. //! physics collisions processor.
/// //!
/// ## World Interrogation //! ## World Interrogation
/// //!
/// ## World Mutation //! ## World Mutation
/// //!
/// - `send_event`: Send an event //! - `send_event`: Send an event
/// //!
/// ## Entity Sorting //! ## Entity Sorting
/// //!
/// There are several functions that take the form "get_{specifier}_{specifier}_entities", such as //! 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 //! `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. //! 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]` //! `{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 //! - `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_` //! 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` implies that the returned entity for that side will, if a match is found, be the
/// _parent_ entity of the matching input entity. //! _parent_ entity of the matching input entity.
/// //!
/// **N.B.** The left component will always be queried first //! **N.B.** The left component will always be queried first
/// //!
/// ### Examples //! ### Examples
/// //!
/// - `get_left_right_entities`: Match entities to the left and right components //! - `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_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 //! - `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::{ use bevy_ecs::{
component::Component, component::Component,
entity::Entity, entity::Entity,
...@@ -135,6 +135,13 @@ fn inner_get_left_parent_right_parent_entities< ...@@ -135,6 +135,13 @@ fn inner_get_left_parent_right_parent_entities<
None 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>( pub fn get_left_right_entities<LeftSide: Component, RightSide: Component>(
world: &mut World, world: &mut World,
first: &Entity, first: &Entity,
...@@ -143,6 +150,16 @@ pub fn get_left_right_entities<LeftSide: Component, RightSide: Component>( ...@@ -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) 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< pub fn get_left_right_parent_entities<
LeftSide: Component, LeftSide: Component,
RightSide: Component, RightSide: Component,
...@@ -157,6 +174,12 @@ pub fn get_left_right_parent_entities< ...@@ -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>( pub fn get_left_any_right_entities<LeftComponent: Component>(
world: &mut World, world: &mut World,
first: &Entity, first: &Entity,
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment