Struct World 

pub struct World<S> { /* private fields */ }

A container for managing entities and their components.

Examples

use checs::{ComponentVec, IntoQuery, LendingIterator, Storage, World};

#[derive(Default, Storage)]
struct Storage {
    strs: ComponentVec<&'static str>,
    ints: ComponentVec<i32>,
}

let mut world = World::<Storage>::new();

let e0 = world.spawn_with(("ninety-nine", 99));
let e1 = world.spawn_with(("zero",));
let e2 = world.spawn_with(("forty-two", 42));
let e3 = world.spawn_with((1,));
let e4 = world.spawn_with(("seventeen", 17));

let storage = world.storage_mut();
let mut query = (&storage.strs, &mut storage.ints).into_query();

assert_eq!(query.next(), Some((e0, (&"ninety-nine", &mut 99))));
assert_eq!(query.next(), Some((e2, (&"forty-two", &mut 42))));
assert_eq!(query.next(), Some((e4, (&"seventeen", &mut 17))));
assert_eq!(query.next(), None);

Implementations

impl<S> World<S>

pub fn new() -> Self

where S: Default,

Constructs a new World.

Examples found in repository

examples/basic.rs (line 23)

fn main() {
    let mut world = world::World::<Storage>::new();

    // Create entities with initial components.
    // Either manually...
    let player = world.spawn();
    world.insert(player, Position { x: 0, y: 0 });
    world.insert(player, Visible);
    world.insert(player, Health(80));

    // ...or by using the `spawn` macro...
    let _obstacle = checs::spawn!(world, Position { x: 1, y: 1 }, Visible);
    let _trap = checs::spawn!(world, Position { x: 2, y: 1 });

    // ...or by using `spawn_with`.
    let _enemy = world.spawn_with((Position { x: 1, y: 4 }, Visible, Health(100)));

    let storage = world.storage_mut();

    // Create a query over all entities that have `Position`, `Health`, and
    // `Visible` components.
    let query = (&storage.positions, &mut storage.healths, &storage.visibles).into_query();

    query.for_each(|(_, (_, h, _))| {
        h.0 += 10;
    });

    println!();

    let query = (&storage.positions, &storage.healths, &storage.visibles).into_query();

    query.for_each(|(e, (p, h, v))| {
        println!("{e:?} is {v:?} at ({}, {}) with {} HP", p.x, p.y, h.0);
    });
}

pub fn storage(&self) -> &S

Returns a reference to the component storage.

pub fn storage_mut(&mut self) -> &mut S

Returns a mutable reference to the component storage.

Examples found in repository

examples/basic.rs (line 39)

fn main() {
    let mut world = world::World::<Storage>::new();

    // Create entities with initial components.
    // Either manually...
    let player = world.spawn();
    world.insert(player, Position { x: 0, y: 0 });
    world.insert(player, Visible);
    world.insert(player, Health(80));

    // ...or by using the `spawn` macro...
    let _obstacle = checs::spawn!(world, Position { x: 1, y: 1 }, Visible);
    let _trap = checs::spawn!(world, Position { x: 2, y: 1 });

    // ...or by using `spawn_with`.
    let _enemy = world.spawn_with((Position { x: 1, y: 4 }, Visible, Health(100)));

    let storage = world.storage_mut();

    // Create a query over all entities that have `Position`, `Health`, and
    // `Visible` components.
    let query = (&storage.positions, &mut storage.healths, &storage.visibles).into_query();

    query.for_each(|(_, (_, h, _))| {
        h.0 += 10;
    });

    println!();

    let query = (&storage.positions, &storage.healths, &storage.visibles).into_query();

    query.for_each(|(e, (p, h, v))| {
        println!("{e:?} is {v:?} at ({}, {}) with {} HP", p.x, p.y, h.0);
    });
}

pub fn spawn(&mut self) -> Entity

Creates a new entity.

Examples found in repository

examples/basic.rs (line 27)

