micro_bevy_world_utils 0.9.0

//! `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,
	message::MessageWriter,
	query::{QueryFilter, With},
	system::{Query, SystemState},
	world::World,
};
use bevy_ecs::hierarchy::ChildOf;

pub type Left = Entity;
pub type Right = Entity;
pub type SortedEntities = (Left, Right);

fn inner_get_left_right_entities<
	LeftSide: QueryFilter + 'static,
	RightSide: QueryFilter + 'static,
>(
	world: &mut World,
	first: &Entity,
	second: &Entity,
) -> Option<SortedEntities> {
	let mut state = SystemState::<(Query<(), LeftSide>, Query<(), RightSide>)>::new(world);
	let (left_query, right_query) = state.get(world);

	if left_query.contains(*first) && right_query.contains(*second) {
		Some((*first, *second))
	} else if left_query.contains(*second) && right_query.contains(*first) {
		Some((*second, *first))
	} else {
		None
	}
}

fn inner_get_left_right_parent_entities<
	LeftSide: QueryFilter + 'static,
	RightSide: QueryFilter + 'static,
	ParentSide: QueryFilter + 'static,
>(
	world: &mut World,
	first: &Entity,
	second: &Entity,
) -> Option<SortedEntities> {
	let mut state = SystemState::<(
		Query<(), LeftSide>,
		Query<&ChildOf, RightSide>,
		Query<(), ParentSide>,
	)>::new(world);
	let (left_query, right_query, parent_query) = state.get(world);
	if left_query.contains(*first) {
		if let Ok(related) = right_query.get(*second) {
			let parent = related.parent();
			if parent_query.contains(parent) {
				return Some((*first, parent));
			}
		}
	} else if left_query.contains(*second) {
		if let Ok(related) = right_query.get(*first) {
			let parent = related.parent();
			if parent_query.contains(parent) {
				return Some((*second, parent));
			}
		}
	}

	None
}

fn inner_get_left_parent_right_parent_entities<
	LeftSide: QueryFilter + 'static,
	LeftParent: QueryFilter + 'static,
	RightSide: QueryFilter + 'static,
	RightParent: QueryFilter + 'static,
>(
	world: &mut World,
	first: &Entity,
	second: &Entity,
) -> Option<SortedEntities> {
	let mut state = SystemState::<(
		Query<&ChildOf, LeftSide>,
		Query<&ChildOf, RightSide>,
		Query<(), LeftParent>,
		Query<(), RightParent>,
	)>::new(world);
	let (left_query, right_query, left_parent_query, right_parent_query) = state.get(world);
	if let Ok(left_parent) = left_query.get(*first) {
		if left_parent_query.contains(left_parent.parent()) {
			if let Ok(right_parent) = right_query.get(*second) {
				if right_parent_query.contains(right_parent.parent()) {
					return Some((left_parent.parent(), right_parent.parent()));
				}
			}
		}
	} else if let Ok(left_parent) = left_query.get(*second) {
		if left_parent_query.contains(left_parent.parent()) {
			if let Ok(right_parent) = right_query.get(*first) {
				if right_parent_query.contains(right_parent.parent()) {
					return Some((left_parent.parent(), right_parent.parent()));
				}
			}
		}
	}

	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,
	second: &Entity,
) -> Option<SortedEntities> {
	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,
	ParentSide: Component,
>(
	world: &mut World,
	first: &Entity,
	second: &Entity,
) -> Option<SortedEntities> {
	inner_get_left_right_parent_entities::<With<LeftSide>, With<RightSide>, With<ParentSide>>(
		world, first, second,
	)
}

/// 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,
	second: &Entity,
) -> Option<SortedEntities> {
	inner_get_left_right_entities::<With<LeftComponent>, ()>(world, first, second)
}

pub fn get_left_parent_right_parent_entities<
	LeftSide: Component,
	LeftParent: Component,
	RightSide: Component,
	RightParent: Component,
>(
	world: &mut World,
	first: &Entity,
	second: &Entity,
) -> Option<SortedEntities> {
	inner_get_left_parent_right_parent_entities::<
		With<LeftSide>,
		With<LeftParent>,
		With<RightSide>,
		With<RightParent>,
	>(world, first, second)
}

pub fn get_any_left_parent_any_right_parent_entities<
	LeftParent: Component,
	RightParent: Component,
>(
	world: &mut World,
	first: &Entity,
	second: &Entity,
) -> Option<SortedEntities> {
	inner_get_left_parent_right_parent_entities::<(), With<LeftParent>, (), With<RightParent>>(
		world, first, second,
	)
}

/// Send an event to the appropriate message writer. Writer type is derived from the
/// second parameter passed in, and must be registered with the application before
/// trying to send. Recent bevy versions include a `send_message` function on the
/// [bevy_ecs::prelude::Commands] type
///
/// ## Example
///
/// ```rust
/// # use bevy_ecs::message::Message;
/// # use bevy_ecs::world::World;
///
/// #[derive(Message)]
/// struct MyEventType {
///     message: usize
/// }
///
/// // Do some app setup
///
/// use micro_bevy_world_utils::send_message;
/// pub fn my_world_system(world: &mut World) {
///     // Do some processing here
///     send_message(world, MyEventType { message: 1234 });
/// }
/// ```
pub fn send_message<Event: bevy_ecs::message::Message + Sync + Send + 'static>(
	world: &mut World,
	event: Event,
) {
	SystemState::<MessageWriter<Event>>::new(world)
		.get_mut(world)
		.write(event);
}

#[doc(hidden)]
#[deprecated(note = "Use send_message instead; this function will be removed in a future version")]
pub fn send_event<Event: bevy_ecs::message::Message + Sync + Send + 'static>(
	world: &mut World,
	event: Event,
) {
	send_message(world, event)
}

/// Clone the data from a specific component of the target entity, as long as that entity
/// has that component and the component itself implements `Clone`
///
/// ## Example
///
/// ```rust
///
/// ```
pub fn clone_entity_component<C: Component + Clone>(
	world: &mut World,
	entity: &Entity,
) -> Option<C> {
	let mut state = SystemState::<Query<&'static C>>::new(world);
	let query = state.get(world);
	let item = query.get(*entity);

	if let Ok(value) = item {
		Some(value.clone())
	} else {
		None
	}
}