brood 0.9.1

A fast and flexible entity component system library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

//! A heterogeneous list of [`Component`]s stored within a [`World`].
//!
//! [`Entity`]s are most often defined using the [`entity!`] macro. The items contained within this
//! module should rarely be needed in user code, apart from [`Identifier`].
//!
//! `Entity`s are stored within [`World`]s to allow efficient querying and iteration with other
//! entities of similar components. Since entities are defined as heterogeneous lists, they can be
//! made of an arbitrary number of components. `World`s can store entities made up of any
//! combination of components, so long as those components are stored in the `World`'s
//! [`Registry`].
//!
//! # Example
//! ``` rust
//! use brood::{
//!     entity,
//!     Registry,
//!     World,
//! };
//!
//! // Define components.
//! struct Foo(usize);
//! struct Bar(bool);
//!
//! type Registry = Registry!(Foo, Bar);
//!
//! let mut world = World::<Registry>::new();
//!
//! // Store an entity containing both `Foo` and `Bar`.
//! world.insert(entity!(Foo(42), Bar(false)));
//!
//! // Store an entity containing only `Bar`.
//! world.insert(entity!(Bar(true)));
//!
//! // Store an entity containing zero components.
//! world.insert(entity!());
//! ```
//!
//! [`Component`]: crate::component::Component
//! [`Entity`]: crate::entity::Entity
//! [`entity!`]: crate::entity!
//! [`Identifier`]: crate::entity::Identifier
//! [`Registry`]: crate::registry::Registry
//! [`World`]: crate::world::World

pub(crate) mod allocator;

mod identifier;
mod sealed;

pub use identifier::Identifier;

pub(crate) use allocator::Allocator;

use crate::{
    component,
    hlist::define_null,
};
use sealed::Sealed;

define_null!();

/// A heterogeneous list of [`Component`]s.
///
/// Entities are stored within [`World`]s. In order for an entity to be able to be stored within a
/// `World`, that `World`'s [`Registry`] must include the `Component`s that make up an entity.
///
/// Note that entities must consist of unique component types. Duplicate components are not
/// supported. When multiple components of the same type are included in an entity, a `World` will
/// only store one of those components.
///
/// # Example
/// ``` rust
/// use brood::entity;
///
/// // Define components.
/// struct Foo(usize);
/// struct Bar(bool);
///
/// let entity = entity!(Foo(42), Bar(true));
/// ```
///
/// [`Component`]: crate::component::Component
/// [`Registry`]: crate::registry::Registry
/// [`World`]: crate::world::World
pub trait Entity: Sealed + 'static {}

impl Entity for Null {}

impl<Component, Entity> self::Entity for (Component, Entity)
where
    Component: component::Component,
    Entity: self::Entity,
{
}

/// Creates an entity from the provided components.
///
/// This macro allows an enity to be defined without needing to manually create a heterogeneous
/// list of components. Given an arbitrary number of components, this macro will arrange them into
/// nested tuples forming a heterogeneous list.
///
/// # Example
/// ``` rust
/// use brood::entity;
///
/// // Define components `Foo` and `Bar`.
/// struct Foo(u16);
/// struct Bar(f32);
///
/// // Define an entity containing an instance of `Foo` and `Bar`.
/// let my_entity = entity!(Foo(42), Bar(1.5));
/// ```
#[macro_export]
macro_rules! entity {
    ($component:expr $(,$components:expr)* $(,)?) => {
        ($component, $crate::entity!($($components,)*))
    };
    () => {
        $crate::entity::Null
    };
}

/// Defines the type of an entity containing the provided components.
///
/// # Example
/// ``` rust
/// use brood::Entity;
///
/// // Define components `Foo` and `Bar`.
/// struct Foo(u16);
/// struct Bar(f32);
///
/// // Define the type for an entity containing the components `Foo` and `Bar`.
/// type Entity = Entity!(Foo, Bar);
/// ```
#[macro_export]
macro_rules! Entity {
    ($component:ty $(,$components:ty)* $(,)?) => {
        ($component, $crate::Entity!($($components,)*))
    };
    () => {
        $crate::entity::Null
    };
}

#[cfg(test)]
mod tests {
    use super::*;

    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    struct A(u64);

    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    struct B(char);

    #[test]
    fn entity() {
        assert_eq!(entity!(B('f'), A(42)), (B('f'), (A(42), Null)));
    }
}