fn main() {
    let mut world = world::World::<Storage>::new();

    // Create entities with initial components.
    // Either manually...
    let player = world.spawn();
    world.insert(player, Position { x: 0, y: 0 });
    world.insert(player, Visible);
    world.insert(player, Health(80));

    // ...or by using the `spawn` macro...
    let _obstacle = checs::spawn!(world, Position { x: 1, y: 1 }, Visible);
    let _trap = checs::spawn!(world, Position { x: 2, y: 1 });

    // ...or by using `spawn_with`.
    let _enemy = world.spawn_with((Position { x: 1, y: 4 }, Visible, Health(100)));

    let storage = world.storage_mut();

    // Create a query over all entities that have `Position`, `Health`, and
    // `Visible` components.
    let query = (&storage.positions, &mut storage.healths, &storage.visibles).into_query();

    query.for_each(|(_, (_, h, _))| {
        h.0 += 10;
    });

    println!();

    let query = (&storage.positions, &storage.healths, &storage.visibles).into_query();

    query.for_each(|(e, (p, h, v))| {
        println!("{e:?} is {v:?} at ({}, {}) with {} HP", p.x, p.y, h.0);
    });
}

pub fn spawn_with<T>(&mut self, value: T) -> Entity

where Self: InsertMany<T>,

Creates a new entity with initial components.

Examples found in repository

examples/basic.rs (line 37)

fn main() {
    let mut world = world::World::<Storage>::new();

    // Create entities with initial components.
    // Either manually...
    let player = world.spawn();
    world.insert(player, Position { x: 0, y: 0 });
    world.insert(player, Visible);
    world.insert(player, Health(80));

    // ...or by using the `spawn` macro...
    let _obstacle = checs::spawn!(world, Position { x: 1, y: 1 }, Visible);
    let _trap = checs::spawn!(world, Position { x: 2, y: 1 });

    // ...or by using `spawn_with`.
    let _enemy = world.spawn_with((Position { x: 1, y: 4 }, Visible, Health(100)));

    let storage = world.storage_mut();

    // Create a query over all entities that have `Position`, `Health`, and
    // `Visible` components.
    let query = (&storage.positions, &mut storage.healths, &storage.visibles).into_query();

    query.for_each(|(_, (_, h, _))| {
        h.0 += 10;
    });

    println!();

    let query = (&storage.positions, &storage.healths, &storage.visibles).into_query();

    query.for_each(|(e, (p, h, v))| {
        println!("{e:?} is {v:?} at ({}, {}) with {} HP", p.x, p.y, h.0);
    });
}

pub fn despawn(&mut self, entity: Entity) -> Result<(), Error>

where S: RemoveAll,

Removes an entity and its components.

Errors

The method internally calls entity::Allocator::free, so it might return any of its errors.

pub fn despawn_all<T>(&mut self) -> Result<(), Error>

where S: RemoveAll + AsRef<ComponentVec<T>>,

Removes all entities that have the specified component T.

Also removes all of their other components.

Errors

The method internally calls entity::Allocator::free, so it might return any of its errors.

pub fn despawn_entities<'a, I>(&'a mut self, entities: I) -> Result<(), Error>

where S: RemoveAll, I: IntoIterator<Item = &'a Entity>,

Removes all entities in the iterator from the world.

Also removes all of their components.

Errors

The method internally calls entity::Allocator::free, so it might return any of its errors.

pub fn get<T>(&self, entity: Entity) -> Option<&T>

where S: AsRef<ComponentVec<T>>,

Returns a reference to the entity’s component, or None if the entity does not have that component.

pub fn get_mut<T>(&mut self, entity: Entity) -> Option<&mut T>

where S: AsMut<ComponentVec<T>>,

Returns a mutable reference to an entity’s component, or None if the entity does not have that component.

pub fn insert<T>(&mut self, entity: Entity, value: T) -> Option<T>

where S: AsMut<ComponentVec<T>>,

Adds a component to the entity.

If the entity already had that component its value is updated and the old value is returned.

Examples found in repository

examples/basic.rs (line 28)

fn main() {
    let mut world = world::World::<Storage>::new();

    // Create entities with initial components.
    // Either manually...
    let player = world.spawn();
    world.insert(player, Position { x: 0, y: 0 });
    world.insert(player, Visible);
    world.insert(player, Health(80));

    // ...or by using the `spawn` macro...
    let _obstacle = checs::spawn!(world, Position { x: 1, y: 1 }, Visible);
    let _trap = checs::spawn!(world, Position { x: 2, y: 1 });

    // ...or by using `spawn_with`.
    let _enemy = world.spawn_with((Position { x: 1, y: 4 }, Visible, Health(100)));

    let storage = world.storage_mut();

    // Create a query over all entities that have `Position`, `Health`, and
    // `Visible` components.
    let query = (&storage.positions, &mut storage.healths, &storage.visibles).into_query();

    query.for_each(|(_, (_, h, _))| {
        h.0 += 10;
    });

    println!();

    let query = (&storage.positions, &storage.healths, &storage.visibles).into_query();

    query.for_each(|(e, (p, h, v))| {
        println!("{e:?} is {v:?} at ({}, {}) with {} HP", p.x, p.y, h.0);
    });
}

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

