API reference v3.10.0

This commit is contained in:
Michele Caini
2022-04-18 19:54:29 +02:00
parent 6fdc43199c
commit 378182736c
1056 changed files with 21834 additions and 21924 deletions
+177 -204
View File
@@ -22,7 +22,7 @@
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">EnTT
&#160;<span id="projectnumber">3.9.0</span>
&#160;<span id="projectnumber">3.10.0</span>
</div>
</td>
</tr>
@@ -66,59 +66,57 @@ $(function() {
<div class="title">Crash Course: entity-component system </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md45"></a>
<div class="textblock"><h1><a class="anchor" id="autotoc_md48"></a>
Introduction</h1>
<p><code>EnTT</code> is a header-only, tiny and easy to use entity-component system (and much more) written in modern C++.<br />
The entity-component-system (also known as <em>ECS</em>) is an architectural pattern used mostly in game development.</p>
<h1><a class="anchor" id="autotoc_md46"></a>
<h1><a class="anchor" id="autotoc_md49"></a>
Design decisions</h1>
<h2><a class="anchor" id="autotoc_md47"></a>
<h2><a class="anchor" id="autotoc_md50"></a>
Type-less and bitset-free</h2>
<p><code>EnTT</code> offers a <em>bitset-free</em> entity-component system that doesn't require users to specify the set of components neither at compile-time nor at runtime.<br />
<p><code>EnTT</code> offers a sparse set based model that doesn't require users to specify the set of components neither at compile-time nor at runtime.<br />
This is why users can instantiate the core class simply like:</p>
<div class="fragment"><div class="line"><a class="code" href="classentt_1_1basic__registry.html">entt::registry</a> <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>;</div>
<div class="ttc" id="aclassentt_1_1basic__registry_html"><div class="ttname"><a href="classentt_1_1basic__registry.html">entt::basic_registry</a></div><div class="ttdoc">Fast and reliable entity-component system.</div><div class="ttdef"><b>Definition:</b> <a href="registry_8hpp_source.html#l00173">registry.hpp:173</a></div></div>
<div class="ttc" id="aclassentt_1_1basic__registry_html"><div class="ttname"><a href="classentt_1_1basic__registry.html">entt::basic_registry</a></div><div class="ttdoc">Fast and reliable entity-component system.</div><div class="ttdef"><b>Definition:</b> <a href="registry_8hpp_source.html#l00221">registry.hpp:221</a></div></div>
<div class="ttc" id="anamespaceentt_html_a292643317d1dbb13e45824f757bd1086"><div class="ttname"><a href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">entt::registry</a></div><div class="ttdeci">basic_registry&lt; entity &gt; registry</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00060">fwd.hpp:60</a></div></div>
</div><!-- fragment --><p>In place of its more annoying and error-prone counterpart:</p>
<div class="fragment"><div class="line"><a class="code" href="classentt_1_1basic__registry.html">entt::registry</a>&lt;comp_0, comp_1, ..., comp_n&gt; <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>;</div>
</div><!-- fragment --><p>Furthermore, it isn't necessary to announce the existence of a component type. When the time comes, just use it and that's all.</p>
<h2><a class="anchor" id="autotoc_md48"></a>
<h2><a class="anchor" id="autotoc_md51"></a>
Build your own</h2>
<p><code>EnTT</code> is designed as a container that can be used at any time just as a vector or any other tool would be used. It doesn't attempt in any way to take over on the user code base, nor to control its main loop or process scheduling.<br />
Unlike other more or less known models, it makes use of independent pools. This has some advantages and disadvantages. The main purpose is to provide a fully customizable tool, where users have the freedom to define pools and opaque proxies for types with specific requirements.</p>
<p>The library provides a default implementation for many things and a mixin model that allows users to completely replace or even just enrich the pool dedicated to one or more components.<br />
The built-in signal support is an example of that: defined as a mixin, it's easily disabled if not needed. Similarly, the storage class has a specialization that shows how everything is customizable down to the smallest detail.</p>
<h2><a class="anchor" id="autotoc_md49"></a>
<p><code>EnTT</code> is designed as a container that can be used at any time, just like a vector or any other container. It doesn't attempt in any way to take over on the user codebase, nor to control its main loop or process scheduling.<br />
Unlike other more or less well known models, it also makes use of independent pools that can be extended via <em>static mixins</em>. The built-in signal support is an example of this flexible model: defined as a mixin, it's easily disabled if not needed. Similarly, the storage class has a specialization that shows how everything is customizable down to the smallest detail.</p>
<h2><a class="anchor" id="autotoc_md52"></a>
Pay per use</h2>
<p><code>EnTT</code> is entirely designed around the principle that users have to pay only for what they want.</p>
<p>When it comes to using an entity-component system, the tradeoff is usually between performance and memory usage. The faster it is, the more memory it uses. Even worse, some approaches tend to heavily affect other functionalities like the construction and destruction of components to favor iterations, even when it isn't strictly required. In fact, slightly worse performance along non-critical paths are the right price to pay to reduce memory usage and have overall better perfomance sometimes and I've always wondered why this kind of tools do not leave me the choice.<br />
<p>When it comes to using an entity-component system, the tradeoff is usually between performance and memory usage. The faster it is, the more memory it uses. Even worse, some approaches tend to heavily affect other functionalities like the construction and destruction of components to favor iterations, even when it isn't strictly required. In fact, slightly worse performance along non-critical paths are the right price to pay to reduce memory usage and have overall better performance.<br />
<code>EnTT</code> follows a completely different approach. It gets the best out from the basic data structures and gives users the possibility to pay more for higher performance where needed.</p>
<p>So far, this choice has proven to be a good one and I really hope it can be for many others besides me.</p>
<h2><a class="anchor" id="autotoc_md50"></a>
<h2><a class="anchor" id="autotoc_md53"></a>
All or nothing</h2>
<p><code>EnTT</code> is such that a <code>T**</code> pointer (or whatever a custom pool returns) is always available to directly access all the instances of a given component type <code>T</code>.<br />
I cannot say whether it will be useful or not to the reader, but it's worth to mention it since it's one of the corner stones of this library.</p>
<p>Many of the tools described below give the possibility to get this information and have been designed around this need.<br />
The rest is experimentation and the desire to invent something new, hoping to have succeeded.</p>
<h1><a class="anchor" id="autotoc_md51"></a>
<h1><a class="anchor" id="autotoc_md54"></a>
Vademecum</h1>
<p>The registry to store, the views and the groups to iterate. That's all.</p>
<p>An entity (the <em>E</em> of an <em>ECS</em>) is an opaque identifier that users should use as-is. Inspecting an identifier isn't recommended since its format can change in future and a registry has all the functionalities to query them out-of-the-box. The type <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> implements the concept of <em>entity identifier</em>.<br />
Components (the <em>C</em> of an <em>ECS</em>) must be both move constructible and move assignable. They are list initialized by using the parameters provided to construct the component itself. No need to register components or their types neither with the registry nor with the entity-component system at all.<br />
<p>The <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> type implements the concept of <em>entity identifier</em>. An entity (the <em>E</em> of an <em>ECS</em>) is an opaque element to use as-is. Inspecting it isn't recommended since its format can change in future.<br />
Components (the <em>C</em> of an <em>ECS</em>) are both move constructible and move assignable types. No need to register them nor their types.<br />
Systems (the <em>S</em> of an <em>ECS</em>) can be plain functions, functors, lambdas and so on. It's not required to announce them in any case and have no requirements.</p>
<p>The following sections explain in short how to use the entity-component system, the core part of the whole library.<br />
The project is composed of many other classes in addition to those describe below. For more details, please refer to the inline documentation.</p>
<h1><a class="anchor" id="autotoc_md52"></a>
<p>The next sections go into detail on how to use the entity-component system part of the <code>EnTT</code> library.<br />
The project is composed of many other classes in addition to those described below. For more details, please refer to the inline documentation.</p>
<h1><a class="anchor" id="autotoc_md55"></a>
Pools</h1>
<p>In <code>EnTT</code>, pools of components are made available through a specialized version of a sparse set.</p>
<p>Each pool contains all the instances of a single component and all the entities to which it's assigned. Sparse arrays are <em>paged</em> to avoid wasting memory in some cases. Packed arrays of components are also paged to have pointer stability upon additions. Packed arrays of entities are not instead.<br />
All pools can rearrange their items in order to keep the internal arrays tightly packed and maximize performance.</p>
<h1><a class="anchor" id="autotoc_md53"></a>
<p>Pools of components are a sort of <em>specialized version</em> of a sparse set. Each pool contains all the instances of a single component type and all the entities to which it's assigned.<br />
Sparse arrays are <em>paged</em> to avoid wasting memory. Packed arrays of components are also paged to have pointer stability upon additions. Packed arrays of entities are not instead.<br />
All pools rearranges their items in order to keep the internal arrays tightly packed and maximize performance, unless pointer stability is enabled.</p>
<h1><a class="anchor" id="autotoc_md56"></a>
The Registry, the Entity and the Component</h1>
<p>A registry can store and manage entities, as well as create views and groups to iterate the underlying data structures.<br />
The class template <code>basic_registry</code> lets users decide what's the preferred type to represent an entity. Because <code>std::uint32_t</code> is large enough for almost all the cases, there exists also the enum class <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> that <em>wraps</em> it and the alias <code><a class="el" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086" title="Alias declaration for the most common use case.">entt::registry</a></code> for <code><a class="el" href="classentt_1_1basic__registry.html" title="Fast and reliable entity-component system.">entt::basic_registry</a>&lt;<a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>&gt;</code>.</p>
<p>A registry stores and manages entities (or better, identifiers) and pools.<br />
The class template <code>basic_registry</code> lets users decide what's the preferred type to represent an entity. Because <code>std::uint32_t</code> is large enough for almost all the cases, there also exists the enum class <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> that <em>wraps</em> it and the alias <code><a class="el" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086" title="Alias declaration for the most common use case.">entt::registry</a></code> for <code><a class="el" href="classentt_1_1basic__registry.html" title="Fast and reliable entity-component system.">entt::basic_registry</a>&lt;<a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>&gt;</code>.</p>
<p>Entities are represented by <em>entity identifiers</em>. An entity identifier contains information about the entity itself and its version.<br />
User defined identifiers can be introduced through enum classes and class types that define an <code>entity_type</code> member of type <code>std::uint32_t</code> or <code>std::uint64_t</code>.</p>
User defined identifiers are allowed as enum classes and class types that define an <code>entity_type</code> member of type <code>std::uint32_t</code> or <code>std::uint64_t</code>.</p>
<p>A registry is used both to construct and to destroy entities:</p>
<div class="fragment"><div class="line"><span class="comment">// constructs a naked entity with no components and returns its identifier</span></div>
<div class="line"><span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.create();</div>
@@ -126,12 +124,12 @@ The Registry, the Entity and the Component</h1>
<div class="line"><span class="comment">// destroys an entity and all its components</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.destroy(entity);</div>
<div class="ttc" id="anamespaceentt_html_a0b54e231d069e8a231e14b223388808a"><div class="ttname"><a href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a></div><div class="ttdeci">entity</div><div class="ttdoc">Default entity identifier.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00047">fwd.hpp:47</a></div></div>
</div><!-- fragment --><p>The <code>create</code> member function accepts also a hint and has an overload that gets two iterators and can be used to generate multiple entities at once efficiently. Similarly, the <code>destroy</code> member function works also with a range of entities:</p>
</div><!-- fragment --><p>The <code>create</code> member function also accepts a hint and has an overload that gets two iterators and can be used to generate multiple entities at once efficiently. Similarly, the <code>destroy</code> member function also works with a range of entities:</p>
<div class="fragment"><div class="line"><span class="comment">// destroys all the entities in a range</span></div>
<div class="line"><span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.view&lt;a_component, another_component&gt;();</div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.destroy(<a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a>.begin(), <a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a>.end());</div>
<div class="ttc" id="anamespaceentt_html_a87b7ba6bd51a290113765bc97188d247"><div class="ttname"><a href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">entt::view</a></div><div class="ttdeci">basic_view&lt; entity, Get, Exclude &gt; view</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00103">fwd.hpp:103</a></div></div>
</div><!-- fragment --><p>In addition to offering an overload to force the version upon destruction. Note that this function removes all components from an entity before releasing its identifier. There exists also a <em>lighter</em> alternative that only releases the elements without poking in any pool, for use with orphaned entities:</p>
</div><!-- fragment --><p>In addition to offering an overload to force the version upon destruction. Note that this function removes all components from an entity before releasing its identifier. There also exists a <em>lighter</em> alternative that only releases the elements without poking in any pool, for use with orphaned entities:</p>
<div class="fragment"><div class="line"><span class="comment">// releases an orphaned identifier</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.release(entity);</div>
</div><!-- fragment --><p>As with the <code>destroy</code> function, also in this case entity ranges are supported and it's possible to force the version during release.</p>
@@ -190,7 +188,7 @@ The Registry, the Entity and the Component</h1>
<div class="line"> </div>
<div class="line"><span class="comment">// true if entity has at least one of the given components</span></div>
<div class="line"><span class="keywordtype">bool</span> <a class="code" href="namespaceentt.html#a4846741b8f485584c196304f588b94ad">any</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.any_of&lt;position, velocity&gt;(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
<div class="ttc" id="anamespaceentt_html_a4846741b8f485584c196304f588b94ad"><div class="ttname"><a href="namespaceentt.html#a4846741b8f485584c196304f588b94ad">entt::any</a></div><div class="ttdeci">basic_any&lt;&gt; any</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="core_2fwd_8hpp_source.html#l00016">fwd.hpp:16</a></div></div>
<div class="ttc" id="anamespaceentt_html_a4846741b8f485584c196304f588b94ad"><div class="ttname"><a href="namespaceentt.html#a4846741b8f485584c196304f588b94ad">entt::any</a></div><div class="ttdeci">basic_any&lt;&gt; any</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="core_2fwd_8hpp_source.html#l00017">fwd.hpp:17</a></div></div>
</div><!-- fragment --><p>If the goal is to delete a component from an entity that owns it, the <code>erase</code> member function template is the way to go:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.erase&lt;position&gt;(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
</div><!-- fragment --><p>When in doubt whether the entity owns the component, use the <code>remove</code> member function instead. It behaves similarly to <code>erase</code> but it erases the component if and only if it exists, otherwise it returns safely to the caller:</p>
@@ -215,11 +213,11 @@ The Registry, the Entity and the Component</h1>
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> [cpos, cvel] = cregistry.get&lt;position, velocity&gt;(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
<div class="line"><span class="keyword">auto</span> [pos, vel] = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.get&lt;position, velocity&gt;(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
</div><!-- fragment --><p>The <code>get</code> member function template gives direct access to the component of an entity stored in the underlying data structures of the registry. There exists also an alternative member function named <code>try_get</code> that returns a pointer to the component owned by an entity if any, a null pointer otherwise.</p>
<h2><a class="anchor" id="autotoc_md54"></a>
<h2><a class="anchor" id="autotoc_md57"></a>
Observe changes</h2>
<p>Because of how the registry works internally, it stores a bunch of signal handlers for each pool in order to notify some of its data structures on the construction and destruction of components or when an instance of a component is explicitly replaced by the user.<br />
These signal handlers are also exposed and made available to users. These are the basic bricks to build fancy things like dependencies and reactive systems.</p>
<p>To get a sink to be used to connect and disconnect listeners so as to be notified on the creation of a component, use the <code>on_construct</code> member function:</p>
<p>By default, each storage comes with a mixin that adds signal support to it.<br />
This allows for fancy things like dependencies and reactive systems.</p>
<p>The <code>on_construct</code> member function returns a <em>sink</em> (which is an object for connecting and disconnecting listeners) for those interested in notifications when a new instance of a given component type is created:</p>
<div class="fragment"><div class="line"><span class="comment">// connects a free function</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.on_construct&lt;position&gt;().connect&lt;&amp;my_free_function&gt;();</div>
<div class="line"> </div>
@@ -231,9 +229,9 @@ Observe changes</h2>
<div class="line"> </div>
<div class="line"><span class="comment">// disconnects a member function</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.on_construct&lt;position&gt;().disconnect&lt;&amp;my_class::member&gt;(instance);</div>
</div><!-- fragment --><p>To be notified when a component is destroyed, use the <code>on_destroy</code> member function instead. Finally, the <code>on_update</code> member function will return a sink to which to connect listeners to observe changes.<br />
In the last case, given the way C++ works, it's also necessary to use specific member functions to allow the signal to be triggered. In particular, listeners attached to <code>on_update</code> will only be invoked following a call to <code>replace</code> or <code>patch</code>.</p>
<p>The function type of a listener should be equivalent to the following:</p>
</div><!-- fragment --><p>Similarly, <code>on_destroy</code> and <code>on_update</code> are used to receive notifications about the destruction and update of an instance, respectively.<br />
Because of how C++ works, listeners attached to <code>on_update</code> are only invoked following a call to <code>replace</code>, <code>emplace_or_replace</code> or <code>patch</code>.</p>
<p>The function type of a listener is equivalent to the following:</p>
<div class="fragment"><div class="line">void(<a class="code" href="classentt_1_1basic__registry.html">entt::registry</a> &amp;, <a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a>);</div>
</div><!-- fragment --><p>In all cases, listeners are provided with the registry that triggered the notification and the involved entity.</p>
<p>Note also that:</p>
@@ -248,11 +246,9 @@ Observe changes</h2>
<li>Removing the component from within the body of a listener that observes the construction or update of instances of a given type isn't allowed.</li>
<li>Assigning and removing components from within the body of a listener that observes the destruction of instances of a given type should be avoided. It can lead to undefined behavior in some cases. This type of listeners is intended to provide users with an easy way to perform cleanup and nothing more.</li>
</ul>
<p>To a certain extent, these limitations don't apply. However, it's risky to try to force them and users should respect the limitations unless they know exactly what they are doing.</p>
<p>Events and therefore listeners must not be used as replacements for systems. They shouldn't contain much logic and interactions with a registry should be kept to a minimum. Moreover, the greater the number of listeners, the greater the performance hit when components are created or destroyed.</p>
<p>Please, refer to the documentation of the signal class to know all the features it offers.<br />
<p>Please, refer to the documentation of the signal class to know about all the features it offers.<br />
There are many useful but less known functionalities that aren't described here, such as the connection objects or the possibility to attach listeners with a list of parameters that is shorter than that of the signal itself.</p>
<h3><a class="anchor" id="autotoc_md55"></a>
<h3><a class="anchor" id="autotoc_md58"></a>
They call me Reactive System</h3>
<p>Signals are the basic tools to construct reactive systems, even if they aren't enough on their own. <code>EnTT</code> tries to take another step in that direction with the <code>observer</code> class template.<br />
In order to explain what reactive systems are, this is a slightly revised quote from the documentation of the library that first introduced this tool, <a href="https://github.com/sschmid/Entitas-CSharp">Entitas</a>:</p>
@@ -299,12 +295,12 @@ They call me Reactive System</h3>
<p>In addition, a matcher can be filtered with a <code>where</code> clause:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#aea8b073b774362fe800d9cce3542927a">entt::collector</a>.update&lt;sprite&gt;().where&lt;position&gt;(entt::exclude&lt;velocity&gt;);</div>
</div><!-- fragment --><p>This clause introduces a way to intercept entities if and only if they are already part of a hypothetical group. If they are not, they aren't returned by the observer, no matter if they matched the given rule.<br />
In the example above, whenever the component <code>sprite</code> of an entity is updated, the observer probes the entity itself to verify that it has at least <code>position</code> and has not <code>velocity</code> before to store it aside. If one of the two conditions of the filter isn't respected, the entity is discared, no matter what.</p>
In the example above, whenever the component <code>sprite</code> of an entity is updated, the observer probes the entity itself to verify that it has at least <code>position</code> and has not <code>velocity</code> before to store it aside. If one of the two conditions of the filter isn't respected, the entity is discarded, no matter what.</p>
<p>A <code>where</code> clause accepts a theoretically unlimited number of types as well as multiple elements in the exclusion list. Moreover, every matcher can have its own clause and multiple clauses for the same matcher are combined in a single one.</p>
<h2><a class="anchor" id="autotoc_md56"></a>
<h2><a class="anchor" id="autotoc_md59"></a>
Sorting: is it possible?</h2>
<p>Sorting entities and components is possible with <code>EnTT</code>. In particular, it's feasible with an in-place algorithm that doesn't require memory allocations nor anything else and is therefore particularly convenient.<br />
With this in mind, there are two functions that respond to slightly different needs:</p>
<p>Sorting entities and components is possible with <code>EnTT</code>. In particular, it uses an in-place algorithm that doesn't require memory allocations nor anything else and is therefore particularly convenient.<br />
There are two functions that respond to slightly different needs:</p>
<ul>
<li>Components can be sorted either directly:</li>
</ul>
@@ -322,13 +318,12 @@ Sorting: is it possible?</h2>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.sort&lt;movement, physics&gt;();</div>
</div><!-- fragment --><p>In this case, instances of <code>movement</code> are arranged in memory so that cache misses are minimized when the two components are iterated together.</p>
<p>As a side note, the use of groups limits the possibility of sorting pools of components. Refer to the specific documentation for more details.</p>
<h2><a class="anchor" id="autotoc_md57"></a>
<h2><a class="anchor" id="autotoc_md60"></a>
Helpers</h2>
<p>The so called <em>helpers</em> are small classes and functions mainly designed to offer built-in support for the most basic functionalities.<br />
The list of helpers will grow longer as time passes and new ideas come out.</p>
<h3><a class="anchor" id="autotoc_md58"></a>
<p>The so called <em>helpers</em> are small classes and functions mainly designed to offer built-in support for the most basic functionalities.</p>
<h3><a class="anchor" id="autotoc_md61"></a>
Null entity</h3>
<p>In <code>EnTT</code>, the <code><a class="el" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b" title="Compile-time constant for null entities.">entt::null</a></code> variable models the concept of <em>null entity</em>.<br />
<p>The <code><a class="el" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b" title="Compile-time constant for null entities.">entt::null</a></code> variable models the concept of <em>null entity</em>.<br />
The library guarantees that the following expression always returns false:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.valid(<a class="code" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>);</div>
<div class="ttc" id="anamespaceentt_html_a2f0c0a1c1d953ea991591748744cdd8b"><div class="ttname"><a href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a></div><div class="ttdeci">constexpr null_t null</div><div class="ttdoc">Compile-time constant for null entities.</div><div class="ttdef"><b>Definition:</b> <a href="entity_8hpp_source.html#l00326">entity.hpp:326</a></div></div>
@@ -340,10 +335,10 @@ Null entity</h3>
<div class="line"><span class="keyword">const</span> <span class="keywordtype">bool</span> <span class="keyword">null</span> = (<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a> == <a class="code" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b">entt::null</a>);</div>
</div><!-- fragment --><p>As for its integral form, the null entity only affects the entity part of an identifier and is instead completely transparent to its version.</p>
<p>Be aware that <code><a class="el" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b" title="Compile-time constant for null entities.">entt::null</a></code> and entity 0 aren't the same thing. Likewise, a zero initialized entity isn't the same as <code><a class="el" href="namespaceentt.html#a2f0c0a1c1d953ea991591748744cdd8b" title="Compile-time constant for null entities.">entt::null</a></code>. Therefore, although <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>{}</code> is in some sense an alias for entity 0, none of them can be used to create a null entity.</p>
<h3><a class="anchor" id="autotoc_md59"></a>
<h3><a class="anchor" id="autotoc_md62"></a>
Tombstone</h3>
<p>In addition to the null entity, <code>EnTT</code> also models the concept of <em>tombstone</em> with the <code><a class="el" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862" title="Compile-time constant for tombstone entities.">entt::tombstone</a></code> variable.<br />
Once created, the integral form of the two values is the same, although they affect different parts of an identifier. In fact, the tombstone uses only the version part and is completely transparent to the entity part.</p>
<p>Similar to the null entity, the <code><a class="el" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862" title="Compile-time constant for tombstone entities.">entt::tombstone</a></code> variable models the concept of <em>tombstone</em>.<br />
Once created, the integral form of the two values is the same, although they affect different parts of an identifier. In fact, the tombstone only uses the version part of it and is completely transparent to the entity part.</p>
<p>Also in this case, the following expression always returns false:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.valid(<a class="code" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a>);</div>
<div class="ttc" id="anamespaceentt_html_a674269102fdfe3fd6d7766210a828862"><div class="ttname"><a href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a></div><div class="ttdeci">constexpr tombstone_t tombstone</div><div class="ttdoc">Compile-time constant for tombstone entities.</div><div class="ttdef"><b>Definition:</b> <a href="entity_8hpp_source.html#l00335">entity.hpp:335</a></div></div>
@@ -356,14 +351,14 @@ Tombstone</h3>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.create();</div>
<div class="line"><span class="keyword">const</span> <span class="keywordtype">bool</span> <a class="code" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">tombstone</a> = (<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a> == <a class="code" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862">entt::tombstone</a>);</div>
</div><!-- fragment --><p>Be aware that <code><a class="el" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862" title="Compile-time constant for tombstone entities.">entt::tombstone</a></code> and entity 0 aren't the same thing. Likewise, a zero initialized entity isn't the same as <code><a class="el" href="namespaceentt.html#a674269102fdfe3fd6d7766210a828862" title="Compile-time constant for tombstone entities.">entt::tombstone</a></code>. Therefore, although <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a>{}</code> is in some sense an alias for entity 0, none of them can be used to create tombstones.</p>
<h3><a class="anchor" id="autotoc_md60"></a>
<h3><a class="anchor" id="autotoc_md63"></a>
To entity</h3>
<p>Sometimes it's useful to get the entity from a component instance.<br />
This is what the <code><a class="el" href="namespaceentt.html#ae1b0b05750caf25f9718c2bebf55d25c" title="Returns the entity part once converted to the underlying type.">entt::to_entity</a></code> helper does. It accepts a registry and an instance of a component and returns the entity associated with the latter:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a> = <a class="code" href="namespaceentt.html#ae1b0b05750caf25f9718c2bebf55d25c">entt::to_entity</a>(registry, position);</div>
<div class="ttc" id="anamespaceentt_html_ae1b0b05750caf25f9718c2bebf55d25c"><div class="ttname"><a href="namespaceentt.html#ae1b0b05750caf25f9718c2bebf55d25c">entt::to_entity</a></div><div class="ttdeci">constexpr entt_traits&lt; Entity &gt;::entity_type to_entity(const Entity value)</div><div class="ttdoc">Returns the entity part once converted to the underlying type.</div><div class="ttdef"><b>Definition:</b> <a href="entity_8hpp_source.html#l00148">entity.hpp:148</a></div></div>
</div><!-- fragment --><p>A null entity is returned in case the component doesn't belong to the registry.</p>
<h3><a class="anchor" id="autotoc_md61"></a>
<h3><a class="anchor" id="autotoc_md64"></a>
Dependencies</h3>
<p>The <code>registry</code> class is designed to be able to create short circuits between its functions. This simplifies the definition of <em>dependencies</em> between different operations.<br />
For example, the following adds (or replaces) the component <code>a_type</code> whenever <code>my_type</code> is assigned to an entity:</p>
@@ -373,13 +368,13 @@ Dependencies</h3>
</div><!-- fragment --><p>A dependency can also be easily broken as follows:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.on_construct&lt;my_type&gt;().disconnect&lt;&amp;entt::registry::emplace_or_replace&lt;a_type&gt;&gt;();</div>
</div><!-- fragment --><p>There are many other types of dependencies. In general, most of the functions that accept an entity as the first argument are good candidates for this purpose.</p>
<h3><a class="anchor" id="autotoc_md62"></a>
<h3><a class="anchor" id="autotoc_md65"></a>
Invoke</h3>
<p>Sometimes it's useful to be able to directly invoke a member function of a component as a callback. It's already possible in practice but requires users to <em>extend</em> their classes and this may not always be possible.<br />
<p>Sometimes it's useful to directly invoke a member function of a component as a callback. It's already possible in practice but requires users to <em>extend</em> their classes and this may not always be possible.<br />
The <code>invoke</code> helper allows to <em>propagate</em> the signal in these cases:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.on_construct&lt;clazz&gt;().connect&lt;entt::invoke&lt;&amp;clazz::func&gt;&gt;();</div>
</div><!-- fragment --><p>All it does is pick up the <em>right</em> component for the received entity and invoke the requested method, passing on the arguments if necessary.</p>
<h3><a class="anchor" id="autotoc_md63"></a>
<h3><a class="anchor" id="autotoc_md66"></a>
Handle</h3>
<p>A handle is a thin wrapper around an entity and a registry. It provides the same functions that the registry offers for working with components, such as <code>emplace</code>, <code>get</code>, <code>patch</code>, <code>remove</code> and so on. The difference being that the entity is implicitly passed to the registry.<br />
It's default constructible as an invalid handle that contains a null registry and a null entity. When it contains a null registry, calling functions that delegate execution to the registry will cause an undefined behavior, so it's recommended to check the validity of the handle with implicit cast to <code>bool</code> when in doubt.<br />
@@ -388,15 +383,15 @@ Handle</h3>
Users can also easily create their own aliases for custom identifiers as:</p>
<div class="fragment"><div class="line"><span class="keyword">using</span> my_handle = <a class="code" href="structentt_1_1basic__handle.html">entt::basic_handle&lt;my_identifier&gt;</a>;</div>
<div class="line"><span class="keyword">using</span> my_const_handle = <a class="code" href="structentt_1_1basic__handle.html">entt::basic_handle&lt;const my_identifier&gt;</a>;</div>
<div class="ttc" id="astructentt_1_1basic__handle_html"><div class="ttname"><a href="structentt_1_1basic__handle.html">entt::basic_handle</a></div><div class="ttdoc">Non-owning handle to an entity.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2handle_8hpp_source.html#l00023">handle.hpp:23</a></div></div>
<div class="ttc" id="astructentt_1_1basic__handle_html"><div class="ttname"><a href="structentt_1_1basic__handle.html">entt::basic_handle</a></div><div class="ttdoc">Non-owning handle to an entity.</div><div class="ttdef"><b>Definition:</b> <a href="handle_8hpp_source.html#l00023">handle.hpp:23</a></div></div>
</div><!-- fragment --><p>Handles are also implicitly convertible to const handles out of the box but not the other way around.<br />
A handle stores a non-const pointer to a registry and therefore it can do all the things that can be done with a non-const registry. On the other hand, a const handles store const pointers to registries and offer a restricted set of functionalities.</p>
<p>This class is intended to simplify function signatures. In case of functions that take a registry and an entity and do most of their work on that entity, users might want to consider using handles, either const or non-const.</p>
<h3><a class="anchor" id="autotoc_md64"></a>
<h3><a class="anchor" id="autotoc_md67"></a>
Organizer</h3>
<p>The <code>organizer</code> class template offers minimal support (but sufficient in many cases) for creating an execution graph from functions and their requirements on resources.<br />
<p>The <code>organizer</code> class template offers support for creating an execution graph from a set of functions and their requirements on resources.<br />
The resulting tasks aren't executed in any case. This isn't the goal of this tool. Instead, they are returned to the user in the form of a graph that allows for safe execution.</p>
<p>The functions are added in order of execution to the organizer. Free functions and member functions are supported as template parameters, however there is also the possibility to pass pointers to free functions or decayed lambdas as parameters to the <code>emplace</code> member function:</p>
<p>All functions are added in order of execution to the organizer:</p>
<div class="fragment"><div class="line"><a class="code" href="classentt_1_1basic__organizer.html">entt::organizer</a> <a class="code" href="namespaceentt.html#a5870a148e25a503557bdd47327c7a05a">organizer</a>;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// adds a free function to the organizer</span></div>
@@ -408,15 +403,15 @@ Organizer</h3>
<div class="line"> </div>
<div class="line"><span class="comment">// adds a decayed lambda directly</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a5870a148e25a503557bdd47327c7a05a">organizer</a>.emplace(+[](<span class="keyword">const</span> <span class="keywordtype">void</span> *, <a class="code" href="classentt_1_1basic__registry.html">entt::registry</a> &amp;) { <span class="comment">/* ... */</span> });</div>
<div class="ttc" id="aclassentt_1_1basic__organizer_html"><div class="ttname"><a href="classentt_1_1basic__organizer.html">entt::basic_organizer</a></div><div class="ttdoc">Utility class for creating a static task graph.</div><div class="ttdef"><b>Definition:</b> <a href="organizer_8hpp_source.html#l00111">organizer.hpp:111</a></div></div>
<div class="ttc" id="aclassentt_1_1basic__organizer_html"><div class="ttname"><a href="classentt_1_1basic__organizer.html">entt::basic_organizer</a></div><div class="ttdoc">Utility class for creating a static task graph.</div><div class="ttdef"><b>Definition:</b> <a href="organizer_8hpp_source.html#l00108">organizer.hpp:108</a></div></div>
<div class="ttc" id="anamespaceentt_html_a5870a148e25a503557bdd47327c7a05a"><div class="ttname"><a href="namespaceentt.html#a5870a148e25a503557bdd47327c7a05a">entt::organizer</a></div><div class="ttdeci">basic_organizer&lt; entity &gt; organizer</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00066">fwd.hpp:66</a></div></div>
</div><!-- fragment --><p>As for free functions and member functions, these are the parameters that can be presented by their function types and that will be correctly handled:</p>
</div><!-- fragment --><p>These are the parameters that a free function or a member function can accept:</p>
<ul>
<li>A possibly constant reference to a registry. The one passed to the task when it's run will also be passed to the function as-is.</li>
<li>An <code><a class="el" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247" title="Alias declaration for the most common use case.">entt::view</a></code> with any possible combination of types. It will be created from the registry passed to the task and supplied directly to the function.</li>
<li>A possibly constant reference to any type <code>T</code>. It will be interpreted as context variable, which will be created within the registry and passed to the function.</li>
<li>A possibly constant reference to a registry.</li>
<li>An <code><a class="el" href="classentt_1_1basic__view.html" title="View implementation.">entt::basic_view</a></code> with any possible combination of types.</li>
<li>A possibly constant reference to any type <code>T</code> (that is, a context variable).</li>
</ul>
<p>The function type for free functions and decayed lambdas passed as parameters to <code>emplace</code> is <code>void(const void *, entt::registry &amp;)</code> instead. The registry is the same as provided to the task. The first parameter is an optional pointer to user defined data to provide upon registration:</p>
<p>The function type for free functions and decayed lambdas passed as parameters to <code>emplace</code> is <code>void(const void *, entt::registry &amp;)</code> instead. The first parameter is an optional pointer to user defined data to provide upon registration:</p>
<div class="fragment"><div class="line">clazz instance;</div>
<div class="line"><a class="code" href="namespaceentt.html#a5870a148e25a503557bdd47327c7a05a">organizer</a>.emplace(+[](<span class="keyword">const</span> <span class="keywordtype">void</span> *, <a class="code" href="classentt_1_1basic__registry.html">entt::registry</a> &amp;) { <span class="comment">/* ... */</span> }, &amp;instance);</div>
</div><!-- fragment --><p>In all cases, it's also possible to associate a name with the task when creating it. For example:</p>
@@ -449,76 +444,81 @@ Organizer</h3>
<div class="line"> node.prepare(registry);</div>
<div class="line">}</div>
</div><!-- fragment --><p>The actual scheduling of the tasks is the responsibility of the user, who can use the preferred tool.</p>
<h2><a class="anchor" id="autotoc_md65"></a>
<h2><a class="anchor" id="autotoc_md68"></a>
Context variables</h2>
<p>It is often convenient to assign context variables to a registry, so as to make it the only <em>source of truth</em> of an application.<br />
This is possible by means of a member function named <code>set</code> to use to create a context variable from a given type. Either <code>ctx</code> or <code>try_ctx</code> can be used to retrieve the newly created instance, while <code>unset</code> is meant to clear the variable if needed:</p>
<div class="fragment"><div class="line"><span class="comment">// creates a new context variable initialized with the given values</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.set&lt;my_type&gt;(42, <span class="charliteral">&#39;c&#39;</span>);</div>
<p>Each registry has a <em>context</em> associated with it, which is an <code>any</code> object map accessible by both type and <em>name</em> for convenience. The <em>name</em> isn't really a name though. In fact, it's a numeric id of type <code>id_type</code> to be used as a key for the variable. Any value is accepted, even runtime ones.<br />
The context is returned via the <code>ctx</code> functions and offers a minimal set of feature including the following:</p>
<div class="fragment"><div class="line"><span class="comment">// creates a new context variable by type</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().emplace&lt;my_type&gt;(42, <span class="charliteral">&#39;c&#39;</span>);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// gets the context variable as a non-const reference from a non-const registry</span></div>
<div class="line"><span class="keyword">auto</span> &amp;var = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx&lt;my_type&gt;();</div>
<div class="line"><span class="comment">// creates a new context variable with a name</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().emplace_hint&lt;my_type&gt;(<span class="stringliteral">&quot;my_variable&quot;</span>_hs, 42, <span class="charliteral">&#39;c&#39;</span>);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// gets the context variable as a const reference from either a const or a non-const registry</span></div>
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> &amp;cvar = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx&lt;<span class="keyword">const</span> my_type&gt;();</div>
<div class="line"><span class="comment">// gets the context variable by type as a non-const reference from a non-const registry</span></div>
<div class="line"><span class="keyword">auto</span> &amp;var = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().at&lt;my_type&gt;();</div>
<div class="line"> </div>
<div class="line"><span class="comment">// unsets the context variable</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.unset&lt;my_type&gt;();</div>
</div><!-- fragment --><p>The type of a context variable must be such that it's default constructible and can be moved. The <code>set</code> member function either creates a new instance of the context variable or overwrites an already existing one if any.<br />
The <code>try_ctx</code> member function returns a pointer to the context variable if it exists, otherwise it returns a null pointer. As <code>ctx</code>, it supports both const and non-const types and requires a const one when used on a const registry:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(<span class="keyword">auto</span> *cptr = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.try_ctx&lt;<span class="keyword">const</span> my_type&gt;(); cptr) {</div>
<div class="line"> <span class="comment">// uses the context variable associated with the registry, if any</span></div>
<div class="line">}</div>
</div><!-- fragment --><h3><a class="anchor" id="autotoc_md66"></a>
<div class="line"><span class="comment">// gets the context variable by name as a const reference from either a const or a non-const registry</span></div>
<div class="line"><span class="keyword">const</span> <span class="keyword">auto</span> &amp;cvar = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().at&lt;<span class="keyword">const</span> my_type&gt;(<span class="stringliteral">&quot;my_variable&quot;</span>_hs);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// resets the context variable by type</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().erase&lt;my_type&gt;();</div>
<div class="line"> </div>
<div class="line"><span class="comment">// resets the context variable associated with the given name</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().erase&lt;my_type&gt;(<span class="stringliteral">&quot;my_variable&quot;</span>_hs);</div>
</div><!-- fragment --><p>The type of a context variable must be such that it's default constructible and can be moved. If the supplied type doesn't match that of the variable when using a <em>name</em>, the operation will fail.<br />
For all users who want to use the context but don't want to create elements, the <code>contains</code> and <code>find</code> functions are also available:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">bool</span> contains = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().contains&lt;my_type&gt;();</div>
<div class="line"><span class="keyword">const</span> my_type *value = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().find&lt;<span class="keyword">const</span> my_type&gt;(<span class="stringliteral">&quot;my_variable&quot;</span>_hs);</div>
</div><!-- fragment --><p>Also in this case, both functions support constant types and accept a <em>name</em> for the variable to look up, as does <code>at</code>.</p>
<h3><a class="anchor" id="autotoc_md69"></a>
Aliased properties</h3>
<p>Context variables can also be used to create aliases for existing variables that aren't directly managed by the registry. In this case, it's also possible to make them read-only.<br />
To do that, the type used upon construction must be a reference type and an lvalue is necessarily provided as an argument:</p>
<div class="fragment"><div class="line">time clock;</div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.set&lt;my_type &amp;&gt;(clock);</div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().emplace&lt;my_type &amp;&gt;(clock);</div>
</div><!-- fragment --><p>Read-only aliased properties are created using const types instead:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.set&lt;<span class="keyword">const</span> my_type &amp;&gt;(clock);</div>
</div><!-- fragment --><p>From the point of view of the user, there are no differences between a variable that is managed by the registry and an aliased property. However, read-only variables aren't accesible as non-const references:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().emplace&lt;<span class="keyword">const</span> my_type &amp;&gt;(clock);</div>
</div><!-- fragment --><p>From the point of view of the user, there are no differences between a variable that is managed by the registry and an aliased property. However, read-only variables aren't accessible as non-const references:</p>
<div class="fragment"><div class="line"><span class="comment">// read-only variables only support const access</span></div>
<div class="line"><span class="keyword">const</span> my_type *ptr = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.try_ctx&lt;<span class="keyword">const</span> my_type&gt;();</div>
<div class="line"><span class="keyword">const</span> my_type &amp;var = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx&lt;<span class="keyword">const</span> my_type&gt;();</div>
</div><!-- fragment --><p>Aliased properties can be unset and are overwritten when <code>set</code> is invoked, as it happens with standard variables.</p>
<h2><a class="anchor" id="autotoc_md67"></a>
<div class="line"><span class="keyword">const</span> my_type *ptr = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().find&lt;<span class="keyword">const</span> my_type&gt;();</div>
<div class="line"><span class="keyword">const</span> my_type &amp;var = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.ctx().at&lt;<span class="keyword">const</span> my_type&gt;();</div>
</div><!-- fragment --><p>Aliased properties can be erased as it happens with any other variable. Similarly, they can also be associated with user-generated <em>names</em> (or ids).</p>
<h2><a class="anchor" id="autotoc_md70"></a>
Component traits</h2>
<p>In <code>EnTT</code>, almost everything is customizable. Components are no exception.<br />
In this case, the <em>standardized</em> way to access all component properties is the <code>component_traits</code> class.</p>
<p>Various parts of the library access component properties through this class. It makes it possible to use any type as a component, as long as its specialization of <code>component_traits</code> implements all the required functionalities.<br />
The non-specialized version of this class contains the following members:</p>
<ul>
<li><code>in_place_delete</code>: <code>Type::in_place_delete</code> if present, false otherwise.</li>
<li><code>page_size</code>: <code>Type::page_size</code> if present, <code>ENTT_PACKED_PAGE</code> (for non-empty types) or 0 (for empty types) otherwise.</li>
</ul>
<p>Where <code>Type</code> is any type of component. All properties can be customized by specializing the above class and defining all its members, or by adding only those of interest to a component definition:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>transform {</div>
<div class="line"> <span class="keyword">static</span> constexpr <span class="keyword">auto</span> in_place_delete = <span class="keyword">true</span>;</div>
<div class="line"> <span class="comment">// ... other data members ...</span></div>
<div class="line">};</div>
</div><!-- fragment --><p>The <code>component_traits</code> class template will take care of correctly extracting the properties from the supplied type to pass them to the rest of the library.<br />
In the case of a direct specialization, the class is also <em>sfinae-friendly</em>. It supports single and multi type specializations as well as feature-based ones.</p>
<h2><a class="anchor" id="autotoc_md71"></a>
Pointer stability</h2>
<p>The ability to achieve pointer stability for one, several or all components is a direct consequence of the design of <code>EnTT</code> and of its default storage.<br />
In fact, although it contains what is commonly referred to as a <em>packed array</em>, the default storage is paged and doesn't suffer from invalidation of references when it runs out of space and has to reallocate.<br />
However, this isn't enough to ensure pointer stability in case of deletion. For this reason, a <em>stable</em> deletion method is also offered. This one is such that the position of the elements is preserved by creating tombstones upon deletion rather than trying to fill the holes that are created.</p>
<p>For performance reasons, <code>EnTT</code> will also favor storage compaction in all cases, although often accessing a component occurs mostly randomly or traversing pools in a non-linear order on the user side (as in the case of a hierarchy).<br />
<p>For performance reasons, <code>EnTT</code> favors storage compaction in all cases, although often accessing a component occurs mostly randomly or traversing pools in a non-linear order on the user side (as in the case of a hierarchy).<br />
In other words, pointer stability is not automatic but is enabled on request.</p>
<h3><a class="anchor" id="autotoc_md68"></a>
<h3><a class="anchor" id="autotoc_md72"></a>
In-place delete</h3>
<p>By default, <code>EnTT</code> keeps all pools compact when a component is removed. This is done through a swap-and-pop between the removed item and the one occupying the last position in the storage.<br />
Unfortunately, this also inevitably leads the components to change position within the storage, making direct access almost impossible (be it via pointer or index).</p>
<p>However, the underlying model with its independent pools helps introduce storage with different deletion policies, so that users can best choose type by type.<br />
In particular, the library offers out of the box support for in-place deletion, thus offering storage with completely stable pointers. To do so, it's required to specialize the <code>component_traits</code> class.<br />
The definition common to all components is the following:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>basic_component_traits {</div>
<div class="line"> <span class="keyword">static</span> constexpr <span class="keyword">auto</span> in_place_delete = <span class="keyword">false</span>;</div>
<div class="line"> <span class="keyword">static</span> constexpr <span class="keyword">auto</span> ignore_if_empty = ENTT_IGNORE_IF_EMPTY;</div>
<div class="line"> <span class="keyword">static</span> constexpr <span class="keyword">auto</span> page_size = ENTT_PACKED_PAGE;</div>
<div class="line">};</div>
</div><!-- fragment --><p>Where <code>in_place_delete</code> instructs the library on the deletion policy for a given type while <code>ignore_if_empty</code> selectively disables empty type optimization and <code>page_size</code> dictates the storage behavior for non-empty types.<br />
The <code>component_traits</code> class template is <em>sfinae-friendly</em>, it supports single and multi type specializations as well as feature-based ones:</p>
<div class="fragment"><div class="line"><span class="keyword">template</span>&lt;&gt;</div>
<div class="line"><span class="keyword">struct </span><a class="code" href="structentt_1_1component__traits.html">entt::component_traits</a>&lt;position&gt;: basic_component_traits {</div>
<div class="line"> <span class="keyword">using</span> <a class="code" href="structentt_1_1basic__component__traits.html#a4ca4508bcd9833ab7c3354704144c90b">in_place_delete</a> = std::true_type;</div>
<div class="line">};</div>
<div class="ttc" id="astructentt_1_1basic__component__traits_html_a4ca4508bcd9833ab7c3354704144c90b"><div class="ttname"><a href="structentt_1_1basic__component__traits.html#a4ca4508bcd9833ab7c3354704144c90b">entt::basic_component_traits::in_place_delete</a></div><div class="ttdeci">static constexpr auto in_place_delete</div><div class="ttdoc">Pointer stability, default is false.</div><div class="ttdef"><b>Definition:</b> <a href="component_8hpp_source.html#l00012">component.hpp:12</a></div></div>
<div class="ttc" id="astructentt_1_1component__traits_html"><div class="ttname"><a href="structentt_1_1component__traits.html">entt::component_traits</a></div><div class="ttdoc">Common way to access various properties of components.</div><div class="ttdef"><b>Definition:</b> <a href="component_8hpp_source.html#l00024">component.hpp:24</a></div></div>
</div><!-- fragment --><p>This will ensure in-place deletion for the <code>position</code> component without further user intervention.<br />
Views and groups adapt accordingly when they detect a storage with a different deletion policy than the default. No specific action is required from the user once in-place deletion is enabled. In particular:</p>
<p>The library offers out of the box support for in-place deletion, thus offering storage with completely stable pointers. This is achieved by specializing the <code>component_traits</code> class or by adding the required properties to the component definition when needed.<br />
Views and groups adapt accordingly when they detect a storage with a different deletion policy than the default. In particular:</p>
<ul>
<li>Groups are incompatible with stable storage and will trigger a compile-time error if detected.</li>
<li>Multi type views are completely transparent to storage policies.</li>
<li>Groups are incompatible with stable storage and will even refuse to compile.</li>
<li>Multi type and runtime views are completely transparent to storage policies.</li>
<li>Single type views for stable storage types offer the same interface of multi type views. For example, only <code>size_hint</code> is available.</li>
</ul>
<p>In other words, the more generic version of a view will be provided in case of stable storage, even for single components, always supported by an appropriate iteration policy if required.<br />
The latter will be such that in no case will a tombstone be returned from the view itself, regardless of the iteration method. Similarly, no non-existent components will be accessed, which could result in an UB otherwise.</p>
<h3><a class="anchor" id="autotoc_md69"></a>
<p>In other words, the more generic version of a view is provided in case of stable storage, even for a single type view.<br />
In no case a tombstone is returned from the view itself. Likewise, non-existent components aren't returned, which could otherwise result in an UB.</p>
<h3><a class="anchor" id="autotoc_md73"></a>
Hierarchies and the like</h3>
<p><code>EnTT</code> doesn't attempt in any way to offer built-in methods with hidden or unclear costs to facilitate the creation of hierarchies.<br />
There are various solutions to the problem, such as using the following class:</p>
@@ -533,48 +533,27 @@ Hierarchies and the like</h3>
</div><!-- fragment --><p>However, it should be pointed out that the possibility of having stable pointers for one, many or all types solves the problem of hierarchies at the root in many cases.<br />
In fact, if a certain type of component is visited mainly in random order or according to hierarchical relationships, using direct pointers has many advantages:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>transform {</div>
<div class="line"> <span class="keyword">static</span> constexpr <span class="keyword">auto</span> in_place_delete = <span class="keyword">true</span>;</div>
<div class="line"> </div>
<div class="line"> transform *parent;</div>
<div class="line"> <span class="comment">// ... other data members ...</span></div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="keyword">template</span>&lt;&gt;</div>
<div class="line"><span class="keyword">struct </span><a class="code" href="structentt_1_1component__traits.html">entt::component_traits</a>&lt;transform&gt;: basic_component_traits {</div>
<div class="line"> <span class="keyword">using</span> <a class="code" href="structentt_1_1basic__component__traits.html#a4ca4508bcd9833ab7c3354704144c90b">in_place_delete</a> = std::true_type;</div>
<div class="line">};</div>
</div><!-- fragment --><p>Furthermore, it's quite common for a group of elements to be created close in time and therefore fallback into adjacent positions, thus favoring locality even on random accesses. Locality that won't be sacrificed over time given the stability of storage positions, with undoubted performance advantages.<br />
Of course, the cost moves to linear iterations, where views and groups will have to identify (and discard) all tombstones. However, once considered the benefits, from performance to ease of use, and given the many optimizations that make this cost negligible, this is configured as one of the most convenient solutions and certainly something to take into consideration.</p>
<h2><a class="anchor" id="autotoc_md70"></a>
Making the most of range-destroy</h2>
<p>The range-destroy functionality offers an improved path under the hood. To understand it, let's try to describe what problem it tries to solve.<br />
This function accepts two iterators that point to the beginning and end of a range of entities. If the iterators are those returned from a view, this pair cannot be passed to the first storage asking to remove all entities and then to all other storage. This is because the range may be empty when passed to the second pool, as not all of those entities still own all the components iterated from the view itself.<br />
As a result, only one component is removed and no entities are destroyed.</p>
<p>To avoid this, in many cases the registry doesn't pass the range to all pools. Instead, it iterates the range and passes an entity at a time to all pools.<br />
It goes without saying that the latter is slightly slower than the former.</p>
<p>On the other side, the <code>destroy</code> function also uses <code>is_iterator_type</code> under the hood to detect <em>dangerous</em> iterators. Whenever possible, it still chooses the fastest path.<br />
This means that performance will improve if, for example, two iterators returned from an <code>std::vector</code> are used or, more in general, with all iterators that are not part of <code>EnTT</code>.</p>
<p>Unfortunately, this risks falling into the error described above in some corner cases. In particular, where an iterator is used that is not defined by <code>EnTT</code> but which uses one of the latter <em>within</em> it.<br />
It's quite unlikely to happen even in large software. However, the library offers a solution also in this case, so as to allow for custom iterators and better performance at the same time.<br />
In particular, it's necessary to either expose the member type <code>iterator_type</code> and declare that an iterator from <code>EnTT</code> is used internally or specialize the <code>is_iterator_type</code> class to drive the choice of the <code>destroy</code> function.<br />
In both cases, the aim is to not choose the optimized route if it can cause problems.</p>
<p>With a good chance, the last note can be ignored and there will never be a need to do the above even after writing millions of lines of code.<br />
However, it's good to know how to exploit the <code>destroy</code> function to get the best out of it.</p>
<h2><a class="anchor" id="autotoc_md71"></a>
</div><!-- fragment --><p>Furthermore, it's quite common for a group of elements to be created close in time and therefore fallback into adjacent positions, thus favoring locality even on random accesses. Locality that won't be sacrificed over time given the stability of storage positions, with undoubted performance advantages.</p>
<h2><a class="anchor" id="autotoc_md74"></a>
Meet the runtime</h2>
<p><code>EnTT</code> takes full advantage of what the language offers at compile-time.<br />
However, this can have its downsides (well known to those familiar with type erasure techniques).</p>
<p>To bridge this gap, the library provides a bunch of utilities and features that can be very useful when needed.<br />
On the one hand, storage classes are standalone objects that allow users to work with components within certain limits and without knowing the actual types. On the other hand, it's possible to create component storage dynamically and link them to a name rather than a type.</p>
<h3><a class="anchor" id="autotoc_md72"></a>
<p><code>EnTT</code> takes advantage of what the language offers at compile-time. However, this can have its downsides (well known to those familiar with type erasure techniques).<br />
To fill the gap, the library also provides a bunch of utilities and feature that can be very useful to handle types and pools at runtime.</p>
<h3><a class="anchor" id="autotoc_md75"></a>
A base class to rule them all</h3>
<p>Storage classes are fully self-contained types. These can be extended via mixins to add more functionalities (generic or type specific). In addition, they offer a basic set of functions that already allow users to go very far.<br />
The aim is to limit the need for customizations as much as possible, offering what is usually necessary for the majority of cases.</p>
The aim is to limit the need for customizations as much as possible, offering what is usually necessary for the vast majority of cases.</p>
<p>When a storage is used through its base class (i.e. when its actual type isn't known), there is always the possibility of receiving a <code>type_info</code> describing the type of the objects associated with the entities (if any):</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(entt::type_id&lt;velocity&gt;() == base.type()) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>Furthermore, all features rely on internal functions that forward the calls to the mixins. The latter can then make use of any context variables, which can be set via <code>bind</code>:</p>
</div><!-- fragment --><p>Furthermore, all features rely on internal functions that forward the calls to the mixins. The latter can then make use of any information, which can be set via <code>bind</code>:</p>
<div class="fragment"><div class="line">base.bind(<a class="code" href="namespaceentt.html#a810f66c2c91deba50f96cae9119f2feb">entt::forward_as_any</a>(registry));</div>
<div class="ttc" id="anamespaceentt_html_a810f66c2c91deba50f96cae9119f2feb"><div class="ttname"><a href="namespaceentt.html#a810f66c2c91deba50f96cae9119f2feb">entt::forward_as_any</a></div><div class="ttdeci">basic_any&lt; Len, Align &gt; forward_as_any(Type &amp;&amp;value)</div><div class="ttdoc">Forwards its argument and avoids copies for lvalue references.</div><div class="ttdef"><b>Definition:</b> <a href="any_8hpp_source.html#l00488">any.hpp:488</a></div></div>
<div class="ttc" id="anamespaceentt_html_a810f66c2c91deba50f96cae9119f2feb"><div class="ttname"><a href="namespaceentt.html#a810f66c2c91deba50f96cae9119f2feb">entt::forward_as_any</a></div><div class="ttdeci">basic_any&lt; Len, Align &gt; forward_as_any(Type &amp;&amp;value)</div><div class="ttdoc">Forwards its argument and avoids copies for lvalue references.</div><div class="ttdef"><b>Definition:</b> <a href="any_8hpp_source.html#l00484">any.hpp:484</a></div></div>
</div><!-- fragment --><p>The <code>bind</code> function accepts an <code><a class="el" href="namespaceentt.html#a4846741b8f485584c196304f588b94ad" title="Alias declaration for the most common use case.">entt::any</a></code> object, that is a <em>typed type-erased</em> value.<br />
This is how a registry <em>passes</em> itself to all pools that support signals and also why a storage keeps sending events without requiring the registry to be passed to it every time.</p>
<p>Alongside these more specific things, there are also a couple of functions designed to address some common requirements such as copying an entity.<br />
@@ -588,17 +567,17 @@ A base class to rule them all</h3>
<p>This means that, starting from a reference to the base, it's possible to bind components with entities without knowing their actual type and even initialize them by copy if needed:</p>
<div class="fragment"><div class="line"><span class="comment">// create a copy of an entity component by component</span></div>
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &amp;&amp;curr: <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage()) {</div>
<div class="line"> <span class="keywordflow">if</span>(<span class="keyword">auto</span> &amp;storage = curr.second; <a class="code" href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">storage</a>.contains(entity)) {</div>
<div class="line"> <a class="code" href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">storage</a>.emplace(other, <a class="code" href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">storage</a>.get(entity));</div>
<div class="line"> <span class="keywordflow">if</span>(<span class="keyword">auto</span> &amp;storage = curr.second; <a class="code" href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">storage</a>.contains(src)) {</div>
<div class="line"> <a class="code" href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">storage</a>.emplace(dst, <a class="code" href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">storage</a>.get(src));</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="ttc" id="anamespaceentt_html_abcedb8f29753130e2bf3185bca211f05"><div class="ttname"><a href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">entt::storage</a></div><div class="ttdeci">basic_storage&lt; entity, Args... &gt; storage</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00057">fwd.hpp:57</a></div></div>
</div><!-- fragment --><p>This is particularly useful to clone entities in an opaque way. In addition, the decoupling of features allows for filtering or use of different copying policies depending on the type.</p>
<h3><a class="anchor" id="autotoc_md73"></a>
<h3><a class="anchor" id="autotoc_md76"></a>
Beam me up, registry</h3>
<p><code>EnTT</code> is strongly based on types and has always allowed to create only one storage of a certain type within a registry.<br />
However, this doesn't work well for users who want to create multiple storage of the same type associated with different <em>names</em>, such as for interacting with a scripting system.</p>
<p>Nowadays, the library has <em>solved</em> this limitation and offers the possibility of associating a <em>type</em> with a name (or rather, a numeric identifier):</p>
<p>Nowadays, the library has solved this problem and offers the possibility of associating a type with a <em>name</em> (or rather, a numeric identifier):</p>
<div class="fragment"><div class="line"><span class="keyword">using namespace </span>entt::literals;</div>
<div class="line"><span class="keyword">auto</span> &amp;&amp;<a class="code" href="namespaceentt.html#abcedb8f29753130e2bf3185bca211f05">storage</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;velocity&gt;(<span class="stringliteral">&quot;second pool&quot;</span>_hs);</div>
</div><!-- fragment --><p>If a name isn't provided, the default storage associated with the given type is always returned.<br />
@@ -612,7 +591,7 @@ Beam me up, registry</h3>
On the other hand, those calls involving all storage are guaranteed to also <em>reach</em> manually created ones:</p>
<div class="fragment"><div class="line"><span class="comment">// will remove the entity from both storage</span></div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.destroy(entity);</div>
</div><!-- fragment --><p>Finally, a storage of this type can be used with any view (which also accept multiple storages of the same type, if necessary):</p>
</div><!-- fragment --><p>Finally, a storage of this type can be used with any view (which also accepts multiple storages of the same type, if necessary):</p>
<div class="fragment"><div class="line"><span class="comment">// direct initialization</span></div>
<div class="line"><a class="code" href="classentt_1_1basic__view.html">entt::basic_view</a> direct{</div>
<div class="line"> <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;velocity&gt;(),</div>
@@ -624,7 +603,7 @@ Beam me up, registry</h3>
<div class="ttc" id="aclassentt_1_1basic__view_html"><div class="ttname"><a href="classentt_1_1basic__view.html">entt::basic_view</a></div><div class="ttdoc">View implementation.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00020">fwd.hpp:20</a></div></div>
</div><!-- fragment --><p>The possibility of direct use of storage combined with the freedom of being able to create and use more than one of the same type opens the door to the use of <code>EnTT</code> <em>at runtime</em>, which was previously quite limited.<br />
Sure the basic design remains very type-bound, but finally it's no longer bound to this one option alone.</p>
<h2><a class="anchor" id="autotoc_md74"></a>
<h2><a class="anchor" id="autotoc_md77"></a>
Snapshot: complete vs continuous</h2>
<p>The <code>registry</code> class offers basic support to serialization.<br />
It doesn't convert components to bytes directly, there wasn't the need of another tool for serialization out there. Instead, it accepts an opaque object with a suitable interface (namely an <em>archive</em>) to serialize its internal data structures and restore them later. The way types and instances are converted to a bunch of bytes is completely in charge to the archive and thus to final users.</p>
@@ -653,7 +632,7 @@ Snapshot: complete vs continuous</h2>
</div><!-- fragment --><p>Note that <code>component</code> stores items along with entities. It means that it works properly without a call to the <code>entities</code> member function.</p>
<p>Once a snapshot is created, there exist mainly two <em>ways</em> to load it: as a whole and in a kind of <em>continuous mode</em>.<br />
The following sections describe both loaders and archives in details.</p>
<h3><a class="anchor" id="autotoc_md75"></a>
<h3><a class="anchor" id="autotoc_md78"></a>
Snapshot loader</h3>
<p>A snapshot loader requires that the destination registry be empty and loads all the data at once while keeping intact the identifiers that the entities originally had.<br />
To use it, just pass to the constructor a valid registry:</p>
@@ -668,7 +647,7 @@ Snapshot loader</h3>
<p>The <code>entities</code> member function restores the sets of entities and the versions that they originally had at the source.</p>
<p>The <code>component</code> member function restores all and only the components specified and assigns them to the right entities. Note that the template parameter list must be exactly the same used during the serialization.</p>
<p>The <code>orphans</code> member function literally releases those entities that have no components attached. It's usually useless if the snapshot is a full dump of the source. However, in case all the entities are serialized but only few components are saved, it could happen that some of the entities have no components once restored. The best the users can do to deal with them is to release those entities and thus update their versions.</p>
<h3><a class="anchor" id="autotoc_md76"></a>
<h3><a class="anchor" id="autotoc_md79"></a>
Continuous loader</h3>
<p>A continuous loader is designed to load data from a source registry to a (possibly) non-empty destination. The loader can accommodate in a registry more than one snapshot in a sort of <em>continuous loading</em> that updates the destination one step at a time.<br />
Identifiers that entities originally had are not transferred to the target. Instead, the loader maps remote identifiers to local ones while restoring a snapshot. Because of that, this kind of loader offers a way to update automatically identifiers that are part of components (as an example, as data members or gathered in a container).<br />
@@ -688,7 +667,7 @@ Continuous loader</h3>
In case the component contains entities itself (either as data members of type <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code> or as containers of entities), the loader can update them automatically. To do that, it's enough to specify the data members to update as shown in the example.</p>
<p>The <code>orphans</code> member function literally releases those entities that have no components after a restore. It has exactly the same purpose described in the previous section and works the same way.</p>
<p>Finally, <code>shrink</code> helps to purge local entities that no longer have a remote conterpart. Users should invoke this member function after restoring each snapshot, unless they know exactly what they are doing.</p>
<h3><a class="anchor" id="autotoc_md77"></a>
<h3><a class="anchor" id="autotoc_md80"></a>
Archives</h3>
<p>Archives must publicly expose a predefined set of member functions. The API is straightforward and consists only of a group of function call operators that are invoked by the snapshot class and the loaders.</p>
<p>In particular:</p>
@@ -712,12 +691,12 @@ Archives</h3>
</div><!-- fragment --><p>In addition, the archive must accept a pair of references to an entity and its component for each type to be restored. Therefore, given a type <code>T</code>, the archive must contain a function call operator with the following signature:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> operator()(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> &amp;, T &amp;);</div>
</div><!-- fragment --><p>Every time such an operator is invoked, the archive must read the next elements from the underlying storage and copy them in the given variables.</p>
<h3><a class="anchor" id="autotoc_md78"></a>
<h3><a class="anchor" id="autotoc_md81"></a>
One example to rule them all</h3>
<p><code>EnTT</code> comes with some examples (actually some tests) that show how to integrate a well known library for serialization as an archive. It uses <a href="https://uscilab.github.io/cereal/"><code>Cereal C++</code></a> under the hood, mainly because I wanted to learn how it works at the time I was writing the code.</p>
<p>The code is not production-ready and it isn't neither the only nor (probably) the best way to do it. However, feel free to use it at your own risk.</p>
<p>The basic idea is to store everything in a group of queues in memory, then bring everything back to the registry with different loaders.</p>
<h1><a class="anchor" id="autotoc_md79"></a>
<h1><a class="anchor" id="autotoc_md82"></a>
Views and Groups</h1>
<p>First of all, it's worth answering a question: why views and groups?<br />
Briefly, they're a good tool to enforce single responsibility. A system that has access to a registry can create and destroy entities, as well as assign and remove components. On the other side, a system that has access to a view or a group can only iterate, read and update entities and components.<br />
@@ -733,7 +712,7 @@ Views and Groups</h1>
<p>Groups come in three different flavors: <em>full-owning groups</em>, <em>partial-owning groups</em> and <em>non-owning groups</em>. The main difference between them is in terms of performance.<br />
Groups can literally <em>own</em> one or more component types. They are allowed to rearrange pools so as to speed up iterations. Roughly speaking: the more components a group owns, the faster it is to iterate them.<br />
A given component can belong to multiple groups only if they are <em>nested</em>, so users have to define groups carefully to get the best out of them.</p>
<h2><a class="anchor" id="autotoc_md80"></a>
<h2><a class="anchor" id="autotoc_md83"></a>
Views</h2>
<p>A view behaves differently if it's constructed for a single component or if it has been created to iterate multiple components. Even the API is slightly different in the two cases.</p>
<p>Single type views are specialized to give a boost in terms of performance in all the situations. This kind of views can access the underlying data structures directly and avoid superfluous checks. There is nothing as fast as a single type view. In fact, they walk through a packed (actually paged) array of components and return them one at a time.<br />
@@ -788,7 +767,7 @@ Views</h2>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">}</div>
</div><!-- fragment --><p><b>Note</b>: prefer the <code>get</code> member function of a view instead of that of a registry during iterations to get the types iterated by the view itself.</p>
<h3><a class="anchor" id="autotoc_md81"></a>
<h3><a class="anchor" id="autotoc_md84"></a>
View pack</h3>
<p>Views are combined with each other to create new and more specific types.<br />
The type returned when combining multiple views together is itself a view, more in general a multi component one.</p>
@@ -799,34 +778,33 @@ View pack</h3>
<div class="line"><span class="keyword">auto</span> pack = <a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a> | other;</div>
</div><!-- fragment --><p>The constness of the types is preserved and their order depends on the order in which the views are combined. Therefore, the pack in the example above will return an instance of <code>position</code> first and then one of <code>velocity</code>.<br />
Since combining views generates views, a chain can be of arbitrary length and the above type order rules apply sequentially.</p>
<h3><a class="anchor" id="autotoc_md82"></a>
<h3><a class="anchor" id="autotoc_md85"></a>
Runtime views</h3>
<p>Runtime views iterate entities that have at least all the given components in their bags. During construction, these views look at the number of entities available for each component and pick up a reference to the smallest set of candidates in order to speed up iterations.<br />
They offer more or less the same functionalities of a multi type view. However, they don't expose a <code>get</code> member function and users should refer to the registry that generated the view to access components. In particular, a runtime view exposes utility functions to get the estimated number of entities it is going to return and to know whether it's empty or not. It's also possible to ask a runtime view if it contains a given entity.<br />
Refer to the inline documentation for all the details.</p>
<p>Runtime views are pretty cheap to construct and should not be stored aside in any case. They should be used immediately after creation and then they should be thrown away.<br />
To iterate a runtime view, either use it in a range-for loop:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a13e040e7b38a8f86d1ab2f096f37b627">entt::id_type</a> types[] = { <a class="code" href="structentt_1_1type__hash.html#a95f5ae709a95f0959a7dfd1af6af6c74">entt::type_hash&lt;position&gt;::value</a>(), <a class="code" href="structentt_1_1type__hash.html#a95f5ae709a95f0959a7dfd1af6af6c74">entt::type_hash&lt;velocity&gt;::value</a>() };</div>
<div class="line"><span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.runtime_view(std::cbegin(types), std::cend(types));</div>
<div class="fragment"><div class="line"><a class="code" href="structentt_1_1basic__runtime__view.html">entt::runtime_view</a> <a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a>{};</div>
<div class="line"><a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a>.iterate(<a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;position&gt;()).iterate(<a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;velocity&gt;());</div>
<div class="line"> </div>
<div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> entity: view) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">}</div>
<div class="ttc" id="anamespaceentt_html_a13e040e7b38a8f86d1ab2f096f37b627"><div class="ttname"><a href="namespaceentt.html#a13e040e7b38a8f86d1ab2f096f37b627">entt::id_type</a></div><div class="ttdeci">std::uint32_t id_type</div><div class="ttdoc">Alias declaration for type identifiers.</div><div class="ttdef"><b>Definition:</b> <a href="core_2fwd_8hpp_source.html#l00013">fwd.hpp:13</a></div></div>
<div class="ttc" id="astructentt_1_1type__hash_html_a95f5ae709a95f0959a7dfd1af6af6c74"><div class="ttname"><a href="structentt_1_1type__hash.html#a95f5ae709a95f0959a7dfd1af6af6c74">entt::type_hash::value</a></div><div class="ttdeci">static constexpr id_type value()</div><div class="ttdoc">Returns the numeric representation of a given type.</div><div class="ttdef"><b>Definition:</b> <a href="type__info_8hpp_source.html#l00109">type_info.hpp:109</a></div></div>
<div class="ttc" id="astructentt_1_1basic__runtime__view_html"><div class="ttname"><a href="structentt_1_1basic__runtime__view.html">entt::basic_runtime_view</a></div><div class="ttdoc">Runtime view implementation.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00023">fwd.hpp:23</a></div></div>
</div><!-- fragment --><p>Or rely on the <code>each</code> member function to iterate entities:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a13e040e7b38a8f86d1ab2f096f37b627">entt::id_type</a> types[] = { <a class="code" href="structentt_1_1type__hash.html#a95f5ae709a95f0959a7dfd1af6af6c74">entt::type_hash&lt;position&gt;::value</a>(), <a class="code" href="structentt_1_1type__hash.html#a95f5ae709a95f0959a7dfd1af6af6c74">entt::type_hash&lt;velocity&gt;::value</a>() };</div>
<div class="line"> </div>
<div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.runtime_view(std::cbegin(types), std::cend(types)).each([](<span class="keyword">auto</span> entity) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">});</div>
<div class="fragment"><div class="line"><a class="code" href="structentt_1_1basic__runtime__view.html">entt::runtime_view</a>{}</div>
<div class="line"> .iterate(<a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;position&gt;())</div>
<div class="line"> .iterate(<a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;velocity&gt;())</div>
<div class="line"> .each([](<span class="keyword">auto</span> entity) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"> });</div>
</div><!-- fragment --><p>Performance are exactly the same in both cases.<br />
Filtering entities by components is also supported for this kind of views:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a13e040e7b38a8f86d1ab2f096f37b627">entt::id_type</a> components[] = { <a class="code" href="structentt_1_1type__hash.html#a95f5ae709a95f0959a7dfd1af6af6c74">entt::type_hash&lt;position&gt;::value</a>() };</div>
<div class="line"><a class="code" href="namespaceentt.html#a13e040e7b38a8f86d1ab2f096f37b627">entt::id_type</a> filter[] = { <a class="code" href="structentt_1_1type__hash.html#a95f5ae709a95f0959a7dfd1af6af6c74">entt::type_hash&lt;velocity&gt;::value</a>() };</div>
<div class="line"><span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.runtime_view(std::cbegin(components), std::cend(components), std::cbegin(filter), std::cend(filter));</div>
</div><!-- fragment --><p><b>Note</b>: runtime views are meant for all those cases where users don't know at compile-time what components to <em>use</em> to iterate entities. If possible, don't use runtime views as their performance are inferior to those of the other views.</p>
<h2><a class="anchor" id="autotoc_md83"></a>
<div class="fragment"><div class="line"><a class="code" href="structentt_1_1basic__runtime__view.html">entt::runtime_view</a> <a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a>{};</div>
<div class="line"><a class="code" href="namespaceentt.html#a87b7ba6bd51a290113765bc97188d247">view</a>.iterate(<a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;position&gt;()).exclude(<a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.storage&lt;velocity&gt;());</div>
</div><!-- fragment --><p>Runtime views are meant for when users don't know at compile-time what types to <em>use</em> to iterate entities. The <code>storage</code> member function of a registry could be useful in this regard.</p>
<h2><a class="anchor" id="autotoc_md86"></a>
Groups</h2>
<p>Groups are meant to iterate multiple components at once and to offer a faster alternative to multi type views.<br />
Groups overcome the performance of the other tools available but require to get the ownership of components and this sets some constraints on pools. On the other side, groups aren't an automatism that increases memory consumption, affects functionalities and tries to optimize iterations for all the possible combinations of components. Users can decide when to pay for groups and to what extent.<br />
@@ -868,7 +846,7 @@ Groups</h2>
</div><!-- fragment --><p>Note that entities can also be excluded from the parameter list when received through a callback and this can improve even further the performance during iterations.<br />
Since they aren't explicitly instantiated, empty components aren't returned in any case.</p>
<p><b>Note</b>: prefer the <code>get</code> member function of a group instead of that of a registry during iterations to get the types iterated by the group itself.</p>
<h3><a class="anchor" id="autotoc_md84"></a>
<h3><a class="anchor" id="autotoc_md87"></a>
Full-owning groups</h3>
<p>A full-owning group is the fastest tool an user can expect to use to iterate multiple components at once. It iterates all the components directly, no indirection required. This type of groups performs more or less as if users are accessing sequentially a bunch of packed arrays of components all sorted identically, with no jumps nor branches.</p>
<p>A full-owning group is created as:</p>
@@ -877,7 +855,7 @@ Full-owning groups</h3>
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a2628e82fa8042f75d817c58fc09c7aaf">group</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.group&lt;position, velocity&gt;(entt::exclude&lt;renderable&gt;);</div>
</div><!-- fragment --><p>Once created, the group gets the ownership of all the components specified in the template parameter list and arranges their pools as needed.</p>
<p>Sorting owned components is no longer allowed once the group has been created. However, full-owning groups can be sorted by means of their <code>sort</code> member functions. Sorting a full-owning group affects all its instances.</p>
<h3><a class="anchor" id="autotoc_md85"></a>
<h3><a class="anchor" id="autotoc_md88"></a>
Partial-owning groups</h3>
<p>A partial-owning group works similarly to a full-owning group for the components it owns, but relies on indirection to get components owned by other groups. This isn't as fast as a full-owning group, but it's already much faster than views when there are only one or two free components to retrieve (the most common cases likely). In the worst case, it's not slower than views anyway.</p>
<p>A partial-owning group is created as:</p>
@@ -886,7 +864,7 @@ Partial-owning groups</h3>
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a2628e82fa8042f75d817c58fc09c7aaf">group</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.group&lt;position&gt;(entt::get&lt;velocity&gt;, entt::exclude&lt;renderable&gt;);</div>
</div><!-- fragment --><p>Once created, the group gets the ownership of all the components specified in the template parameter list and arranges their pools as needed. The ownership of the types provided via <code><a class="el" href="namespaceentt.html#a8c24ecc5ab0055f9f2a4725c95afb29e" title="Variable template for lists of observed components.">entt::get</a></code> doesn't pass to the group instead.</p>
<p>Sorting owned components is no longer allowed once the group has been created. However, partial-owning groups can be sorted by means of their <code>sort</code> member functions. Sorting a partial-owning group affects all its instances.</p>
<h3><a class="anchor" id="autotoc_md86"></a>
<h3><a class="anchor" id="autotoc_md89"></a>
Non-owning groups</h3>
<p>Non-owning groups are usually fast enough, for sure faster than views and well suited for most of the cases. However, they require custom data structures to work properly and they increase memory consumption. As a rule of thumb, users should avoid using non-owning groups, if possible.</p>
<p>A non-owning group is created as:</p>
@@ -895,7 +873,7 @@ Non-owning groups</h3>
<div class="fragment"><div class="line"><span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a2628e82fa8042f75d817c58fc09c7aaf">group</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.group&lt;&gt;(entt::get&lt;position, velocity&gt;, entt::exclude&lt;renderable&gt;);</div>
</div><!-- fragment --><p>The group doesn't receive the ownership of any type of component in this case. This type of groups is therefore the least performing in general, but also the only one that can be used in any situation to slightly improve performance.</p>
<p>Non-owning groups can be sorted by means of their <code>sort</code> member functions. Sorting a non-owning group affects all its instances.</p>
<h3><a class="anchor" id="autotoc_md87"></a>
<h3><a class="anchor" id="autotoc_md90"></a>
Nested groups</h3>
<p>A type of component cannot be owned by two or more conflicting groups such as:</p>
<ul>
@@ -909,7 +887,7 @@ Nested groups</h3>
</ul>
<p>Fortunately, these are also very common cases if not the most common ones.<br />
It allows to increase performance on a greater number of component combinations.</p>
<p>Two nested groups are such that they own at least one componet type and the list of component types involved by one of them is contained entirely in that of the other. More specifically, this applies independently to all component lists used to define a group.<br />
<p>Two nested groups are such that they own at least one component type and the list of component types involved by one of them is contained entirely in that of the other. More specifically, this applies independently to all component lists used to define a group.<br />
Therefore, the rules for defining whether two or more groups are nested can be summarized as:</p>
<ul>
<li>One of the groups involves one or more additional component types with respect to the other, whether they are owned, observed or excluded.</li>
@@ -940,7 +918,7 @@ Nested groups</h3>
In fact, given a list of component types involved by a group, the greater the number of those owned, the greater the performance of the group itself.</p>
<p>As a side note, it's no longer possible to sort all groups when defining nested ones. This is because the most restrictive group shares its elements with the less restrictive ones and ordering the latter would invalidate the former.<br />
However, given a family of nested groups, it's still possible to sort the most restrictive of them. To prevent users from having to remember which of their groups is the most restrictive, the registry class offers the <code>sortable</code> member function to know if a group can be sorted or not.</p>
<h2><a class="anchor" id="autotoc_md88"></a>
<h2><a class="anchor" id="autotoc_md91"></a>
Types: const, non-const and all in between</h2>
<p>The <code>registry</code> class offers two overloads when it comes to constructing views and groups: a const version and a non-const one. The former accepts only const types as template parameters, the latter accepts both const and non-const types instead.<br />
It means that views and groups can be constructed from a const registry and they propagate the constness of the registry to the types involved. As an example:</p>
@@ -964,7 +942,7 @@ Types: const, non-const and all in between</h2>
<div class="line">});</div>
</div><!-- fragment --><p>A caller can still refer to the <code>position</code> components through a const reference because of the rules of the language that fortunately already allow it.</p>
<p>The same concepts apply to groups as well.</p>
<h2><a class="anchor" id="autotoc_md89"></a>
<h2><a class="anchor" id="autotoc_md92"></a>
Give me everything</h2>
<p>Views and groups are narrow windows on the entire list of entities. They work by filtering entities according to their components.<br />
In some cases there may be the need to iterate all the entities still in use regardless of their components. The registry offers a specific member function to do that:</p>
@@ -980,7 +958,7 @@ Give me everything</h2>
<div class="line">});</div>
</div><!-- fragment --><p>In general, iterating all entities can result in poor performance. It should not be done frequently to avoid the risk of a performance hit.<br />
However, it can be convenient when initializing an editor or to reclaim pending identifiers.</p>
<h2><a class="anchor" id="autotoc_md90"></a>
<h2><a class="anchor" id="autotoc_md93"></a>
What is allowed and what is not</h2>
<p>Most of the <em>ECS</em> available out there don't allow to create and destroy entities and components during iterations, nor to have pointer stability.<br />
<code>EnTT</code> partially solves the problem with a few limitations:</p>
@@ -1005,9 +983,9 @@ What is allowed and what is not</h2>
<li>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.</li>
</ul>
<p>A notable side effect of this feature is that the number of required allocations is further reduced in most cases.</p>
<h3><a class="anchor" id="autotoc_md91"></a>
<h3><a class="anchor" id="autotoc_md94"></a>
More performance, more constraints</h3>
<p>Groups are a (much) faster alternative to views. However, the higher the performance, the greater the constraints on what is allowed and what is not.<br />
<p>Groups are a faster alternative to views. However, the higher the performance, the greater the constraints on what is allowed and what is not.<br />
In particular, groups add in some rare cases a limitation on the creation of components during iterations. It happens in quite particular cases. Given the nature and the scope of the groups, it isn't something in which it will happen to come across probably, but it's good to know it anyway.</p>
<p>First of all, it must be said that creating components while iterating a group isn't a problem at all and can be done freely as it happens with the views. The same applies to the destruction of components and entities, for which the rules mentioned above apply.</p>
<p>The additional limitation pops out instead when a given component that is owned by a group is iterated outside of it. In this case, adding components that are part of the group itself may invalidate the iterators. There are no further limitations to the destruction of components and entities.<br />
@@ -1018,20 +996,15 @@ More performance, more constraints</h3>
</ul>
<p>In other words, the limitation doesn't exist as long as a type is treated as a free type (as an example with multi type views and partial- or non-owning groups) or iterated with its own group, but it can occur if the type is used as a main type to rule on an iteration.<br />
This happens because groups own the pools of their components and organize the data internally to maximize performance. Because of that, full consistency for owned components is guaranteed only when they are iterated as part of their groups or as free types with multi type views and groups in general.</p>
<h1><a class="anchor" id="autotoc_md92"></a>
<h1><a class="anchor" id="autotoc_md95"></a>
Empty type optimization</h1>
<p>An empty type <code>T</code> is such that <code>std::is_empty_v&lt;T&gt;</code> returns true. They are also the same types for which <em>empty base optimization</em> (EBO) is possibile.<br />
<p>An empty type <code>T</code> is such that <code>std::is_empty_v&lt;T&gt;</code> returns true. They also are the same types for which <em>empty base optimization</em> (EBO) is possible.<br />
<code>EnTT</code> handles these types in a special way, optimizing both in terms of performance and memory usage. However, this also has consequences that are worth mentioning.</p>
<p>When an empty type is detected, it's not instantiated in any case. Therefore, only the entities to which it's assigned are made available.<br />
There doesn't exist a way to <em>get</em> empty types from a registry, views and groups will never return instances for them (for example, during a call to <code>each</code>) and some functions such as <code>try_get</code> or the raw access to the list of components aren't available for empty types. Finally, the <code>sort</code> functionality will only accepts callbacks that require to return entities rather than components:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.sort&lt;empty_type&gt;([](<span class="keyword">const</span> <a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> lhs, <span class="keyword">const</span> <a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a> rhs) {</div>
<div class="line"> <span class="keywordflow">return</span> entt::registry::entity(lhs) &lt; entt::registry::entity(rhs);</div>
<div class="line">});</div>
</div><!-- fragment --><p>On the other hand, iterations are faster because only the entities to which the type is assigned are considered. Moreover, less memory is used, mainly because there doesn't exist any instance of the component, no matter how many entities it is assigned to.</p>
<p>More in general, none of the features offered by the library is affected, but for the ones that require to return actual instances.<br />
This optimization can be disabled for the whole application by defining the <code>ENTT_NO_ETO</code> macro. In this case, empty types will be treated like all other types, no matter what.<br />
Otherwise, users can specialize the <code>component_traits</code> template class and in particular the <code>ignore_if_empty</code> alias, disabling this optimization for some types only.</p>
<h1><a class="anchor" id="autotoc_md93"></a>
<p>When an empty type is detected, it's not instantiated by default. Therefore, only the entities to which it's assigned are made available. There doesn't exist a way to <em>get</em> empty types from a registry. Views and groups will never return their instances (for example, during a call to <code>each</code>).<br />
On the other hand, iterations are faster because only the entities to which the type is assigned are considered. Moreover, less memory is used, mainly because there doesn't exist any instance of the component, no matter how many entities it is assigned to.</p>
<p>More in general, none of the feature offered by the library is affected, but for the ones that require to return actual instances.<br />
This optimization is disabled by defining the <code>ENTT_NO_ETO</code> macro. In this case, empty types are treated like all other types. Setting a page size at component level via the <code>component_traits</code> class template is another way to disable this optimization selectively rather than globally.</p>
<h1><a class="anchor" id="autotoc_md96"></a>
Multithreading</h1>
<p>In general, the entire registry isn't thread safe as it is. Thread safety isn't something that users should want out of the box for several reasons. Just to mention one of them: performance.<br />
Views, groups and consequently the approach adopted by <code>EnTT</code> are the great exception to the rule. It's true that views, groups and iterators in general aren't thread safe by themselves. Because of this users shouldn't try to iterate a set of components and modify the same set concurrently. However:</p>
@@ -1044,7 +1017,7 @@ Multithreading</h1>
<p>Finally, <code>EnTT</code> can be configured via a few compile-time definitions to make some of its parts implicitly thread-safe, roughly speaking only the ones that really make sense and can't be turned around.<br />
In particular, when multiple instances of objects referencing the type index generator (such as the <code>registry</code> class) are used in different threads, then it might be useful to define <code>ENTT_USE_ATOMIC</code>.<br />
See the relevant documentation for more information.</p>
<h2><a class="anchor" id="autotoc_md94"></a>
<h2><a class="anchor" id="autotoc_md97"></a>
Iterators</h2>
<p>A special mention is needed for the iterators returned by views and groups. Most of the times they meet the requirements of random access iterators, in all cases they meet at least the requirements of forward iterators.<br />
In other terms, they are suitable for use with the parallel algorithms of the standard library. If it's not clear, this is a great thing.</p>
@@ -1057,7 +1030,7 @@ Iterators</h2>
</div><!-- fragment --><p>This can increase the throughput considerably, even without resorting to who knows what artifacts that are difficult to maintain over time.</p>
<p>Unfortunately, because of the limitations of the current revision of the standard, the parallel <code>std::for_each</code> accepts only forward iterators. This means that the default iterators provided by the library cannot return proxy objects as references and <b>must</b> return actual reference types instead.<br />
This may change in the future and the iterators will almost certainly return both the entities and a list of references to their components by default sooner or later. Multi-pass guarantee won't break in any case and the performance should even benefit from it further.</p>
<h2><a class="anchor" id="autotoc_md95"></a>
<h2><a class="anchor" id="autotoc_md98"></a>
Const registry</h2>
<p>A const registry is also fully thread safe. This means that it won't be able to lazily initialize a missing storage when a view is generated.<br />
The reason for this is easy to explain. To avoid requiring types to be <em>announced</em> in advance, a registry lazily creates the storage objects for the different components. However, this isn't possible for a thread safe const registry.<br />
@@ -1066,9 +1039,9 @@ Const registry</h2>
As a result, a view created from a const registry may behave incorrectly over time if it's kept for a second use.<br />
Therefore, if the general advice is to create views when necessary and discard them immediately afterwards, this becomes almost a rule when it comes to views generated from a const registry.</p>
<p>Fortunately, there is also a way to instantiate storage classes early when in doubt or when there are special requirements.<br />
Calling the <code>prepare</code> method is equivalent to <em>announcing</em> the existence of a particular storage, to avoid running into problems. For those interested, there are also alternative approaches, such as a single threaded tick for the registry warm-up, but these are not always applicable.<br />
Calling the <code>storage</code> method is equivalent to <em>announcing</em> the existence of a particular storage, to avoid running into problems. For those interested, there are also alternative approaches, such as a single threaded tick for the registry warm-up, but these are not always applicable.<br />
In this case, no placeholders will be used since all storage exist. In other words, views never risk becoming <em>invalid</em>.</p>
<h1><a class="anchor" id="autotoc_md96"></a>
<h1><a class="anchor" id="autotoc_md99"></a>
Beyond this document</h1>
<p>There are many other features and functions not listed in this document.<br />
<code>EnTT</code> and in particular its ECS part is in continuous development and some things could be forgotten, others could have been omitted on purpose to reduce the size of this file. Unfortunately, some parts may even be outdated and still to be updated.</p>