Struct hecs::World

pub struct World { /* fields omitted */ }

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

pub fn new() -> Self

Create an empty world

pub fn spawn(&mut self, components: impl DynamicBundle) -> Entity

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>

Destroy an entity and all its components

pub fn clear(&mut self)

Despawn all entities

Preserves allocated storage for reuse.

pub fn contains(&self, entity: Entity) -> bool

Whether entity still exists

Important traits for QueryIter<'a, Q>

impl<'a, Q: Query<'a>> Iterator for QueryIter<'a, Q> type Item = (Entity, Q);

pub fn query<'a, Q: Query<'a>>(&'a self) -> QueryIter<'a, Q>

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.

Query types can also be constructed with #[derive(Query)] on a struct whose fields all have query types.

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)>().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>

Borrow the T component of entity

Panics if the component is already uniquely borrowed.

pub fn get_mut<T: Component>(
    &self,
    entity: Entity
) -> Result<RefMut<T>, ComponentError>

Uniquely borrow the T component of entity

Panics if the component is already borrowed.

pub fn entity(&self, entity: Entity) -> Result<EntityRef, NoSuchEntity>

Access an entity regardless of its component types

Does not immediately borrow any component.

Important traits for Iter<'a>

impl<'a> Iterator for Iter<'a> type Item = (Entity, EntityRef<'a>);

pub fn iter(&self) -> Iter

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>

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>

Add component to entity

See insert.

pub fn remove<T: Bundle>(&mut self, entity: Entity) -> Result<T, ComponentError>

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>

Remove the T component from entity

See remove.

Trait Implementations

impl Default for World

fn default() -> World

Returns the "default value" for a type.

impl<A: DynamicBundle> Extend<A> for World

fn extend<T>(&mut self, iter: T) where
    T: IntoIterator<Item = A>, 

Extends a collection with the contents of an iterator.

impl<A: DynamicBundle> FromIterator<A> for World

fn from_iter<I: IntoIterator<Item = A>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> IntoIterator for &'a World

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>

impl<'a> Iterator for Iter<'a> type Item = (Entity, EntityRef<'a>);

fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl Sync for World