where S: AsMut<ComponentVec<T>>,

Removes a component from the entity and returns the component.

Trait Implementations

impl<S> Default for World<S>

where S: Default,

fn default() -> World<S>

Returns the “default value” for a type.

impl<S> InsertMany<()> for World<S>

type Output = ()

The type of the (possibly) updated components.

fn insert_many(&mut self, _entity: Entity, _value: ()) -> Self::Output

Adds components to the entity.

impl<S, A, B, C, D, E, F, G> InsertMany<(A, B, C, D, E, F, G)> for World<S>

where S: AsMut<ComponentVec<A>> + AsMut<ComponentVec<B>> + AsMut<ComponentVec<C>> + AsMut<ComponentVec<D>> + AsMut<ComponentVec<E>> + AsMut<ComponentVec<F>> + AsMut<ComponentVec<G>>,

type Output = (Option<A>, Option<B>, Option<C>, Option<D>, Option<E>, Option<F>, Option<G>)

The type of the (possibly) updated components.

fn insert_many( &mut self, entity: Entity, value: (A, B, C, D, E, F, G), ) -> Self::Output

Adds components to the entity.

impl<S, B, C, D, E, F, G> InsertMany<(B, C, D, E, F, G)> for World<S>

where S: AsMut<ComponentVec<B>> + AsMut<ComponentVec<C>> + AsMut<ComponentVec<D>> + AsMut<ComponentVec<E>> + AsMut<ComponentVec<F>> + AsMut<ComponentVec<G>>,

type Output = (Option<B>, Option<C>, Option<D>, Option<E>, Option<F>, Option<G>)

The type of the (possibly) updated components.

fn insert_many( &mut self, entity: Entity, value: (B, C, D, E, F, G), ) -> Self::Output

Adds components to the entity.

impl<S, C, D, E, F, G> InsertMany<(C, D, E, F, G)> for World<S>

where S: AsMut<ComponentVec<C>> + AsMut<ComponentVec<D>> + AsMut<ComponentVec<E>> + AsMut<ComponentVec<F>> + AsMut<ComponentVec<G>>,

type Output = (Option<C>, Option<D>, Option<E>, Option<F>, Option<G>)

The type of the (possibly) updated components.

fn insert_many( &mut self, entity: Entity, value: (C, D, E, F, G), ) -> Self::Output

Adds components to the entity.

impl<S, D, E, F, G> InsertMany<(D, E, F, G)> for World<S>

where S: AsMut<ComponentVec<D>> + AsMut<ComponentVec<E>> + AsMut<ComponentVec<F>> + AsMut<ComponentVec<G>>,

type Output = (Option<D>, Option<E>, Option<F>, Option<G>)

The type of the (possibly) updated components.

fn insert_many(&mut self, entity: Entity, value: (D, E, F, G)) -> Self::Output

Adds components to the entity.

impl<S, E, F, G> InsertMany<(E, F, G)> for World<S>

where S: AsMut<ComponentVec<E>> + AsMut<ComponentVec<F>> + AsMut<ComponentVec<G>>,

type Output = (Option<E>, Option<F>, Option<G>)

The type of the (possibly) updated components.

fn insert_many(&mut self, entity: Entity, value: (E, F, G)) -> Self::Output

Adds components to the entity.

impl<S, F, G> InsertMany<(F, G)> for World<S>

where S: AsMut<ComponentVec<F>> + AsMut<ComponentVec<G>>,

type Output = (Option<F>, Option<G>)

The type of the (possibly) updated components.

fn insert_many(&mut self, entity: Entity, value: (F, G)) -> Self::Output

Adds components to the entity.

impl<S, G> InsertMany<(G,)> for World<S>

where S: AsMut<ComponentVec<G>>,

type Output = (Option<G>,)

The type of the (possibly) updated components.

fn insert_many(&mut self, entity: Entity, value: (G,)) -> Self::Output

Adds components to the entity.