dynec 0.2.1

An opinionated ECS-like framework
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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208

//! A storage is the data structure where components of the same type for all entities are stored.

use crate::entity;

mod vec;
pub use vec::VecStorage as Vec;

mod tree;
pub use tree::Tree;

pub(crate) mod simple;
pub(crate) use simple::Simple;
mod isotope;
pub(crate) use isotope::{AnyMap as AnyIsotopeMap, Map as IsotopeMap, MapInner as IsotopeMapInner};

#[cfg(test)]
mod tests;

/// A storage for storing component data.
pub trait Storage: Access + Default + Send + Sync + 'static {
    /// Gets a shared reference to the component for a specific entity if it is present.
    fn get(&self, id: Self::RawEntity) -> Option<&Self::Comp>;

    /// Sets or removes the component for a specific entity,
    /// returning the original value if it was present.
    fn set(&mut self, id: Self::RawEntity, value: Option<Self::Comp>) -> Option<Self::Comp>;

    /// Returns the number of components that exist in this storage.
    fn cardinality(&self) -> usize;

    /// Return value of [`iter`](Self::iter).
    type Iter<'t>: Iterator<Item = (Self::RawEntity, &'t Self::Comp)> + 't;
    /// Returns an immutable iterator over the storage, ordered by entity index order.
    fn iter(&self) -> Self::Iter<'_>;

    /// Return value of [`iter_chunks`](Self::iter_chunks).
    type IterChunks<'t>: Iterator<Item = ChunkRef<'t, Self>> + 't;
    /// Returns an immutable iterator of slices over the storage, ordered by entity index order.
    ///
    /// Each item yielded by the iterator is a tuple of `(index, slice)`,
    /// where `slice` is the slice of components in the chunk,
    /// and `index` is the entity index of `slice[0]`.
    /// `slice` is always nonempty.
    ///
    /// Non-chunked storages should implement this function by returning a chunk for each entity.
    fn iter_chunks(&self) -> Self::IterChunks<'_>;

    /// Return value of [`iter_chunks_mut`](Self::iter_chunks_mut).
    type IterChunksMut<'t>: Iterator<Item = ChunkMut<'t, Self>> + 't;
    /// Returns a mutable iterator of slices over the storage, ordered by entity index order.
    ///
    /// Each item yielded by the iterator is a tuple of `(index, slice)`,
    /// where `slice` is the slice of components in the chunk,
    /// and `index` is the entity index of `slice[0]`.
    /// `slice` is always nonempty.
    ///
    /// Non-chunked storages should implement this function by returning a chunk for each entity.
    fn iter_chunks_mut(&mut self) -> Self::IterChunksMut<'_>;

    /// Return value of [`as_partition`](Self::as_partition).
    type Partition<'u>: Partition<'u, RawEntity = Self::RawEntity, Comp = Self::Comp>
    where
        Self: 'u;
    /// Converts the storage to a [`Partition`] that covers the whole storage (similar to `slice[..]`).
    fn as_partition(&mut self) -> Self::Partition<'_>;
}

/// Borrows a slice of a storage, analogously `&'t mut Storage[..]`.
///
/// This trait does not provide `set` because
/// adding/removing items may cause rebalances in the tree implementation
/// and result in dangling references in other partitions that are not `&mut`-locked.
pub trait Partition<'t>: Access + Send + Sync + Sized + 't {
    /// Return value of [`by_ref`](Self::by_ref).
    type ByRef<'u>: Partition<'u, RawEntity = Self::RawEntity, Comp = Self::Comp>
    where
        Self: 'u;
    /// Re-borrows the partition with reduced lifetime.
    ///
    /// This is useful for calling [`into_iter_mut`](Self::into_iter_mut)
    /// and [`split_at`](Self::split_at),
    /// which take `self` as receiver to preserve the lifetime.
    fn by_ref(&mut self) -> Self::ByRef<'_>;

    /// Splits the partition further into two subpartitions.
    /// `entity` must be `> 0` and `< partition_length`,
    /// i.e. the expected key ranges of both partitions must be nonempty.
    /// (It is allowed to have a nonempty range which does not contain any existing keys)
    fn split_at(mut self, entity: Self::RawEntity) -> (Self, Self) {
        let right = self.split_out(entity);
        (self, right)
    }

    /// Splits the partition further into two subpartitions,
    /// replacing `self` with the left partition.
    ///
    /// `entity` must be `> 0` and `< partition_length`,
    /// i.e. the expected key ranges of both partitions must be nonempty.
    /// (It is allowed to have a nonempty range which does not contain any existing keys)
    fn split_out(&mut self, entity: Self::RawEntity) -> Self;

