diff --git a/README_8md_source.html b/README_8md_source.html index 6ee34d080..b5217c999 100644 --- a/README_8md_source.html +++ b/README_8md_source.html @@ -63,7 +63,7 @@ $(function() {
README.md
-
1 # The EnTT Framework
2 
3 [![Build Status](https://travis-ci.org/skypjack/entt.svg?branch=master)](https://travis-ci.org/skypjack/entt)
4 [![Build status](https://ci.appveyor.com/api/projects/status/rvhaabjmghg715ck?svg=true)](https://ci.appveyor.com/project/skypjack/entt)
5 [![Coverage Status](https://coveralls.io/repos/github/skypjack/entt/badge.svg?branch=master)](https://coveralls.io/github/skypjack/entt?branch=master)
6 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)
7 
8 # Introduction
9 
10 `EnTT` is a header-only, tiny and easy to use framework written in modern
11 C++.<br/>
12 It's entirely designed around an architectural pattern pattern called _ECS_ that
13 is used mostly in game development. For further details:
14 
15 * [Entity Systems Wiki](http://entity-systems.wikidot.com/)
16 * [Evolve Your Hierarchy](http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/)
17 * [ECS on Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system)
18 
19 Originally, `EnTT` was written as a faster alternative to other well known and
20 open source entity-component systems.<br/>
21 After a while the codebase has grown and more features have become part of the
22 framework.
23 
24 ## Code Example
25 
26 ```cpp
27 #include <registry.hpp>
28 
29 struct Position {
30  float x;
31  float y;
32 };
33 
34 struct Velocity {
35  float dx;
36  float dy;
37 };
38 
39 void update(entt::DefaultRegistry &registry) {
40  auto view = ecs.view<Position, Velocity>();
41 
42  for(auto entity: view) {
43  auto &position = view.get<Position>(entity);
44  auto &velocity = view.get<Velocity>(entity);
45  // ...
46  }
47 }
48 
49 int main() {
50  entt::DefaultRegistry registry;
51 
52  for(auto i = 0; i < 10; ++i) {
53  auto entity = registry.create();
54  registry.assign<Position>(entity, i * 1.f, i * 1.f);
55  if(i % 2 == 0) { registry.assign<Velocity>(entity, i * .1f, i * .1f); }
56  }
57 
58  update(registry);
59  // ...
60 }
61 ```
62 
63 ## Motivation
64 
65 I started working on `EnTT` because of the wrong reason: my goal was to design
66 an entity-component system that beated another well known open source solution
67 in terms of performance.<br/>
68 I did it, of course, but it wasn't much satisfying. Actually it wasn't
69 satisfying at all. The fastest and nothing more, fairly little indeed. When I
70 realized it, I tried hard to keep intact the great performance of `EnTT` and to
71 add all the features I wanted to see in *my* entity-component system at the same
72 time.
73 
74 Today `EnTT` is finally what I was looking for: still faster than its _rivals_,
75 a really good API and an amazing set of features. And even more, of course.
76 
77 ## Performance
78 
79 As it stands right now, `EnTT` is just fast enough for my requirements if
80 compared to my first choice (that was already amazingly fast indeed).<br/>
81 Here is a comparision between the two (both of them compiled with GCC 7.2.0 on a
82 Dell XPS 13 out of the mid 2014):
83 
84 | Benchmark | EntityX (experimental/compile_time) | EnTT |
85 |-----------|-------------|-------------|
86 | Creating 10M entities | 0.128881s | **0.0408754s** |
87 | Destroying 10M entities | **0.0531374s** | 0.0545839s |
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** |
102 | Sort 150k entities, one component | - | **0.0080046s** |
103 | Sort 150k entities, match two components | - | **0.00608322s** |
104 
105 `EnTT` includes its own tests and benchmarks. See
106 [benchmark.cpp](https://github.com/skypjack/entt/blob/master/test/benchmark.cpp)
107 for further details.<br/>
108 On Github users can find also a
109 [benchmark suite](https://github.com/abeimler/ecs_benchmark) that compares a
110 bunch of different projects, one of which is `EnTT`.
111 
112 Of course, probably I'll try to get out of `EnTT` more features and better
113 performance in the future, mainly for fun.<br/>
114 If you want to contribute and/or have any suggestion, feel free to make a PR or
115 open an issue to discuss your idea.
116 
117 # Build Instructions
118 
119 ## Requirements
120 
121 To be able to use `EnTT`, users must provide a full-featured compiler that
122 supports at least C++14.<br/>
123 The requirements below are mandatory to compile the tests and to extract the
124 documentation:
125 
126 * CMake version 3.2 or later.
127 * Doxygen version 1.8 or later.
128 
129 ## Library
130 
131 `EnTT` is a header-only library. This means that including the `registry.hpp`
132 header is enough to use it.<br/>
133 It's a matter of adding the following line at the top of a file:
134 
135 ```cpp
136 #include <registry.hpp>
137 ```
138 
139 Then pass the proper `-I` argument to the compiler to add the `src` directory to
140 the include paths.
141 
142 ## Documentation
143 
144 The documentation is based on [doxygen](http://www.stack.nl/~dimitri/doxygen/).
145 To build it:
146 
147  $ cd build
148  $ cmake ..
149  $ make docs
150 
151 The API reference will be created in HTML format within the directory
152 `build/docs/html`. To navigate it with your favorite browser:
153 
154  $ cd build
155  $ your_favorite_browser docs/html/index.html
156 
157 The API reference is also available [online](https://skypjack.github.io/entt/)
158 for the latest version.
159 
160 ## Tests
161 
162 To compile and run the tests, `EnTT` requires *googletest*.<br/>
163 `cmake` will download and compile the library before to compile anything else.
164 
165 To build the tests:
166 
167 * `$ cd build`
168 * `$ cmake ..`
169 * `$ make`
170 * `$ make test`
171 
172 To build the benchmarks, use the following line instead:
173 
174 * `$ cmake -DCMAKE_BUILD_TYPE=Release ..`
175 
176 Benchmarks are compiled only in release mode currently.
177 
178 # Crash Course
179 
180 ## Vademecum
181 
182 The `Registry` to store, the `View`s to iterate. That's all.
183 
184 An entity (the _E_ of an _ECS_) is an opaque identifier that users should just
185 use as-is and store around if needed. Do not try to inspect an entity
186 identifier, its type can change in future and a registry offers all the
187 functionalities to query them out-of-the-box. The underlying type of an entity
188 (either `std::uint16_t`, `std::uint32_t` or `std::uint64_t`) can be specified
189 when defining a registry (actually the DefaultRegistry is nothing more than a
190 Registry where the type of the entities is `std::uint32_t`).<br/>
191 Components (the _C_ of an _ECS_) should be plain old data structures or more
192 complex and moveable data structures with a proper constructor. They are list
193 initialized by using the parameters provided to construct the component. No need
194 to register components or their types neither with the registry nor with the
195 entity-component system at all.<br/>
196 Systems (the _S_ of an _ECS_) are just plain functions, functors, lambdas or
197 whatever the users want. They can accept a Registry, a View or a PersistentView
198 and use them the way they prefer. No need to register systems or their types
199 neither with the registry nor with the entity-component system at all.
200 
201 The following sections will explain in short how to use the entity-component
202 system, the core part of the `EnTT` framework.<br/>
203 In fact, the framework is composed of many other classes in addition to those
204 describe below. For more details, please refer to the
205 [online documentation](https://skypjack.github.io/entt/).
206 
207 ## The Registry, the Entity and the Component
208 
209 A registry is used to store and manage entities as well as to create views to
210 iterate the underlying data structures.<br/>
211 Registry is a class template that lets the users decide what's the preferred
212 type to represent an entity. Because `std::uint32_t` is large enough for almost
213 all the cases, there exists also an alias named DefaultRegistry for
214 `Registry<std::uint32_t>`.
215 
216 Entities are represented by _entitiy identifiers_. An entity identifier is an
217 opaque type that users should not inspect or modify in any way. It carries
218 information about the entity itself and its version.
219 
220 A registry can be used both to construct and to destroy entities:
221 
222 ```cpp
223 // constructs a naked entity with no components ad returns its identifier
224 auto entity = registry.create();
225 
226 // constructs an entity and assigns it default-initialized components
227 auto another = registry.create<Position, Velocity>();
228 
229 // destroys an entity and all its components
230 registry.destroy(entity);
231 ```
232 
233 Once an entity is deleted, the registry can freely reuse it internally with a
234 slightly different identifier. In particular, the version of an entity is
235 increased each and every time it's destroyed.<br/>
236 In case entity identifiers are stored around, the registry offers all the
237 functionalities required to test them and get out of the them all the
238 information they carry:
239 
240 ```cpp
241 // returns true if the entity is still valid, false otherwise
242 bool b = registry.valid(entity);
243 
244 // gets the version contained in the entity identifier
245 auto version = registry.version(entity);
246 
247 // gets the actual version for the given entity
248 auto curr = registry.current(entity);
249 ```
250 
251 Components can be assigned to or removed from entities at any time with a few
252 calls to member functions of the registry. As for the entities, the registry
253 offers also a set of functionalities users can use to work with the components.
254 
255 The `assign` member function template creates, initializes and assigns to an
256 entity the given component. It accepts a variable number of arguments that are
257 used to construct the component itself if present:
258 
259 ```cpp
260 registry.assign<Position>(entity, 0., 0.);
261 
262 // ...
263 
264 auto &velocity = registry.assign<Velocity>(entity);
265 velocity.dx = 0.;
266 velocity.dy = 0.;
267 ```
268 
269 If the entity already has the given component, the `replace` member function
270 template can be used to replace it:
271 
272 ```cpp
273 registry.replace<Position>(entity, 0., 0.);
274 
275 // ...
276 
277 auto &velocity = registry.replace<Velocity>(entity);
278 velocity.dx = 0.;
279 velocity.dy = 0.;
280 ```
281 
282 In case users want to assign a component to an entity, but it's unknown whether
283 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
285 fact that it must check if `entity` already has the given component or not):
286 
287 ```cpp
288 registry.accomodate<Position>(entity, 0., 0.);
289 
290 // ...
291 
292 auto &velocity = registry.accomodate<Velocity>(entity);
293 velocity.dx = 0.;
294 velocity.dy = 0.;
295 ```
296 
297 Note that `accomodate` is a sliglhty faster alternative for the following
298 `if`/`else` statement and nothing more:
299 
300 ```cpp
301 if(registry.has<Comp>(entity)) {
302  registry.replace<Comp>(entity, arg1, argN);
303 } else {
304  registry.assign<Comp>(entity, arg1, argN);
305 }
306 ```
307 
308 As already shown, if in doubt about whether or not an entity has one or more
309 components, the `has` member function template may be useful:
310 
311 ```cpp
312 bool b = registry.has<Position, Velocity>(entity);
313 ```
314 
315 On the other side, if the goal is to delete a single component, the `remove`
316 member function template is the way to go when it's certain that the entity owns
317 a copy of the component:
318 
319 ```cpp
320 registry.remove<Position>(entity);
321 ```
322 
323 Otherwise consider to use the `reset` member function. It behaves similarly to
324 `remove` but with a strictly defined behaviour (and a performance penalty is the
325 price to pay for that). In particular it removes the component if and only if it
326 exists, otherwise it returns safely to the caller:
327 
328 ```cpp
329 registry.reset<Position>(entity);
330 ```
331 
332 There exist also two other _versions_ of the `reset` member function:
333 
334 * If no entity is passed to it, `reset` will remove the given component from
335 each entity that has it:
336 
337  ```cpp
338  registry.reset<Position>();
339  ```
340 
341 * If neither the entity nor the component are specified, all the entities and
342 their components are destroyed:
343 
344  ```cpp
345  registry.reset();
346  ```
347 
348 Finally, references to components can be retrieved by just doing this:
349 
350 ```cpp
351 // either a non-const reference ...
352 DefaultRegistry registry;
353 auto &position = registry.get<Position>(entity);
354 
355 // ... or a const one
356 const auto &cregistry = registry;
357 const auto &position = cregistry.get<Position>(entity);
358 ```
359 
360 The `get` member function template gives direct access to the component of an
361 entity stored in the underlying data structures of the registry.
362 
363 ### Sorting: is it possible?
364 
365 Of course, sorting entities and components is an option with `EnTT`.<br/>
366 In fact, there are two functions that respond to slightly different needs:
367 
368 * Components can be sorted directly:
369 
370  ```cpp
371  registry.sort<Renderable>([](const auto &lhs, const auto &rhs) {
372  return lhs.z < rhs.z;
373  });
374  ```
375 
376 * Components can be sorted according to the order imposed by another component:
377 
378  ```cpp
379  registry.sort<Movement, Physics>();
380  ```
381 
382  In this case, instances of `Movement` are arranged in memory so that cache
383  misses are minimized when the two components are iterated together.
384 
385 ## View: to persist or not to persist?
386 
387 There are mainly two kinds of views: standard (also known as View) and
388 persistent (alsa known as PersistentView).<br/>
389 Both of them have pros and cons to take in consideration. In particular:
390 
391 * Standard views:
392 
393  Pros:
394  * They work out-of-the-box and don't require any dedicated data
395  structure.
396  * Creating and destroying them isn't expensive at all because they don't
397  have any type of initialization.
398  * They are the best tool to iterate single components.
399  * They are the best tool to iterate multiple components at once when
400  tags are involved or one of the component is assigned to a
401  significantly low number of entities.
402  * They don't affect any other operations of the registry.
403 
404  Cons:
405  * Their performance tend to degenerate when the number of components
406  to iterate grows up and the most of the entities have all of them.
407 
408 * Persistent views:
409 
410  Pros:
411  * Once prepared, creating and destroying them isn't expensive at all
412  because they don't have any type of initialization.
413  * They are the best tool to iterate multiple components at once when
414  the most of the entities have all of them.
415 
416  Cons:
417  * They have dedicated data structures and thus affect the memory
418  pressure to a minimal extent.
419  * If not previously prepared, the first time they are used they go
420  through an initialization step that could take a while.
421  * They affect to a minimum the creation and destruction of entities and
422  components. In other terms: the more persistent views there will be,
423  the less performing will be creating and destroying entities and
424  components.
425 
426 To sum up and as a rule of thumb, use a standard view:
427 * To iterate entities for a single component.
428 * To iterate entities for multiple components when a significantly low
429  number of entities have one of the components.
430 * In all those cases where a persistent view would give a boost to
431  performance but the iteration isn't performed frequently.
432 
433 Use a persistent view in all the other cases.
434 
435 To easily iterate entities, all the views offer _C++-ish_ `begin` and `end`
436 member functions that allow users to use them in a typical range-for loop.<br/>
437 Continue reading for more details or refer to the
438 [official documentation](https://skypjack.github.io/entt/).
439 
440 ### Standard View
441 
442 A standard view behaves differently if it's constructed for a single component
443 or if it has been requested to iterate multiple components. Even the API is
444 different in the two cases.<br/>
445 All that they share is the way they are created by means of a registry:
446 
447 ```cpp
448 // single component standard view
449 auto single = registry.view<Position>();
450 
451 // multi component standard view
452 auto multi = registry.view<Position, Velocity>();
453 ```
454 
455 For all that remains, it's worth discussing them separately.<br/>
456 
457 #### Single component standard view
458 
459 Single component standard views are specialized in order to give a boost in
460 terms of performance in all the situation. This kind of views can access the
461 underlying data structures directly and avoid superflous checks.<br/>
462 They offer a bunch of functionalities to get the number of entities they are
463 going to return and a raw access to the entity list as well as to the component
464 list.<br/>
465 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
466 the details.
467 
468 There is no need to store views around for they are extremely cheap to
469 construct, even though they can be copied without problems and reused
470 freely. In fact, they return newly created and correctly initialized iterators
471 whenever `begin` or `end` are invoked.<br/>
472 To iterate a single component standard view, just use it in range-for:
473 
474 ```cpp
475 auto view = registry.view<Renderable>();
476 
477 for(auto entity: view) {
478  auto &renderable = view.get(entity);
479 
480  // ...
481 }
482 ```
483 
484 **Note**: prefer the `get` member function of the view instead of the `get`
485 member function template of the registry during iterations.
486 
487 #### Multi component standard view
488 
489 Multi component standard views iterate entities that have at least all the given
490 components in their bags. During construction, these views look at the number
491 of entities available for each component and pick up a reference to the smallest
492 set of candidates in order to speed up iterations.<br/>
493 They offer fewer functionalities than their companion views for single
494 component, the most important of which can be used to reset the view and refresh
495 the reference to the set of candidate entities to iterate.<br/>
496 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
497 the details.
498 
499 There is no need to store views around for they are extremely cheap to
500 construct, even though they can be copied without problems and reused
501 freely. In fact, they return newly created and correctly initialized iterators
502 whenever `begin` or `end` are invoked.<br/>
503 To iterate a multi component standard view, just use it in range-for:
504 
505 ```cpp
506 auto view = registry.view<Position, Velocity>();
507 
508 for(auto entity: view) {
509  auto &position = view.get<Position>(entity);
510  auto &velocity = view.get<Velocity>(entity);
511 
512  // ...
513 }
514 ```
515 
516 **Note**: prefer the `get` member function template of the view instead of the
517 `get` member function template of the registry during iterations.
518 
519 ### Persistent View
520 
521 A persistent view returns all the entities and only the entities that have at
522 least the given components. Moreover, it's guaranteed that the entity list is
523 thightly packed in memory for fast iterations.<br/>
524 In general, persistent views don't stay true to the order of any set of
525 components unless users explicitly sort them.
526 
527 Persistent views can be used only to iterate multiple components. Create them
528 as it follows:
529 
530 ```cpp
531 auto view = registry.persistent<Position, Velocity>();
532 ```
533 
534 There is no need to store views around for they are extremely cheap to
535 construct, even though they can be copied without problems and reused
536 freely. In fact, they return newly created and correctly initialized iterators
537 whenever `begin` or `end` are invoked.<br/>
538 That being said, persistent views perform an initialization step the very first
539 time they are constructed and this could be quite costly. To avoid it, consider
540 asking to the registry to _prepare_ them when no entities have been created yet:
541 
542 ```cpp
543 registry.prepare<Position, Velocity>();
544 ```
545 
546 If the registry is empty, preparation is extremely fast. Moreover the `prepare`
547 member function template is idempotent. Feel free to invoke it even more than
548 once: if the view has been alreadt prepared before, the function returns
549 immediately and does nothing.
550 
551 A persistent view offers a bunch of functionalities to get the number of
552 entities it's going to return, a raw access to the entity list and the
553 possibility to sort the underlying data structures according to the order of one
554 of the components for which it has been constructed.<br/>
555 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
556 the details.
557 
558 To iterate a persistent view, just use it in range-for:
559 
560 ```cpp
561 auto view = registry.persistent<Position, Velocity>();
562 
563 for(auto entity: view) {
564  auto &position = view.get<Position>(entity);
565  auto &velocity = view.get<Velocity>(entity);
566 
567  // ...
568 }
569 ```
570 
571 **Note**: prefer the `get` member function template of the view instead of the
572 `get` member function template of the registry during iterations.
573 
574 ## Side notes
575 
576 * Entity identifiers are numbers and nothing more. They are not classes and they
577  have no member functions at all. As already mentioned, do no try to inspect or
578  modify an entity descriptor in any way.
579 
580 * As shown in the examples above, the preferred way to get references to the
581  components while iterating a view is by using the view itself. It's a faster
582  alternative to the `get` member function template that is part of the API of
583  the Registry. That's because the registry must ensure that a pool for the
584  given component exists before to use it; on the other side, views force the
585  construction of the pools for all their components and access them directly,
586  thus avoiding all the checks.
587 
588 * Most of the _ECS_ available out there have an annoying limitation (at least
589  from my point of view): entities and components cannot be created and/or
590  deleted during iterations.<br/>
591  `EnTT` partially solves the problem with a few limitations:
592 
593  * Creating entities and components is allowed during iterations.
594  * Deleting an entity or removing its components is allowed during
595  iterations if it's the one currently returned by a view. For all the
596  other entities, destroying them or removing their components isn't
597  allowed and it can result in undefined behavior.
598 
599  Iterators are invalidated and the behaviour is undefined if an entity is
600  modified or destroyed and it's not the one currently returned by the
601  view.<br/>
602  To work around it, possible approaches are:
603 
604  * Store aside the entities and the components to be removed and perform the
605  operations at the end of the iteration.
606  * Mark entities and components with a proper tag component that indicates
607  they must be purged, then perform a second iteration to clean them up one
608  by one.
609 
610 * Views and thus their iterators aren't thread safe. Do no try to iterate a set
611  of components and modify the same set concurrently.<br/>
612  That being said, as long as a thread iterates the entities that have the
613  component `X` or assign and removes that component from a set of entities,
614  another thread can safely do the same with components `Y` and `Z` and
615  everything will work like a charm.<br/>
616  As an example, users can freely execute the rendering system and iterate the
617  renderable entities while updating a physic component concurrently on a
618  separate thread if needed.
619 
620 ## What else?
621 
622 The `EnTT` framework is moving its first steps. More and more will come in the
623 future and hopefully I'm going to work on it for a long time.<br/>
624 Here is a brief list of what it offers today:
625 
626 * Statically generated integer identifiers for types.
627 * An entity-component system based on sparse sets.
628 * Signal handlers and event emitters of any type.
629 * ...
630 * Any other business.
631 
632 Consider it a work in progress. For more details and an updated list, please
633 refer to the [online documentation](https://skypjack.github.io/entt/).
634 
635 # Contributors
636 
637 If you want to contribute, please send patches as pull requests against the
638 branch `master`.<br/>
639 Check the
640 [contributors list](https://github.com/skypjack/entt/blob/master/AUTHORS) to see
641 who has partecipated so far.
642 
643 # License
644 
645 Code and documentation Copyright (c) 2017 Michele Caini.<br/>
646 Code released under
647 [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).
648 Docs released under
649 [Creative Commons](https://github.com/skypjack/entt/blob/master/docs/LICENSE).
650 
651 # Donation
652 
653 Developing and maintaining `EnTT` takes some time and lots of coffee. I'd like
654 to add more and more functionalities in future and turn it in a full-featured
655 framework.<br/>
656 If you want to support this project, you can offer me an espresso. I'm from
657 Italy, we're used to turning the best coffee ever in code. If you find that
658 it's not enough, feel free to support me the way you prefer.<br/>
659 Take a look at the donation button at the top of the page for more details or
660 just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).
+
1 # The EnTT Framework
2 
3 [![Build Status](https://travis-ci.org/skypjack/entt.svg?branch=master)](https://travis-ci.org/skypjack/entt)
4 [![Build status](https://ci.appveyor.com/api/projects/status/rvhaabjmghg715ck?svg=true)](https://ci.appveyor.com/project/skypjack/entt)
5 [![Coverage Status](https://coveralls.io/repos/github/skypjack/entt/badge.svg?branch=master)](https://coveralls.io/github/skypjack/entt?branch=master)
6 [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)
7 
8 # Introduction
9 
10 `EnTT` is a header-only, tiny and easy to use framework written in modern
11 C++.<br/>
12 It's entirely designed around an architectural pattern pattern called _ECS_ that
13 is used mostly in game development. For further details:
14 
15 * [Entity Systems Wiki](http://entity-systems.wikidot.com/)
16 * [Evolve Your Hierarchy](http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/)
17 * [ECS on Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system)
18 
19 Originally, `EnTT` was written as a faster alternative to other well known and
20 open source entity-component systems.<br/>
21 After a while the codebase has grown and more features have become part of the
22 framework.
23 
24 ## Code Example
25 
26 ```cpp
27 #include <registry.hpp>
28 
29 struct Position {
30  float x;
31  float y;
32 };
33 
34 struct Velocity {
35  float dx;
36  float dy;
37 };
38 
39 void update(entt::DefaultRegistry &registry) {
40  auto view = ecs.view<Position, Velocity>();
41 
42  for(auto entity: view) {
43  auto &position = view.get<Position>(entity);
44  auto &velocity = view.get<Velocity>(entity);
45  // ...
46  }
47 }
48 
49 int main() {
50  entt::DefaultRegistry registry;
51 
52  for(auto i = 0; i < 10; ++i) {
53  auto entity = registry.create();
54  registry.assign<Position>(entity, i * 1.f, i * 1.f);
55  if(i % 2 == 0) { registry.assign<Velocity>(entity, i * .1f, i * .1f); }
56  }
57 
58  update(registry);
59  // ...
60 }
61 ```
62 
63 ## Motivation
64 
65 I started working on `EnTT` because of the wrong reason: my goal was to design
66 an entity-component system that beated another well known open source solution
67 in terms of performance.<br/>
68 I did it, of course, but it wasn't much satisfying. Actually it wasn't
69 satisfying at all. The fastest and nothing more, fairly little indeed. When I
70 realized it, I tried hard to keep intact the great performance of `EnTT` and to
71 add all the features I wanted to see in *my* entity-component system at the same
72 time.
73 
74 Today `EnTT` is finally what I was looking for: still faster than its _rivals_,
75 a really good API and an amazing set of features. And even more, of course.
76 
77 ## Performance
78 
79 As it stands right now, `EnTT` is just fast enough for my requirements if
80 compared to my first choice (that was already amazingly fast indeed).<br/>
81 Here is a comparision between the two (both of them compiled with GCC 7.2.0 on a
82 Dell XPS 13 out of the mid 2014):
83 
84 | Benchmark | EntityX (experimental/compile_time) | EnTT |
85 |-----------|-------------|-------------|
86 | Creating 10M entities | 0.128881s | **0.0408754s** |
87 | Destroying 10M entities | **0.0531374s** | 0.0545839s |
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** |
102 | Sort 150k entities, one component | - | **0.0080046s** |
103 | Sort 150k entities, match two components | - | **0.00608322s** |
104 
105 `EnTT` includes its own tests and benchmarks. See
106 [benchmark.cpp](https://github.com/skypjack/entt/blob/master/test/benchmark.cpp)
107 for further details.<br/>
108 On Github users can find also a
109 [benchmark suite](https://github.com/abeimler/ecs_benchmark) that compares a
110 bunch of different projects, one of which is `EnTT`.
111 
112 Of course, probably I'll try to get out of `EnTT` more features and better
113 performance in the future, mainly for fun.<br/>
114 If you want to contribute and/or have any suggestion, feel free to make a PR or
115 open an issue to discuss your idea.
116 
117 # Build Instructions
118 
119 ## Requirements
120 
121 To be able to use `EnTT`, users must provide a full-featured compiler that
122 supports at least C++14.<br/>
123 The requirements below are mandatory to compile the tests and to extract the
124 documentation:
125 
126 * CMake version 3.2 or later.
127 * Doxygen version 1.8 or later.
128 
129 ## Library
130 
131 `EnTT` is a header-only library. This means that including the `entt.hpp`
132 header is enough to include the whole framework and use it. For those who are
133 interested only in the entity-component system, consider to include the sole
134 `entity/registry.hpp` header instead.<br/>
135 It's a matter of adding the following line to the top of a file:
136 
137 ```cpp
138 #include <entt/entt.hpp>
139 ```
140 
141 Use the line below to include only the entity-component system instead:
142 
143 ```cpp
144 #include <entt/entity/registry.hpp>
145 ```
146 
147 Then pass the proper `-I` argument to the compiler to add the `src` directory to
148 the include paths.
149 
150 ## Documentation
151 
152 The documentation is based on [doxygen](http://www.stack.nl/~dimitri/doxygen/).
153 To build it:
154 
155  $ cd build
156  $ cmake ..
157  $ make docs
158 
159 The API reference will be created in HTML format within the directory
160 `build/docs/html`. To navigate it with your favorite browser:
161 
162  $ cd build
163  $ your_favorite_browser docs/html/index.html
164 
165 The API reference is also available [online](https://skypjack.github.io/entt/)
166 for the latest version.
167 
168 ## Tests
169 
170 To compile and run the tests, `EnTT` requires *googletest*.<br/>
171 `cmake` will download and compile the library before to compile anything else.
172 
173 To build the tests:
174 
175 * `$ cd build`
176 * `$ cmake ..`
177 * `$ make`
178 * `$ make test`
179 
180 To build the benchmarks, use the following line instead:
181 
182 * `$ cmake -DCMAKE_BUILD_TYPE=Release ..`
183 
184 Benchmarks are compiled only in release mode currently.
185 
186 # Crash Course
187 
188 ## Vademecum
189 
190 The `Registry` to store, the `View`s to iterate. That's all.
191 
192 An entity (the _E_ of an _ECS_) is an opaque identifier that users should just
193 use as-is and store around if needed. Do not try to inspect an entity
194 identifier, its type can change in future and a registry offers all the
195 functionalities to query them out-of-the-box. The underlying type of an entity
196 (either `std::uint16_t`, `std::uint32_t` or `std::uint64_t`) can be specified
197 when defining a registry (actually the DefaultRegistry is nothing more than a
198 Registry where the type of the entities is `std::uint32_t`).<br/>
199 Components (the _C_ of an _ECS_) should be plain old data structures or more
200 complex and moveable data structures with a proper constructor. They are list
201 initialized by using the parameters provided to construct the component. No need
202 to register components or their types neither with the registry nor with the
203 entity-component system at all.<br/>
204 Systems (the _S_ of an _ECS_) are just plain functions, functors, lambdas or
205 whatever the users want. They can accept a Registry, a View or a PersistentView
206 and use them the way they prefer. No need to register systems or their types
207 neither with the registry nor with the entity-component system at all.
208 
209 The following sections will explain in short how to use the entity-component
210 system, the core part of the `EnTT` framework.<br/>
211 In fact, the framework is composed of many other classes in addition to those
212 describe below. For more details, please refer to the
213 [online documentation](https://skypjack.github.io/entt/).
214 
215 ## The Registry, the Entity and the Component
216 
217 A registry is used to store and manage entities as well as to create views to
218 iterate the underlying data structures.<br/>
219 Registry is a class template that lets the users decide what's the preferred
220 type to represent an entity. Because `std::uint32_t` is large enough for almost
221 all the cases, there exists also an alias named DefaultRegistry for
222 `Registry<std::uint32_t>`.
223 
224 Entities are represented by _entitiy identifiers_. An entity identifier is an
225 opaque type that users should not inspect or modify in any way. It carries
226 information about the entity itself and its version.
227 
228 A registry can be used both to construct and to destroy entities:
229 
230 ```cpp
231 // constructs a naked entity with no components ad returns its identifier
232 auto entity = registry.create();
233 
234 // constructs an entity and assigns it default-initialized components
235 auto another = registry.create<Position, Velocity>();
236 
237 // destroys an entity and all its components
238 registry.destroy(entity);
239 ```
240 
241 Once an entity is deleted, the registry can freely reuse it internally with a
242 slightly different identifier. In particular, the version of an entity is
243 increased each and every time it's destroyed.<br/>
244 In case entity identifiers are stored around, the registry offers all the
245 functionalities required to test them and get out of the them all the
246 information they carry:
247 
248 ```cpp
249 // returns true if the entity is still valid, false otherwise
250 bool b = registry.valid(entity);
251 
252 // gets the version contained in the entity identifier
253 auto version = registry.version(entity);
254 
255 // gets the actual version for the given entity
256 auto curr = registry.current(entity);
257 ```
258 
259 Components can be assigned to or removed from entities at any time with a few
260 calls to member functions of the registry. As for the entities, the registry
261 offers also a set of functionalities users can use to work with the components.
262 
263 The `assign` member function template creates, initializes and assigns to an
264 entity the given component. It accepts a variable number of arguments that are
265 used to construct the component itself if present:
266 
267 ```cpp
268 registry.assign<Position>(entity, 0., 0.);
269 
270 // ...
271 
272 auto &velocity = registry.assign<Velocity>(entity);
273 velocity.dx = 0.;
274 velocity.dy = 0.;
275 ```
276 
277 If the entity already has the given component, the `replace` member function
278 template can be used to replace it:
279 
280 ```cpp
281 registry.replace<Position>(entity, 0., 0.);
282 
283 // ...
284 
285 auto &velocity = registry.replace<Velocity>(entity);
286 velocity.dx = 0.;
287 velocity.dy = 0.;
288 ```
289 
290 In case users want to assign a component to an entity, but it's unknown whether
291 the entity already has it or not, `accomodate` does the work in a single call
292 (of course, there is a performance penalty to pay for that mainly due to the
293 fact that it must check if `entity` already has the given component or not):
294 
295 ```cpp
296 registry.accomodate<Position>(entity, 0., 0.);
297 
298 // ...
299 
300 auto &velocity = registry.accomodate<Velocity>(entity);
301 velocity.dx = 0.;
302 velocity.dy = 0.;
303 ```
304 
305 Note that `accomodate` is a sliglhty faster alternative for the following
306 `if`/`else` statement and nothing more:
307 
308 ```cpp
309 if(registry.has<Comp>(entity)) {
310  registry.replace<Comp>(entity, arg1, argN);
311 } else {
312  registry.assign<Comp>(entity, arg1, argN);
313 }
314 ```
315 
316 As already shown, if in doubt about whether or not an entity has one or more
317 components, the `has` member function template may be useful:
318 
319 ```cpp
320 bool b = registry.has<Position, Velocity>(entity);
321 ```
322 
323 On the other side, if the goal is to delete a single component, the `remove`
324 member function template is the way to go when it's certain that the entity owns
325 a copy of the component:
326 
327 ```cpp
328 registry.remove<Position>(entity);
329 ```
330 
331 Otherwise consider to use the `reset` member function. It behaves similarly to
332 `remove` but with a strictly defined behaviour (and a performance penalty is the
333 price to pay for that). In particular it removes the component if and only if it
334 exists, otherwise it returns safely to the caller:
335 
336 ```cpp
337 registry.reset<Position>(entity);
338 ```
339 
340 There exist also two other _versions_ of the `reset` member function:
341 
342 * If no entity is passed to it, `reset` will remove the given component from
343 each entity that has it:
344 
345  ```cpp
346  registry.reset<Position>();
347  ```
348 
349 * If neither the entity nor the component are specified, all the entities and
350 their components are destroyed:
351 
352  ```cpp
353  registry.reset();
354  ```
355 
356 Finally, references to components can be retrieved by just doing this:
357 
358 ```cpp
359 // either a non-const reference ...
360 DefaultRegistry registry;
361 auto &position = registry.get<Position>(entity);
362 
363 // ... or a const one
364 const auto &cregistry = registry;
365 const auto &position = cregistry.get<Position>(entity);
366 ```
367 
368 The `get` member function template gives direct access to the component of an
369 entity stored in the underlying data structures of the registry.
370 
371 ### Sorting: is it possible?
372 
373 Of course, sorting entities and components is possible with `EnTT`.<br/>
374 In fact, there are two functions that respond to slightly different needs:
375 
376 * Components can be sorted directly:
377 
378  ```cpp
379  registry.sort<Renderable>([](const auto &lhs, const auto &rhs) {
380  return lhs.z < rhs.z;
381  });
382  ```
383 
384 * Components can be sorted according to the order imposed by another component:
385 
386  ```cpp
387  registry.sort<Movement, Physics>();
388  ```
389 
390  In this case, instances of `Movement` are arranged in memory so that cache
391  misses are minimized when the two components are iterated together.
392 
393 ## View: to persist or not to persist?
394 
395 There are mainly two kinds of views: standard (also known as View) and
396 persistent (alsa known as PersistentView).<br/>
397 Both of them have pros and cons to take in consideration. In particular:
398 
399 * Standard views:
400 
401  Pros:
402  * They work out-of-the-box and don't require any dedicated data
403  structure.
404  * Creating and destroying them isn't expensive at all because they don't
405  have any type of initialization.
406  * They are the best tool to iterate single components.
407  * They are the best tool to iterate multiple components at once when
408  tags are involved or one of the component is assigned to a
409  significantly low number of entities.
410  * They don't affect any other operations of the registry.
411 
412  Cons:
413  * Their performance tend to degenerate when the number of components
414  to iterate grows up and the most of the entities have all of them.
415 
416 * Persistent views:
417 
418  Pros:
419  * Once prepared, creating and destroying them isn't expensive at all
420  because they don't have any type of initialization.
421  * They are the best tool to iterate multiple components at once when
422  the most of the entities have all of them.
423 
424  Cons:
425  * They have dedicated data structures and thus affect the memory
426  pressure to a minimal extent.
427  * If not previously prepared, the first time they are used they go
428  through an initialization step that could take a while.
429  * They affect to a minimum the creation and destruction of entities and
430  components. In other terms: the more persistent views there will be,
431  the less performing will be creating and destroying entities and
432  components.
433 
434 To sum up and as a rule of thumb, use a standard view:
435 * To iterate entities for a single component.
436 * To iterate entities for multiple components when a significantly low
437  number of entities have one of the components.
438 * In all those cases where a persistent view would give a boost to
439  performance but the iteration isn't performed frequently.
440 
441 Use a persistent view in all the other cases.
442 
443 To easily iterate entities, all the views offer _C++-ish_ `begin` and `end`
444 member functions that allow users to use them in a typical range-for loop.<br/>
445 Continue reading for more details or refer to the
446 [official documentation](https://skypjack.github.io/entt/).
447 
448 ### Standard View
449 
450 A standard view behaves differently if it's constructed for a single component
451 or if it has been requested to iterate multiple components. Even the API is
452 different in the two cases.<br/>
453 All that they share is the way they are created by means of a registry:
454 
455 ```cpp
456 // single component standard view
457 auto single = registry.view<Position>();
458 
459 // multi component standard view
460 auto multi = registry.view<Position, Velocity>();
461 ```
462 
463 For all that remains, it's worth discussing them separately.<br/>
464 
465 #### Single component standard view
466 
467 Single component standard views are specialized in order to give a boost in
468 terms of performance in all the situation. This kind of views can access the
469 underlying data structures directly and avoid superflous checks.<br/>
470 They offer a bunch of functionalities to get the number of entities they are
471 going to return and a raw access to the entity list as well as to the component
472 list.<br/>
473 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
474 the details.
475 
476 There is no need to store views around for they are extremely cheap to
477 construct, even though they can be copied without problems and reused
478 freely. In fact, they return newly created and correctly initialized iterators
479 whenever `begin` or `end` are invoked.<br/>
480 To iterate a single component standard view, just use it in range-for:
481 
482 ```cpp
483 auto view = registry.view<Renderable>();
484 
485 for(auto entity: view) {
486  auto &renderable = view.get(entity);
487 
488  // ...
489 }
490 ```
491 
492 **Note**: prefer the `get` member function of the view instead of the `get`
493 member function template of the registry during iterations.
494 
495 #### Multi component standard view
496 
497 Multi component standard views iterate entities that have at least all the given
498 components in their bags. During construction, these views look at the number
499 of entities available for each component and pick up a reference to the smallest
500 set of candidates in order to speed up iterations.<br/>
501 They offer fewer functionalities than their companion views for single
502 component, the most important of which can be used to reset the view and refresh
503 the reference to the set of candidate entities to iterate.<br/>
504 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
505 the details.
506 
507 There is no need to store views around for they are extremely cheap to
508 construct, even though they can be copied without problems and reused
509 freely. In fact, they return newly created and correctly initialized iterators
510 whenever `begin` or `end` are invoked.<br/>
511 To iterate a multi component standard view, just use it in range-for:
512 
513 ```cpp
514 auto view = registry.view<Position, Velocity>();
515 
516 for(auto entity: view) {
517  auto &position = view.get<Position>(entity);
518  auto &velocity = view.get<Velocity>(entity);
519 
520  // ...
521 }
522 ```
523 
524 **Note**: prefer the `get` member function template of the view instead of the
525 `get` member function template of the registry during iterations.
526 
527 ### Persistent View
528 
529 A persistent view returns all the entities and only the entities that have at
530 least the given components. Moreover, it's guaranteed that the entity list is
531 thightly packed in memory for fast iterations.<br/>
532 In general, persistent views don't stay true to the order of any set of
533 components unless users explicitly sort them.
534 
535 Persistent views can be used only to iterate multiple components. Create them
536 as it follows:
537 
538 ```cpp
539 auto view = registry.persistent<Position, Velocity>();
540 ```
541 
542 There is no need to store views around for they are extremely cheap to
543 construct, even though they can be copied without problems and reused
544 freely. In fact, they return newly created and correctly initialized iterators
545 whenever `begin` or `end` are invoked.<br/>
546 That being said, persistent views perform an initialization step the very first
547 time they are constructed and this could be quite costly. To avoid it, consider
548 asking to the registry to _prepare_ them when no entities have been created yet:
549 
550 ```cpp
551 registry.prepare<Position, Velocity>();
552 ```
553 
554 If the registry is empty, preparation is extremely fast. Moreover the `prepare`
555 member function template is idempotent. Feel free to invoke it even more than
556 once: if the view has been alreadt prepared before, the function returns
557 immediately and does nothing.
558 
559 A persistent view offers a bunch of functionalities to get the number of
560 entities it's going to return, a raw access to the entity list and the
561 possibility to sort the underlying data structures according to the order of one
562 of the components for which it has been constructed.<br/>
563 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
564 the details.
565 
566 To iterate a persistent view, just use it in range-for:
567 
568 ```cpp
569 auto view = registry.persistent<Position, Velocity>();
570 
571 for(auto entity: view) {
572  auto &position = view.get<Position>(entity);
573  auto &velocity = view.get<Velocity>(entity);
574 
575  // ...
576 }
577 ```
578 
579 **Note**: prefer the `get` member function template of the view instead of the
580 `get` member function template of the registry during iterations.
581 
582 ## Side notes
583 
584 * Entity identifiers are numbers and nothing more. They are not classes and they
585  have no member functions at all. As already mentioned, do no try to inspect or
586  modify an entity descriptor in any way.
587 
588 * As shown in the examples above, the preferred way to get references to the
589  components while iterating a view is by using the view itself. It's a faster
590  alternative to the `get` member function template that is part of the API of
591  the Registry. That's because the registry must ensure that a pool for the
592  given component exists before to use it; on the other side, views force the
593  construction of the pools for all their components and access them directly,
594  thus avoiding all the checks.
595 
596 * Most of the _ECS_ available out there have an annoying limitation (at least
597  from my point of view): entities and components cannot be created and/or
598  deleted during iterations.<br/>
599  `EnTT` partially solves the problem with a few limitations:
600 
601  * Creating entities and components is allowed during iterations.
602  * Deleting an entity or removing its components is allowed during
603  iterations if it's the one currently returned by a view. For all the
604  other entities, destroying them or removing their components isn't
605  allowed and it can result in undefined behavior.
606 
607  Iterators are invalidated and the behaviour is undefined if an entity is
608  modified or destroyed and it's not the one currently returned by the
609  view.<br/>
610  To work around it, possible approaches are:
611 
612  * Store aside the entities and the components to be removed and perform the
613  operations at the end of the iteration.
614  * Mark entities and components with a proper tag component that indicates
615  they must be purged, then perform a second iteration to clean them up one
616  by one.
617 
618 * Views and thus their iterators aren't thread safe. Do no try to iterate a set
619  of components and modify the same set concurrently.<br/>
620  That being said, as long as a thread iterates the entities that have the
621  component `X` or assign and removes that component from a set of entities,
622  another thread can safely do the same with components `Y` and `Z` and
623  everything will work like a charm.<br/>
624  As an example, users can freely execute the rendering system and iterate the
625  renderable entities while updating a physic component concurrently on a
626  separate thread if needed.
627 
628 ## What else?
629 
630 The `EnTT` framework is moving its first steps. More and more will come in the
631 future and hopefully I'm going to work on it for a long time.<br/>
632 Here is a brief list of what it offers today:
633 
634 * Statically generated integer identifiers for types.
635 * An entity-component system based on sparse sets.
636 * Signal handlers and event emitters of any type.
637 * ...
638 * Any other business.
639 
640 Consider it a work in progress. For more details and an updated list, please
641 refer to the [online documentation](https://skypjack.github.io/entt/).
642 
643 # Contributors
644 
645 If you want to contribute, please send patches as pull requests against the
646 branch `master`.<br/>
647 Check the
648 [contributors list](https://github.com/skypjack/entt/blob/master/AUTHORS) to see
649 who has partecipated so far.
650 
651 # License
652 
653 Code and documentation Copyright (c) 2017 Michele Caini.<br/>
654 Code released under
655 [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).
656 Docs released under
657 [Creative Commons](https://github.com/skypjack/entt/blob/master/docs/LICENSE).
658 
659 # Donation
660 
661 Developing and maintaining `EnTT` takes some time and lots of coffee. I'd like
662 to add more and more functionalities in future and turn it in a full-featured
663 framework.<br/>
664 If you want to support this project, you can offer me an espresso. I'm from
665 Italy, we're used to turning the best coffee ever in code. If you find that
666 it's not enough, feel free to support me the way you prefer.<br/>
667 Take a look at the donation button at the top of the page for more details or
668 just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).
Generated by   diff --git a/index.html b/index.html index 34ddb974a..1558ed498 100644 --- a/index.html +++ b/index.html @@ -142,9 +142,10 @@ Requirements

Library

-

EnTT is a header-only library. This means that including the registry.hpp header is enough to use it.
- It's a matter of adding the following line at the top of a file:

-
#include <registry.hpp>

Then pass the proper -I argument to the compiler to add the src directory to the include paths.

+

EnTT is a header-only library. This means that including the entt.hpp header is enough to include the whole framework and use it. For those who are interested only in the entity-component system, consider to include the sole entity/registry.hpp header instead.
+ It's a matter of adding the following line to the top of a file:

+
#include <entt/entt.hpp>

Use the line below to include only the entity-component system instead:

+
#include <entt/entity/registry.hpp>

Then pass the proper -I argument to the compiler to add the src directory to the include paths.

Documentation

The documentation is based on doxygen. To build it: 

$ cd build
@@ -206,7 +207,7 @@ The Registry, the Entity and the Component
 
// either a non-const reference ...
DefaultRegistry registry;
auto &position = registry.get<Position>(entity);
// ... or a const one
const auto &cregistry = registry;
const auto &position = cregistry.get<Position>(entity);
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.

+
Of course, sorting entities and components is possible with EnTT.

  In fact, there are two functions that respond to slightly different needs:

 
    
 
  • Components can be sorted directly:
    • 
diff --git a/sigh_8hpp_source.html b/sigh_8hpp_source.html
index 45a547491..fa3070cca 100644
--- a/sigh_8hpp_source.html
+++ b/sigh_8hpp_source.html
@@ -67,7 +67,7 @@ $(function() {
 
    sigh.hpp
      
 
 
    
-
        1 #ifndef ENTT_SIGNAL_SIGH_HPP
        2 #define ENTT_SIGNAL_SIGH_HPP
        3 
        4 
        5 #include <algorithm>
        6 #include <utility>
        7 #include <vector>
        8 
        9 
       10 namespace entt {
       11 
       12 
       13 namespace {
       14 
       15 
       16 template<typename, typename>
       17 struct Invoker;
       18 
       19 
       20 template<typename Ret, typename... Args, typename Collector>
       21 struct Invoker<Ret(Args...), Collector> {
       22     using proto_type = Ret(*)(void *, Args...);
       23     using call_type = std::pair<void *, proto_type>;
       24 
       25     virtual ~Invoker() = default;
       26 
       27     template<typename SFINAE = Ret>
       28     typename std::enable_if<std::is_void<SFINAE>::value, bool>::type
       29     invoke(Collector &, proto_type proto, void *instance, Args... args) {
       30         proto(instance, args...);
       31         return true;
       32     }
       33 
       34     template<typename SFINAE = Ret>
       35     typename std::enable_if<not std::is_void<SFINAE>::value, bool>::type
       36     invoke(Collector &collector, proto_type proto, void *instance, Args... args) {
       37         return collector(proto(instance, args...));
       38     }
       39 };
       40 
       41 
       42 template<typename Ret>
       43 struct NullCollector final {
       44     using result_type = Ret;
       45     bool operator()(result_type) const noexcept { return true; }
       46 };
       47 
       48 
       49 template<>
       50 struct NullCollector<void> final {
       51     using result_type = void;
       52     bool operator()() const noexcept { return true; }
       53 };
       54 
       55 
       56 template<typename>
       57 struct DefaultCollector;
       58 
       59 
       60 template<typename Ret, typename... Args>
       61 struct DefaultCollector<Ret(Args...)> final {
       62     using collector_type = NullCollector<Ret>;
       63 };
       64 
       65 
       66 template<typename Function>
       67 using DefaultCollectorType = typename DefaultCollector<Function>::collector_type;
       68 
       69 
       70 }
       71 
       72 
       79 template<typename Function, typename = DefaultCollectorType<Function>>
       80 class SigH;
       81 
       82 
      104 template<typename Ret, typename... Args, typename Collector>
      105 class SigH<Ret(Args...), Collector> final: private Invoker<Ret(Args...), Collector> {
      106     using typename Invoker<Ret(Args...), Collector>::call_type;
      107 
      108     template<Ret(*Function)(Args...)>
      109     static Ret proto(void *, Args... args) {
      110         return (Function)(args...);
      111     }
      112 
      113     template<typename Class, Ret(Class::*Member)(Args... args)>
      114     static Ret proto(void *instance, Args... args) {
      115         return (static_cast<Class *>(instance)->*Member)(args...);
      116     }
      117 
      118 public:
      120     using size_type = typename std::vector<call_type>::size_type;
      122     using collector_type = Collector;
      123 
      125     explicit SigH() noexcept = default;
      126 
      128     ~SigH() noexcept = default;
      129 
      134     SigH(const SigH &other)
      135         : calls{other.calls}
      136     {}
      137 
      142     SigH(SigH &&other): SigH{} {
      143         swap(*this, other);
      144     }
      145 
      151     SigH & operator=(const SigH &other) {
      152         calls = other.calls;
      153         return *this;
      154     }
      155 
      161     SigH & operator=(SigH &&other) {
      162         swap(*this, other);
      163         return *this;
      164     }
      165 
      170     size_type size() const noexcept {
      171         return calls.size();
      172     }
      173 
      178     bool empty() const noexcept {
      179         return calls.empty();
      180     }
      181 
      185     void clear() noexcept {
      186         calls.clear();
      187     }
      188 
      198     template<Ret(*Function)(Args...)>
      199     void connect() {
      200         disconnect<Function>();
      201         calls.emplace_back(nullptr, &proto<Function>);
      202     }
      203 
      219     template <typename Class, Ret(Class::*Member)(Args...)>
      220     void connect(Class *instance) {
      221         disconnect<Class, Member>(instance);
      222         calls.emplace_back(instance, &proto<Class, Member>);
      223     }
      224 
      229     template<Ret(*Function)(Args...)>
      230     void disconnect() {
      231         call_type target{nullptr, &proto<Function>};
      232         calls.erase(std::remove(calls.begin(), calls.end(), std::move(target)), calls.end());
      233     }
      234 
      241     template<typename Class, Ret(Class::*Member)(Args...)>
      242     void disconnect(Class *instance) {
      243         call_type target{instance, &proto<Class, Member>};
      244         calls.erase(std::remove(calls.begin(), calls.end(), std::move(target)), calls.end());
      245     }
      246 
      252     template<typename Class>
      253     void disconnect(Class *instance) {
      254         auto func = [instance](const call_type &call) { return call.first == instance; };
      255         calls.erase(std::remove_if(calls.begin(), calls.end(), std::move(func)), calls.end());
      256     }
      257 
      265     void publish(Args... args) {
      266         for(auto &&call: calls) {
      267             call.second(call.first, args...);
      268         }
      269     }
      270 
      276     collector_type collect(Args... args) {
      277         collector_type collector;
      278 
      279         for(auto &&call: calls) {
      280             if(!this->invoke(collector, call.second, call.first, args...)) {
      281                 break;
      282             }
      283         }
      284 
      285         return collector;
      286     }
      287 
      293     friend void swap(SigH &lhs, SigH &rhs) {
      294         using std::swap;
      295         swap(lhs.calls, rhs.calls);
      296     }
      297 
      307     bool operator==(const SigH &other) const noexcept {
      308         return (calls.size() == other.calls.size()) && std::equal(calls.cbegin(), calls.cend(), other.calls.cbegin());
      309     }
      310 
      311 private:
      312     std::vector<call_type> calls;
      313 };
      314 
      315 
      328 template<typename Ret, typename... Args>
      329 bool operator!=(const SigH<Ret(Args...)> &lhs, const SigH<Ret(Args...)> &rhs) noexcept {
      330     return !(lhs == rhs);
      331 }
      332 
      333 
      341 template<typename Event>
      342 using EventH = SigH<void(const Event &)>;
      343 
      344 
      345 }
      346 
      347 
      348 #endif // ENTT_SIGNAL_SIGH_HPP
    entt::SigH< Ret(Args...), Collector >::collector_type
    Collector collector_type
    Collector type. 
    Definition: sigh.hpp:122
    
+
        1 #ifndef ENTT_SIGNAL_SIGH_HPP
        2 #define ENTT_SIGNAL_SIGH_HPP
        3 
        4 
        5 #include <algorithm>
        6 #include <utility>
        7 #include <vector>
        8 
        9 
       10 namespace entt {
       11 
       12 
       13 namespace {
       14 
       15 
       16 template<typename, typename>
       17 struct Invoker;
       18 
       19 
       20 template<typename Ret, typename... Args, typename Collector>
       21 struct Invoker<Ret(Args...), Collector> {
       22     using proto_type = Ret(*)(void *, Args...);
       23     using call_type = std::pair<void *, proto_type>;
       24 
       25     virtual ~Invoker() = default;
       26 
       27     template<typename SFINAE = Ret>
       28     typename std::enable_if<std::is_void<SFINAE>::value, bool>::type
       29     invoke(Collector &, proto_type proto, void *instance, Args... args) {
       30         proto(instance, args...);
       31         return true;
       32     }
       33 
       34     template<typename SFINAE = Ret>
       35     typename std::enable_if<!std::is_void<SFINAE>::value, bool>::type
       36     invoke(Collector &collector, proto_type proto, void *instance, Args... args) {
       37         return collector(proto(instance, args...));
       38     }
       39 };
       40 
       41 
       42 template<typename Ret>
       43 struct NullCollector final {
       44     using result_type = Ret;
       45     bool operator()(result_type) const noexcept { return true; }
       46 };
       47 
       48 
       49 template<>
       50 struct NullCollector<void> final {
       51     using result_type = void;
       52     bool operator()() const noexcept { return true; }
       53 };
       54 
       55 
       56 template<typename>
       57 struct DefaultCollector;
       58 
       59 
       60 template<typename Ret, typename... Args>
       61 struct DefaultCollector<Ret(Args...)> final {
       62     using collector_type = NullCollector<Ret>;
       63 };
       64 
       65 
       66 template<typename Function>
       67 using DefaultCollectorType = typename DefaultCollector<Function>::collector_type;
       68 
       69 
       70 }
       71 
       72 
       79 template<typename Function, typename = DefaultCollectorType<Function>>
       80 class SigH;
       81 
       82 
      104 template<typename Ret, typename... Args, typename Collector>
      105 class SigH<Ret(Args...), Collector> final: private Invoker<Ret(Args...), Collector> {
      106     using typename Invoker<Ret(Args...), Collector>::call_type;
      107 
      108     template<Ret(*Function)(Args...)>
      109     static Ret proto(void *, Args... args) {
      110         return (Function)(args...);
      111     }
      112 
      113     template<typename Class, Ret(Class::*Member)(Args... args)>
      114     static Ret proto(void *instance, Args... args) {
      115         return (static_cast<Class *>(instance)->*Member)(args...);
      116     }
      117 
      118 public:
      120     using size_type = typename std::vector<call_type>::size_type;
      122     using collector_type = Collector;
      123 
      125     explicit SigH() noexcept = default;
      126 
      128     ~SigH() noexcept = default;
      129 
      134     SigH(const SigH &other)
      135         : calls{other.calls}
      136     {}
      137 
      142     SigH(SigH &&other): SigH{} {
      143         swap(*this, other);
      144     }
      145 
      151     SigH & operator=(const SigH &other) {
      152         calls = other.calls;
      153         return *this;
      154     }
      155 
      161     SigH & operator=(SigH &&other) {
      162         swap(*this, other);
      163         return *this;
      164     }
      165 
      170     size_type size() const noexcept {
      171         return calls.size();
      172     }
      173 
      178     bool empty() const noexcept {
      179         return calls.empty();
      180     }
      181 
      185     void clear() noexcept {
      186         calls.clear();
      187     }
      188 
      198     template<Ret(*Function)(Args...)>
      199     void connect() {
      200         disconnect<Function>();
      201         calls.emplace_back(nullptr, &proto<Function>);
      202     }
      203 
      219     template <typename Class, Ret(Class::*Member)(Args...)>
      220     void connect(Class *instance) {
      221         disconnect<Class, Member>(instance);
      222         calls.emplace_back(instance, &proto<Class, Member>);
      223     }
      224 
      229     template<Ret(*Function)(Args...)>
      230     void disconnect() {
      231         call_type target{nullptr, &proto<Function>};
      232         calls.erase(std::remove(calls.begin(), calls.end(), std::move(target)), calls.end());
      233     }
      234 
      241     template<typename Class, Ret(Class::*Member)(Args...)>
      242     void disconnect(Class *instance) {
      243         call_type target{instance, &proto<Class, Member>};
      244         calls.erase(std::remove(calls.begin(), calls.end(), std::move(target)), calls.end());
      245     }
      246 
      252     template<typename Class>
      253     void disconnect(Class *instance) {
      254         auto func = [instance](const call_type &call) { return call.first == instance; };
      255         calls.erase(std::remove_if(calls.begin(), calls.end(), std::move(func)), calls.end());
      256     }
      257 
      265     void publish(Args... args) {
      266         for(auto &&call: calls) {
      267             call.second(call.first, args...);
      268         }
      269     }
      270 
      276     collector_type collect(Args... args) {
      277         collector_type collector;
      278 
      279         for(auto &&call: calls) {
      280             if(!this->invoke(collector, call.second, call.first, args...)) {
      281                 break;
      282             }
      283         }
      284 
      285         return collector;
      286     }
      287 
      293     friend void swap(SigH &lhs, SigH &rhs) {
      294         using std::swap;
      295         swap(lhs.calls, rhs.calls);
      296     }
      297 
      307     bool operator==(const SigH &other) const noexcept {
      308         return (calls.size() == other.calls.size()) && std::equal(calls.cbegin(), calls.cend(), other.calls.cbegin());
      309     }
      310 
      311 private:
      312     std::vector<call_type> calls;
      313 };
      314 
      315 
      328 template<typename Ret, typename... Args>
      329 bool operator!=(const SigH<Ret(Args...)> &lhs, const SigH<Ret(Args...)> &rhs) noexcept {
      330     return !(lhs == rhs);
      331 }
      332 
      333 
      341 template<typename Event>
      342 using EventH = SigH<void(const Event &)>;
      343 
      344 
      345 }
      346 
      347 
      348 #endif // ENTT_SIGNAL_SIGH_HPP
    entt::SigH< Ret(Args...), Collector >::collector_type
    Collector collector_type
    Collector type. 
    Definition: sigh.hpp:122
    
 
    entt::SigH< Ret(Args...), Collector >::operator=
    SigH & operator=(const SigH &other)
    Assignment operator, listeners are also connected to this signal. 
    Definition: sigh.hpp:151
    
 
    entt
    EnTT default namespace. 
    Definition: family.hpp:10
    
 
    entt::SigH< Ret(Args...), Collector >::operator==
    bool operator==(const SigH &other) const noexcept
    Checks if the contents of the two signals are identical. 
    Definition: sigh.hpp:307