10 `EnTT` is a header-only, tiny and easy to use framework written in modern C++.<br/>
11 It's entirely designed around an architectural pattern pattern called _ECS_ that is used mostly in game development. For further details:
12
13 * [Entity Systems Wiki](http://entity-systems.wikidot.com/)
14 * [Evolve Your Hierarchy](http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/)
15 * [ECS on Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system)
16
17 Originally, `EnTT` was written as a faster alternative to other well known and open source entity-component systems.<br/>
18 After a while the codebase has grown and more features have become part of the framework.
19
20 ## Code Example
21
22 ```cpp
23 #include <registry.hpp>
24
25 struct Position {
26 float x;
27 float y;
28 };
29
30 struct Velocity {
31 float dx;
32 float dy;
33 };
34
35 void update(entt::DefaultRegistry ®istry) {
36 auto view = ecs.view<Position, Velocity>();
37
38 for(auto entity: view) {
39 auto &position = view.get<Position>(entity);
40 auto &velocity = view.get<Velocity>(entity);
41 // ...
42 }
43 }
44
45 int main() {
46 entt::DefaultRegistry registry;
47
48 for(auto i = 0; i < 10; ++i) {
49 auto entity = registry.create();
50 registry.assign<Position>(entity, i * 1.f, i * 1.f);
51 if(i % 2 == 0) { registry.assign<Velocity>(entity, i * .1f, i * .1f); }
52 }
53
54 update(registry);
55 // ...
56 }
57 ```
58
59 ## Motivation
60
61 I started working on `EnTT` because of the wrong reason: my goal was to design an entity-component system that beated another well known open source solution in terms of performance.<br/>
62 I did it, of course, but it wasn't much satisfying. Actually it wasn't satisfying at all. The fastest and nothing more, fairly little indeed.
63 When I realized it, I tried hard to keep intact the great performance of `EnTT` and to add all the features I wanted to see in *my* entity-component system at the same time.
64
65 Today `EnTT` is finally what I was looking for: still faster than its _rivals_, a really good API and an amazing set of features. And even more, of course.
66
67 ### Performance
68
69 As it stands right now, `EnTT` is just fast enough for my requirements if compared to my first choice (that was already amazingly fast indeed).<br/>
70 Here is a comparision between the two (both of them compiled with GCC 7.2.0 on a Dell XPS 13 out of the mid 2014):
76 | Iterating over 10M entities, unpacking one component, standard view | 0.010661s | **1.58e-07s** |
77 | Iterating over 10M entities, unpacking two components, standard view | **0.0112664s** | 0.0840068s |
78 | Iterating over 10M entities, unpacking two components, standard view, half of the entities have all the components | **0.0077951s** | 0.042168s |
79 | Iterating over 10M entities, unpacking two components, standard view, one of the entities has all the components | 0.00713398s | **8.93e-07s** |
80 | Iterating over 10M entities, unpacking two components, persistent view | 0.0112664s | **5.68e-07s** |
81 | Iterating over 10M entities, unpacking five components, standard view | **0.00905084s** | 0.137757s |
82 | Iterating over 10M entities, unpacking five components, persistent view | 0.00905084s | **2.9e-07s** |
83 | Iterating over 10M entities, unpacking ten components, standard view | **0.0104708s** | 0.388602s |
84 | Iterating over 10M entities, unpacking ten components, standard view, half of the entities have all the components | **0.00899859s** | 0.200752s |
85 | Iterating over 10M entities, unpacking ten components, standard view, one of the entities has all the components | 0.00700349s | **2.565e-06s** |
86 | Iterating over 10M entities, unpacking ten components, persistent view | 0.0104708s | **6.23e-07s** |
87 | Iterating over 50M entities, unpacking one component, standard view | 0.055194s | **2.87e-07s** |
88 | Iterating over 50M entities, unpacking two components, standard view | **0.0533921s** | 0.243197s |
89 | Iterating over 50M entities, unpacking two components, persistent view | 0.055194s | **4.47e-07s** |
91 | Sort 150k entities, match two components | - | **0.00608322s** |
92
93 `EnTT` includes its own tests and benchmarks. See [benchmark.cpp](https://github.com/skypjack/entt/blob/master/test/benchmark.cpp) for further details.<br/>
94 On Github users can find also a [benchmark suite](https://github.com/abeimler/ecs_benchmark) that compares a bunch of different projects, one of which is `EnTT`.
95
96 Of course, probably I'll try to get out of `EnTT` more features and better performance in the future, mainly for fun.<br/>
97 If you want to contribute and/or have any suggestion, feel free to make a PR or open an issue to discuss your idea.
98
99 # Build Instructions
100
101 ## Requirements
102
103 To be able to use `EnTT`, users must provide a full-featured compiler that supports at least C++14.<br/>
104 The requirements below are mandatory to compile the tests and to extract the documentation:
105
106 * CMake version 3.2 or later.
107 * Doxygen version 1.8 or later.
108
109 ## Library
110
111 `EnTT` is a header-only library. This means that including the `registry.hpp` header is enough to use it.<br/>
112 It's a matter of adding the following line at the top of a file:
113
114 ```cpp
115 #include <registry.hpp>
116 ```
117
118 Then pass the proper `-I` argument to the compiler to add the `src` directory to the include paths.
119
120 ## Documentation
121
122 ### API Reference
123
124 The documentation is based on [doxygen](http://www.stack.nl/~dimitri/doxygen/). To build it:
125
126 $ cd build
127 $ cmake ..
128 $ make docs
129
130 The API reference will be created in HTML format within the directory `build/docs/html`.
131 To navigate it with your favorite browser:
132
133 $ cd build
134 $ your_favorite_browser docs/html/index.html
135
136 The API reference is also available [online](https://skypjack.github.io/entt/) for the latest version.
137
138 ### Crash Course
139
140 #### Vademecum
141
142 The `Registry` to store, the `View`s to iterate. That's all.
143
144 <!--
145 `EnTT` has two main actors: the **Registry** and the **View**.<br/>
146 The former can be used to manage components, entities and collections of components and entities. The latter allows users to iterate the underlying collections.
147
148 #### The Registry
149
150 There are two options to instantiate a registry:
151
152 * Use the `DefaultRegistry` alias:
153
154 ```cpp
155 auto registry = entt::DefaultRegistry<Components...>{args...};
156 ```
157
158 Users must provide the whole list of components to be registered with the default registry and that's all.
159
160 * Use directly the `Registry` class template:
161
162 ```cpp
163 auto registry = entt::Registry<std::uint16_t, Components...>{args...};
164 ```
165
166 Users must provide the whole list of components to be registered with the registry **and** the desired type for the entities.
167 Note that the default type (the one used by the default registry) is `std::uint32_t`, that is larger enough for almost all the games but also too big for the most of the games.
168
169 In both cases there are no requirements for the components but to be moveable, therefore POD types are just fine.
170
171 The `Registry` class offers a bunch of basic functionalities to query the internal data structures.
172 In almost all the cases those member functions can be used to query either the entity list or the components lists.<br/>
173 As an example, the member functions `empty` can be used to know if at least an entity exists and/or if at least one component of the given type has been assigned to an entity.<br/>
174
175 ```cpp
176 bool b = registry.empty();
177 // ...
178 bool b = registry.empty<MyComponent>();
179 ```
180
181 Similarly, `size` can be used to know the number of entities alive and/or the number of components of a given type still assigned to entities. `capacity` follows the same pattern and returns the storage capacity for the given element.
182
183 The `valid` member function returns true if `entity` is still in use, false otherwise:
184
185 ```cpp
186 bool b = registry.valid(entity);
187 ```
188
189 Boring, I agree. Let's go to something more tasty.
190 The following functionalities are meant to give users the chance to play with entities and components within a registry.
191
192 The `create` member function can be used to construct a new entity and it comes in two flavors:
193
194 * The plain version just creates a _naked_ entity with no components assigned to it:
195
196 ```cpp
197 auto entity = registry.create();
198 ```
199
200 * The member function template creates an entity and assigns to it the given _default-initialized_ components:
201
202 ```cpp
203 auto entity = registry.create<Position, Velocity>();
204 ```
205
206 It's a helper function, mostly syncactic sugar and it's equivalent to the following snippet:
207
208 ```cpp
209 auto entity = registry.create();
210 registry.assign<Position>();
211 registry.assign<Velocity>();
212 ```
213
214 See below to find more about the `assign` member function.
215
216 On the other side, the `destroy` member function can be used to delete an entity and all its components (if any):
217
218 ```cpp
219 registry.destroy(entity);
220 ```
221
222 It requires that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.
223
224 If the purpose is to remove a single component instead, the `remove` member function template is the way to go:
225
226 ```cpp
227 registry.remove<Position>(entity);
228 ```
229
230 Again, it requires that `entity` is valid. Moreover, an instance of the component must have been previously assigned to the entity.
231 If one of the requirements isn't satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.
232
233 The `reset` member function behaves similarly but with a strictly defined behaviour (and a performance penalty is the price to pay for that). In particular it removes the component if and only if it exists, otherwise it returns safely to the caller:
234
235 ```cpp
236 registry.reset<Position>(entity);
237 ```
238
239 It requires only that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.
240
241 There exist also two more _versions_ of the `reset` member function:
242
243 * If no entity is passed to it, `reset` will remove the given component from each entity that has it:
244
245 ```cpp
246 registry.reset<Position>();
247 ```
248
249 * If neither the entity nor the component are specified, all the entities and their components are destroyed:
250
251 ```cpp
252 registry.reset();
253 ```
254
255 **Note**: the registry has an assert in debug mode that verifies that entities are no longer valid when it's destructed. This function can be used to reset the registry to its initial state and thus to satisfy the requirement.
256
257 To assign a component to an entity, users can rely on the `assign` member function template. It accepts a variable number of arguments that are used to construct the component itself if present:
258
259 ```cpp
260 registry.assign<Position>(entity, 0., 0.);
261 // ...
262 auto &velocity = registry.assign<Velocity>(entity);
263 velocity.dx = 0.;
264 velocity.dy = 0.;
265 ```
266
267 It requires that `entity` is valid. Moreover, the entity shouldn't have another instance of the component assigned to it.
268 If one of the requirements isn't satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.
269
270 If the entity already has the given component and the user wants to replace it, the `replace` member function template is the way to go:
271
272 ```cpp
273 registry.replace<Position>(entity, 0., 0.);
274 // ...
275 auto &velocity = registry.replace<Velocity>(entity);
276 velocity.dx = 0.;
277 velocity.dy = 0.;
278 ```
279
280 It requires that `entity` is valid. Moreover, an instance of the component must have been previously assigned to the entity.
281 If one of the requirements isn't satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.
282
283 In case users want to assign a component to an entity, but it's unknown whether the entity already has it or not, `accomodate` does the work in a single call
284 (of course, there is a performance penalty to pay for that mainly due to the fact that it must check if `entity` already has the given component or not):
289 auto &velocity = registry.accomodate<Velocity>(entity);
290 velocity.dx = 0.;
291 velocity.dy = 0.;
292 ```
293
294 It requires only that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.<br/>
295 Note that `accomodate` is a sliglhty faster alternative for the following if/else statement and nothing more:
296
297 ```cpp
298 if(registry.has<Comp>(entity)) {
299 registry.replace<Comp>(entity, arg1, argN);
300 } else {
301 registry.assign<Comp>(entity, arg1, argN);
302 }
303 ```
304
305 As already shown, if in doubt about whether or not an entity has one or more components, the `has` member function template may be useful:
306
307 ```cpp
308 bool b = registry.has<Position, Velocity>(entity);
309 ```
310
311 It requires only that `entity` is valid. In case it is not, an assertion will fail in debug mode and the behaviour is undefined in release mode.
312
313 Entities can also be cloned and either partially or fully copied:
314
315 ```cpp
316 auto entity = registry.clone(other);
317 // ...
318 auto &velocity = registry.copy<Velocity>(to, from);
319 // ...
320 registry.copy(dst, src);
321 ```
322
323 In particular:
324
325 * The `clone` member function creates a new entity and copy all the components from the given one.
326 * The `copy` member function template copies one component from an entity to another one.
327 * The `copy` member function copies all the components from an entity to another one.
328
329 All the functions above mentioned require that entities provided as arguments are valid and components exist wherever they have to be accessed.
330 In case they are not, an assertion will fail in debug mode and the behaviour is undefined in release mode.
331
332 There exists also an utility member function that can be used to `swap` components between entities:
333
334 ```cpp
335 registry.swap<Position>(e1, e2);
336 ```
337
338 As usual, it requires that the two entities are valid and that two instances of the component have been previously assigned to them.
339 In case they are not, an assertion will fail in debug mode and the behaviour is undefined in release mode.
340
341 The `get` member function template (either the non-const or the const version) gives direct access to the component of an entity instead:
342
343 ```cpp
344 auto &position = registry.get<Position>(entity);
345 ```
346
347 It requires that `entity` is valid. Moreover, an instance of the component must have been previously assigned to the entity.
348 If one of the requirements isn't satisfied, an assertion will fail in debug mode and the behaviour is undefined in release mode.
349
350 Components can also be sorted in memory by means of the `sort` member function templates. In particular:
351
352 * Components can be sorted according to a component:
353
354 ```cpp
355 registry.sort<Renderable>([](const auto &lhs, const auto &rhs) { return lhs.z < rhs.z; });
356 ```
357
358 * Components can be sorted according to the order imposed by another component:
359
360 ```cpp
361 registry.sort<Movement, Physics>();
362 ```
363
364 In this case, instances of `Movement` are arranged in memory so that cache misses are minimized when the two components are iterated together.
365
366 Finally, the `view` member function template returns an iterable portion of entities and components:
367
368 ```cpp
369 auto view = registry.view<Position, Velocity>();
370 ```
371
372 Views are the other core component of `EnTT` and are usually extensively used by softwares that include it. See below for more details about the types of views.
373
374 #### The View
375
376 There are two types of views:
377
378 * **Single component view**.
379
380 A single component view gives direct access to both the components and the entities to which the components are assigned.<br/>
381 This kind of views are created from the `Registry` class by means of the `view` member function template as it follows:
382
383 ```cpp
384 // Actual type is Registry<Components...>::view_type<Comp>, where Comp is the component for which the view should be created ...
385 // ... well, auto is far easier to use in this case, isn't it?
386 auto view = registry.view<Sprite>();
387 ```
388
389 Components and entities are stored in tightly packed arrays and single component views are the fastest solution to iterate them.<br/>
390 They have the _C++11-ish_ `begin` and `end` member function that allow users to use them in a typical range-for loop:
391
392 ```cpp
393 auto view = registry.view<Sprite>();
394
395 for(auto entity: view) {
396 auto &sprite = registry.get<Sprite>(entity);
397 // ...
398 }
399 ```
400
401 Iterating a view this way returns entities that can be further used to get components or perform other activities.<br/>
402 There is also another method one can use to iterate the array of entities, that is by using the `size` and `data` member functions:
403
404 ```cpp
405 auto view = registry.view<Sprite>();
406 const auto *data = view.data();
407
408 for(auto i = 0, end = view.size(); i < end; ++i) {
409 auto entity = *(data + i);
410 // ...
411 }
412 ```
413
414 Entites are good when the sole component isn't enough to perform a task.
415 Anyway they come with a cost: accessing components by entities has an extra level of indirection. It's pretty fast, but not that fast in some cases.<br/>
416 Direct access to the packed array of components is the other option around of a single component view. Member functions `size` and `raw` are there for that:
417
418 ```cpp
419 auto view = registry.view<Sprite>();
420 const auto *raw = view.raw();
421
422 for(auto i = 0, end = view.size(); i < end; ++i) {
423 auto &sprite = *(raw + i);
424 // ...
425 }
426 ```
427
428 This is the fastest solution to iterate over the components: they are packed together by construction and visit them in order will reduce to a minimum the number of cache misses.
429
430 * **Multi component view**.
431
432 A multi component view gives access only to the entities to which the components are assigned.<br/>
433 This kind of views are created from the `Registry` class by means of the `view` member function template as it follows:
434
435 ```cpp
436 // Actual type is Registry<Components...>::view_type<Comp...>, where Comp... are the components for which the view should be created ...
437 // ... well, auto is far easier to use in this case, isn't it?
438 auto view = registry.view<Position, Velocity>();
439 ```
440
441 Multi component views can be iterated by means of the `begin` and `end` member functions in a typical range-for loop:
442
443 ```cpp
444 auto view = registry.view<Position, Velocity>();
445
446 for(auto entity: view) {
447 auto &position = registry.get<Position>(entity);
448 auto &velocity = registry.get<Velocity>(entity);
449 // ...
450 }
451 ```
452
453 Note that there exists a packed array of entities to which the component is assigned for each component.
454 Iterators of a multi component view pick the shortest array up and use it to visit the smallest set of potential entities.<br/>
455 The choice is performed when the view is constructed. It's good enough as long as views are discarded once they have been used.
456 For all the other cases, the `reset` member function can be used whenever the data within the registry are known to be changed and forcing the choice again could speed up the execution.
457
458 **Note**: one could argue that an iterator should return the set of references to components for each entity instead of the entity itself.
459 Well, who wants to spend CPU cycles to get a reference to an useless tag component? This drove the design choice indeed.
460
461 All the views can be used more than once. They return newly created and correctly initialized iterators whenever `begin` or `end` is invoked.
462 The same is valid for `data` and `raw` too. Anyway views and iterators are tiny objects and the time spent to construct them can be safely ignored.<br/>
463 I'd suggest not to store them anywhere and to invoke the `Registry::view` member function template at each iteration to get a properly initialized view through which to iterate.
464
465 #### Side notes
466
467 * Entities are numbers and nothing more. They are not classes and they have no member functions at all.
468
469 * Most of the _ECS_ available out there have an annoying limitation (at least from my point of view): entities and components cannot be created, assigned or deleted while users are iterating on them.<br/>
470 `EnTT` partially solves the problem with a few limitations:
471
472 * Entities can be created at any time while iterating one or more components.
473 * Components can be assigned to any entity at any time while iterating one or more components.
474 * During an iteration, the current entity (that is the one returned by the iterator) can be deleted and all its components can be removed safely.
475
476 Entities that are not the current one (that is the one returned by the iterator) cannot be deleted from within a loop.<br/>
477 Components assigned to entities that are not the current one (that is the one returned by the iterator) cannot be removed from within a loop.<br/>
478 In this case, iterators are invalidated and the behaviour is undefined if one continues to use those iterators. Possible approaches are:
479
480 * Store aside the entities and components to be removed and perform the operations at the end of the iteration.
481 * Mark entities and components with a proper tag component that indicates that they must be purged, then perform a second iteration to clean them up one by one.
482
483 * Iterators aren't thread safe. Do no try to iterate over a set of components and modify them concurrently.<br/>
484 That being said, as long as a thread iterates over the entities that have the component `X` or assign and removes that component from a set of entities and another thread does something similar with components `Y` and `Z`, it shouldn't be a problem at all.<br/>
485 As an example, that means that users can freely run the rendering system over the renderable entities and update the physics concurrently on a separate thread if needed.
486 -->
487
488 ## Tests
489
490 To compile and run the tests, `EnTT` requires *googletest*.<br/>
491 `cmake` will download and compile the library before to compile anything else.
492
493 To build the tests:
494
495 * `$ cd build`
496 * `$ cmake ..`
497 * `$ make`
498 * `$ make test`
499
500 To build the benchmarks, use the following line instead:
501
502 * `$ cmake -DCMAKE_BUILD_TYPE=Release ..`
503
504 Benchmarks are compiled only in release mode currently.
505
506 # Contributors
507
508 If you want to contribute, please send patches as pull requests against the branch master.<br/>
509 Check the [contributors list](https://github.com/skypjack/entt/blob/master/AUTHORS) to see who has partecipated so far.
510
511 # License
512
513 Code and documentation Copyright (c) 2017 Michele Caini.<br/>
514 Code released under [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).
515 Docs released under [Creative Commons](https://github.com/skypjack/entt/blob/master/docs/LICENSE).
516
517 # Donation
518
519 Developing and maintaining `EnTT` takes some time and lots of coffee. It still lacks a proper test suite, documentation is partially incomplete and not all functionalities have been fully implemented yet.<br/>
520 If you want to support this project, you can offer me an espresso. I'm from Italy, we're used to turning the best coffee ever in code.<br/>
521 Take a look at the donation button at the top of the page for more details or just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).
88 | Iterating over 10M entities, unpacking one component, standard view | 0.010661s | **1.58e-07s** |
89 | Iterating over 10M entities, unpacking two components, standard view | **0.0112664s** | 0.0840068s |
90 | Iterating over 10M entities, unpacking two components, standard view, half of the entities have all the components | **0.0077951s** | 0.042168s |
91 | Iterating over 10M entities, unpacking two components, standard view, one of the entities has all the components | 0.00713398s | **8.93e-07s** |
92 | Iterating over 10M entities, unpacking two components, persistent view | 0.0112664s | **5.68e-07s** |
93 | Iterating over 10M entities, unpacking five components, standard view | **0.00905084s** | 0.137757s |
94 | Iterating over 10M entities, unpacking five components, persistent view | 0.00905084s | **2.9e-07s** |
95 | Iterating over 10M entities, unpacking ten components, standard view | **0.0104708s** | 0.388602s |
96 | Iterating over 10M entities, unpacking ten components, standard view, half of the entities have all the components | **0.00899859s** | 0.200752s |
97 | Iterating over 10M entities, unpacking ten components, standard view, one of the entities has all the components | 0.00700349s | **2.565e-06s** |
98 | Iterating over 10M entities, unpacking ten components, persistent view | 0.0104708s | **6.23e-07s** |
99 | Iterating over 50M entities, unpacking one component, standard view | 0.055194s | **2.87e-07s** |
100 | Iterating over 50M entities, unpacking two components, standard view | **0.0533921s** | 0.243197s |
101 | Iterating over 50M entities, unpacking two components, persistent view | 0.055194s | **4.47e-07s** |
647 Developing and maintaining `EnTT` takes some time and lots of coffee. I'd like
648 to add more and more functionalities in future and turn it in a full-featured
649 framework.<br/>
650 If you want to support this project, you can offer me an espresso. I'm from
651 Italy, we're used to turning the best coffee ever in code. If you find that
652 it's not enough, feel free to support me the way you prefer.<br/>
653 Take a look at the donation button at the top of the page for more details or
654 just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).
Users should not care about the type of the returned entity identifier. In case entity identifers are stored around, the current member function can be used to know if they are still valid or the entity has been destroyed and potentially recycled.
Destroys all the entities. After a call to reset, all the entities previously created are recycled with a new version number. In case entity identifers are stored around, the current member function can be used to know if they are still valid.
Single component views are incredibly fast and iterate a packed array of entities, all of which has the given component.
Multi component views look at the number of entities available for each component and pick up a reference to the smallest set of candidates to test for the given components.
-
Note
Multi component views are pretty fast. However their performance tend to degenerate when the number of components grows up and the most of the entities have all the given components.
+
Note
Multi component views are pretty fast. However their performance tend to degenerate when the number of components to iterate grows up and the most of the entities have all the given components.
To get a performance boost, consider using a PersistentView instead.
Unmanaged signal handler. It works directly with naked pointers to classes and pointers to member functions as well as pointers to free functions. Users of this class are in charge of disconnecting instances before deleting them.
+
This class serves mainly two purposes:
+
Creating signals to be used later to notify a bunch of listeners.
+
Collecting results from a set of functions like in a voting system.
+
+
The default collector does nothing. To properly collect data, define and use a class that has a call operator the signature of which is bool(Param) and:
+
Param is a type to which Ret can be converted.
+
The return type is true if the handler must stop collecting data, false otherwise.
The Registry to store, the Views to iterate. That's all.
-
+
An entity (the E of an ECS) is an opaque identifier that users should just use as-is and store around if needed. Do not try to inspect an entity identifier, its type can change in future and a registry offers all the functionalities to query them out-of-the-box. The underlying type of an entity (either std::uint16_t, std::uint32_t or std::uint64_t) can be specified when defining a registry (actually the DefaultRegistry is nothing more than a Registry where the type of the entities is std::uint32_t).
+ Components (the C of an ECS) should be plain old data structures or more complex and moveable data structures with a proper constructor. They are list initialized by using the parameters provided to construct the component. No need to register components or their types neither with the registry nor with the entity-component system at all.
+ Systems (the S of an ECS) are just plain functions, functors, lambdas or whatever the users want. They can accept a Registry, a View or a PersistentView and use them the way they prefer. No need to register systems or their types neither with the registry nor with the entity-component system at all.
+
The following sections will explain in short how to use the entity-component system, the core part of the EnTT framework.
+ In fact, the framework is composed of many other classes in addition to those describe below. For more details, please refer to the online documentation.
+
+The Registry, the Entity and the Component
+
A registry is used to store and manage entities as well as to create views to iterate the underlying data structures.
+ Registry is a class template that lets the users decide what's the preferred type to represent an entity. Because std::uint32_t is large enough for almost all the cases, there exists also an alias named DefaultRegistry for Registry<std::uint32_t>.
+
Entities are represented by entitiy identifiers. An entity identifier is an opaque type that users should not inspect or modify in any way. It carries information about the entity itself and its version.
+
A registry can be used both to construct and to destroy entities:
+
// constructs a naked entity with no components ad returns its identifier
Once an entity is deleted, the registry can freely reuse it internally with a slightly different identifier. In particular, the version of an entity is increased each and every time it's destroyed.
+ In case entity identifiers are stored around, the registry offers all the functionalities required to test them and get out of the them all the information they carry:
+
// returns true if the entity is still valid, false otherwise
Components can be assigned to or removed from entities at any time with a few calls to member functions of the registry. As for the entities, the registry offers also a set of functionalities users can use to work with the components.
+
The assign member function template creates, initializes and assigns to an entity the given component. It accepts a variable number of arguments that are used to construct the component itself if present:
auto &velocity = registry.replace<Velocity>(entity);
velocity.dx = 0.;
velocity.dy = 0.;
In case users want to assign a component to an entity, but it's unknown whether the entity already has it or not, accomodate does the work in a single call (of course, there is a performance penalty to pay for that mainly due to the fact that it must check if entity already has the given component or not):
As already shown, if in doubt about whether or not an entity has one or more components, the has member function template may be useful:
+
bool b = registry.has<Position, Velocity>(entity);
On the other side, if the goal is to delete a single component, the remove member function template is the way to go when it's certain that the entity owns a copy of the component:
Otherwise consider to use the reset member function. It behaves similarly to remove but with a strictly defined behaviour (and a performance penalty is the price to pay for that). In particular it removes the component if and only if it exists, otherwise it returns safely to the caller:
The get member function template gives direct access to the component of an entity stored in the underlying data structures of the registry.
+
Sorting: is it possible?
+
Of course, sorting entities and components is an option with EnTT.
+ In fact, there are two functions that respond to slightly different needs:
+
+
Components can be sorted directly:
+
```cpp registry.sort<Renderable>([](const auto &lhs, const auto &rhs) { return lhs.z < rhs.z; }); ```
+
+
Components can be sorted according to the order imposed by another component:
+
```cpp registry.sort<Movement, Physics>(); ```
+
In this case, instances of Movement are arranged in memory so that cache misses are minimized when the two components are iterated together.
+
+
+
+View: to persist or not to persist?
+
There are mainly two kinds of views: standard (also known as View) and persistent (alsa known as PersistentView).
+ Both of them have pros and cons to take in consideration. In particular:
+
+
Standard views: Pros:
+
They work out-of-the-box and don't require any dedicated data structure.
+
Creating and destroying them isn't expensive at all because they don't have any type of initialization.
+
They are the best tool to iterate single components.
+
They are the best tool to iterate multiple components at once when tags are involved or one of the component is assigned to a significantly low number of entities.
+
They don't affect any other operations of the registry. Cons:
+
Their performance tend to degenerate when the number of components to iterate grows up and the most of the entities have all of them.
+
+
+
Persistent views: Pros:
+
Once prepared, creating and destroying them isn't expensive at all because they don't have any type of initialization.
+
They are the best tool to iterate multiple components at once when the most of the entities have all of them. Cons:
+
They have dedicated data structures and thus affect the memory pressure to a minimal extent.
+
If not previously prepared, the first time they are used they go through an initialization step that could take a while.
+
They affect to a minimum the creation and destruction of entities and components. In other terms: the more persistent views there will be, the less performing will be creating and destroying entities and components.
+
+
+
+
To sum up and as a rule of thumb, use a standard view:
+
To iterate entities for a single component.
+
To iterate entities for multiple components when a significantly low number of entities have one of the components.
+
In all those cases where a persistent view would give a boost to performance but the iteration isn't performed frequently.
+
+
Use a persistent view in all the other cases.
+
To easily iterate entities, all the views offer C++-ishbegin and end member functions that allow users to use them in a typical range-for loop.
+ Continue reading for more details or refer to the official documentation.
+
Standard View
+
A standard view behaves differently if it's constructed for a single component or if it has been requested to iterate multiple components. Even the API is different in the two cases.
+ All that they share is the way they are created by means of a registry:
+
// single component standard view
auto single = registry.view<Position>();
// multi component standard view
auto multi = registry.view<Position, Velocity>();
For all that remains, it's worth discussing them separately.
+
+
Single component
+
Single component standard views are specialized in order to give a boost in terms of performance in all the situation. This kind of views can access the underlying data structures directly and avoid superflous checks.
+ They offer a bunch of functionalities to get the number of entities they are going to return and a raw access to the entity list as well as to the component list.
+ Refer to the official documentation for all the details.
+
There is no need to store views around for they are extremely cheap to construct, even though they can be copied without problems and reused freely. In fact, they return newly created and correctly initialized iterators whenever begin or end are invoked.
+ To iterate a single component standard view, just use it in range-for:
+
auto view = registry.view<Renderable>();
for(auto entity: view) {
auto &renderable = view.get(entity);
// ...
}
Note: prefer the get member function of the view instead of the get member function template of the registry during iterations.
+
Multi component
+
Multi component standard views iterate entities that have at least all the given components in their bags. During construction, these views look at the number of entities available for each component and pick up a reference to the smallest set of candidates in order to speed up iterations.
+ They offer fewer functionalities than their companion views for single component, the most important of which can be used to reset the view and refresh the reference to the set of candidate entities to iterate.
+ Refer to the official documentation for all the details.
+
There is no need to store views around for they are extremely cheap to construct, even though they can be copied without problems and reused freely. In fact, they return newly created and correctly initialized iterators whenever begin or end are invoked.
+ To iterate a multi component standard view, just use it in range-for:
+
auto view = registry.view<Position, Velocity>();
for(auto entity: view) {
auto &position = view.get<Position>(entity);
auto &velocity = view.get<Velocity>(entity);
// ...
}
Note: prefer the get member function template of the view instead of the get member function template of the registry during iterations.
+
Persistent View
+
A persistent view returns all the entities and only the entities that have at least the given components. Moreover, it's guaranteed that the entity list is thightly packed in memory for fast iterations.
+ In general, persistent views don't stay true to the order of any set of components unless users explicitly sort them.
+
Persistent views can be used only to iterate multiple components. Create them as it follows:
+
auto view = registry.persistent<Position, Velocity>();
There is no need to store views around for they are extremely cheap to construct, even though they can be copied without problems and reused freely. In fact, they return newly created and correctly initialized iterators whenever begin or end are invoked.
+ That being said, persistent views perform an initialization step the very first time they are constructed and this could be quite costly. To avoid it, consider asking to the registry to prepare them when no entities have been created yet:
+
registry.prepare<Position, Velocity>();
If the registry is empty, preparation is extremely fast. Moreover the prepare member function template is idempotent. Feel free to invoke it even more than once: if the view has been alreadt prepared before, the function returns immediately and does nothing.
+
A persistent view offers a bunch of functionalities to get the number of entities it's going to return, a raw access to the entity list and the possibility to sort the underlying data structures according to the order of one of the components for which it has been constructed.
+ Refer to the official documentation for all the details.
+
To iterate a persistent view, just use it in range-for:
+
auto view = registry.persistent<Position, Velocity>();
for(auto entity: view) {
auto &position = view.get<Position>(entity);
auto &velocity = view.get<Velocity>(entity);
// ...
}
Note: prefer the get member function template of the view instead of the get member function template of the registry during iterations.
+
+Side notes
+
+
Entity identifiers are numbers and nothing more. They are not classes and they have no member functions at all. As already mentioned, do no try to inspect or modify an entity descriptor in any way.
+
As shown in the examples above, the preferred way to get references to the components while iterating a view is by using the view itself. It's a faster alternative to the get member function template that is part of the API of the Registry. That's because the registry must ensure that a pool for the given component exists before to use it; on the other side, views force the construction of the pools for all their components and access them directly, thus avoiding all the checks.
+
Most of the ECS available out there have an annoying limitation (at least from my point of view): entities and components cannot be created and/or deleted during iterations.
+ EnTT partially solves the problem with a few limitations:
* Creating entities and components is allowed during iterations.
+* Deleting an entity or removing its components is allowed during
+ iterations if it's the one currently returned by a view. For all the
+ other entities, destroying them or removing their components isn't
+ allowed and it can result in undefined behavior.
+
Iterators are invalidated and the behaviour is undefined if an entity is modified or destroyed and it's not the one currently returned by the view.
+ To work around it, possible approaches are:
+
Store aside the entities and the components to be removed and perform the operations at the end of the iteration.
+
Mark entities and components with a proper tag component that indicates they must be purged, then perform a second iteration to clean them up one by one.
+
+
+
Views and thus their iterators aren't thread safe. Do no try to iterate a set of components and modify the same set concurrently.
+ That being said, as long as a thread iterates the entities that have the component X or assign and removes that component from a set of entities, another thread can safely do the same with components Y and Z and everything will work like a charm.
+ As an example, users can freely execute the rendering system and iterate the renderable entities while updating a physic component concurrently on a separate thread if needed.
+
+
+What else?
+
The EnTT framework is moving its first steps. More and more will come in the future and hopefully I'm going to work on it for a long time.
+ Here is a brief list of what it offers today (consider it a work in progress):
To compile and run the tests, EnTT requires googletest. cmake will download and compile the library before to compile anything else.
@@ -175,18 +309,18 @@ Tests
$ cmake -DCMAKE_BUILD_TYPE=Release ..
Benchmarks are compiled only in release mode currently.
-
+
Contributors
-
If you want to contribute, please send patches as pull requests against the branch master.
+
If you want to contribute, please send patches as pull requests against the branch master.
Check the contributors list to see who has partecipated so far.
-
+
License
Code and documentation Copyright (c) 2017 Michele Caini.
Code released under the MIT license. Docs released under Creative Commons.
-
+
Donation
-
Developing and maintaining EnTT takes some time and lots of coffee. It still lacks a proper test suite, documentation is partially incomplete and not all functionalities have been fully implemented yet.
- If you want to support this project, you can offer me an espresso. I'm from Italy, we're used to turning the best coffee ever in code.
+
Developing and maintaining EnTT takes some time and lots of coffee. I'd like to add more and more functionalities in future and turn it in a full-featured framework.
+ If you want to support this project, you can offer me an espresso. I'm from Italy, we're used to turning the best coffee ever in code. If you find that it's not enough, feel free to support me the way you prefer.
Take a look at the donation button at the top of the page for more details or just click here.
diff --git a/inherit_graph_10.map b/inherit_graph_10.map
index b11003411..84291e569 100644
--- a/inherit_graph_10.map
+++ b/inherit_graph_10.map
@@ -1,4 +1,3 @@
diff --git a/inherit_graph_10.md5 b/inherit_graph_10.md5
index c522d3c5e..492aeb8b7 100644
--- a/inherit_graph_10.md5
+++ b/inherit_graph_10.md5
@@ -1 +1 @@
-8b49e5d4ab6821a094273ac533350361
\ No newline at end of file
+d277977b1425339c8f946591267cbe20
\ No newline at end of file
diff --git a/inherit_graph_10.png b/inherit_graph_10.png
index 35698545c..65754a7cb 100644
Binary files a/inherit_graph_10.png and b/inherit_graph_10.png differ
diff --git a/inherit_graph_11.map b/inherit_graph_11.map
index 84291e569..8b565bf7e 100644
--- a/inherit_graph_11.map
+++ b/inherit_graph_11.map
@@ -1,3 +1,3 @@
diff --git a/inherit_graph_11.md5 b/inherit_graph_11.md5
index 492aeb8b7..b79b6846b 100644
--- a/inherit_graph_11.md5
+++ b/inherit_graph_11.md5
@@ -1 +1 @@
-d277977b1425339c8f946591267cbe20
\ No newline at end of file
+621c711cd444e7dcd7b795f1703c5cd0
\ No newline at end of file
diff --git a/inherit_graph_11.png b/inherit_graph_11.png
index 65754a7cb..1298a81b6 100644
Binary files a/inherit_graph_11.png and b/inherit_graph_11.png differ
diff --git a/inherit_graph_12.map b/inherit_graph_12.map
index 8b565bf7e..d4b0989d5 100644
--- a/inherit_graph_12.map
+++ b/inherit_graph_12.map
@@ -1,3 +1,3 @@
diff --git a/inherit_graph_12.md5 b/inherit_graph_12.md5
index b79b6846b..054df0392 100644
--- a/inherit_graph_12.md5
+++ b/inherit_graph_12.md5
@@ -1 +1 @@
-621c711cd444e7dcd7b795f1703c5cd0
\ No newline at end of file
+e858ed2f3c399ac5179f89b14a40a3d7
\ No newline at end of file
diff --git a/inherit_graph_12.png b/inherit_graph_12.png
index 1298a81b6..31938c30a 100644
Binary files a/inherit_graph_12.png and b/inherit_graph_12.png differ
diff --git a/inherit_graph_13.map b/inherit_graph_13.map
index d4b0989d5..cd9cba107 100644
--- a/inherit_graph_13.map
+++ b/inherit_graph_13.map
@@ -1,3 +1,3 @@
diff --git a/inherit_graph_13.md5 b/inherit_graph_13.md5
index 054df0392..a1dd1729a 100644
--- a/inherit_graph_13.md5
+++ b/inherit_graph_13.md5
@@ -1 +1 @@
-e858ed2f3c399ac5179f89b14a40a3d7
\ No newline at end of file
+9ec2ec1f7c03ab25a019e90b2440537e
\ No newline at end of file
diff --git a/inherit_graph_13.png b/inherit_graph_13.png
index 31938c30a..412035b1f 100644
Binary files a/inherit_graph_13.png and b/inherit_graph_13.png differ
diff --git a/inherit_graph_14.map b/inherit_graph_14.map
deleted file mode 100644
index cd9cba107..000000000
--- a/inherit_graph_14.map
+++ /dev/null
@@ -1,3 +0,0 @@
-
diff --git a/inherit_graph_14.md5 b/inherit_graph_14.md5
deleted file mode 100644
index a1dd1729a..000000000
--- a/inherit_graph_14.md5
+++ /dev/null
@@ -1 +0,0 @@
-9ec2ec1f7c03ab25a019e90b2440537e
\ No newline at end of file
diff --git a/inherit_graph_14.png b/inherit_graph_14.png
deleted file mode 100644
index 412035b1f..000000000
Binary files a/inherit_graph_14.png and /dev/null differ
diff --git a/inherit_graph_7.map b/inherit_graph_7.map
index 5b0935174..ecd2ab3a8 100644
--- a/inherit_graph_7.map
+++ b/inherit_graph_7.map
@@ -1,3 +1,3 @@
diff --git a/inherit_graph_7.md5 b/inherit_graph_7.md5
index 551a0eb6b..43c403c06 100644
--- a/inherit_graph_7.md5
+++ b/inherit_graph_7.md5
@@ -1 +1 @@
-287cd55dcfdd28d382a5360dead0d4ec
\ No newline at end of file
+7d8290e1b4cc0a905297900cf787ba57
\ No newline at end of file
diff --git a/inherit_graph_7.png b/inherit_graph_7.png
index 0884027f3..2a884a71a 100644
Binary files a/inherit_graph_7.png and b/inherit_graph_7.png differ
diff --git a/inherit_graph_8.map b/inherit_graph_8.map
index d695a5238..5b16ab6a8 100644
--- a/inherit_graph_8.map
+++ b/inherit_graph_8.map
@@ -1,3 +1,3 @@
diff --git a/inherit_graph_8.md5 b/inherit_graph_8.md5
index 35307de1c..47a323b52 100644
--- a/inherit_graph_8.md5
+++ b/inherit_graph_8.md5
@@ -1 +1 @@
-3772132e4cb53ada561399f1079dd462
\ No newline at end of file
+f36c2d5f413df2a35065e3015ebbed94
\ No newline at end of file
diff --git a/inherit_graph_8.png b/inherit_graph_8.png
index ccbc14ca6..1d2bcf060 100644
Binary files a/inherit_graph_8.png and b/inherit_graph_8.png differ
diff --git a/inherit_graph_9.map b/inherit_graph_9.map
index 2eeb6ee26..b11003411 100644
--- a/inherit_graph_9.map
+++ b/inherit_graph_9.map
@@ -1,3 +1,4 @@
diff --git a/inherit_graph_9.md5 b/inherit_graph_9.md5
index 3b2383ad9..c522d3c5e 100644
--- a/inherit_graph_9.md5
+++ b/inherit_graph_9.md5
@@ -1 +1 @@
-7a4f1c5a89186d4683e011455382fccb
\ No newline at end of file
+8b49e5d4ab6821a094273ac533350361
\ No newline at end of file
diff --git a/inherit_graph_9.png b/inherit_graph_9.png
index 3952bffba..35698545c 100644
Binary files a/inherit_graph_9.png and b/inherit_graph_9.png differ
diff --git a/inherits.html b/inherits.html
index f33475ded..32e2ceee2 100644
--- a/inherits.html
+++ b/inherits.html
@@ -101,43 +101,38 @@ $(function() {
-
-
Functions
@@ -156,7 +160,28 @@ Variables
The default registry is the best choice for almost all the applications.
Users should have a really good reason to choose something different.
Unmanaged event handler. Collecting data for this kind of signals doesn't make sense at all. Its sole purpose is to provide the listeners with the given event.
+ 1.8.13
+
+
+
diff --git a/classentt_1_1SigH_3_01Ret_07Args_8_8_8_08_4.html b/classentt_1_1SigH_3_01Ret_07Args_8_8_8_08_00_01Collector_01_4.html
similarity index 55%
rename from classentt_1_1SigH_3_01Ret_07Args_8_8_8_08_4.html
rename to classentt_1_1SigH_3_01Ret_07Args_8_8_8_08_00_01Collector_01_4.html
index 7c4a118d8..1be60a074 100644
--- a/classentt_1_1SigH_3_01Ret_07Args_8_8_8_08_4.html
+++ b/classentt_1_1SigH_3_01Ret_07Args_8_8_8_08_00_01Collector_01_4.html
@@ -5,7 +5,7 @@
-
+
+
+
+
-