[−][src]Struct hecs::World
An unordered collection of entities, each having any number of distinctly typed components
Similar to HashMap<Entity, Vec<Box<dyn Any>>>
where each Vec
never contains two of the same
type, but far more efficient to traverse.
The components of entities who have the same set of component types are stored in contiguous runs, allowing for extremely fast, cache-friendly iteration.
Methods
impl World
[src]
pub fn new() -> Self
[src]
Create an empty world
pub fn spawn(&mut self, components: impl DynamicBundle) -> Entity
[src]
Create an entity with certain components
Returns the ID of the newly created entity.
Arguments can be tuples, structs annotated with #[derive(Bundle)]
, or EntityBuilder
,
preferred if the set of components isn't statically known. To spawn an entity with only one
component, use a one-element tuple like (x,)
.
Example
let mut world = World::new(); let a = world.spawn((123, "abc")); let b = world.spawn((456, true));
pub fn despawn(&mut self, entity: Entity) -> Result<(), NoSuchEntity>
[src]
Destroy an entity and all its components
pub fn clear(&mut self)
[src]
Despawn all entities
Preserves allocated storage for reuse.
pub fn contains(&self, entity: Entity) -> bool
[src]
Whether entity
still exists
pub fn query<Q: Query>(&self) -> QueryBorrow<Q>
[src]
Efficiently iterate over all entities that have certain components
Yields (Entity, Q)
tuples, where Q
is some query type. A query type is &T
, &mut T
, a
tuple of query types, or an Option
wrapping a query type, where T
is any component
type. Components queried with &mut
must only appear once. Entities which do not have a
component type referenced outside of an Option
will be skipped.
Entities are yielded in arbitrary order.
Constructing a query will panic if it would violate an existing unique reference or construct an invalid unique reference. This occurs when two simultaneously-active queries could expose the same entity. Simultaneous queries can access the same component type if and only if the world contains no entities that have all components required by both queries, assuming no other component borrows are outstanding.
Example
let mut world = World::new(); let a = world.spawn((123, true, "abc")); let b = world.spawn((456, false)); let c = world.spawn((42, "def")); let entities = world.query::<(&i32, &bool)>() .iter() .map(|(e, (&i, &b))| (e, i, b)) // Copy out of the world .collect::<Vec<_>>(); assert_eq!(entities.len(), 2); assert!(entities.contains(&(a, 123, true))); assert!(entities.contains(&(b, 456, false)));
pub fn get<T: Component>(
&self,
entity: Entity
) -> Result<Ref<T>, ComponentError>
[src]
&self,
entity: Entity
) -> Result<Ref<T>, ComponentError>
Borrow the T
component of entity
Panics if the component is already uniquely borrowed from another entity with the same components.
pub fn get_mut<T: Component>(
&self,
entity: Entity
) -> Result<RefMut<T>, ComponentError>
[src]
&self,
entity: Entity
) -> Result<RefMut<T>, ComponentError>
Uniquely borrow the T
component of entity
Panics if the component is already borrowed from another entity with the same components.
pub fn entity(&self, entity: Entity) -> Result<EntityRef, NoSuchEntity>
[src]
Access an entity regardless of its component types
Does not immediately borrow any component.
ⓘImportant traits for Iter<'a>pub fn iter(&self) -> Iter
[src]
Iterate over all entities in the world
Entities are yielded in arbitrary order. Prefer World::query
for better performance when
components will be accessed in predictable patterns.
Example
let mut world = World::new(); let a = world.spawn(()); let b = world.spawn(()); assert_eq!(world.iter().map(|(id, _)| id).collect::<Vec<_>>(), &[a, b]);
pub fn insert(
&mut self,
entity: Entity,
components: impl DynamicBundle
) -> Result<(), NoSuchEntity>
[src]
&mut self,
entity: Entity,
components: impl DynamicBundle
) -> Result<(), NoSuchEntity>
Add components
to entity
Computational cost is proportional to the number of components entity
has. If an entity
already has a component of a certain type, it is dropped and replaced.
Example
let mut world = World::new(); let e = world.spawn((123, "abc")); world.insert(e, (456, true)); assert_eq!(*world.get::<i32>(e).unwrap(), 456); assert_eq!(*world.get::<bool>(e).unwrap(), true);
pub fn insert_one(
&mut self,
entity: Entity,
component: impl Component
) -> Result<(), NoSuchEntity>
[src]
&mut self,
entity: Entity,
component: impl Component
) -> Result<(), NoSuchEntity>
Add component
to entity
See insert
.
pub fn remove<T: Bundle>(&mut self, entity: Entity) -> Result<T, ComponentError>
[src]
Remove components from entity
Computational cost is proportional to the number of components entity
has. The entity
itself is not removed, even if no components remain; use despawn
for that. If any
component in T
is not present in entity
, no components are removed and an error is
returned.
Example
let mut world = World::new(); let e = world.spawn((123, "abc", true)); assert_eq!(world.remove::<(i32, &str)>(e), Ok((123, "abc"))); assert!(world.get::<i32>(e).is_err()); assert!(world.get::<&str>(e).is_err()); assert_eq!(*world.get::<bool>(e).unwrap(), true);
pub fn remove_one<T: Component>(
&mut self,
entity: Entity
) -> Result<T, ComponentError>
[src]
&mut self,
entity: Entity
) -> Result<T, ComponentError>
Remove the T
component from entity
See remove
.
Trait Implementations
impl Default for World
[src]
impl<A: DynamicBundle> Extend<A> for World
[src]
fn extend<T>(&mut self, iter: T) where
T: IntoIterator<Item = A>,
[src]
T: IntoIterator<Item = A>,
impl<A: DynamicBundle> FromIterator<A> for World
[src]
fn from_iter<I: IntoIterator<Item = A>>(iter: I) -> Self
[src]
impl<'a> IntoIterator for &'a World
[src]
type IntoIter = Iter<'a>
Which kind of iterator are we turning this into?
type Item = (Entity, EntityRef<'a>)
The type of the elements being iterated over.
ⓘImportant traits for Iter<'a>fn into_iter(self) -> Iter<'a>
[src]
impl Sync for World
[src]
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,