Struct brood::World

pub struct World<R>where
    R: Registry,{ /* private fields */ }

A container of entities.

A World can contain entities made of any combination of components contained in the Registry R. These entities are not stored in any defined order, and thier internal location is subject to change. Therefore, entities stored inside a World are uniquely identified using an entity::Identifier.

use brood::{
    entity,
    registry,
    World,
};

// Define components.
struct Foo(u32);
struct Bar(bool);

// Create a world.
let mut world = World::<registry!(Foo, Bar)>::new();

// Insert a new entity. The returned identifier uniquely identifies the entity.
let entity_identifier = world.insert(entity!(Foo(42), Bar(true)));

Note that a World can only contain entities made of components defined in the World’s registry. Attempting to insert entities containing components not in the registry will result in a panic.

Components of entities can be queried using the query() method. Systems can also be run over components of entities using the various run methods.

Implementations

impl<R> World<R>where
    R: Registry,

pub fn new() -> Self

Creates an empty World.

Often, calls to new() are accompanied with a Registry to tell the compiler what components the World can contain.

Example

use brood::{
    registry,
    World,
};

struct Foo(u32);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

let world = World::<Registry>::new();

pub fn insert<E, I, P, Q>(&mut self, entity: E) -> Identifierwhere
    E: Entity,
    R: ContainsEntity<E, P, Q, I>,

Insert an entity, returning an entity::Identifier.

Example

use brood::{
    entity,
    registry,
    World,
};

struct Foo(u32);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

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

let entity_identifier = world.insert(entity!(Foo(42), Bar(false)));

pub fn extend<E, I, P, Q>(&mut self, entities: Batch<E>) -> Vec<Identifier>where
    E: Entities,
    R: ContainsEntities<E, P, Q, I>,

Insert multiple entities made from the same components, returning a Vec of entity::Identifiers.

Example

use brood::{
    entities,
    registry,
    World,
};

struct Foo(u32);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

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

let entity_identiifers = world.extend(entities![(Foo(1), Bar(false)), (Foo(2), Bar(true))]);

pub fn query<'a, V, F, VI, FI, P, I, Q>(
    &'a mut self,
    query: Query<V, F>
) -> Iter<'a, R, F, FI, V, VI, P, I, Q>where
    V: Views<'a> + Filter,
    F: Filter,
    R: ContainsQuery<'a, F, FI, V, VI, P, I, Q>,

Query for components contained within the World using the given Views V and Filter F, returning an Iterator over all components of entities matching the query.

Note that the order of the entities returned by a query is not specified.

Example

use brood::{
    entity,
    query::{
        filter,
        result,
        views,
    },
    registry,
    Query,
    World,
};

struct Foo(u32);
struct Bar(bool);
struct Baz(u32);

type Registry = registry!(Foo, Bar, Baz);

let mut world = World::<Registry>::new();
let inserted_entity_identifier = world.insert(entity!(Foo(42), Bar(true), Baz(100)));

// Note that the views provide implicit filters.
for result!(foo, baz, entity_identifier) in world.query(Query::<
    views!(&mut Foo, &Baz, entity::Identifier),
    filter::Has<Bar>,
>::new())
{
    // Allows immutable or mutable access to queried components.
    foo.0 = baz.0;
    // Also allows access to entity identifiers.
    assert_eq!(entity_identifier, inserted_entity_identifier);
}

For more information about Views and Filter, see the query module documentaion.

pub fn par_query<'a, V, F, VI, FI, P, I, Q>(
    &'a mut self,
    query: Query<V, F>
) -> ParIter<'a, R, F, FI, V, VI, P, I, Q>where
    V: ParViews<'a> + Filter,
    F: Filter,
    R: ContainsParQuery<'a, F, FI, V, VI, P, I, Q>,

Available on crate feature rayon only.

Query for components contained within the World using the given ParViews V and Filter F, returning a ParallelIterator over all components of entities matching the query.

The difference between this method and query() is that this method allow results to be operated on in parallel rather than sequentially.

Example

use brood::{
    entity,
    query::{
        filter,
        result,
        views,
    },
    registry,
    Query,
    World,
};
use rayon::iter::ParallelIterator;

struct Foo(u32);
struct Bar(bool);
struct Baz(u32);

type Registry = registry!(Foo, Bar, Baz);

let mut world = World::<Registry>::new();
let inserted_entity_identifier = world.insert(entity!(Foo(42), Bar(true), Baz(100)));

