diff --git a/README_8md_source.html b/README_8md_source.html index 434cb0e16..981e9a61a 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 ### API Reference
145 
146 The documentation is based on [doxygen](http://www.stack.nl/~dimitri/doxygen/).
147 To build it:
148 
149 $ cd build
150 $ cmake ..
151 $ make docs
152 
153 The API reference will be created in HTML format within the directory
154 `build/docs/html`. To navigate it with your favorite browser:
155 
156 $ cd build
157 $ your_favorite_browser docs/html/index.html
158 
159 The API reference is also available [online](https://skypjack.github.io/entt/)
160 for the latest version.
161 
162 ### Crash Course
163 
164 #### Vademecum
165 
166 The `Registry` to store, the `View`s to iterate. That's all.
167 
168 An entity (the _E_ of an _ECS_) is an opaque identifier that users should just
169 use as-is and store around if needed. Do not try to inspect an entity
170 identifier, its type can change in future and a registry offers all the
171 functionalities to query them out-of-the-box. The underlying type of an entity
172 (either `std::uint16_t`, `std::uint32_t` or `std::uint64_t`) can be specified
173 when defining a registry (actually the DefaultRegistry is nothing more than a
174 Registry where the type of the entities is `std::uint32_t`).<br/>
175 Components (the _C_ of an _ECS_) should be plain old data structures or more
176 complex and moveable data structures with a proper constructor. They are list
177 initialized by using the parameters provided to construct the component. No need
178 to register components or their types neither with the registry nor with the
179 entity-component system at all.<br/>
180 Systems (the _S_ of an _ECS_) are just plain functions, functors, lambdas or
181 whatever the users want. They can accept a Registry, a View or a PersistentView
182 and use them the way they prefer. No need to register systems or their types
183 neither with the registry nor with the entity-component system at all.
184 
185 The following sections will explain in short how to use the entity-component
186 system, the core part of the `EnTT` framework.<br/>
187 In fact, the framework is composed of many other classes in addition to those
188 describe below. For more details, please refer to the
189 [online documentation](https://skypjack.github.io/entt/).
190 
191 #### The Registry, the Entity and the Component
192 
193 A registry is used to store and manage entities as well as to create views to
194 iterate the underlying data structures.<br/>
195 Registry is a class template that lets the users decide what's the preferred
196 type to represent an entity. Because `std::uint32_t` is large enough for almost
197 all the cases, there exists also an alias named DefaultRegistry for
198 `Registry<std::uint32_t>`.
199 
200 Entities are represented by _entitiy identifiers_. An entity identifier is an
201 opaque type that users should not inspect or modify in any way. It carries
202 information about the entity itself and its version.
203 
204 A registry can be used both to construct and to destroy entities:
205 
206 ```cpp
207 // constructs a naked entity with no components ad returns its identifier
208 auto entity = registry.create();
209 
210 // constructs an entity and assigns it default-initialized components
211 auto another = registry.create<Position, Velocity>();
212 
213 // destroys an entity and all its components
214 registry.destroy(entity);
215 ```
216 
217 Once an entity is deleted, the registry can freely reuse it internally with a
218 slightly different identifier. In particular, the version of an entity is
219 increased each and every time it's destroyed.<br/>
220 In case entity identifiers are stored around, the registry offers all the
221 functionalities required to test them and get out of the them all the
222 information they carry:
223 
224 ```cpp
225 // returns true if the entity is still valid, false otherwise
226 bool b = registry.valid(entity);
227 
228 // gets the version contained in the entity identifier
229 auto version = registry.version(entity);
230 
231 // gets the actual version for the given entity
232 auto curr = registry.current(entity);
233 ```
234 
235 Components can be assigned to or removed from entities at any time with a few
236 calls to member functions of the registry. As for the entities, the registry
237 offers also a set of functionalities users can use to work with the components.
238 
239 The `assign` member function template creates, initializes and assigns to an
240 entity the given component. It accepts a variable number of arguments that are
241 used to construct the component itself if present:
242 
243 ```cpp
244 registry.assign<Position>(entity, 0., 0.);
245 
246 // ...
247 
248 auto &velocity = registry.assign<Velocity>(entity);
249 velocity.dx = 0.;
250 velocity.dy = 0.;
251 ```
252 
253 If the entity already has the given component, the `replace` member function
254 template can be used to replace it:
255 
256 ```cpp
257 registry.replace<Position>(entity, 0., 0.);
258 
259 // ...
260 
261 auto &velocity = registry.replace<Velocity>(entity);
262 velocity.dx = 0.;
263 velocity.dy = 0.;
264 ```
265 
266 In case users want to assign a component to an entity, but it's unknown whether
267 the entity already has it or not, `accomodate` does the work in a single call
268 (of course, there is a performance penalty to pay for that mainly due to the
269 fact that it must check if `entity` already has the given component or not):
270 
271 ```cpp
272 registry.accomodate<Position>(entity, 0., 0.);
273 
274 // ...
275 
276 auto &velocity = registry.accomodate<Velocity>(entity);
277 velocity.dx = 0.;
278 velocity.dy = 0.;
279 ```
280 
281 Note that `accomodate` is a sliglhty faster alternative for the following
282 `if`/`else` statement and nothing more:
283 
284 ```cpp
285 if(registry.has<Comp>(entity)) {
286  registry.replace<Comp>(entity, arg1, argN);
287 } else {
288  registry.assign<Comp>(entity, arg1, argN);
289 }
290 ```
291 
292 As already shown, if in doubt about whether or not an entity has one or more
293 components, the `has` member function template may be useful:
294 
295 ```cpp
296 bool b = registry.has<Position, Velocity>(entity);
297 ```
298 
299 On the other side, if the goal is to delete a single component, the `remove`
300 member function template is the way to go when it's certain that the entity owns
301 a copy of the component:
302 
303 ```cpp
304 registry.remove<Position>(entity);
305 ```
306 
307 Otherwise consider to use the `reset` member function. It behaves similarly to
308 `remove` but with a strictly defined behaviour (and a performance penalty is the
309 price to pay for that). In particular it removes the component if and only if it
310 exists, otherwise it returns safely to the caller:
311 
312 ```cpp
313 registry.reset<Position>(entity);
314 ```
315 
316 There exist also two other _versions_ of the `reset` member function:
317 
318 * If no entity is passed to it, `reset` will remove the given component from
319 each entity that has it:
320 
321  ```cpp
322  registry.reset<Position>();
323  ```
324 
325 * If neither the entity nor the component are specified, all the entities and
326 their components are destroyed:
327 
328  ```cpp
329  registry.reset();
330  ```
331 
332 Finally, references to components can be retrieved by just doing this:
333 
334 ```cpp
335 // either a non-const reference ...
336 DefaultRegistry registry;
337 auto &position = registry.get<Position>(entity);
338 
339 // ... or a const one
340 const auto &cregistry = registry;
341 const auto &position = cregistry.get<Position>(entity);
342 ```
343 
344 The `get` member function template gives direct access to the component of an
345 entity stored in the underlying data structures of the registry.
346 
347 ##### Sorting: is it possible?
348 
349 Of course, sorting entities and components is an option with `EnTT`.<br/>
350 In fact, there are two functions that respond to slightly different needs:
351 
352 * Components can be sorted directly:
353 
354  ```cpp
355  registry.sort<Renderable>([](const auto &lhs, const auto &rhs) {
356  return lhs.z < rhs.z;
357  });
358  ```
359 
360 * Components can be sorted according to the order imposed by another component:
361 
362  ```cpp
363  registry.sort<Movement, Physics>();
364  ```
365 
366  In this case, instances of `Movement` are arranged in memory so that cache
367  misses are minimized when the two components are iterated together.
368 
369 #### View: to persist or not to persist?
370 
371 There are mainly two kinds of views: standard (also known as View) and
372 persistent (alsa known as PersistentView).<br/>
373 Both of them have pros and cons to take in consideration. In particular:
374 
375 * Standard views:
376  Pros:
377  * They work out-of-the-box and don't require any dedicated data
378  structure.
379  * Creating and destroying them isn't expensive at all because they don't
380  have any type of initialization.
381  * They are the best tool to iterate single components.
382  * They are the best tool to iterate multiple components at once when
383  tags are involved or one of the component is assigned to a
384  significantly low number of entities.
385  * They don't affect any other operations of the registry.
386  Cons:
387  * Their performance tend to degenerate when the number of components
388  to iterate grows up and the most of the entities have all of them.
389 
390 * Persistent views:
391  Pros:
392  * Once prepared, creating and destroying them isn't expensive at all
393  because they don't have any type of initialization.
394  * They are the best tool to iterate multiple components at once when
395  the most of the entities have all of them.
396  Cons:
397  * They have dedicated data structures and thus affect the memory
398  pressure to a minimal extent.
399  * If not previously prepared, the first time they are used they go
400  through an initialization step that could take a while.
401  * They affect to a minimum the creation and destruction of entities and
402  components. In other terms: the more persistent views there will be,
403  the less performing will be creating and destroying entities and
404  components.
405 
406 To sum up and as a rule of thumb, use a standard view:
407  * To iterate entities for a single component.
408  * To iterate entities for multiple components when a significantly low
409  number of entities have one of the components.
410  * In all those cases where a persistent view would give a boost to
411  performance but the iteration isn't performed frequently.
412 
413 Use a persistent view in all the other cases.
414 
415 To easily iterate entities, all the views offer _C++-ish_ `begin` and `end`
416 member functions that allow users to use them in a typical range-for loop.<br/>
417 Continue reading for more details or refer to the
418 [official documentation](https://skypjack.github.io/entt/).
419 
420 ##### Standard View
421 
422 A standard view behaves differently if it's constructed for a single component
423 or if it has been requested to iterate multiple components. Even the API is
424 different in the two cases.<br/>
425 All that they share is the way they are created by means of a registry:
426 
427 ```cpp
428 // single component standard view
429 auto single = registry.view<Position>();
430 
431 // multi component standard view
432 auto multi = registry.view<Position, Velocity>();
433 ```
434 
435 For all that remains, it's worth discussing them separately.<br/>
436 
437 ###### Single component
438 
439 Single component standard views are specialized in order to give a boost in
440 terms of performance in all the situation. This kind of views can access the
441 underlying data structures directly and avoid superflous checks.<br/>
442 They offer a bunch of functionalities to get the number of entities they are
443 going to return and a raw access to the entity list as well as to the component
444 list.<br/>
445 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
446 the details.
447 
448 There is no need to store views around for they are extremely cheap to
449 construct, even though they can be copied without problems and reused
450 freely. In fact, they return newly created and correctly initialized iterators
451 whenever `begin` or `end` are invoked.<br/>
452 To iterate a single component standard view, just use it in range-for:
453 
454 ```cpp
455 auto view = registry.view<Renderable>();
456 
457 for(auto entity: view) {
458  auto &renderable = view.get(entity);
459 
460  // ...
461 }
462 ```
463 
464 **Note**: prefer the `get` member function of the view instead of the `get`
465 member function template of the registry during iterations.
466 
467 ###### Multi component
468 
469 Multi component standard views iterate entities that have at least all the given
470 components in their bags. During construction, these views look at the number
471 of entities available for each component and pick up a reference to the smallest
472 set of candidates in order to speed up iterations.<br/>
473 They offer fewer functionalities than their companion views for single
474 component, the most important of which can be used to reset the view and refresh
475 the reference to the set of candidate entities to iterate.<br/>
476 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
477 the details.
478 
479 There is no need to store views around for they are extremely cheap to
480 construct, even though they can be copied without problems and reused
481 freely. In fact, they return newly created and correctly initialized iterators
482 whenever `begin` or `end` are invoked.<br/>
483 To iterate a multi component standard view, just use it in range-for:
484 
485 ```cpp
486 auto view = registry.view<Position, Velocity>();
487 
488 for(auto entity: view) {
489  auto &position = view.get<Position>(entity);
490  auto &velocity = view.get<Velocity>(entity);
491 
492  // ...
493 }
494 ```
495 
496 **Note**: prefer the `get` member function template of the view instead of the
497 `get` member function template of the registry during iterations.
498 
499 ##### Persistent View
500 
501 A persistent view returns all the entities and only the entities that have at
502 least the given components. Moreover, it's guaranteed that the entity list is
503 thightly packed in memory for fast iterations.<br/>
504 In general, persistent views don't stay true to the order of any set of
505 components unless users explicitly sort them.
506 
507 Persistent views can be used only to iterate multiple components. Create them
508 as it follows:
509 
510 ```cpp
511 auto view = registry.persistent<Position, Velocity>();
512 ```
513 
514 There is no need to store views around for they are extremely cheap to
515 construct, even though they can be copied without problems and reused
516 freely. In fact, they return newly created and correctly initialized iterators
517 whenever `begin` or `end` are invoked.<br/>
518 That being said, persistent views perform an initialization step the very first
519 time they are constructed and this could be quite costly. To avoid it, consider
520 asking to the registry to _prepare_ them when no entities have been created yet:
521 
522 ```cpp
523 registry.prepare<Position, Velocity>();
524 ```
525 
526 If the registry is empty, preparation is extremely fast. Moreover the `prepare`
527 member function template is idempotent. Feel free to invoke it even more than
528 once: if the view has been alreadt prepared before, the function returns
529 immediately and does nothing.
530 
531 A persistent view offers a bunch of functionalities to get the number of
532 entities it's going to return, a raw access to the entity list and the
533 possibility to sort the underlying data structures according to the order of one
534 of the components for which it has been constructed.<br/>
535 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
536 the details.
537 
538 To iterate a persistent view, just use it in range-for:
539 
540 ```cpp
541 auto view = registry.persistent<Position, Velocity>();
542 
543 for(auto entity: view) {
544  auto &position = view.get<Position>(entity);
545  auto &velocity = view.get<Velocity>(entity);
546 
547  // ...
548 }
549 ```
550 
551 **Note**: prefer the `get` member function template of the view instead of the
552 `get` member function template of the registry during iterations.
553 
554 #### Side notes
555 
556 * Entity identifiers are numbers and nothing more. They are not classes and they
557  have no member functions at all. As already mentioned, do no try to inspect or
558  modify an entity descriptor in any way.
559 
560 * As shown in the examples above, the preferred way to get references to the
561  components while iterating a view is by using the view itself. It's a faster
562  alternative to the `get` member function template that is part of the API of
563  the Registry. That's because the registry must ensure that a pool for the
564  given component exists before to use it; on the other side, views force the
565  construction of the pools for all their components and access them directly,
566  thus avoiding all the checks.
567 
568 * Most of the _ECS_ available out there have an annoying limitation (at least
569  from my point of view): entities and components cannot be created and/or
570  deleted during iterations.<br/>
571  `EnTT` partially solves the problem with a few limitations:
572 
573  * Creating entities and components is allowed during iterations.
574  * Deleting an entity or removing its components is allowed during
575  iterations if it's the one currently returned by a view. For all the
576  other entities, destroying them or removing their components isn't
577  allowed and it can result in undefined behavior.
578 
579  Iterators are invalidated and the behaviour is undefined if an entity is
580  modified or destroyed and it's not the one currently returned by the
581  view.<br/>
582  To work around it, possible approaches are:
583 
584  * Store aside the entities and the components to be removed and perform the
585  operations at the end of the iteration.
586  * Mark entities and components with a proper tag component that indicates
587  they must be purged, then perform a second iteration to clean them up one
588  by one.
589 
590 * Views and thus their iterators aren't thread safe. Do no try to iterate a set
591  of components and modify the same set concurrently.<br/>
592  That being said, as long as a thread iterates the entities that have the
593  component `X` or assign and removes that component from a set of entities,
594  another thread can safely do the same with components `Y` and `Z` and
595  everything will work like a charm.<br/>
596  As an example, users can freely execute the rendering system and iterate the
597  renderable entities while updating a physic component concurrently on a
598  separate thread if needed.
599 
600 ### What else?
601 
602 The `EnTT` framework is moving its first steps. More and more will come in the
603 future and hopefully I'm going to work on it for a long time.<br/>
604 Here is a brief list of what it offers today (consider it a work in progress):
605 
606 TODO
607 
608 For more details, please refer directly to the
609 [online documentation](https://skypjack.github.io/entt/).
610 
611 ## Tests
612 
613 To compile and run the tests, `EnTT` requires *googletest*.<br/>
614 `cmake` will download and compile the library before to compile anything else.
615 
616 To build the tests:
617 
618 * `$ cd build`
619 * `$ cmake ..`
620 * `$ make`
621 * `$ make test`
622 
623 To build the benchmarks, use the following line instead:
624 
625 * `$ cmake -DCMAKE_BUILD_TYPE=Release ..`
626 
627 Benchmarks are compiled only in release mode currently.
628 
629 # Contributors
630 
631 If you want to contribute, please send patches as pull requests against the
632 branch `master`.<br/>
633 Check the
634 [contributors list](https://github.com/skypjack/entt/blob/master/AUTHORS) to see
635 who has partecipated so far.
636 
637 # License
638 
639 Code and documentation Copyright (c) 2017 Michele Caini.<br/>
640 Code released under
641 [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).
642 Docs released under
643 [Creative Commons](https://github.com/skypjack/entt/blob/master/docs/LICENSE).
644 
645 # Donation
646 
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&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 `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 ### API Reference
145 
146 The documentation is based on [doxygen](http://www.stack.nl/~dimitri/doxygen/).
147 To build it:
148 
149  $ cd build
150  $ cmake ..
151  $ make docs
152 
153 The API reference will be created in HTML format within the directory
154 `build/docs/html`. To navigate it with your favorite browser:
155 
156  $ cd build
157  $ your_favorite_browser docs/html/index.html
158 
159 The API reference is also available [online](https://skypjack.github.io/entt/)
160 for the latest version.
161 
162 ### Crash Course
163 
164 #### Vademecum
165 
166 The `Registry` to store, the `View`s to iterate. That's all.
167 
168 An entity (the _E_ of an _ECS_) is an opaque identifier that users should just
169 use as-is and store around if needed. Do not try to inspect an entity
170 identifier, its type can change in future and a registry offers all the
171 functionalities to query them out-of-the-box. The underlying type of an entity
172 (either `std::uint16_t`, `std::uint32_t` or `std::uint64_t`) can be specified
173 when defining a registry (actually the DefaultRegistry is nothing more than a
174 Registry where the type of the entities is `std::uint32_t`).<br/>
175 Components (the _C_ of an _ECS_) should be plain old data structures or more
176 complex and moveable data structures with a proper constructor. They are list
177 initialized by using the parameters provided to construct the component. No need
178 to register components or their types neither with the registry nor with the
179 entity-component system at all.<br/>
180 Systems (the _S_ of an _ECS_) are just plain functions, functors, lambdas or
181 whatever the users want. They can accept a Registry, a View or a PersistentView
182 and use them the way they prefer. No need to register systems or their types
183 neither with the registry nor with the entity-component system at all.
184 
185 The following sections will explain in short how to use the entity-component
186 system, the core part of the `EnTT` framework.<br/>
187 In fact, the framework is composed of many other classes in addition to those
188 describe below. For more details, please refer to the
189 [online documentation](https://skypjack.github.io/entt/).
190 
191 #### The Registry, the Entity and the Component
192 
193 A registry is used to store and manage entities as well as to create views to
194 iterate the underlying data structures.<br/>
195 Registry is a class template that lets the users decide what's the preferred
196 type to represent an entity. Because `std::uint32_t` is large enough for almost
197 all the cases, there exists also an alias named DefaultRegistry for
198 `Registry<std::uint32_t>`.
199 
200 Entities are represented by _entitiy identifiers_. An entity identifier is an
201 opaque type that users should not inspect or modify in any way. It carries
202 information about the entity itself and its version.
203 
204 A registry can be used both to construct and to destroy entities:
205 
206 ```cpp
207 // constructs a naked entity with no components ad returns its identifier
208 auto entity = registry.create();
209 
210 // constructs an entity and assigns it default-initialized components
211 auto another = registry.create<Position, Velocity>();
212 
213 // destroys an entity and all its components
214 registry.destroy(entity);
215 ```
216 
217 Once an entity is deleted, the registry can freely reuse it internally with a
218 slightly different identifier. In particular, the version of an entity is
219 increased each and every time it's destroyed.<br/>
220 In case entity identifiers are stored around, the registry offers all the
221 functionalities required to test them and get out of the them all the
222 information they carry:
223 
224 ```cpp
225 // returns true if the entity is still valid, false otherwise
226 bool b = registry.valid(entity);
227 
228 // gets the version contained in the entity identifier
229 auto version = registry.version(entity);
230 
231 // gets the actual version for the given entity
232 auto curr = registry.current(entity);
233 ```
234 
235 Components can be assigned to or removed from entities at any time with a few
236 calls to member functions of the registry. As for the entities, the registry
237 offers also a set of functionalities users can use to work with the components.
238 
239 The `assign` member function template creates, initializes and assigns to an
240 entity the given component. It accepts a variable number of arguments that are
241 used to construct the component itself if present:
242 
243 ```cpp
244 registry.assign<Position>(entity, 0., 0.);
245 
246 // ...
247 
248 auto &velocity = registry.assign<Velocity>(entity);
249 velocity.dx = 0.;
250 velocity.dy = 0.;
251 ```
252 
253 If the entity already has the given component, the `replace` member function
254 template can be used to replace it:
255 
256 ```cpp
257 registry.replace<Position>(entity, 0., 0.);
258 
259 // ...
260 
261 auto &velocity = registry.replace<Velocity>(entity);
262 velocity.dx = 0.;
263 velocity.dy = 0.;
264 ```
265 
266 In case users want to assign a component to an entity, but it's unknown whether
267 the entity already has it or not, `accomodate` does the work in a single call
268 (of course, there is a performance penalty to pay for that mainly due to the
269 fact that it must check if `entity` already has the given component or not):
270 
271 ```cpp
272 registry.accomodate<Position>(entity, 0., 0.);
273 
274 // ...
275 
276 auto &velocity = registry.accomodate<Velocity>(entity);
277 velocity.dx = 0.;
278 velocity.dy = 0.;
279 ```
280 
281 Note that `accomodate` is a sliglhty faster alternative for the following
282 `if`/`else` statement and nothing more:
283 
284 ```cpp
285 if(registry.has<Comp>(entity)) {
286  registry.replace<Comp>(entity, arg1, argN);
287 } else {
288  registry.assign<Comp>(entity, arg1, argN);
289 }
290 ```
291 
292 As already shown, if in doubt about whether or not an entity has one or more
293 components, the `has` member function template may be useful:
294 
295 ```cpp
296 bool b = registry.has<Position, Velocity>(entity);
297 ```
298 
299 On the other side, if the goal is to delete a single component, the `remove`
300 member function template is the way to go when it's certain that the entity owns
301 a copy of the component:
302 
303 ```cpp
304 registry.remove<Position>(entity);
305 ```
306 
307 Otherwise consider to use the `reset` member function. It behaves similarly to
308 `remove` but with a strictly defined behaviour (and a performance penalty is the
309 price to pay for that). In particular it removes the component if and only if it
310 exists, otherwise it returns safely to the caller:
311 
312 ```cpp
313 registry.reset<Position>(entity);
314 ```
315 
316 There exist also two other _versions_ of the `reset` member function:
317 
318 * If no entity is passed to it, `reset` will remove the given component from
319 each entity that has it:
320 
321  ```cpp
322  registry.reset<Position>();
323  ```
324 
325 * If neither the entity nor the component are specified, all the entities and
326 their components are destroyed:
327 
328  ```cpp
329  registry.reset();
330  ```
331 
332 Finally, references to components can be retrieved by just doing this:
333 
334 ```cpp
335 // either a non-const reference ...
336 DefaultRegistry registry;
337 auto &position = registry.get<Position>(entity);
338 
339 // ... or a const one
340 const auto &cregistry = registry;
341 const auto &position = cregistry.get<Position>(entity);
342 ```
343 
344 The `get` member function template gives direct access to the component of an
345 entity stored in the underlying data structures of the registry.
346 
347 ##### Sorting: is it possible?
348 
349 Of course, sorting entities and components is an option with `EnTT`.<br/>
350 In fact, there are two functions that respond to slightly different needs:
351 
352 * Components can be sorted directly:
353 
354  ```cpp
355  registry.sort<Renderable>([](const auto &lhs, const auto &rhs) {
356  return lhs.z < rhs.z;
357  });
358  ```
359 
360 * Components can be sorted according to the order imposed by another component:
361 
362  ```cpp
363  registry.sort<Movement, Physics>();
364  ```
365 
366  In this case, instances of `Movement` are arranged in memory so that cache
367  misses are minimized when the two components are iterated together.
368 
369 #### View: to persist or not to persist?
370 
371 There are mainly two kinds of views: standard (also known as View) and
372 persistent (alsa known as PersistentView).<br/>
373 Both of them have pros and cons to take in consideration. In particular:
374 
375 * Standard views:
376  Pros:
377  * They work out-of-the-box and don't require any dedicated data
378  structure.
379  * Creating and destroying them isn't expensive at all because they don't
380  have any type of initialization.
381  * They are the best tool to iterate single components.
382  * They are the best tool to iterate multiple components at once when
383  tags are involved or one of the component is assigned to a
384  significantly low number of entities.
385  * They don't affect any other operations of the registry.
386  Cons:
387  * Their performance tend to degenerate when the number of components
388  to iterate grows up and the most of the entities have all of them.
389 
390 * Persistent views:
391  Pros:
392  * Once prepared, creating and destroying them isn't expensive at all
393  because they don't have any type of initialization.
394  * They are the best tool to iterate multiple components at once when
395  the most of the entities have all of them.
396  Cons:
397  * They have dedicated data structures and thus affect the memory
398  pressure to a minimal extent.
399  * If not previously prepared, the first time they are used they go
400  through an initialization step that could take a while.
401  * They affect to a minimum the creation and destruction of entities and
402  components. In other terms: the more persistent views there will be,
403  the less performing will be creating and destroying entities and
404  components.
405 
406 To sum up and as a rule of thumb, use a standard view:
407  * To iterate entities for a single component.
408  * To iterate entities for multiple components when a significantly low
409  number of entities have one of the components.
410  * In all those cases where a persistent view would give a boost to
411  performance but the iteration isn't performed frequently.
412 
413 Use a persistent view in all the other cases.
414 
415 To easily iterate entities, all the views offer _C++-ish_ `begin` and `end`
416 member functions that allow users to use them in a typical range-for loop.<br/>
417 Continue reading for more details or refer to the
418 [official documentation](https://skypjack.github.io/entt/).
419 
420 ##### Standard View
421 
422 A standard view behaves differently if it's constructed for a single component
423 or if it has been requested to iterate multiple components. Even the API is
424 different in the two cases.<br/>
425 All that they share is the way they are created by means of a registry:
426 
427 ```cpp
428 // single component standard view
429 auto single = registry.view<Position>();
430 
431 // multi component standard view
432 auto multi = registry.view<Position, Velocity>();
433 ```
434 
435 For all that remains, it's worth discussing them separately.<br/>
436 
437 ###### Single component
438 
439 Single component standard views are specialized in order to give a boost in
440 terms of performance in all the situation. This kind of views can access the
441 underlying data structures directly and avoid superflous checks.<br/>
442 They offer a bunch of functionalities to get the number of entities they are
443 going to return and a raw access to the entity list as well as to the component
444 list.<br/>
445 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
446 the details.
447 
448 There is no need to store views around for they are extremely cheap to
449 construct, even though they can be copied without problems and reused
450 freely. In fact, they return newly created and correctly initialized iterators
451 whenever `begin` or `end` are invoked.<br/>
452 To iterate a single component standard view, just use it in range-for:
453 
454 ```cpp
455 auto view = registry.view<Renderable>();
456 
457 for(auto entity: view) {
458  auto &renderable = view.get(entity);
459 
460  // ...
461 }
462 ```
463 
464 **Note**: prefer the `get` member function of the view instead of the `get`
465 member function template of the registry during iterations.
466 
467 ###### Multi component
468 
469 Multi component standard views iterate entities that have at least all the given
470 components in their bags. During construction, these views look at the number
471 of entities available for each component and pick up a reference to the smallest
472 set of candidates in order to speed up iterations.<br/>
473 They offer fewer functionalities than their companion views for single
474 component, the most important of which can be used to reset the view and refresh
475 the reference to the set of candidate entities to iterate.<br/>
476 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
477 the details.
478 
479 There is no need to store views around for they are extremely cheap to
480 construct, even though they can be copied without problems and reused
481 freely. In fact, they return newly created and correctly initialized iterators
482 whenever `begin` or `end` are invoked.<br/>
483 To iterate a multi component standard view, just use it in range-for:
484 
485 ```cpp
486 auto view = registry.view<Position, Velocity>();
487 
488 for(auto entity: view) {
489  auto &position = view.get<Position>(entity);
490  auto &velocity = view.get<Velocity>(entity);
491 
492  // ...
493 }
494 ```
495 
496 **Note**: prefer the `get` member function template of the view instead of the
497 `get` member function template of the registry during iterations.
498 
499 ##### Persistent View
500 
501 A persistent view returns all the entities and only the entities that have at
502 least the given components. Moreover, it's guaranteed that the entity list is
503 thightly packed in memory for fast iterations.<br/>
504 In general, persistent views don't stay true to the order of any set of
505 components unless users explicitly sort them.
506 
507 Persistent views can be used only to iterate multiple components. Create them
508 as it follows:
509 
510 ```cpp
511 auto view = registry.persistent<Position, Velocity>();
512 ```
513 
514 There is no need to store views around for they are extremely cheap to
515 construct, even though they can be copied without problems and reused
516 freely. In fact, they return newly created and correctly initialized iterators
517 whenever `begin` or `end` are invoked.<br/>
518 That being said, persistent views perform an initialization step the very first
519 time they are constructed and this could be quite costly. To avoid it, consider
520 asking to the registry to _prepare_ them when no entities have been created yet:
521 
522 ```cpp
523 registry.prepare<Position, Velocity>();
524 ```
525 
526 If the registry is empty, preparation is extremely fast. Moreover the `prepare`
527 member function template is idempotent. Feel free to invoke it even more than
528 once: if the view has been alreadt prepared before, the function returns
529 immediately and does nothing.
530 
531 A persistent view offers a bunch of functionalities to get the number of
532 entities it's going to return, a raw access to the entity list and the
533 possibility to sort the underlying data structures according to the order of one
534 of the components for which it has been constructed.<br/>
535 Refer to the [official documentation](https://skypjack.github.io/entt/) for all
536 the details.
537 
538 To iterate a persistent view, just use it in range-for:
539 
540 ```cpp
541 auto view = registry.persistent<Position, Velocity>();
542 
543 for(auto entity: view) {
544  auto &position = view.get<Position>(entity);
545  auto &velocity = view.get<Velocity>(entity);
546 
547  // ...
548 }
549 ```
550 
551 **Note**: prefer the `get` member function template of the view instead of the
552 `get` member function template of the registry during iterations.
553 
554 #### Side notes
555 
556 * Entity identifiers are numbers and nothing more. They are not classes and they
557  have no member functions at all. As already mentioned, do no try to inspect or
558  modify an entity descriptor in any way.
559 
560 * As shown in the examples above, the preferred way to get references to the
561  components while iterating a view is by using the view itself. It's a faster
562  alternative to the `get` member function template that is part of the API of
563  the Registry. That's because the registry must ensure that a pool for the
564  given component exists before to use it; on the other side, views force the
565  construction of the pools for all their components and access them directly,
566  thus avoiding all the checks.
567 
568 * Most of the _ECS_ available out there have an annoying limitation (at least
569  from my point of view): entities and components cannot be created and/or
570  deleted during iterations.<br/>
571  `EnTT` partially solves the problem with a few limitations:
572 
573  * Creating entities and components is allowed during iterations.
574  * Deleting an entity or removing its components is allowed during
575  iterations if it's the one currently returned by a view. For all the
576  other entities, destroying them or removing their components isn't
577  allowed and it can result in undefined behavior.
578 
579  Iterators are invalidated and the behaviour is undefined if an entity is
580  modified or destroyed and it's not the one currently returned by the
581  view.<br/>
582  To work around it, possible approaches are:
583 
584  * Store aside the entities and the components to be removed and perform the
585  operations at the end of the iteration.
586  * Mark entities and components with a proper tag component that indicates
587  they must be purged, then perform a second iteration to clean them up one
588  by one.
589 
590 * Views and thus their iterators aren't thread safe. Do no try to iterate a set
591  of components and modify the same set concurrently.<br/>
592  That being said, as long as a thread iterates the entities that have the
593  component `X` or assign and removes that component from a set of entities,
594  another thread can safely do the same with components `Y` and `Z` and
595  everything will work like a charm.<br/>
596  As an example, users can freely execute the rendering system and iterate the
597  renderable entities while updating a physic component concurrently on a
598  separate thread if needed.
599 
600 ### What else?
601 
602 The `EnTT` framework is moving its first steps. More and more will come in the
603 future and hopefully I'm going to work on it for a long time.<br/>
604 Here is a brief list of what it offers today (consider it a work in progress):
605 
606 TODO
607 
608 For more details, please refer directly to the
609 [online documentation](https://skypjack.github.io/entt/).
610 
611 ## Tests
612 
613 To compile and run the tests, `EnTT` requires *googletest*.<br/>
614 `cmake` will download and compile the library before to compile anything else.
615 
616 To build the tests:
617 
618 * `$ cd build`
619 * `$ cmake ..`
620 * `$ make`
621 * `$ make test`
622 
623 To build the benchmarks, use the following line instead:
624 
625 * `$ cmake -DCMAKE_BUILD_TYPE=Release ..`
626 
627 Benchmarks are compiled only in release mode currently.
628 
629 # Contributors
630 
631 If you want to contribute, please send patches as pull requests against the
632 branch `master`.<br/>
633 Check the
634 [contributors list](https://github.com/skypjack/entt/blob/master/AUTHORS) to see
635 who has partecipated so far.
636 
637 # License
638 
639 Code and documentation Copyright (c) 2017 Michele Caini.<br/>
640 Code released under
641 [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).
642 Docs released under
643 [Creative Commons](https://github.com/skypjack/entt/blob/master/docs/LICENSE).
644 
645 # Donation
646 
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&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).
Generated by   diff --git a/index.html b/index.html index 6ccfba034..6c0aa53ad 100644 --- a/index.html +++ b/index.html @@ -149,11 +149,12 @@ Library Documentation

API Reference

-

The documentation is based on doxygen. To build it:

-

$ cd build $ cmake .. $ make docs

-

The API reference will be created in HTML format within the directory build/docs/html. To navigate it with your favorite browser:

-

$ cd build $ your_favorite_browser docs/html/index.html

-

The API reference is also available online for the latest version.

+

The documentation is based on doxygen. To build it: 

$ cd build
+$ cmake ..
+$ make docs
+

The API reference will be created in HTML format within the directory build/docs/html. To navigate it with your favorite browser: 

$ cd build
+$ your_favorite_browser docs/html/index.html
+

The API reference is also available online for the latest version.

Crash Course

@@ -272,12 +273,11 @@ 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.
    + 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.