Struct shipyard::Entities

pub struct Entities { /* private fields */ }

Entities holds the EntityIds to all entities: living, removed and dead.

A living entity is an entity currently present, with or without component.

Removed and dead entities don’t have any component.

The big difference is that removed ones can become alive again.

The life cycle of an entity looks like this:

Generation -> Deletion -> Dead
          ⬑–––––↵

Implementations

impl Entities

pub fn is_alive(&self, entity: EntityId) -> bool

Returns true if entity matches a living entity.

pub fn add_component<S: AddComponent>(
    &self,
    entity: EntityId,
    storages: S,
    component: S::Component
)

Adds component to entity, multiple components can be added at the same time using a tuple.
Entities is only borrowed immutably.

Panics

• entity is not alive.

Example

use shipyard::{Component, EntitiesView, ViewMut, World};

#[derive(Component)]
struct U32(u32);

let mut world = World::new();

let entity = world.add_entity(());

let (entities, mut u32s) = world.borrow::<(EntitiesView, ViewMut<U32>)>().unwrap();

entities.add_component(entity, &mut u32s, U32(0));

pub fn add_distinct_component<S: AddDistinctComponent>(
    &self,
    entity: EntityId,
    storages: S,
    component: S::Component
) -> bool

Adds component to entity, multiple components can be added at the same time using a tuple.
If the entity already has this component, it won’t be replaced. Very useful if you want accurate modification tracking.
Entities is only borrowed immutably.

Returns true if the component was added.

Panics

• entity is not alive.

Example

use shipyard::{Component, EntitiesView, ViewMut, World};

#[derive(Component, PartialEq)]
struct U32(u32);

let mut world = World::new();

let entity = world.add_entity(());

let (entities, mut u32s) = world.borrow::<(EntitiesView, ViewMut<U32>)>().unwrap();

assert!(entities.add_distinct_component(entity, &mut u32s, U32(0)));
assert!(!entities.add_distinct_component(entity, &mut u32s, U32(0)));

pub fn delete_unchecked(&mut self, entity_id: EntityId) -> bool

Deletes an entity, returns true if the entity was alive.
If the entity has components, they will not be deleted and still be accessible using this id.

pub fn add_entity<T: AddEntity>(
    &mut self,
    storages: T,
    component: T::Component
) -> EntityId

Stores component in a new entity and returns its EntityId.
Multiple components can be added at the same time using a tuple.

Example:

use shipyard::{Component, EntitiesViewMut, ViewMut, World};

#[derive(Component, Debug, PartialEq, Eq)]
struct U32(u32);

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

let world = World::new();

let (mut entities, mut usizes, mut u32s) = world
    .borrow::<(EntitiesViewMut, ViewMut<USIZE>, ViewMut<U32>)>()
    .unwrap();

let entity = entities.add_entity((&mut usizes, &mut u32s), (USIZE(0), U32(1)));
assert_eq!(usizes[entity], USIZE(0));
assert_eq!(u32s[entity], U32(1));

pub fn bulk_add_entity<T: AddEntity + BulkReserve, I: IntoIterator<Item = T::Component>>(
    &mut self,
    storages: T,
    component: I
) -> BulkEntityIter<'_>

Creates multiple new entities and returns an iterator yielding the new EntityIds.
Multiple components can be added at the same time using a tuple.

Example

use shipyard::{Component, EntitiesViewMut, ViewMut, World};

#[derive(Component)]
struct U32(u32);

#[derive(Component)]
struct USIZE(usize);

let world = World::new();

let (mut entities, mut usizes, mut u32s) = world
    .borrow::<(EntitiesViewMut, ViewMut<USIZE>, ViewMut<U32>)>()
    .unwrap();

let new_entities =
    entities.bulk_add_entity((&mut u32s, &mut usizes), (10..20).map(|i| (U32(i as u32), USIZE(i))));

pub fn iter(&self) -> EntitiesIter<'_>

Creates an iterator over all entities.

pub fn spawn(&mut self, entity: EntityId) -> bool

Make the given entity alive.
Does nothing if an entity with a greater generation is already at this index.
Returns true if the entity is successfully spawned.

Trait Implementations

impl<'a> IntoIterator for &'a Entities

type Item = EntityId

The type of the elements being iterated over.

type IntoIter = EntitiesIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Storage for Entities

fn clear(&mut self, _current: u32)

Deletes all components of this storage.

fn memory_usage(&self) -> Option<StorageMemoryUsage>

Returns how much memory this storage uses.

fn is_empty(&self) -> bool

Returns true if the storage is empty.

fn any(&self) -> &dyn Any

Casts to &dyn Any.

fn any_mut(&mut self) -> &mut dyn Any

Casts to &mut dyn Any.

fn delete(&mut self, _entity: EntityId, _current: u32)

Deletes an entity from this storage.

fn name(&self) -> Cow<'static, str>

Returns the storage’s name.

fn sparse_array(&self) -> Option<&SparseArray<EntityId, 32>>

Returns a SparseSet’s internal SparseArray.

fn clear_all_removed_or_deleted(&mut self)

Clear all deletion and removal tracking data.

fn clear_all_removed_or_deleted_older_than_timestamp(
    &mut self,
    _timestamp: TrackingTimestamp
)

Clear all deletion and removal tracking data older than some timestamp.