// Note that the views provide implicit filters.
world
    .par_query(Query::<
        views!(&mut Foo, &Baz, entity::Identifier),
        filter::Has<Bar>,
    >::new())
    .for_each(|result!(foo, baz, entity_identifier)| {
        // Allows immutable or mutable access to queried components.
        foo.0 = baz.0;
        // Also allows access to entity identifiers.
        assert_eq!(entity_identifier, inserted_entity_identifier);
    });

For more information about ParViews and Filter, see the query module documentaion.

pub fn run_system<'a, S, FI, VI, P, I, Q>(&'a mut self, system: &mut S)where
    S: System<'a>,
    R: ContainsQuery<'a, S::Filter, FI, S::Views, VI, P, I, Q>,

Run a System over the entities in this World.

Example

use brood::{
    entity,
    query::{
        filter,
        filter::Filter,
        result,
        views,
    },
    registry,
    registry::ContainsQuery,
    system::System,
    World,
};

// Define components.
struct Foo(usize);
struct Bar(usize);

type MyRegistry = registry!(Foo, Bar);

// Define system.
struct MySystem;

impl<'a> System<'a> for MySystem {
    type Views = views!(&'a mut Foo, &'a Bar);
    type Filter = filter::None;

    fn run<R, FI, VI, P, I, Q>(
        &mut self,
        query_results: result::Iter<'a, R, Self::Filter, FI, Self::Views, VI, P, I, Q>,
    ) where
        R: ContainsQuery<'a, Self::Filter, FI, Self::Views, VI, P, I, Q> + 'a,
    {
        for result!(foo, bar) in query_results {
            // Increment `Foo` by `Bar`.
            foo.0 += bar.0;
        }
    }
}

let mut world = World::<MyRegistry>::new();
world.insert(entity!(Foo(42), Bar(100)));

world.run_system(&mut MySystem);

pub fn run_par_system<'a, S, FI, VI, P, I, Q>(&'a mut self, par_system: &mut S)where
    S: ParSystem<'a>,
    R: ContainsParQuery<'a, S::Filter, FI, S::Views, VI, P, I, Q>,

Available on crate feature rayon only.

Run a ParSystem over the entities in this World.

Example

use brood::{
    entity,
    query::{
        filter,
        filter::Filter,
        result,
        views,
    },
    registry,
    registry::ContainsParQuery,
    system::ParSystem,
    World,
};
use rayon::iter::ParallelIterator;

// Define components.
struct Foo(usize);
struct Bar(usize);

type MyRegistry = registry!(Foo, Bar);

// Define system.
struct MySystem;

impl<'a> ParSystem<'a> for MySystem {
    type Views = views!(&'a mut Foo, &'a Bar);
    type Filter = filter::None;

    fn run<R, FI, VI, P, I, Q>(
        &mut self,
        query_results: result::ParIter<'a, R, Self::Filter, FI, Self::Views, VI, P, I, Q>,
    ) where
        R: ContainsParQuery<'a, Self::Filter, FI, Self::Views, VI, P, I, Q> + 'a,
    {
        query_results.for_each(|result!(foo, bar)| foo.0 += bar.0);
    }
}

let mut world = World::<MyRegistry>::new();
world.insert(entity!(Foo(42), Bar(100)));

world.run_par_system(&mut MySystem);

pub fn run_schedule<'a, S, SFI, SVI, PFI, PVI, SP, SI, SQ, PP, PI, PQ>(
    &'a mut self,
    schedule: &mut Schedule<S>
)where
    S: Stages<'a, R, SFI, SVI, PFI, PVI, SP, SI, SQ, PP, PI, PQ>,

Available on crate feature rayon only.

Run a Schedule over the entities in this World.

Example

use brood::{
    entity,
    query::{
        filter,
        filter::Filter,
        result,
        views,
    },
    registry,
    registry::ContainsQuery,
    system::{
        Schedule,
        System,
    },
    World,
};

// Define components.
struct Foo(usize);
struct Bar(usize);

type MyRegistry = registry!(Foo, Bar);

// Define systems.
struct SystemA;
struct SystemB;

