Struct apecs::Components

pub struct Components { /* private fields */ }

The set of all entities’ components.

Exists as a resource in the World by default.

Components is the store that holds every entity’s components. It is an archetypal storage, which means it is optimized for fast traversal and space-saving (in terms of CPU memory).

Use Components when you need to add or remove components from entities eagerly and immediately. For this you will need a mutable reference, which means it will block access to Components by other systems. If you don’t need to see the effects of your changes immediately you can use crate::Entity::insert_bundle, which works lazily (changes appear at the end of each frame), and within an async context crate::Entity::updates will return a future that completes when these changes have resolved.

Here’s an example of a syncronous system that creates and updates an entity immediately:

fn mk_ent(
    (mut entities, mut components): (Write<Entities>, Write<Components>),
) -> anyhow::Result<ShouldContinue> {
    let e = entities.create();
    components.insert_bundle(e.id(), (123, "123", 123.0));
    end()
}
let mut world = World::default();
world.with_system("mk_ent", mk_ent).unwrap();
world.run();

A note about bundles

Component archetypes (the collection of unique components for a set of entities) are made up of bundles. Bundles are tuples that implement IsBundle. Each component element in a bundle must be unique and 'static. IsBundle is implemented by tuples sized 1 to 12.

Implementations

impl Components

pub fn insert_bundle<B: IsBundle>(&mut self, entity_id: usize, bundle: B)

Inserts the bundled components for the given entity.

Panics

• if the bundle’s types are not unique

use apecs::*;

let mut components = Components::default();
components.insert_bundle(0, ("zero", 0u32, 0.0f32));

pub fn get_component<T: Send + Sync + 'static>(
    &self,
    entity_id: usize
) -> Option<impl Deref<Target = T> + '_>

Returns a reference to a single component, if possible.

pub fn get_component_mut<T: Send + Sync + 'static>(
    &mut self,
    entity_id: usize
) -> Option<impl DerefMut<Target = T> + '_>

Returns a mutable reference to a single component, if possible.

pub fn insert_component<T: Send + Sync + 'static>(
    &mut self,
    entity_id: usize,
    component: T
) -> Option<T>

Insert a single component for the given entity.

Returns the previous component, if available.

use apecs::*;

let mut components = Components::default();
components.insert_component(0, "zero");
components.insert_component(0, 0u32);
components.insert_component(0, 0.0f32);
let prev = components.insert_component(0, "none");
assert_eq!(Some("zero"), prev);

pub fn remove<B: IsBundle>(&mut self, entity_id: usize) -> Option<B>

Remove all components of the given entity and return them as a typed bundle.

Warning

Any components not contained in B will be discarded.

Panics

Panics if the component types are not unique.

use apecs::*;

let mut components = Components::default();
components.insert_bundle(0, ("zero", 0u32, 0.0f32));
let prev = components.remove::<(u32, f32)>(0);
assert_eq!(Some((0, 0.0)), prev);

pub fn remove_component<T: Send + Sync + 'static>(
    &mut self,
    entity_id: usize
) -> Option<T>

Remove a single component from the given entity, returning it if the entity had a component of that type.

use apecs::*;

let mut components = Components::default();
components.insert_bundle(0, ("zero", 0u32, 0.0f32));
let prev = components.remove_component::<&str>(0);
assert_eq!(Some("zero"), prev);
let dne = components.remove_component::<bool>(0);
assert_eq!(None, dne);

pub fn len(&self) -> usize

Return the number of entities with archetypes.

pub fn is_empty(&self) -> bool

Return whether any entities with archetypes exist in storage.

impl Components

pub fn extend<B: IsBundle>(
    &mut self,
    extension: <B::MutBundle as IsQuery>::ExtensionColumns
)where
    B::MutBundle: IsQuery,

Append to the existing set of archetypes in bulk.

This assumes the entries being inserted have unique ids and don’t already exist in the set.

use apecs::*;
let mut components = Components::default();
let a = Box::new((0..10_000).map(|id| Entry::new(id, id as u32)));
let b = Box::new((0..10_000).map(|id| Entry::new(id, id as f32)));
let c = Box::new((0..10_000).map(|id| Entry::new(id, format!("string{}", id))));
let d = Box::new((0..10_000).map(|id| Entry::new(id, id % 2 == 0)));
components.extend::<(u32, f32, String, bool)>((a, b, c, d));
assert_eq!(10_000, components.len());

pub fn query<Q: IsQuery + 'static>(&mut self) -> QueryGuard<'_, Q>

Prepare a query.

use apecs::*;

let mut components = Components::default();
components.insert_bundle(0, ("zero", 0.0f32, 0u32));
components.insert_bundle(1, ("zero", 0.0f32, 0u32));
components.insert_bundle(2, ("zero", 0.0f32, 0u32));

for (f, u) in components.query::<(&f32, &u32)>().iter_mut() {
    assert_eq!(**f, **u as f32);
}

Trait Implementations

impl Debug for Components

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Components

fn default() -> Self

Returns the “default value” for a type.