    /// Return value of [`into_iter_mut`](Self::into_iter_mut).
    type IntoIterMut: Iterator<Item = (Self::RawEntity, &'t mut Self::Comp)>;
    /// Same as [`iter_mut`](Access::iter_mut), but moves the partition object into the iterator.
    fn into_iter_mut(self) -> Self::IntoIterMut;

    /// Same as [`get_mut`](Access::get_mut), but returns a reference with lifetime `'t`.
    fn into_mut(self, entity: Self::RawEntity) -> Option<&'t mut Self::Comp>;

    /// Same as [`get_many_mut`](Access::get_many_mut), but returns a reference with lifetime `'t`.
    fn into_many_mut<const N: usize>(
        self,
        entities: [Self::RawEntity; N],
    ) -> Option<[&'t mut Self::Comp; N]>;
}

/// Mutable access functions for a storage, generalizing [`Storage`] and [`Partition`].
pub trait Access {
    /// The type of entity ID used for identification.
    type RawEntity: entity::Raw;
    /// The component type stored.
    type Comp: Send + Sync + 'static;

    /// Gets a mutable reference to the component for a specific entity if it is present.
    fn get_mut(&mut self, entity: Self::RawEntity) -> Option<&mut Self::Comp>;

    /// Gets mutable references to the components for specific entities if they are present.
    ///
    /// Returns `None` if any entity is uninitialized
    /// or if any entity appeared in `entities` more than once.
    fn get_many_mut<const N: usize>(
        &mut self,
        entities: [Self::RawEntity; N],
    ) -> Option<[&mut Self::Comp; N]>;

    /// Return value of [`iter_mut`](Self::iter_mut).
    type IterMut<'u>: Iterator<Item = (Self::RawEntity, &'u mut Self::Comp)> + 'u
    where
        Self: 'u;
    /// Returns a mutable iterator over the storage, ordered by entity index order.
    fn iter_mut(&mut self) -> Self::IterMut<'_>;
}

/// Provides chunked access capabilities,
/// i.e. the storage can always return a slice for contiguous present components.
pub trait Chunked: Storage + AccessChunked {
    /// Gets a shared reference to a slice of components.
    ///
    /// Returns `None` if any of the components in the range is missing.
    ///
    /// Panics if `start > end`.
    fn get_chunk(&self, start: Self::RawEntity, end: Self::RawEntity) -> Option<&[Self::Comp]>;

    /// Return value of [`as_partition_chunk`](Self::as_partition_chunk).
    type PartitionChunked<'u>: PartitionChunked<'u, RawEntity = Self::RawEntity, Comp = Self::Comp>;
    /// Converts the storage to a [`PartitionChunked`] that covers the whole storage (similar to `slice[..]`).
    fn as_partition_chunk(&mut self) -> Self::PartitionChunked<'_>;
}

/// Mutable chunk access functions for a storage, generalizing [`Chunked`] and [`PartitionChunked`].
pub trait AccessChunked: Access {
    /// Gets a mutable reference to a slice of components.
    ///
    /// Returns `None` if any of the components in the range is missing.
    ///
    /// Panics if `start > end`.
    fn get_chunk_mut(
        &mut self,
        start: Self::RawEntity,
        end: Self::RawEntity,
    ) -> Option<&mut [Self::Comp]>;
}

/// Borrows a slice of a chunked storage, analogously `&'t mut Chunked[..]`.
///
/// This trait does not provide `set` because
/// adding/removing items may cause rebalances in the tree implementation
/// and result in dangling references in other partitions that are not `&mut`-locked.
pub trait PartitionChunked<'t>: Partition<'t> + AccessChunked {
    /// Gets a mutable reference to a slice of components,
    /// preserving the lifetime `'t` of this partition object.
    fn into_chunk_mut(
        self,
        start: Self::RawEntity,
        end: Self::RawEntity,
    ) -> Option<&'t mut [Self::Comp]>;

    /// Return value of [`into_iter_chunks_mut`](Self::into_iter_chunks_mut).
    type IntoIterChunksMut: Iterator<Item = (Self::RawEntity, &'t mut [Self::Comp])>;
    /// Returns a mutable iterator over the storage, ordered by entity index order.
    fn into_iter_chunks_mut(self) -> Self::IntoIterChunksMut;
}

/// The iterator item of [`Storage::iter_chunks`].
pub struct ChunkRef<'t, S: Storage> {
    /// The slice of components in the chunk.
    pub slice: &'t [S::Comp],
    /// The entity index of `slice[0]`.
    pub start: S::RawEntity,
}

/// The iterator item of [`Storage::iter_chunks_mut`].
pub struct ChunkMut<'t, S: Storage> {
    /// The slice of components in the chunk.
    pub slice: &'t mut [S::Comp],
    /// The entity index of `slice[0]`.
    pub start: S::RawEntity,
}