impl<'a> System<'a> for SystemA {
    type Views = views!(&'a mut Foo);
    type Filter = filter::None;

    fn run<R, FI, VI, P, I, Q>(
        &mut self,
        query_results: result::Iter<'a, R, Self::Filter, FI, Self::Views, VI, P, I, Q>,
    ) where
        R: ContainsQuery<'a, Self::Filter, FI, Self::Views, VI, P, I, Q> + 'a,
    {
        for result!(foo) in query_results {
            foo.0 += 1;
        }
    }
}

impl<'a> System<'a> for SystemB {
    type Views = views!(&'a mut Bar);
    type Filter = filter::None;

    fn run<R, FI, VI, P, I, Q>(
        &mut self,
        query_results: result::Iter<'a, R, Self::Filter, FI, Self::Views, VI, P, I, Q>,
    ) where
        R: ContainsQuery<'a, Self::Filter, FI, Self::Views, VI, P, I, Q> + 'a,
    {
        for result!(bar) in query_results {
            bar.0 += 1;
        }
    }
}

// Define schedule.
let mut schedule = Schedule::builder().system(SystemA).system(SystemB).build();

let mut world = World::<MyRegistry>::new();
world.insert(entity!(Foo(42), Bar(100)));

world.run_schedule(&mut schedule);

pub fn contains(&self, entity_identifier: Identifier) -> bool

Returns true if the world contains an entity identified by entity_identifier.

Example

use brood::{
    entity,
    registry,
    World,
};

struct Foo(usize);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

let mut world = World::<Registry>::new();
let entity_identifier = world.insert(entity!(Foo(42), Bar(true)));

assert!(world.contains(entity_identifier));
world.remove(entity_identifier);
assert!(!world.contains(entity_identifier));

pub fn entry(&mut self, entity_identifier: Identifier) -> Option<Entry<'_, R>>

Gets an Entry for the entity associated with an entity::Identifier for component-level manipulation.

If no such entity exists, None is returned.

Example

use brood::{
    entity,
    registry,
    World,
};

struct Foo(u32);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

let mut world = World::<Registry>::new();
let entity_identifier = world.insert(entity!(Foo(42), Bar(true)));

let mut entry = world.entry(entity_identifier).unwrap();
// Remove the `Bar` component.
entry.remove::<Bar, _>();

pub fn remove(&mut self, entity_identifier: Identifier)

Remove the entity associated with an entity::Identifier.

If the entity has already been removed, this method will do nothing.

Example

use brood::{
    entity,
    registry,
    World,
};

struct Foo(u32);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

let mut world = World::<Registry>::new();
let entity_identifier = world.insert(entity!(Foo(42), Bar(true)));

world.remove(entity_identifier);

pub fn clear(&mut self)

Removes all entities.

Keeps the allocated memory for reuse.

Example

use brood::{
    entity,
    registry,
    World,
};

struct Foo(usize);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

let mut world = World::<Registry>::new();
world.insert(entity!(Foo(42), Bar(true)));

world.clear();

pub fn len(&self) -> usize

Returns the number of entities in the world.

Example

use brood::{entities, registry, World};

#[derive(Clone)]
struct Foo(usize);
#[derive(Clone)]
struct Bar(bool);

type Registry = registry!(Foo, Bar);

let mut world = World::<Registry>::new();
world.extend(entities!((Foo(42), Bar(false)); 100));

assert_eq!(world.len(), 100);

pub fn is_empty(&self) -> bool

Returns true if the world contains no entities.

Example

use brood::{
    entity,
    registry,
    World,
};

struct Foo(usize);
struct Bar(bool);

type Registry = registry!(Foo, Bar);

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

assert!(world.is_empty());

world.insert(entity!(Foo(42), Bar(false)));

assert!(!world.is_empty());

pub fn shrink_to_fit(&mut self)

Shrinks the allocated capacity of the internal storage as much as possible.

Example

use brood::{entities, registry, World};

#[derive(Clone)]
struct Foo(usize);
#[derive(Clone)]
struct Bar(bool);

type Registry = registry!(Foo, Bar);

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

world.extend(entities!((Foo(42), Bar(false)); 10));
world.clear();
world.extend(entities!((Foo(42), Bar(false)); 3));

// This will reduce the current allocation.
world.shrink_to_fit();

Trait Implementations

impl<R> Debug for World<R>where
    R: RegistryDebug,

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

Formats the value using the given formatter.

impl<R> Default for World<R>where
    R: Registry,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, R> Deserialize<'de> for World<R>where
    R: RegistryDeserialize<'de>,

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
    D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<R> PartialEq<World<R>> for World<R>where
    R: RegistryPartialEq,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<R> Serialize for World<R>where
    R: RegistrySerialize,

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>where
    S: Serializer,

Serialize this value into the given Serde serializer.

impl<R> Eq for World<R>where
    R: RegistryEq,

impl<R> Send for World<R>where
    R: RegistrySend,

impl<R> Sync for World<R>where
    R: RegistrySync,