75 lines
221 KiB
HTML
75 lines
221 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.13"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>EnTT: docs/md/entity.md Source File</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">EnTT
|
|
 <span id="projectnumber">3.2.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.13 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">docs/md/entity.md</div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> # Crash Course: entity-component system</div><div class="line"><a name="l00002"></a><span class="lineno"> 2</span> </div><div class="line"><a name="l00003"></a><span class="lineno"> 3</span> <!--</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> @cond TURN_OFF_DOXYGEN</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> --></div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span> # Table of Contents</div><div class="line"><a name="l00007"></a><span class="lineno"> 7</span> </div><div class="line"><a name="l00008"></a><span class="lineno"> 8</span> * [Introduction](#introduction)</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span> * [Design decisions](#design-decisions)</div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span>  * [A bitset-free entity-component system](#a-bitset-free-entity-component-system)</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span>  * [Pay per use](#pay-per-use)</div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span>  * [All or nothing](#all-or-nothing)</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span>  * [Stateless systems](#stateless-systems)</div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span> * [Vademecum](#vademecum)</div><div class="line"><a name="l00015"></a><span class="lineno"> 15</span> * [The Registry, the Entity and the Component](#the-registry-the-entity-and-the-component)</div><div class="line"><a name="l00016"></a><span class="lineno"> 16</span>  * [Observe changes](#observe-changes)</div><div class="line"><a name="l00017"></a><span class="lineno"> 17</span>  * [They call me Reactive System](#they-call-me-reactive-system)</div><div class="line"><a name="l00018"></a><span class="lineno"> 18</span>  * [Runtime components](#runtime-components)</div><div class="line"><a name="l00019"></a><span class="lineno"> 19</span>  * [A journey through a plugin](#a-journey-through-a-plugin)</div><div class="line"><a name="l00020"></a><span class="lineno"> 20</span>  * [Sorting: is it possible?](#sorting-is-it-possible)</div><div class="line"><a name="l00021"></a><span class="lineno"> 21</span>  * [Helpers](#helpers)</div><div class="line"><a name="l00022"></a><span class="lineno"> 22</span>  * [Null entity](#null-entity)</div><div class="line"><a name="l00023"></a><span class="lineno"> 23</span>  * [Stomp and spawn](#stomp-and-spawn)</div><div class="line"><a name="l00024"></a><span class="lineno"> 24</span>  * [Dependencies](#dependencies)</div><div class="line"><a name="l00025"></a><span class="lineno"> 25</span>  * [Tags](#tags)</div><div class="line"><a name="l00026"></a><span class="lineno"> 26</span>  * [Actor](#actor)</div><div class="line"><a name="l00027"></a><span class="lineno"> 27</span>  * [Context variables](#context-variables)</div><div class="line"><a name="l00028"></a><span class="lineno"> 28</span>  * [Snapshot: complete vs continuous](#snapshot-complete-vs-continuous)</div><div class="line"><a name="l00029"></a><span class="lineno"> 29</span>  * [Snapshot loader](#snapshot-loader)</div><div class="line"><a name="l00030"></a><span class="lineno"> 30</span>  * [Continuous loader](#continuous-loader)</div><div class="line"><a name="l00031"></a><span class="lineno"> 31</span>  * [Archives](#archives)</div><div class="line"><a name="l00032"></a><span class="lineno"> 32</span>  * [One example to rule them all](#one-example-to-rule-them-all)</div><div class="line"><a name="l00033"></a><span class="lineno"> 33</span> * [Views and Groups](#views-and-groups)</div><div class="line"><a name="l00034"></a><span class="lineno"> 34</span>  * [Views](#views)</div><div class="line"><a name="l00035"></a><span class="lineno"> 35</span>  * [Runtime views](#runtime-views)</div><div class="line"><a name="l00036"></a><span class="lineno"> 36</span>  * [Groups](#groups)</div><div class="line"><a name="l00037"></a><span class="lineno"> 37</span>  * [Full-owning groups](#full-owning-groups)</div><div class="line"><a name="l00038"></a><span class="lineno"> 38</span>  * [Partial-owning groups](#partial-owning-groups)</div><div class="line"><a name="l00039"></a><span class="lineno"> 39</span>  * [Non-owning groups](#non-owning-groups)</div><div class="line"><a name="l00040"></a><span class="lineno"> 40</span>  * [Nested groups](#nested-groups)</div><div class="line"><a name="l00041"></a><span class="lineno"> 41</span>  * [Types: const, non-const and all in between](#types-const-non-const-and-all-in-between)</div><div class="line"><a name="l00042"></a><span class="lineno"> 42</span>  * [Give me everything](#give-me-everything)</div><div class="line"><a name="l00043"></a><span class="lineno"> 43</span>  * [What is allowed and what is not](#what-is-allowed-and-what-is-not)</div><div class="line"><a name="l00044"></a><span class="lineno"> 44</span>  * [More performance, more constraints](#more-performance-more-constraints)</div><div class="line"><a name="l00045"></a><span class="lineno"> 45</span> * [Empty type optimization](#empty-type-optimization)</div><div class="line"><a name="l00046"></a><span class="lineno"> 46</span> * [Multithreading](#multithreading)</div><div class="line"><a name="l00047"></a><span class="lineno"> 47</span>  * [Iterators](#iterators)</div><div class="line"><a name="l00048"></a><span class="lineno"> 48</span> * [Beyond this document](#beyond-this-document)</div><div class="line"><a name="l00049"></a><span class="lineno"> 49</span> <!--</div><div class="line"><a name="l00050"></a><span class="lineno"> 50</span> @endcond TURN_OFF_DOXYGEN</div><div class="line"><a name="l00051"></a><span class="lineno"> 51</span> --></div><div class="line"><a name="l00052"></a><span class="lineno"> 52</span> </div><div class="line"><a name="l00053"></a><span class="lineno"> 53</span> # Introduction</div><div class="line"><a name="l00054"></a><span class="lineno"> 54</span> </div><div class="line"><a name="l00055"></a><span class="lineno"> 55</span> `EnTT` is a header-only, tiny and easy to use entity-component system (and much</div><div class="line"><a name="l00056"></a><span class="lineno"> 56</span> more) written in modern C++.<br/></div><div class="line"><a name="l00057"></a><span class="lineno"> 57</span> The entity-component-system (also known as _ECS_) is an architectural pattern</div><div class="line"><a name="l00058"></a><span class="lineno"> 58</span> used mostly in game development.</div><div class="line"><a name="l00059"></a><span class="lineno"> 59</span> </div><div class="line"><a name="l00060"></a><span class="lineno"> 60</span> # Design decisions</div><div class="line"><a name="l00061"></a><span class="lineno"> 61</span> </div><div class="line"><a name="l00062"></a><span class="lineno"> 62</span> ## A bitset-free entity-component system</div><div class="line"><a name="l00063"></a><span class="lineno"> 63</span> </div><div class="line"><a name="l00064"></a><span class="lineno"> 64</span> `EnTT` offers a _bitset-free_ entity-component system that doesn't require users</div><div class="line"><a name="l00065"></a><span class="lineno"> 65</span> to specify the set of components neither at compile-time nor at runtime before</div><div class="line"><a name="l00066"></a><span class="lineno"> 66</span> being able to use the library itself.<br/></div><div class="line"><a name="l00067"></a><span class="lineno"> 67</span> This is why users can instantiate the core class simply like:</div><div class="line"><a name="l00068"></a><span class="lineno"> 68</span> </div><div class="line"><a name="l00069"></a><span class="lineno"> 69</span> ```cpp</div><div class="line"><a name="l00070"></a><span class="lineno"> 70</span> entt::registry registry;</div><div class="line"><a name="l00071"></a><span class="lineno"> 71</span> ```</div><div class="line"><a name="l00072"></a><span class="lineno"> 72</span> </div><div class="line"><a name="l00073"></a><span class="lineno"> 73</span> In place of its more annoying and error-prone counterpart:</div><div class="line"><a name="l00074"></a><span class="lineno"> 74</span> </div><div class="line"><a name="l00075"></a><span class="lineno"> 75</span> ```cpp</div><div class="line"><a name="l00076"></a><span class="lineno"> 76</span> entt::registry<comp_0, comp_1, ..., comp_n> registry;</div><div class="line"><a name="l00077"></a><span class="lineno"> 77</span> ```</div><div class="line"><a name="l00078"></a><span class="lineno"> 78</span> </div><div class="line"><a name="l00079"></a><span class="lineno"> 79</span> Furthermore, there is no need to indicate to the library in any way that a type</div><div class="line"><a name="l00080"></a><span class="lineno"> 80</span> of component exists and will be used sooner or later. When the time comes, users</div><div class="line"><a name="l00081"></a><span class="lineno"> 81</span> can just use it and that's all.</div><div class="line"><a name="l00082"></a><span class="lineno"> 82</span> </div><div class="line"><a name="l00083"></a><span class="lineno"> 83</span> ## Pay per use</div><div class="line"><a name="l00084"></a><span class="lineno"> 84</span> </div><div class="line"><a name="l00085"></a><span class="lineno"> 85</span> `EnTT` is entirely designed around the principle that users have to pay only for</div><div class="line"><a name="l00086"></a><span class="lineno"> 86</span> what they want.</div><div class="line"><a name="l00087"></a><span class="lineno"> 87</span> </div><div class="line"><a name="l00088"></a><span class="lineno"> 88</span> When it comes to using an entity-component system, the tradeoff is usually</div><div class="line"><a name="l00089"></a><span class="lineno"> 89</span> between performance and memory usage. The faster it is, the more memory it uses.</div><div class="line"><a name="l00090"></a><span class="lineno"> 90</span> Even worse, some approaches tend to heavily affect other functionalities like</div><div class="line"><a name="l00091"></a><span class="lineno"> 91</span> the construction and destruction of components to favor iterations, even when it</div><div class="line"><a name="l00092"></a><span class="lineno"> 92</span> isn't strictly required. In fact, slightly worse performance along non-critical</div><div class="line"><a name="l00093"></a><span class="lineno"> 93</span> paths are the right price to pay to reduce memory usage and have overall better</div><div class="line"><a name="l00094"></a><span class="lineno"> 94</span> perfomance sometimes and I've always wondered why this kind of tools do not</div><div class="line"><a name="l00095"></a><span class="lineno"> 95</span> leave me the choice.<br/></div><div class="line"><a name="l00096"></a><span class="lineno"> 96</span> `EnTT` follows a completely different approach. It gets the best out from the</div><div class="line"><a name="l00097"></a><span class="lineno"> 97</span> basic data structures and gives users the possibility to pay more for higher</div><div class="line"><a name="l00098"></a><span class="lineno"> 98</span> performance where needed.<br/></div><div class="line"><a name="l00099"></a><span class="lineno"> 99</span> The disadvantage of this approach is that users need to know the systems they</div><div class="line"><a name="l00100"></a><span class="lineno"> 100</span> are working on and the tools they are using. Otherwise, the risk to ruin the</div><div class="line"><a name="l00101"></a><span class="lineno"> 101</span> performance along critical paths is high.</div><div class="line"><a name="l00102"></a><span class="lineno"> 102</span> </div><div class="line"><a name="l00103"></a><span class="lineno"> 103</span> So far, this choice has proven to be a good one and I really hope it can be for</div><div class="line"><a name="l00104"></a><span class="lineno"> 104</span> many others besides me.</div><div class="line"><a name="l00105"></a><span class="lineno"> 105</span> </div><div class="line"><a name="l00106"></a><span class="lineno"> 106</span> ## All or nothing</div><div class="line"><a name="l00107"></a><span class="lineno"> 107</span> </div><div class="line"><a name="l00108"></a><span class="lineno"> 108</span> `EnTT` is such that at every moment a pair `(T *, size)` is available to</div><div class="line"><a name="l00109"></a><span class="lineno"> 109</span> directly access all the instances of a given component type `T`.<br/></div><div class="line"><a name="l00110"></a><span class="lineno"> 110</span> This was a guideline and a design decision that influenced many choices, for</div><div class="line"><a name="l00111"></a><span class="lineno"> 111</span> better and for worse. I cannot say whether it will be useful or not to the</div><div class="line"><a name="l00112"></a><span class="lineno"> 112</span> reader, but it's worth to mention it, because it's one of the corner stones of</div><div class="line"><a name="l00113"></a><span class="lineno"> 113</span> this library.</div><div class="line"><a name="l00114"></a><span class="lineno"> 114</span> </div><div class="line"><a name="l00115"></a><span class="lineno"> 115</span> Many of the tools described below, from the registry to the views and up to the</div><div class="line"><a name="l00116"></a><span class="lineno"> 116</span> groups give the possibility to get this information and have been designed</div><div class="line"><a name="l00117"></a><span class="lineno"> 117</span> around this need, which was and remains one of my main requirements during the</div><div class="line"><a name="l00118"></a><span class="lineno"> 118</span> development.<br/></div><div class="line"><a name="l00119"></a><span class="lineno"> 119</span> The rest is experimentation and the desire to invent something new, hoping to</div><div class="line"><a name="l00120"></a><span class="lineno"> 120</span> have succeeded.</div><div class="line"><a name="l00121"></a><span class="lineno"> 121</span> </div><div class="line"><a name="l00122"></a><span class="lineno"> 122</span> ## Stateless systems</div><div class="line"><a name="l00123"></a><span class="lineno"> 123</span> </div><div class="line"><a name="l00124"></a><span class="lineno"> 124</span> `EnTT` is designed so that it can work with _stateless systems_. In other words,</div><div class="line"><a name="l00125"></a><span class="lineno"> 125</span> all systems can be free functions and there is no need to define them as classes</div><div class="line"><a name="l00126"></a><span class="lineno"> 126</span> (although nothing prevents users from doing so).<br/></div><div class="line"><a name="l00127"></a><span class="lineno"> 127</span> This is possible because the main class with which the users will work provides</div><div class="line"><a name="l00128"></a><span class="lineno"> 128</span> all what is needed to act as the sole _source of truth_ of an application.</div><div class="line"><a name="l00129"></a><span class="lineno"> 129</span> </div><div class="line"><a name="l00130"></a><span class="lineno"> 130</span> To be honest, this point became part of the design principles at a later date,</div><div class="line"><a name="l00131"></a><span class="lineno"> 131</span> but has also become one of the cornerstones of the library to date, as stateless</div><div class="line"><a name="l00132"></a><span class="lineno"> 132</span> systems are widely used and appreciated in general.</div><div class="line"><a name="l00133"></a><span class="lineno"> 133</span> </div><div class="line"><a name="l00134"></a><span class="lineno"> 134</span> # Vademecum</div><div class="line"><a name="l00135"></a><span class="lineno"> 135</span> </div><div class="line"><a name="l00136"></a><span class="lineno"> 136</span> The registry to store, the views and the groups to iterate. That's all.</div><div class="line"><a name="l00137"></a><span class="lineno"> 137</span> </div><div class="line"><a name="l00138"></a><span class="lineno"> 138</span> An entity (the _E_ of an _ECS_) is an opaque identifier that users should just</div><div class="line"><a name="l00139"></a><span class="lineno"> 139</span> use as-is and store around if needed. Do not try to inspect an entity</div><div class="line"><a name="l00140"></a><span class="lineno"> 140</span> identifier, its format can change in future and a registry offers all the</div><div class="line"><a name="l00141"></a><span class="lineno"> 141</span> functionalities to query them out-of-the-box. The underlying type of an entity</div><div class="line"><a name="l00142"></a><span class="lineno"> 142</span> (either `std::uint16_t`, `std::uint32_t` or `std::uint64_t`) can be specified</div><div class="line"><a name="l00143"></a><span class="lineno"> 143</span> when defining a registry. In fact, an `entt::registry` is nothing more than an</div><div class="line"><a name="l00144"></a><span class="lineno"> 144</span> alias for `entt::basic_registry<entt::entity>` and `entt::entity` is a distinct</div><div class="line"><a name="l00145"></a><span class="lineno"> 145</span> type that implements the concept of _entity identifier_.<br/></div><div class="line"><a name="l00146"></a><span class="lineno"> 146</span> Components (the _C_ of an _ECS_) should be plain old data structures or more</div><div class="line"><a name="l00147"></a><span class="lineno"> 147</span> complex and movable data structures with a proper constructor. Actually, the</div><div class="line"><a name="l00148"></a><span class="lineno"> 148</span> sole requirement of a component type is that it must be both move constructible</div><div class="line"><a name="l00149"></a><span class="lineno"> 149</span> and move assignable. They are list initialized by using the parameters provided</div><div class="line"><a name="l00150"></a><span class="lineno"> 150</span> to construct the component itself. No need to register components or their types</div><div class="line"><a name="l00151"></a><span class="lineno"> 151</span> neither with the registry nor with the entity-component system at all.<br/></div><div class="line"><a name="l00152"></a><span class="lineno"> 152</span> Systems (the _S_ of an _ECS_) are just plain functions, functors, lambdas or</div><div class="line"><a name="l00153"></a><span class="lineno"> 153</span> whatever users want. They can accept a registry, a view or a group of any type</div><div class="line"><a name="l00154"></a><span class="lineno"> 154</span> and use them the way they prefer. No need to register systems or their types</div><div class="line"><a name="l00155"></a><span class="lineno"> 155</span> neither with the registry nor with the entity-component system at all.</div><div class="line"><a name="l00156"></a><span class="lineno"> 156</span> </div><div class="line"><a name="l00157"></a><span class="lineno"> 157</span> The following sections will explain in short how to use the entity-component</div><div class="line"><a name="l00158"></a><span class="lineno"> 158</span> system, the core part of the whole library.<br/></div><div class="line"><a name="l00159"></a><span class="lineno"> 159</span> In fact, the project is composed of many other classes in addition to those</div><div class="line"><a name="l00160"></a><span class="lineno"> 160</span> describe below. For more details, please refer to the inline documentation.</div><div class="line"><a name="l00161"></a><span class="lineno"> 161</span> </div><div class="line"><a name="l00162"></a><span class="lineno"> 162</span> # The Registry, the Entity and the Component</div><div class="line"><a name="l00163"></a><span class="lineno"> 163</span> </div><div class="line"><a name="l00164"></a><span class="lineno"> 164</span> A registry can store and manage entities, as well as create views and groups to</div><div class="line"><a name="l00165"></a><span class="lineno"> 165</span> iterate the underlying data structures.<br/></div><div class="line"><a name="l00166"></a><span class="lineno"> 166</span> The class template `basic_registry` lets users decide what's the preferred type</div><div class="line"><a name="l00167"></a><span class="lineno"> 167</span> to represent an entity. Because `std::uint32_t` is large enough for almost all</div><div class="line"><a name="l00168"></a><span class="lineno"> 168</span> the cases, there exists also the type `entt::entity` for it, as well as the</div><div class="line"><a name="l00169"></a><span class="lineno"> 169</span> alias `entt::registry` for `entt::basic_registry<entt::entity>`.</div><div class="line"><a name="l00170"></a><span class="lineno"> 170</span> </div><div class="line"><a name="l00171"></a><span class="lineno"> 171</span> Entities are represented by _entity identifiers_. An entity identifier is an</div><div class="line"><a name="l00172"></a><span class="lineno"> 172</span> opaque type that users should not inspect or modify in any way. It carries</div><div class="line"><a name="l00173"></a><span class="lineno"> 173</span> information about the entity itself and its version.<br/></div><div class="line"><a name="l00174"></a><span class="lineno"> 174</span> User defined identifiers can be introduced by means of the `ENTT_OPAQUE_TYPE`</div><div class="line"><a name="l00175"></a><span class="lineno"> 175</span> macro if needed.</div><div class="line"><a name="l00176"></a><span class="lineno"> 176</span> </div><div class="line"><a name="l00177"></a><span class="lineno"> 177</span> A registry is used both to construct and to destroy entities:</div><div class="line"><a name="l00178"></a><span class="lineno"> 178</span> </div><div class="line"><a name="l00179"></a><span class="lineno"> 179</span> ```cpp</div><div class="line"><a name="l00180"></a><span class="lineno"> 180</span> // constructs a naked entity with no components and returns its identifier</div><div class="line"><a name="l00181"></a><span class="lineno"> 181</span> auto entity = registry.create();</div><div class="line"><a name="l00182"></a><span class="lineno"> 182</span> </div><div class="line"><a name="l00183"></a><span class="lineno"> 183</span> // destroys an entity and all its components</div><div class="line"><a name="l00184"></a><span class="lineno"> 184</span> registry.destroy(entity);</div><div class="line"><a name="l00185"></a><span class="lineno"> 185</span> ```</div><div class="line"><a name="l00186"></a><span class="lineno"> 186</span> </div><div class="line"><a name="l00187"></a><span class="lineno"> 187</span> There exists also an overload of the `create` and `destroy` member functions</div><div class="line"><a name="l00188"></a><span class="lineno"> 188</span> that accepts two iterators, that is a range to assign or to destroy. It can be</div><div class="line"><a name="l00189"></a><span class="lineno"> 189</span> used to create or destroy multiple entities at once:</div><div class="line"><a name="l00190"></a><span class="lineno"> 190</span> </div><div class="line"><a name="l00191"></a><span class="lineno"> 191</span> ```cpp</div><div class="line"><a name="l00192"></a><span class="lineno"> 192</span> // destroys all the entities in a range</div><div class="line"><a name="l00193"></a><span class="lineno"> 193</span> auto view = registry.view<a_component, another_component>();</div><div class="line"><a name="l00194"></a><span class="lineno"> 194</span> registry.destroy(view.begin(), view.end());</div><div class="line"><a name="l00195"></a><span class="lineno"> 195</span> ```</div><div class="line"><a name="l00196"></a><span class="lineno"> 196</span> </div><div class="line"><a name="l00197"></a><span class="lineno"> 197</span> In both cases, the `create` member function accepts also a list of default</div><div class="line"><a name="l00198"></a><span class="lineno"> 198</span> constructible component types to assign to the entities before to return. It's a</div><div class="line"><a name="l00199"></a><span class="lineno"> 199</span> faster alternative to the creation and subsequent assignment of components in</div><div class="line"><a name="l00200"></a><span class="lineno"> 200</span> separate steps.</div><div class="line"><a name="l00201"></a><span class="lineno"> 201</span> </div><div class="line"><a name="l00202"></a><span class="lineno"> 202</span> When an entity is destroyed, the registry can freely reuse it internally with a</div><div class="line"><a name="l00203"></a><span class="lineno"> 203</span> slightly different identifier. In particular, the version of an entity is</div><div class="line"><a name="l00204"></a><span class="lineno"> 204</span> increased each and every time it's discarded.<br/></div><div class="line"><a name="l00205"></a><span class="lineno"> 205</span> In case entity identifiers are stored around, the registry offers all the</div><div class="line"><a name="l00206"></a><span class="lineno"> 206</span> functionalities required to test them and to get out of them the information</div><div class="line"><a name="l00207"></a><span class="lineno"> 207</span> they carry:</div><div class="line"><a name="l00208"></a><span class="lineno"> 208</span> </div><div class="line"><a name="l00209"></a><span class="lineno"> 209</span> ```cpp</div><div class="line"><a name="l00210"></a><span class="lineno"> 210</span> // returns true if the entity is still valid, false otherwise</div><div class="line"><a name="l00211"></a><span class="lineno"> 211</span> bool b = registry.valid(entity);</div><div class="line"><a name="l00212"></a><span class="lineno"> 212</span> </div><div class="line"><a name="l00213"></a><span class="lineno"> 213</span> // gets the version contained in the entity identifier</div><div class="line"><a name="l00214"></a><span class="lineno"> 214</span> auto version = registry.version(entity);</div><div class="line"><a name="l00215"></a><span class="lineno"> 215</span> </div><div class="line"><a name="l00216"></a><span class="lineno"> 216</span> // gets the actual version for the given entity</div><div class="line"><a name="l00217"></a><span class="lineno"> 217</span> auto curr = registry.current(entity);</div><div class="line"><a name="l00218"></a><span class="lineno"> 218</span> ```</div><div class="line"><a name="l00219"></a><span class="lineno"> 219</span> </div><div class="line"><a name="l00220"></a><span class="lineno"> 220</span> Components can be assigned to or removed from entities at any time with a few</div><div class="line"><a name="l00221"></a><span class="lineno"> 221</span> calls to member functions of the registry. As for the entities, the registry</div><div class="line"><a name="l00222"></a><span class="lineno"> 222</span> offers also a set of functionalities users can use to work with the components.</div><div class="line"><a name="l00223"></a><span class="lineno"> 223</span> </div><div class="line"><a name="l00224"></a><span class="lineno"> 224</span> The `assign` member function template creates, initializes and assigns to an</div><div class="line"><a name="l00225"></a><span class="lineno"> 225</span> entity the given component. It accepts a variable number of arguments to</div><div class="line"><a name="l00226"></a><span class="lineno"> 226</span> construct the component itself if present:</div><div class="line"><a name="l00227"></a><span class="lineno"> 227</span> </div><div class="line"><a name="l00228"></a><span class="lineno"> 228</span> ```cpp</div><div class="line"><a name="l00229"></a><span class="lineno"> 229</span> registry.assign<position>(entity, 0., 0.);</div><div class="line"><a name="l00230"></a><span class="lineno"> 230</span> </div><div class="line"><a name="l00231"></a><span class="lineno"> 231</span> // ...</div><div class="line"><a name="l00232"></a><span class="lineno"> 232</span> </div><div class="line"><a name="l00233"></a><span class="lineno"> 233</span> auto &velocity = registry.assign<velocity>(entity);</div><div class="line"><a name="l00234"></a><span class="lineno"> 234</span> vel.dx = 0.;</div><div class="line"><a name="l00235"></a><span class="lineno"> 235</span> vel.dy = 0.;</div><div class="line"><a name="l00236"></a><span class="lineno"> 236</span> ```</div><div class="line"><a name="l00237"></a><span class="lineno"> 237</span> </div><div class="line"><a name="l00238"></a><span class="lineno"> 238</span> If an entity already has the given component, the `replace` member function</div><div class="line"><a name="l00239"></a><span class="lineno"> 239</span> template can be used to replace it:</div><div class="line"><a name="l00240"></a><span class="lineno"> 240</span> </div><div class="line"><a name="l00241"></a><span class="lineno"> 241</span> ```cpp</div><div class="line"><a name="l00242"></a><span class="lineno"> 242</span> registry.replace<position>(entity, 0., 0.);</div><div class="line"><a name="l00243"></a><span class="lineno"> 243</span> </div><div class="line"><a name="l00244"></a><span class="lineno"> 244</span> // ...</div><div class="line"><a name="l00245"></a><span class="lineno"> 245</span> </div><div class="line"><a name="l00246"></a><span class="lineno"> 246</span> auto &velocity = registry.replace<velocity>(entity);</div><div class="line"><a name="l00247"></a><span class="lineno"> 247</span> vel.dx = 0.;</div><div class="line"><a name="l00248"></a><span class="lineno"> 248</span> vel.dy = 0.;</div><div class="line"><a name="l00249"></a><span class="lineno"> 249</span> ```</div><div class="line"><a name="l00250"></a><span class="lineno"> 250</span> </div><div class="line"><a name="l00251"></a><span class="lineno"> 251</span> In case users want to assign a component to an entity, but it's unknown whether</div><div class="line"><a name="l00252"></a><span class="lineno"> 252</span> the entity already has it or not, `assign_or_replace` does the work in a single</div><div class="line"><a name="l00253"></a><span class="lineno"> 253</span> call (there is a performance penalty to pay for this mainly due to the fact that</div><div class="line"><a name="l00254"></a><span class="lineno"> 254</span> it has to check if the entity already has the given component or not):</div><div class="line"><a name="l00255"></a><span class="lineno"> 255</span> </div><div class="line"><a name="l00256"></a><span class="lineno"> 256</span> ```cpp</div><div class="line"><a name="l00257"></a><span class="lineno"> 257</span> registry.assign_or_replace<position>(entity, 0., 0.);</div><div class="line"><a name="l00258"></a><span class="lineno"> 258</span> </div><div class="line"><a name="l00259"></a><span class="lineno"> 259</span> // ...</div><div class="line"><a name="l00260"></a><span class="lineno"> 260</span> </div><div class="line"><a name="l00261"></a><span class="lineno"> 261</span> auto &velocity = registry.assign_or_replace<velocity>(entity);</div><div class="line"><a name="l00262"></a><span class="lineno"> 262</span> vel.dx = 0.;</div><div class="line"><a name="l00263"></a><span class="lineno"> 263</span> vel.dy = 0.;</div><div class="line"><a name="l00264"></a><span class="lineno"> 264</span> ```</div><div class="line"><a name="l00265"></a><span class="lineno"> 265</span> </div><div class="line"><a name="l00266"></a><span class="lineno"> 266</span> Note that `assign_or_replace` is a slightly faster alternative for the following</div><div class="line"><a name="l00267"></a><span class="lineno"> 267</span> `if/else` statement and nothing more:</div><div class="line"><a name="l00268"></a><span class="lineno"> 268</span> </div><div class="line"><a name="l00269"></a><span class="lineno"> 269</span> ```cpp</div><div class="line"><a name="l00270"></a><span class="lineno"> 270</span> if(registry.has<comp>(entity)) {</div><div class="line"><a name="l00271"></a><span class="lineno"> 271</span>  registry.replace<comp>(entity, arg1, argN);</div><div class="line"><a name="l00272"></a><span class="lineno"> 272</span> } else {</div><div class="line"><a name="l00273"></a><span class="lineno"> 273</span>  registry.assign<comp>(entity, arg1, argN);</div><div class="line"><a name="l00274"></a><span class="lineno"> 274</span> }</div><div class="line"><a name="l00275"></a><span class="lineno"> 275</span> ```</div><div class="line"><a name="l00276"></a><span class="lineno"> 276</span> </div><div class="line"><a name="l00277"></a><span class="lineno"> 277</span> As already shown, if in doubt about whether or not an entity has one or more</div><div class="line"><a name="l00278"></a><span class="lineno"> 278</span> components, the `has` member function template may be useful:</div><div class="line"><a name="l00279"></a><span class="lineno"> 279</span> </div><div class="line"><a name="l00280"></a><span class="lineno"> 280</span> ```cpp</div><div class="line"><a name="l00281"></a><span class="lineno"> 281</span> bool b = registry.has<position, velocity>(entity);</div><div class="line"><a name="l00282"></a><span class="lineno"> 282</span> ```</div><div class="line"><a name="l00283"></a><span class="lineno"> 283</span> </div><div class="line"><a name="l00284"></a><span class="lineno"> 284</span> On the other side, if the goal is to delete a single component, the `remove`</div><div class="line"><a name="l00285"></a><span class="lineno"> 285</span> member function template is the way to go when it's certain that the entity owns</div><div class="line"><a name="l00286"></a><span class="lineno"> 286</span> a copy of the component:</div><div class="line"><a name="l00287"></a><span class="lineno"> 287</span> </div><div class="line"><a name="l00288"></a><span class="lineno"> 288</span> ```cpp</div><div class="line"><a name="l00289"></a><span class="lineno"> 289</span> registry.remove<position>(entity);</div><div class="line"><a name="l00290"></a><span class="lineno"> 290</span> ```</div><div class="line"><a name="l00291"></a><span class="lineno"> 291</span> </div><div class="line"><a name="l00292"></a><span class="lineno"> 292</span> Otherwise consider to use the `reset` member function. It behaves similarly to</div><div class="line"><a name="l00293"></a><span class="lineno"> 293</span> `remove` but with a strictly defined behavior (and a performance penalty is the</div><div class="line"><a name="l00294"></a><span class="lineno"> 294</span> price to pay for this). In particular it removes the component if and only if it</div><div class="line"><a name="l00295"></a><span class="lineno"> 295</span> exists, otherwise it returns safely to the caller:</div><div class="line"><a name="l00296"></a><span class="lineno"> 296</span> </div><div class="line"><a name="l00297"></a><span class="lineno"> 297</span> ```cpp</div><div class="line"><a name="l00298"></a><span class="lineno"> 298</span> registry.reset<position>(entity);</div><div class="line"><a name="l00299"></a><span class="lineno"> 299</span> ```</div><div class="line"><a name="l00300"></a><span class="lineno"> 300</span> </div><div class="line"><a name="l00301"></a><span class="lineno"> 301</span> There exist also two other _versions_ of the `reset` member function:</div><div class="line"><a name="l00302"></a><span class="lineno"> 302</span> </div><div class="line"><a name="l00303"></a><span class="lineno"> 303</span> * If no entity is passed to it, `reset` will remove the given component from</div><div class="line"><a name="l00304"></a><span class="lineno"> 304</span>  each entity that has it:</div><div class="line"><a name="l00305"></a><span class="lineno"> 305</span> </div><div class="line"><a name="l00306"></a><span class="lineno"> 306</span>  ```cpp</div><div class="line"><a name="l00307"></a><span class="lineno"> 307</span>  registry.reset<position>();</div><div class="line"><a name="l00308"></a><span class="lineno"> 308</span>  ```</div><div class="line"><a name="l00309"></a><span class="lineno"> 309</span> </div><div class="line"><a name="l00310"></a><span class="lineno"> 310</span> * If neither the entity nor the component are specified, all the entities still</div><div class="line"><a name="l00311"></a><span class="lineno"> 311</span>  in use and their components are destroyed:</div><div class="line"><a name="l00312"></a><span class="lineno"> 312</span> </div><div class="line"><a name="l00313"></a><span class="lineno"> 313</span>  ```cpp</div><div class="line"><a name="l00314"></a><span class="lineno"> 314</span>  registry.reset();</div><div class="line"><a name="l00315"></a><span class="lineno"> 315</span>  ```</div><div class="line"><a name="l00316"></a><span class="lineno"> 316</span> </div><div class="line"><a name="l00317"></a><span class="lineno"> 317</span> Finally, references to components can be retrieved simply by doing this:</div><div class="line"><a name="l00318"></a><span class="lineno"> 318</span> </div><div class="line"><a name="l00319"></a><span class="lineno"> 319</span> ```cpp</div><div class="line"><a name="l00320"></a><span class="lineno"> 320</span> const auto &cregistry = registry;</div><div class="line"><a name="l00321"></a><span class="lineno"> 321</span> </div><div class="line"><a name="l00322"></a><span class="lineno"> 322</span> // const and non-const reference</div><div class="line"><a name="l00323"></a><span class="lineno"> 323</span> const auto &crenderable = cregistry.get<renderable>(entity);</div><div class="line"><a name="l00324"></a><span class="lineno"> 324</span> auto &renderable = registry.get<renderable>(entity);</div><div class="line"><a name="l00325"></a><span class="lineno"> 325</span> </div><div class="line"><a name="l00326"></a><span class="lineno"> 326</span> // const and non-const references</div><div class="line"><a name="l00327"></a><span class="lineno"> 327</span> const auto &[cpos, cvel] = cregistry.get<position, velocity>(entity);</div><div class="line"><a name="l00328"></a><span class="lineno"> 328</span> auto &[pos, vel] = registry.get<position, velocity>(entity);</div><div class="line"><a name="l00329"></a><span class="lineno"> 329</span> ```</div><div class="line"><a name="l00330"></a><span class="lineno"> 330</span> </div><div class="line"><a name="l00331"></a><span class="lineno"> 331</span> The `get` member function template gives direct access to the component of an</div><div class="line"><a name="l00332"></a><span class="lineno"> 332</span> entity stored in the underlying data structures of the registry. There exists</div><div class="line"><a name="l00333"></a><span class="lineno"> 333</span> also an alternative member function named `try_get` that returns a pointer to</div><div class="line"><a name="l00334"></a><span class="lineno"> 334</span> the component owned by an entity if any, a null pointer otherwise.</div><div class="line"><a name="l00335"></a><span class="lineno"> 335</span> </div><div class="line"><a name="l00336"></a><span class="lineno"> 336</span> ## Observe changes</div><div class="line"><a name="l00337"></a><span class="lineno"> 337</span> </div><div class="line"><a name="l00338"></a><span class="lineno"> 338</span> Because of how the registry works internally, it stores a bunch of signal</div><div class="line"><a name="l00339"></a><span class="lineno"> 339</span> handlers for each pool in order to notify some of its data structures on the</div><div class="line"><a name="l00340"></a><span class="lineno"> 340</span> construction and destruction of components or when an instance of a component is</div><div class="line"><a name="l00341"></a><span class="lineno"> 341</span> explicitly replaced by the user.<br/></div><div class="line"><a name="l00342"></a><span class="lineno"> 342</span> These signal handlers are also exposed and made available to users. These are</div><div class="line"><a name="l00343"></a><span class="lineno"> 343</span> the basic bricks to build fancy things like dependencies and reactive systems.</div><div class="line"><a name="l00344"></a><span class="lineno"> 344</span> </div><div class="line"><a name="l00345"></a><span class="lineno"> 345</span> To get a sink to be used to connect and disconnect listeners so as to be</div><div class="line"><a name="l00346"></a><span class="lineno"> 346</span> notified on the creation of a component, use the `on_construct` member function:</div><div class="line"><a name="l00347"></a><span class="lineno"> 347</span> </div><div class="line"><a name="l00348"></a><span class="lineno"> 348</span> ```cpp</div><div class="line"><a name="l00349"></a><span class="lineno"> 349</span> // connects a free function</div><div class="line"><a name="l00350"></a><span class="lineno"> 350</span> registry.on_construct<position>().connect<&my_free_function>();</div><div class="line"><a name="l00351"></a><span class="lineno"> 351</span> </div><div class="line"><a name="l00352"></a><span class="lineno"> 352</span> // connects a member function</div><div class="line"><a name="l00353"></a><span class="lineno"> 353</span> registry.on_construct<position>().connect<&my_class::member>(instance);</div><div class="line"><a name="l00354"></a><span class="lineno"> 354</span> </div><div class="line"><a name="l00355"></a><span class="lineno"> 355</span> // disconnects a free function</div><div class="line"><a name="l00356"></a><span class="lineno"> 356</span> registry.on_construct<position>().disconnect<&my_free_function>();</div><div class="line"><a name="l00357"></a><span class="lineno"> 357</span> </div><div class="line"><a name="l00358"></a><span class="lineno"> 358</span> // disconnects a member function</div><div class="line"><a name="l00359"></a><span class="lineno"> 359</span> registry.on_construct<position>().disconnect<&my_class::member>(instance);</div><div class="line"><a name="l00360"></a><span class="lineno"> 360</span> ```</div><div class="line"><a name="l00361"></a><span class="lineno"> 361</span> </div><div class="line"><a name="l00362"></a><span class="lineno"> 362</span> To be notified when components are destroyed, use the `on_destroy` member</div><div class="line"><a name="l00363"></a><span class="lineno"> 363</span> function instead. Finally, the `on_replace` member function will return a sink</div><div class="line"><a name="l00364"></a><span class="lineno"> 364</span> to which to connect listeners to observe changes on components.</div><div class="line"><a name="l00365"></a><span class="lineno"> 365</span> </div><div class="line"><a name="l00366"></a><span class="lineno"> 366</span> The function type of a listener for the construction signal should be equivalent</div><div class="line"><a name="l00367"></a><span class="lineno"> 367</span> to the following:</div><div class="line"><a name="l00368"></a><span class="lineno"> 368</span> </div><div class="line"><a name="l00369"></a><span class="lineno"> 369</span> ```cpp</div><div class="line"><a name="l00370"></a><span class="lineno"> 370</span> void(entt::entity, entt::registry &, Component &);</div><div class="line"><a name="l00371"></a><span class="lineno"> 371</span> ```</div><div class="line"><a name="l00372"></a><span class="lineno"> 372</span> </div><div class="line"><a name="l00373"></a><span class="lineno"> 373</span> Where `Component` is intuitively the type of component of interest. In other</div><div class="line"><a name="l00374"></a><span class="lineno"> 374</span> words, a listener is provided with the registry that triggered the notification</div><div class="line"><a name="l00375"></a><span class="lineno"> 375</span> and the entity affected by the change, in addition to the newly created</div><div class="line"><a name="l00376"></a><span class="lineno"> 376</span> instance.<br/></div><div class="line"><a name="l00377"></a><span class="lineno"> 377</span> The sink returned by the `on_replace` member function accepts listeners the</div><div class="line"><a name="l00378"></a><span class="lineno"> 378</span> signature of which is the same of that of the construction signal. The one of</div><div class="line"><a name="l00379"></a><span class="lineno"> 379</span> the destruction signal is also similar, except for the `Component` parameter:</div><div class="line"><a name="l00380"></a><span class="lineno"> 380</span> </div><div class="line"><a name="l00381"></a><span class="lineno"> 381</span> ```cpp</div><div class="line"><a name="l00382"></a><span class="lineno"> 382</span> void(entt::entity, entt::registry &);</div><div class="line"><a name="l00383"></a><span class="lineno"> 383</span> ```</div><div class="line"><a name="l00384"></a><span class="lineno"> 384</span> </div><div class="line"><a name="l00385"></a><span class="lineno"> 385</span> This is mainly due to performance reasons. While the component is made available</div><div class="line"><a name="l00386"></a><span class="lineno"> 386</span> after the construction, it is not when destroyed. Because of that, there are no</div><div class="line"><a name="l00387"></a><span class="lineno"> 387</span> reasons to get it from the underlying storage unless the user requires so. In</div><div class="line"><a name="l00388"></a><span class="lineno"> 388</span> this case, the registry is made available for the purpose.</div><div class="line"><a name="l00389"></a><span class="lineno"> 389</span> </div><div class="line"><a name="l00390"></a><span class="lineno"> 390</span> Note also that:</div><div class="line"><a name="l00391"></a><span class="lineno"> 391</span> </div><div class="line"><a name="l00392"></a><span class="lineno"> 392</span> * Listeners for the construction signal are invoked **after** components have</div><div class="line"><a name="l00393"></a><span class="lineno"> 393</span>  been assigned to entities.</div><div class="line"><a name="l00394"></a><span class="lineno"> 394</span> </div><div class="line"><a name="l00395"></a><span class="lineno"> 395</span> * Listeners designed to observe changes are invoked **before** components have</div><div class="line"><a name="l00396"></a><span class="lineno"> 396</span>  been replaced and therefore before newly created instances have been assigned</div><div class="line"><a name="l00397"></a><span class="lineno"> 397</span>  to entities.</div><div class="line"><a name="l00398"></a><span class="lineno"> 398</span> </div><div class="line"><a name="l00399"></a><span class="lineno"> 399</span> * Listeners for the destruction signal are invoked **before** components have</div><div class="line"><a name="l00400"></a><span class="lineno"> 400</span>  been removed from entities.</div><div class="line"><a name="l00401"></a><span class="lineno"> 401</span> </div><div class="line"><a name="l00402"></a><span class="lineno"> 402</span> * The order of invocation of the listeners isn't guaranteed in any case.</div><div class="line"><a name="l00403"></a><span class="lineno"> 403</span> </div><div class="line"><a name="l00404"></a><span class="lineno"> 404</span> There are also some limitations on what a listener can and cannot do. In</div><div class="line"><a name="l00405"></a><span class="lineno"> 405</span> particular:</div><div class="line"><a name="l00406"></a><span class="lineno"> 406</span> </div><div class="line"><a name="l00407"></a><span class="lineno"> 407</span> * Connecting and disconnecting other functions from within the body of a</div><div class="line"><a name="l00408"></a><span class="lineno"> 408</span>  listener should be avoided. It can lead to undefined behavior in some cases.</div><div class="line"><a name="l00409"></a><span class="lineno"> 409</span> </div><div class="line"><a name="l00410"></a><span class="lineno"> 410</span> * Assigning and removing components from within the body of a listener that</div><div class="line"><a name="l00411"></a><span class="lineno"> 411</span>  observes the destruction of instances of a given type should be avoided. It</div><div class="line"><a name="l00412"></a><span class="lineno"> 412</span>  can lead to undefined behavior in some cases. This type of listeners is</div><div class="line"><a name="l00413"></a><span class="lineno"> 413</span>  intended to provide users with an easy way to perform cleanup and nothing</div><div class="line"><a name="l00414"></a><span class="lineno"> 414</span>  more.</div><div class="line"><a name="l00415"></a><span class="lineno"> 415</span> </div><div class="line"><a name="l00416"></a><span class="lineno"> 416</span> To a certain extent, these limitations don't apply. However, it's risky to try</div><div class="line"><a name="l00417"></a><span class="lineno"> 417</span> to force them and users should respect the limitations unless they know exactly</div><div class="line"><a name="l00418"></a><span class="lineno"> 418</span> what they are doing. Subtle bugs are the price to pay in case of errors</div><div class="line"><a name="l00419"></a><span class="lineno"> 419</span> otherwise.</div><div class="line"><a name="l00420"></a><span class="lineno"> 420</span> </div><div class="line"><a name="l00421"></a><span class="lineno"> 421</span> In general, events and therefore listeners must not be used as replacements for</div><div class="line"><a name="l00422"></a><span class="lineno"> 422</span> systems. They should not contain much logic and interactions with a registry</div><div class="line"><a name="l00423"></a><span class="lineno"> 423</span> should be kept to a minimum, if possible. Note also that the greater the number</div><div class="line"><a name="l00424"></a><span class="lineno"> 424</span> of listeners, the greater the performance hit when components are created or</div><div class="line"><a name="l00425"></a><span class="lineno"> 425</span> destroyed.</div><div class="line"><a name="l00426"></a><span class="lineno"> 426</span> </div><div class="line"><a name="l00427"></a><span class="lineno"> 427</span> Please, refer to the documentation of the signal class to know all the features</div><div class="line"><a name="l00428"></a><span class="lineno"> 428</span> it offers.<br/></div><div class="line"><a name="l00429"></a><span class="lineno"> 429</span> There are many useful but less known functionalities that aren't described here,</div><div class="line"><a name="l00430"></a><span class="lineno"> 430</span> such as the connection objects or the possibility to attach listeners with a</div><div class="line"><a name="l00431"></a><span class="lineno"> 431</span> list of parameters that is shorter than that of the signal itself.</div><div class="line"><a name="l00432"></a><span class="lineno"> 432</span> </div><div class="line"><a name="l00433"></a><span class="lineno"> 433</span> ### They call me Reactive System</div><div class="line"><a name="l00434"></a><span class="lineno"> 434</span> </div><div class="line"><a name="l00435"></a><span class="lineno"> 435</span> As mentioned above, signals are the basic tools to construct reactive systems,</div><div class="line"><a name="l00436"></a><span class="lineno"> 436</span> even if they are not enough on their own.<br/></div><div class="line"><a name="l00437"></a><span class="lineno"> 437</span> `EnTT` tries to take another step in that direction with the `observer` class</div><div class="line"><a name="l00438"></a><span class="lineno"> 438</span> template.</div><div class="line"><a name="l00439"></a><span class="lineno"> 439</span> </div><div class="line"><a name="l00440"></a><span class="lineno"> 440</span> In order to explain what reactive systems are, this is a slightly revised quote</div><div class="line"><a name="l00441"></a><span class="lineno"> 441</span> from the documentation of the library that first introduced this tool,</div><div class="line"><a name="l00442"></a><span class="lineno"> 442</span> [Entitas](https://github.com/sschmid/Entitas-CSharp):</div><div class="line"><a name="l00443"></a><span class="lineno"> 443</span> </div><div class="line"><a name="l00444"></a><span class="lineno"> 444</span> >Imagine you have 100 fighting units on the battlefield but only 10 of them</div><div class="line"><a name="l00445"></a><span class="lineno"> 445</span> >changed their positions. Instead of using a normal system and updating all 100</div><div class="line"><a name="l00446"></a><span class="lineno"> 446</span> >entities depending on the position, you can use a reactive system which will</div><div class="line"><a name="l00447"></a><span class="lineno"> 447</span> >only update the 10 changed units. So efficient.</div><div class="line"><a name="l00448"></a><span class="lineno"> 448</span> </div><div class="line"><a name="l00449"></a><span class="lineno"> 449</span> In `EnTT`, this means to iterating over a reduced set of entities and components</div><div class="line"><a name="l00450"></a><span class="lineno"> 450</span> with respect to what would otherwise be returned from a view or a group.<br/></div><div class="line"><a name="l00451"></a><span class="lineno"> 451</span> On these words, however, the similarities with the proposal of `Entitas` also</div><div class="line"><a name="l00452"></a><span class="lineno"> 452</span> end. The rules of language and the design of the library obviously impose and</div><div class="line"><a name="l00453"></a><span class="lineno"> 453</span> allow different things.</div><div class="line"><a name="l00454"></a><span class="lineno"> 454</span> </div><div class="line"><a name="l00455"></a><span class="lineno"> 455</span> An `observer` is initialized with an instance of a registry and a set of rules</div><div class="line"><a name="l00456"></a><span class="lineno"> 456</span> that describe what are the entities to intercept. As an example:</div><div class="line"><a name="l00457"></a><span class="lineno"> 457</span> </div><div class="line"><a name="l00458"></a><span class="lineno"> 458</span> ```cpp</div><div class="line"><a name="l00459"></a><span class="lineno"> 459</span> entt::observer observer{registry, entt::collector.replace<sprite>()};</div><div class="line"><a name="l00460"></a><span class="lineno"> 460</span> ```</div><div class="line"><a name="l00461"></a><span class="lineno"> 461</span> </div><div class="line"><a name="l00462"></a><span class="lineno"> 462</span> The class is default constructible if required and it can be reconfigured at any</div><div class="line"><a name="l00463"></a><span class="lineno"> 463</span> time by means of the `connect` member function. Moreover, instances can be</div><div class="line"><a name="l00464"></a><span class="lineno"> 464</span> disconnected from the underlying registries through the `disconnect` member</div><div class="line"><a name="l00465"></a><span class="lineno"> 465</span> function.<br/></div><div class="line"><a name="l00466"></a><span class="lineno"> 466</span> The `observer` offers also some member functions to query its internal state and</div><div class="line"><a name="l00467"></a><span class="lineno"> 467</span> to know if it's empty or how many entities it contains. Moreover, it can return</div><div class="line"><a name="l00468"></a><span class="lineno"> 468</span> a raw pointer to the list of entities it contains.</div><div class="line"><a name="l00469"></a><span class="lineno"> 469</span> </div><div class="line"><a name="l00470"></a><span class="lineno"> 470</span> However, the most important features of this class are that:</div><div class="line"><a name="l00471"></a><span class="lineno"> 471</span> </div><div class="line"><a name="l00472"></a><span class="lineno"> 472</span> * It's iterable and therefore users can easily walk through the list of entities</div><div class="line"><a name="l00473"></a><span class="lineno"> 473</span>  by means of a range-for loop or the `each` member function.</div><div class="line"><a name="l00474"></a><span class="lineno"> 474</span> </div><div class="line"><a name="l00475"></a><span class="lineno"> 475</span> * It's clearable and therefore users can consume the entities and literally</div><div class="line"><a name="l00476"></a><span class="lineno"> 476</span>  reset the observer after each iteration.</div><div class="line"><a name="l00477"></a><span class="lineno"> 477</span> </div><div class="line"><a name="l00478"></a><span class="lineno"> 478</span> These aspects make the observer an incredibly powerful tool to know at any time</div><div class="line"><a name="l00479"></a><span class="lineno"> 479</span> what are the entities that matched the given rules since the last time one</div><div class="line"><a name="l00480"></a><span class="lineno"> 480</span> asked:</div><div class="line"><a name="l00481"></a><span class="lineno"> 481</span> </div><div class="line"><a name="l00482"></a><span class="lineno"> 482</span> ```cpp</div><div class="line"><a name="l00483"></a><span class="lineno"> 483</span> for(const auto entity: observer) {</div><div class="line"><a name="l00484"></a><span class="lineno"> 484</span>  // ...</div><div class="line"><a name="l00485"></a><span class="lineno"> 485</span> }</div><div class="line"><a name="l00486"></a><span class="lineno"> 486</span> </div><div class="line"><a name="l00487"></a><span class="lineno"> 487</span> observer.clear();</div><div class="line"><a name="l00488"></a><span class="lineno"> 488</span> ```</div><div class="line"><a name="l00489"></a><span class="lineno"> 489</span> </div><div class="line"><a name="l00490"></a><span class="lineno"> 490</span> Note that the snippet above is equivalent to the following:</div><div class="line"><a name="l00491"></a><span class="lineno"> 491</span> </div><div class="line"><a name="l00492"></a><span class="lineno"> 492</span> ```cpp</div><div class="line"><a name="l00493"></a><span class="lineno"> 493</span> observer.each([](const auto entity) {</div><div class="line"><a name="l00494"></a><span class="lineno"> 494</span>  // ...</div><div class="line"><a name="l00495"></a><span class="lineno"> 495</span> });</div><div class="line"><a name="l00496"></a><span class="lineno"> 496</span> ```</div><div class="line"><a name="l00497"></a><span class="lineno"> 497</span> </div><div class="line"><a name="l00498"></a><span class="lineno"> 498</span> At least as long as the `observer` isn't const. This means that the non-const</div><div class="line"><a name="l00499"></a><span class="lineno"> 499</span> overload of `each` does also reset the underlying data structure before to</div><div class="line"><a name="l00500"></a><span class="lineno"> 500</span> return to the caller, while the const overload does not for obvious reasons.</div><div class="line"><a name="l00501"></a><span class="lineno"> 501</span> </div><div class="line"><a name="l00502"></a><span class="lineno"> 502</span> The `collector` is an utility aimed to generate a list of `matcher`s (the actual</div><div class="line"><a name="l00503"></a><span class="lineno"> 503</span> rules) to use with an `observer` instead.<br/></div><div class="line"><a name="l00504"></a><span class="lineno"> 504</span> There are two types of `matcher`s:</div><div class="line"><a name="l00505"></a><span class="lineno"> 505</span> </div><div class="line"><a name="l00506"></a><span class="lineno"> 506</span> * Observing matcher: an observer will return at least all the living entities</div><div class="line"><a name="l00507"></a><span class="lineno"> 507</span>  for which one or more of the given components have been explicitly replaced</div><div class="line"><a name="l00508"></a><span class="lineno"> 508</span>  and not yet destroyed.</div><div class="line"><a name="l00509"></a><span class="lineno"> 509</span> </div><div class="line"><a name="l00510"></a><span class="lineno"> 510</span>  ```cpp</div><div class="line"><a name="l00511"></a><span class="lineno"> 511</span>  entt::collector.replace<sprite>();</div><div class="line"><a name="l00512"></a><span class="lineno"> 512</span>  ```</div><div class="line"><a name="l00513"></a><span class="lineno"> 513</span> </div><div class="line"><a name="l00514"></a><span class="lineno"> 514</span> * Grouping matcher: an observer will return at least all the living entities</div><div class="line"><a name="l00515"></a><span class="lineno"> 515</span>  that would have entered the given group if it existed and that would have</div><div class="line"><a name="l00516"></a><span class="lineno"> 516</span>  not yet left it.</div><div class="line"><a name="l00517"></a><span class="lineno"> 517</span> </div><div class="line"><a name="l00518"></a><span class="lineno"> 518</span>  ```cpp</div><div class="line"><a name="l00519"></a><span class="lineno"> 519</span>  entt::collector.group<position, velocity>(entt::exclude<destroyed>);</div><div class="line"><a name="l00520"></a><span class="lineno"> 520</span>  ```</div><div class="line"><a name="l00521"></a><span class="lineno"> 521</span> </div><div class="line"><a name="l00522"></a><span class="lineno"> 522</span>  A grouping matcher supports also exclusion lists as well as single components.</div><div class="line"><a name="l00523"></a><span class="lineno"> 523</span> </div><div class="line"><a name="l00524"></a><span class="lineno"> 524</span> Roughly speaking, an observing matcher intercepts the entities for which the</div><div class="line"><a name="l00525"></a><span class="lineno"> 525</span> given components are replaced (as in `registry::replace`) while a grouping</div><div class="line"><a name="l00526"></a><span class="lineno"> 526</span> matcher tracks the entities that have assigned the given components since the</div><div class="line"><a name="l00527"></a><span class="lineno"> 527</span> last time one asked.<br/></div><div class="line"><a name="l00528"></a><span class="lineno"> 528</span> Note that, for a grouping matcher, if an entity already has all the components</div><div class="line"><a name="l00529"></a><span class="lineno"> 529</span> except one and the missing type is assigned to it, it is intercepted.</div><div class="line"><a name="l00530"></a><span class="lineno"> 530</span> </div><div class="line"><a name="l00531"></a><span class="lineno"> 531</span> In addition, a matcher can be filtered with a `where` clause:</div><div class="line"><a name="l00532"></a><span class="lineno"> 532</span> </div><div class="line"><a name="l00533"></a><span class="lineno"> 533</span> ```cpp</div><div class="line"><a name="l00534"></a><span class="lineno"> 534</span> entt::collector.replace<sprite>().where<position>(entt::exclude<velocity>);</div><div class="line"><a name="l00535"></a><span class="lineno"> 535</span> ```</div><div class="line"><a name="l00536"></a><span class="lineno"> 536</span> </div><div class="line"><a name="l00537"></a><span class="lineno"> 537</span> This clause introduces a way to intercept entities if and only if they are</div><div class="line"><a name="l00538"></a><span class="lineno"> 538</span> already part of a hypothetical group. If they are not, they aren't returned by</div><div class="line"><a name="l00539"></a><span class="lineno"> 539</span> the observer, no matter if they matched the given rule.<br/></div><div class="line"><a name="l00540"></a><span class="lineno"> 540</span> In the example above, whenever the component `sprite` of an entity is replaced,</div><div class="line"><a name="l00541"></a><span class="lineno"> 541</span> the observer probes the entity itself to verify that it has at least `position`</div><div class="line"><a name="l00542"></a><span class="lineno"> 542</span> and has not `velocity` before to store it aside. If one of the two conditions of</div><div class="line"><a name="l00543"></a><span class="lineno"> 543</span> the filter isn't respected, the entity is discared, no matter what.</div><div class="line"><a name="l00544"></a><span class="lineno"> 544</span> </div><div class="line"><a name="l00545"></a><span class="lineno"> 545</span> A `where` clause accepts a theoretically unlimited number of types as well as</div><div class="line"><a name="l00546"></a><span class="lineno"> 546</span> multiple elements in the exclusion list. Moreover, every matcher can have it's</div><div class="line"><a name="l00547"></a><span class="lineno"> 547</span> own clause and multiple clauses for the same matcher are combined in a single</div><div class="line"><a name="l00548"></a><span class="lineno"> 548</span> one.</div><div class="line"><a name="l00549"></a><span class="lineno"> 549</span> </div><div class="line"><a name="l00550"></a><span class="lineno"> 550</span> ## Runtime components</div><div class="line"><a name="l00551"></a><span class="lineno"> 551</span> </div><div class="line"><a name="l00552"></a><span class="lineno"> 552</span> Defining components at runtime is useful to support plugin systems and mods in</div><div class="line"><a name="l00553"></a><span class="lineno"> 553</span> general. However, it seems impossible with a tool designed around a bunch of</div><div class="line"><a name="l00554"></a><span class="lineno"> 554</span> templates. Indeed it's not that difficult.<br/></div><div class="line"><a name="l00555"></a><span class="lineno"> 555</span> Of course, some features cannot be easily exported into a runtime</div><div class="line"><a name="l00556"></a><span class="lineno"> 556</span> environment. As an example, sorting a group of components defined at runtime</div><div class="line"><a name="l00557"></a><span class="lineno"> 557</span> isn't for free if compared to most of the other operations. However, the basic</div><div class="line"><a name="l00558"></a><span class="lineno"> 558</span> functionalities of an entity-component system such as `EnTT` fit the problem</div><div class="line"><a name="l00559"></a><span class="lineno"> 559</span> perfectly and can also be used to manage runtime components if required.<br/></div><div class="line"><a name="l00560"></a><span class="lineno"> 560</span> All that is necessary to do it is to know the identifiers of the components. An</div><div class="line"><a name="l00561"></a><span class="lineno"> 561</span> identifier is nothing more than a number or similar that can be used at runtime</div><div class="line"><a name="l00562"></a><span class="lineno"> 562</span> to work with the type system.</div><div class="line"><a name="l00563"></a><span class="lineno"> 563</span> </div><div class="line"><a name="l00564"></a><span class="lineno"> 564</span> In `EnTT`, identifiers are easily accessible:</div><div class="line"><a name="l00565"></a><span class="lineno"> 565</span> </div><div class="line"><a name="l00566"></a><span class="lineno"> 566</span> ```cpp</div><div class="line"><a name="l00567"></a><span class="lineno"> 567</span> entt::registry registry;</div><div class="line"><a name="l00568"></a><span class="lineno"> 568</span> </div><div class="line"><a name="l00569"></a><span class="lineno"> 569</span> // component identifier</div><div class="line"><a name="l00570"></a><span class="lineno"> 570</span> auto type = registry.type<position>();</div><div class="line"><a name="l00571"></a><span class="lineno"> 571</span> ```</div><div class="line"><a name="l00572"></a><span class="lineno"> 572</span> </div><div class="line"><a name="l00573"></a><span class="lineno"> 573</span> Once the identifiers are made available, almost everything becomes pretty</div><div class="line"><a name="l00574"></a><span class="lineno"> 574</span> simple.</div><div class="line"><a name="l00575"></a><span class="lineno"> 575</span> </div><div class="line"><a name="l00576"></a><span class="lineno"> 576</span> ### A journey through a plugin</div><div class="line"><a name="l00577"></a><span class="lineno"> 577</span> </div><div class="line"><a name="l00578"></a><span class="lineno"> 578</span> `EnTT` comes with an example (actually a test) that shows how to integrate</div><div class="line"><a name="l00579"></a><span class="lineno"> 579</span> compile-time and runtime components in a stack based JavaScript environment. It</div><div class="line"><a name="l00580"></a><span class="lineno"> 580</span> uses [`Duktape`](https://github.com/svaarala/duktape) under the hood, mainly</div><div class="line"><a name="l00581"></a><span class="lineno"> 581</span> because I wanted to learn how it works at the time I was writing the code.</div><div class="line"><a name="l00582"></a><span class="lineno"> 582</span> </div><div class="line"><a name="l00583"></a><span class="lineno"> 583</span> The code is not production-ready and overall performance can be highly improved.</div><div class="line"><a name="l00584"></a><span class="lineno"> 584</span> However, I sacrificed optimizations in favor of a more readable piece of code. I</div><div class="line"><a name="l00585"></a><span class="lineno"> 585</span> hope I succeeded.<br/></div><div class="line"><a name="l00586"></a><span class="lineno"> 586</span> Note also that this isn't neither the only nor (probably) the best way to do it.</div><div class="line"><a name="l00587"></a><span class="lineno"> 587</span> In fact, the right way depends on the scripting language and the problem one is</div><div class="line"><a name="l00588"></a><span class="lineno"> 588</span> facing in general.<br/></div><div class="line"><a name="l00589"></a><span class="lineno"> 589</span> That being said, feel free to use it at your own risk.</div><div class="line"><a name="l00590"></a><span class="lineno"> 590</span> </div><div class="line"><a name="l00591"></a><span class="lineno"> 591</span> The basic idea is that of creating a compile-time component aimed to map all the</div><div class="line"><a name="l00592"></a><span class="lineno"> 592</span> runtime components assigned to an entity.<br/></div><div class="line"><a name="l00593"></a><span class="lineno"> 593</span> Identifiers come in use to address the right function from a map when invoked</div><div class="line"><a name="l00594"></a><span class="lineno"> 594</span> from the runtime environment and to filter entities when iterating.<br/></div><div class="line"><a name="l00595"></a><span class="lineno"> 595</span> With a bit of gymnastic, one can narrow views and improve the performance to</div><div class="line"><a name="l00596"></a><span class="lineno"> 596</span> some extent but it was not the goal of the example.</div><div class="line"><a name="l00597"></a><span class="lineno"> 597</span> </div><div class="line"><a name="l00598"></a><span class="lineno"> 598</span> ## Sorting: is it possible?</div><div class="line"><a name="l00599"></a><span class="lineno"> 599</span> </div><div class="line"><a name="l00600"></a><span class="lineno"> 600</span> It goes without saying that sorting entities and components is possible with</div><div class="line"><a name="l00601"></a><span class="lineno"> 601</span> `EnTT`.<br/></div><div class="line"><a name="l00602"></a><span class="lineno"> 602</span> In fact, there are two functions that respond to slightly different needs:</div><div class="line"><a name="l00603"></a><span class="lineno"> 603</span> </div><div class="line"><a name="l00604"></a><span class="lineno"> 604</span> * Components can be sorted either directly:</div><div class="line"><a name="l00605"></a><span class="lineno"> 605</span> </div><div class="line"><a name="l00606"></a><span class="lineno"> 606</span>  ```cpp</div><div class="line"><a name="l00607"></a><span class="lineno"> 607</span>  registry.sort<renderable>([](const auto &lhs, const auto &rhs) {</div><div class="line"><a name="l00608"></a><span class="lineno"> 608</span>  return lhs.z < rhs.z;</div><div class="line"><a name="l00609"></a><span class="lineno"> 609</span> </div><div class="line"><a name="l00610"></a><span class="lineno"> 610</span>  });</div><div class="line"><a name="l00611"></a><span class="lineno"> 611</span>  ```</div><div class="line"><a name="l00612"></a><span class="lineno"> 612</span> </div><div class="line"><a name="l00613"></a><span class="lineno"> 613</span>  Or by accessing their entities:</div><div class="line"><a name="l00614"></a><span class="lineno"> 614</span> </div><div class="line"><a name="l00615"></a><span class="lineno"> 615</span>  ```cpp</div><div class="line"><a name="l00616"></a><span class="lineno"> 616</span>  registry.sort<renderable>([](const entt::entity lhs, const entt::entity rhs) {</div><div class="line"><a name="l00617"></a><span class="lineno"> 617</span>  return entt::registry::entity(lhs) < entt::registry::entity(rhs);</div><div class="line"><a name="l00618"></a><span class="lineno"> 618</span>  });</div><div class="line"><a name="l00619"></a><span class="lineno"> 619</span>  ```</div><div class="line"><a name="l00620"></a><span class="lineno"> 620</span> </div><div class="line"><a name="l00621"></a><span class="lineno"> 621</span>  There exists also the possibility to use a custom sort function object, as</div><div class="line"><a name="l00622"></a><span class="lineno"> 622</span>  long as it adheres to the requirements described in the inline</div><div class="line"><a name="l00623"></a><span class="lineno"> 623</span>  documentation.<br/></div><div class="line"><a name="l00624"></a><span class="lineno"> 624</span>  This is possible mainly because users can get much more with a custom sort</div><div class="line"><a name="l00625"></a><span class="lineno"> 625</span>  function object if the usage pattern is known. As an example, in case of an</div><div class="line"><a name="l00626"></a><span class="lineno"> 626</span>  almost sorted pool, quick sort could be much, much slower than insertion sort.</div><div class="line"><a name="l00627"></a><span class="lineno"> 627</span> </div><div class="line"><a name="l00628"></a><span class="lineno"> 628</span> * Components can be sorted according to the order imposed by another component:</div><div class="line"><a name="l00629"></a><span class="lineno"> 629</span> </div><div class="line"><a name="l00630"></a><span class="lineno"> 630</span>  ```cpp</div><div class="line"><a name="l00631"></a><span class="lineno"> 631</span>  registry.sort<movement, physics>();</div><div class="line"><a name="l00632"></a><span class="lineno"> 632</span>  ```</div><div class="line"><a name="l00633"></a><span class="lineno"> 633</span> </div><div class="line"><a name="l00634"></a><span class="lineno"> 634</span>  In this case, instances of `movement` are arranged in memory so that cache</div><div class="line"><a name="l00635"></a><span class="lineno"> 635</span>  misses are minimized when the two components are iterated together.</div><div class="line"><a name="l00636"></a><span class="lineno"> 636</span> </div><div class="line"><a name="l00637"></a><span class="lineno"> 637</span> As a side note, when groups are involved, the sorting functions are applied</div><div class="line"><a name="l00638"></a><span class="lineno"> 638</span> separately to the elements that are part of the group and to those that are not,</div><div class="line"><a name="l00639"></a><span class="lineno"> 639</span> effectively generating two partitions, both of which can be ordered</div><div class="line"><a name="l00640"></a><span class="lineno"> 640</span> independently of each other.</div><div class="line"><a name="l00641"></a><span class="lineno"> 641</span> </div><div class="line"><a name="l00642"></a><span class="lineno"> 642</span> ## Helpers</div><div class="line"><a name="l00643"></a><span class="lineno"> 643</span> </div><div class="line"><a name="l00644"></a><span class="lineno"> 644</span> The so called _helpers_ are small classes and functions mainly designed to offer</div><div class="line"><a name="l00645"></a><span class="lineno"> 645</span> built-in support for the most basic functionalities.<br/></div><div class="line"><a name="l00646"></a><span class="lineno"> 646</span> The list of helpers will grow longer as time passes and new ideas come out.</div><div class="line"><a name="l00647"></a><span class="lineno"> 647</span> </div><div class="line"><a name="l00648"></a><span class="lineno"> 648</span> ### Null entity</div><div class="line"><a name="l00649"></a><span class="lineno"> 649</span> </div><div class="line"><a name="l00650"></a><span class="lineno"> 650</span> In `EnTT`, there exists a sort of _null entity_ made available to users that is</div><div class="line"><a name="l00651"></a><span class="lineno"> 651</span> accessible via the `entt::null` variable.<br/></div><div class="line"><a name="l00652"></a><span class="lineno"> 652</span> The library guarantees that the following expression always returns false:</div><div class="line"><a name="l00653"></a><span class="lineno"> 653</span> </div><div class="line"><a name="l00654"></a><span class="lineno"> 654</span> ```cpp</div><div class="line"><a name="l00655"></a><span class="lineno"> 655</span> registry.valid(entt::null);</div><div class="line"><a name="l00656"></a><span class="lineno"> 656</span> ```</div><div class="line"><a name="l00657"></a><span class="lineno"> 657</span> </div><div class="line"><a name="l00658"></a><span class="lineno"> 658</span> In other terms, a registry will reject the null entity in all cases because it</div><div class="line"><a name="l00659"></a><span class="lineno"> 659</span> isn't considered valid. It means that the null entity cannot own components for</div><div class="line"><a name="l00660"></a><span class="lineno"> 660</span> obvious reasons.<br/></div><div class="line"><a name="l00661"></a><span class="lineno"> 661</span> The type of the null entity is internal and should not be used for any purpose</div><div class="line"><a name="l00662"></a><span class="lineno"> 662</span> other than defining the null entity itself. However, there exist implicit</div><div class="line"><a name="l00663"></a><span class="lineno"> 663</span> conversions from the null entity to identifiers of any allowed type:</div><div class="line"><a name="l00664"></a><span class="lineno"> 664</span> </div><div class="line"><a name="l00665"></a><span class="lineno"> 665</span> ```cpp</div><div class="line"><a name="l00666"></a><span class="lineno"> 666</span> entt::entity null = entt::null;</div><div class="line"><a name="l00667"></a><span class="lineno"> 667</span> ```</div><div class="line"><a name="l00668"></a><span class="lineno"> 668</span> </div><div class="line"><a name="l00669"></a><span class="lineno"> 669</span> Similarly, the null entity can be compared to any other identifier:</div><div class="line"><a name="l00670"></a><span class="lineno"> 670</span> </div><div class="line"><a name="l00671"></a><span class="lineno"> 671</span> ```cpp</div><div class="line"><a name="l00672"></a><span class="lineno"> 672</span> const auto entity = registry.create();</div><div class="line"><a name="l00673"></a><span class="lineno"> 673</span> const bool null = (entity == entt::null);</div><div class="line"><a name="l00674"></a><span class="lineno"> 674</span> ```</div><div class="line"><a name="l00675"></a><span class="lineno"> 675</span> </div><div class="line"><a name="l00676"></a><span class="lineno"> 676</span> ### Stomp and spawn</div><div class="line"><a name="l00677"></a><span class="lineno"> 677</span> </div><div class="line"><a name="l00678"></a><span class="lineno"> 678</span> The use of multiple registries is quite common. Examples of use are the</div><div class="line"><a name="l00679"></a><span class="lineno"> 679</span> separation of the UI from the simulation or the loading of different scenes in</div><div class="line"><a name="l00680"></a><span class="lineno"> 680</span> the background, possibly on a separate thread, without having to keep track of</div><div class="line"><a name="l00681"></a><span class="lineno"> 681</span> which entity belongs to which scene.<br/></div><div class="line"><a name="l00682"></a><span class="lineno"> 682</span> In fact, with `EnTT` this is even a recommended practice, as the registry is</div><div class="line"><a name="l00683"></a><span class="lineno"> 683</span> nothing more than a container and different optimizations and strategies can be</div><div class="line"><a name="l00684"></a><span class="lineno"> 684</span> applied to different containers.</div><div class="line"><a name="l00685"></a><span class="lineno"> 685</span> </div><div class="line"><a name="l00686"></a><span class="lineno"> 686</span> Once there are multiple registries available, however, one or more methods are</div><div class="line"><a name="l00687"></a><span class="lineno"> 687</span> needed to transfer information from one container to another and this results in</div><div class="line"><a name="l00688"></a><span class="lineno"> 688</span> the `stomp` member function and a couple of overloads of the `create` member</div><div class="line"><a name="l00689"></a><span class="lineno"> 689</span> function for the `registry` class .<br/></div><div class="line"><a name="l00690"></a><span class="lineno"> 690</span> The `stomp` function allows to take one entity from a registry and use it to</div><div class="line"><a name="l00691"></a><span class="lineno"> 691</span> _stomp_ one or more entities in another registry (or even the same, actually</div><div class="line"><a name="l00692"></a><span class="lineno"> 692</span> making local copies). On the other hand, the overloads of the `create` member</div><div class="line"><a name="l00693"></a><span class="lineno"> 693</span> function can be used to spawn new entities from a prototype.</div><div class="line"><a name="l00694"></a><span class="lineno"> 694</span> </div><div class="line"><a name="l00695"></a><span class="lineno"> 695</span> These features open definitely the doors to a lot of interesting features like</div><div class="line"><a name="l00696"></a><span class="lineno"> 696</span> migrating entities between registries, prototypes, shadow registry, prefabs,</div><div class="line"><a name="l00697"></a><span class="lineno"> 697</span> shared components without an explicit owner and copy-on-write policies among the</div><div class="line"><a name="l00698"></a><span class="lineno"> 698</span> other things.</div><div class="line"><a name="l00699"></a><span class="lineno"> 699</span> </div><div class="line"><a name="l00700"></a><span class="lineno"> 700</span> ### Dependencies</div><div class="line"><a name="l00701"></a><span class="lineno"> 701</span> </div><div class="line"><a name="l00702"></a><span class="lineno"> 702</span> The `registry` class is designed to create short circuits between its functions</div><div class="line"><a name="l00703"></a><span class="lineno"> 703</span> within certain limits. This allows to easily define dependencies between</div><div class="line"><a name="l00704"></a><span class="lineno"> 704</span> different operations.<br/></div><div class="line"><a name="l00705"></a><span class="lineno"> 705</span> For example, the following adds (or replaces) the component `a_type` whenever</div><div class="line"><a name="l00706"></a><span class="lineno"> 706</span> `my_type` is assigned to an entity:</div><div class="line"><a name="l00707"></a><span class="lineno"> 707</span> </div><div class="line"><a name="l00708"></a><span class="lineno"> 708</span> ```cpp</div><div class="line"><a name="l00709"></a><span class="lineno"> 709</span> registry.on_construct<my_type>().connect<&entt::registry::assign_or_replace<a_type>>(registry);</div><div class="line"><a name="l00710"></a><span class="lineno"> 710</span> ```</div><div class="line"><a name="l00711"></a><span class="lineno"> 711</span> </div><div class="line"><a name="l00712"></a><span class="lineno"> 712</span> Similarly, the code shown below removes `a_type` from an entity whenever</div><div class="line"><a name="l00713"></a><span class="lineno"> 713</span> `my_type` is assigned to it:</div><div class="line"><a name="l00714"></a><span class="lineno"> 714</span> </div><div class="line"><a name="l00715"></a><span class="lineno"> 715</span> ```cpp</div><div class="line"><a name="l00716"></a><span class="lineno"> 716</span> registry.on_construct<my_type>().connect<&entt::registry::reset<a_type>>(registry);</div><div class="line"><a name="l00717"></a><span class="lineno"> 717</span> ```</div><div class="line"><a name="l00718"></a><span class="lineno"> 718</span> </div><div class="line"><a name="l00719"></a><span class="lineno"> 719</span> A dependency can also be easily broken as follows:</div><div class="line"><a name="l00720"></a><span class="lineno"> 720</span> </div><div class="line"><a name="l00721"></a><span class="lineno"> 721</span> ```cpp</div><div class="line"><a name="l00722"></a><span class="lineno"> 722</span> registry.on_construct<my_type>().disconnect<&entt::registry::assign_or_replace<a_type>>(registry);</div><div class="line"><a name="l00723"></a><span class="lineno"> 723</span> ```</div><div class="line"><a name="l00724"></a><span class="lineno"> 724</span> </div><div class="line"><a name="l00725"></a><span class="lineno"> 725</span> There are many other types of dependencies besides those shown above. In</div><div class="line"><a name="l00726"></a><span class="lineno"> 726</span> general, all functions that accept an entity as the first argument are good</div><div class="line"><a name="l00727"></a><span class="lineno"> 727</span> candidates for this purpose.</div><div class="line"><a name="l00728"></a><span class="lineno"> 728</span> </div><div class="line"><a name="l00729"></a><span class="lineno"> 729</span> ### Tags</div><div class="line"><a name="l00730"></a><span class="lineno"> 730</span> </div><div class="line"><a name="l00731"></a><span class="lineno"> 731</span> There's nothing magical about the way tags can be assigned to entities while</div><div class="line"><a name="l00732"></a><span class="lineno"> 732</span> avoiding a performance hit at runtime. Nonetheless, the syntax can be annoying</div><div class="line"><a name="l00733"></a><span class="lineno"> 733</span> and that's why a more user-friendly shortcut is provided to do it.<br/></div><div class="line"><a name="l00734"></a><span class="lineno"> 734</span> This shortcut is the alias template `entt::tag`.</div><div class="line"><a name="l00735"></a><span class="lineno"> 735</span> </div><div class="line"><a name="l00736"></a><span class="lineno"> 736</span> If used in combination with hashed strings, it helps to use tags where types</div><div class="line"><a name="l00737"></a><span class="lineno"> 737</span> would be required otherwise. As an example:</div><div class="line"><a name="l00738"></a><span class="lineno"> 738</span> </div><div class="line"><a name="l00739"></a><span class="lineno"> 739</span> ```cpp</div><div class="line"><a name="l00740"></a><span class="lineno"> 740</span> registry.assign<entt::tag<"enemy"_hs>>(entity);</div><div class="line"><a name="l00741"></a><span class="lineno"> 741</span> ```</div><div class="line"><a name="l00742"></a><span class="lineno"> 742</span> </div><div class="line"><a name="l00743"></a><span class="lineno"> 743</span> ### Actor</div><div class="line"><a name="l00744"></a><span class="lineno"> 744</span> </div><div class="line"><a name="l00745"></a><span class="lineno"> 745</span> The `actor` class is designed for those who don't feel immediately comfortable</div><div class="line"><a name="l00746"></a><span class="lineno"> 746</span> working with components or for those who are migrating a project and want to</div><div class="line"><a name="l00747"></a><span class="lineno"> 747</span> approach it one step at a time.</div><div class="line"><a name="l00748"></a><span class="lineno"> 748</span> </div><div class="line"><a name="l00749"></a><span class="lineno"> 749</span> This class acts as a thin wrapper for an entity and for all its components. It's</div><div class="line"><a name="l00750"></a><span class="lineno"> 750</span> constructed with a registry to be used behind the scenes and is in charge of the</div><div class="line"><a name="l00751"></a><span class="lineno"> 751</span> destruction of the entity when it goes out of the scope.<br/></div><div class="line"><a name="l00752"></a><span class="lineno"> 752</span> An actor offers all the functionalities required to work with components, such</div><div class="line"><a name="l00753"></a><span class="lineno"> 753</span> as the `assign` and` remove` member functions, but also `has`,` get`, `try_get`</div><div class="line"><a name="l00754"></a><span class="lineno"> 754</span> and so on.</div><div class="line"><a name="l00755"></a><span class="lineno"> 755</span> </div><div class="line"><a name="l00756"></a><span class="lineno"> 756</span> My advice isn't to use the `actor` class to hide entities and components behind</div><div class="line"><a name="l00757"></a><span class="lineno"> 757</span> a more object-oriented interface. Instead, users should rely on it only where</div><div class="line"><a name="l00758"></a><span class="lineno"> 758</span> strictly necessary. In all other cases, it's highly advisable to become familiar</div><div class="line"><a name="l00759"></a><span class="lineno"> 759</span> with the model of `EnTT` and work directly with the registry, the views and the</div><div class="line"><a name="l00760"></a><span class="lineno"> 760</span> groups, rather than with a tool that could introduce a performance degradation.</div><div class="line"><a name="l00761"></a><span class="lineno"> 761</span> </div><div class="line"><a name="l00762"></a><span class="lineno"> 762</span> ### Context variables</div><div class="line"><a name="l00763"></a><span class="lineno"> 763</span> </div><div class="line"><a name="l00764"></a><span class="lineno"> 764</span> It is often convenient to assign context variables to a registry, so as to make</div><div class="line"><a name="l00765"></a><span class="lineno"> 765</span> it the only _source of truth_ of an application.<br/></div><div class="line"><a name="l00766"></a><span class="lineno"> 766</span> This is possible by means of a member function named `set` to use to create a</div><div class="line"><a name="l00767"></a><span class="lineno"> 767</span> context variable from a given type. Later on, either `ctx` or `try_ctx` can be</div><div class="line"><a name="l00768"></a><span class="lineno"> 768</span> used to retrieve the newly created instance and `unset` is there to literally</div><div class="line"><a name="l00769"></a><span class="lineno"> 769</span> reset it if needed.</div><div class="line"><a name="l00770"></a><span class="lineno"> 770</span> </div><div class="line"><a name="l00771"></a><span class="lineno"> 771</span> Example of use:</div><div class="line"><a name="l00772"></a><span class="lineno"> 772</span> </div><div class="line"><a name="l00773"></a><span class="lineno"> 773</span> ```cpp</div><div class="line"><a name="l00774"></a><span class="lineno"> 774</span> // creates a new context variable initialized with the given values</div><div class="line"><a name="l00775"></a><span class="lineno"> 775</span> registry.set<my_type>(42, 'c');</div><div class="line"><a name="l00776"></a><span class="lineno"> 776</span> </div><div class="line"><a name="l00777"></a><span class="lineno"> 777</span> // gets the context variable</div><div class="line"><a name="l00778"></a><span class="lineno"> 778</span> const auto &var = registry.ctx<my_type>();</div><div class="line"><a name="l00779"></a><span class="lineno"> 779</span> </div><div class="line"><a name="l00780"></a><span class="lineno"> 780</span> // if in doubts, probe the registry to avoid assertions in case of errors</div><div class="line"><a name="l00781"></a><span class="lineno"> 781</span> if(auto *ptr = registry.try_ctx<my_type>(); ptr) {</div><div class="line"><a name="l00782"></a><span class="lineno"> 782</span>  // uses the context variable associated with the registry, if any</div><div class="line"><a name="l00783"></a><span class="lineno"> 783</span> }</div><div class="line"><a name="l00784"></a><span class="lineno"> 784</span> </div><div class="line"><a name="l00785"></a><span class="lineno"> 785</span> // unsets the context variable</div><div class="line"><a name="l00786"></a><span class="lineno"> 786</span> registry.unset<my_type>();</div><div class="line"><a name="l00787"></a><span class="lineno"> 787</span> ```</div><div class="line"><a name="l00788"></a><span class="lineno"> 788</span> </div><div class="line"><a name="l00789"></a><span class="lineno"> 789</span> The type of a context variable must be such that it's default constructible and</div><div class="line"><a name="l00790"></a><span class="lineno"> 790</span> can be moved. The `set` member function either creates a new instance of the</div><div class="line"><a name="l00791"></a><span class="lineno"> 791</span> context variable or overwrites an already existing one if any. The `try_ctx`</div><div class="line"><a name="l00792"></a><span class="lineno"> 792</span> member function returns a pointer to the context variable if it exists,</div><div class="line"><a name="l00793"></a><span class="lineno"> 793</span> otherwise it returns a null pointer. This fits well with the `if` statement with</div><div class="line"><a name="l00794"></a><span class="lineno"> 794</span> initializer.</div><div class="line"><a name="l00795"></a><span class="lineno"> 795</span> </div><div class="line"><a name="l00796"></a><span class="lineno"> 796</span> ## Snapshot: complete vs continuous</div><div class="line"><a name="l00797"></a><span class="lineno"> 797</span> </div><div class="line"><a name="l00798"></a><span class="lineno"> 798</span> The `registry` class offers basic support to serialization.<br/></div><div class="line"><a name="l00799"></a><span class="lineno"> 799</span> It doesn't convert components to bytes directly, there wasn't the need of</div><div class="line"><a name="l00800"></a><span class="lineno"> 800</span> another tool for serialization out there. Instead, it accepts an opaque object</div><div class="line"><a name="l00801"></a><span class="lineno"> 801</span> with a suitable interface (namely an _archive_) to serialize its internal data</div><div class="line"><a name="l00802"></a><span class="lineno"> 802</span> structures and restore them later. The way types and instances are converted to</div><div class="line"><a name="l00803"></a><span class="lineno"> 803</span> a bunch of bytes is completely in charge to the archive and thus to final users.</div><div class="line"><a name="l00804"></a><span class="lineno"> 804</span> </div><div class="line"><a name="l00805"></a><span class="lineno"> 805</span> The goal of the serialization part is to allow users to make both a dump of the</div><div class="line"><a name="l00806"></a><span class="lineno"> 806</span> entire registry or a narrower snapshot, that is to select only the components in</div><div class="line"><a name="l00807"></a><span class="lineno"> 807</span> which they are interested.<br/></div><div class="line"><a name="l00808"></a><span class="lineno"> 808</span> Intuitively, the use cases are different. As an example, the first approach is</div><div class="line"><a name="l00809"></a><span class="lineno"> 809</span> suitable for local save/restore functionalities while the latter is suitable for</div><div class="line"><a name="l00810"></a><span class="lineno"> 810</span> creating client-server applications and for transferring somehow parts of the</div><div class="line"><a name="l00811"></a><span class="lineno"> 811</span> representation side to side.</div><div class="line"><a name="l00812"></a><span class="lineno"> 812</span> </div><div class="line"><a name="l00813"></a><span class="lineno"> 813</span> To take a snapshot of the registry, use the `snapshot` member function. It</div><div class="line"><a name="l00814"></a><span class="lineno"> 814</span> returns a temporary object properly initialized to _save_ the whole registry or</div><div class="line"><a name="l00815"></a><span class="lineno"> 815</span> parts of it.</div><div class="line"><a name="l00816"></a><span class="lineno"> 816</span> </div><div class="line"><a name="l00817"></a><span class="lineno"> 817</span> Example of use:</div><div class="line"><a name="l00818"></a><span class="lineno"> 818</span> </div><div class="line"><a name="l00819"></a><span class="lineno"> 819</span> ```cpp</div><div class="line"><a name="l00820"></a><span class="lineno"> 820</span> output_archive output;</div><div class="line"><a name="l00821"></a><span class="lineno"> 821</span> </div><div class="line"><a name="l00822"></a><span class="lineno"> 822</span> registry.snapshot()</div><div class="line"><a name="l00823"></a><span class="lineno"> 823</span>  .entities(output)</div><div class="line"><a name="l00824"></a><span class="lineno"> 824</span>  .destroyed(output)</div><div class="line"><a name="l00825"></a><span class="lineno"> 825</span>  .component<a_component, another_component>(output);</div><div class="line"><a name="l00826"></a><span class="lineno"> 826</span> ```</div><div class="line"><a name="l00827"></a><span class="lineno"> 827</span> </div><div class="line"><a name="l00828"></a><span class="lineno"> 828</span> It isn't necessary to invoke all these functions each and every time. What</div><div class="line"><a name="l00829"></a><span class="lineno"> 829</span> functions to use in which case mostly depends on the goal and there is not a</div><div class="line"><a name="l00830"></a><span class="lineno"> 830</span> golden rule to do that.</div><div class="line"><a name="l00831"></a><span class="lineno"> 831</span> </div><div class="line"><a name="l00832"></a><span class="lineno"> 832</span> The `entities` member function asks the registry to serialize all the entities</div><div class="line"><a name="l00833"></a><span class="lineno"> 833</span> that are still in use along with their versions. On the other side, the</div><div class="line"><a name="l00834"></a><span class="lineno"> 834</span> `destroyed` member function tells to the registry to serialize the entities that</div><div class="line"><a name="l00835"></a><span class="lineno"> 835</span> have been destroyed and are no longer in use.<br/></div><div class="line"><a name="l00836"></a><span class="lineno"> 836</span> These two functions can be used to save and restore the whole set of entities</div><div class="line"><a name="l00837"></a><span class="lineno"> 837</span> with the versions they had during serialization.</div><div class="line"><a name="l00838"></a><span class="lineno"> 838</span> </div><div class="line"><a name="l00839"></a><span class="lineno"> 839</span> The `component` member function is a function template the aim of which is to</div><div class="line"><a name="l00840"></a><span class="lineno"> 840</span> store aside components. The presence of a template parameter list is a</div><div class="line"><a name="l00841"></a><span class="lineno"> 841</span> consequence of a couple of design choices from the past and in the present:</div><div class="line"><a name="l00842"></a><span class="lineno"> 842</span> </div><div class="line"><a name="l00843"></a><span class="lineno"> 843</span> * First of all, there is no reason to force a user to serialize all the</div><div class="line"><a name="l00844"></a><span class="lineno"> 844</span>  components at once and most of the times it isn't desiderable. As an example,</div><div class="line"><a name="l00845"></a><span class="lineno"> 845</span>  in case the stuff for the HUD in a game is put into the registry for some</div><div class="line"><a name="l00846"></a><span class="lineno"> 846</span>  reasons, its components can be freely discarded during a serialization step</div><div class="line"><a name="l00847"></a><span class="lineno"> 847</span>  because probably the software already knows how to reconstruct the HUD</div><div class="line"><a name="l00848"></a><span class="lineno"> 848</span>  correctly from scratch.</div><div class="line"><a name="l00849"></a><span class="lineno"> 849</span> </div><div class="line"><a name="l00850"></a><span class="lineno"> 850</span> * Furthermore, the registry makes heavy use of _type-erasure_ techniques</div><div class="line"><a name="l00851"></a><span class="lineno"> 851</span>  internally and doesn't know at any time what component types it contains.</div><div class="line"><a name="l00852"></a><span class="lineno"> 852</span>  Therefore being explicit at the call point is mandatory.</div><div class="line"><a name="l00853"></a><span class="lineno"> 853</span> </div><div class="line"><a name="l00854"></a><span class="lineno"> 854</span> There exists also another version of the `component` member function that</div><div class="line"><a name="l00855"></a><span class="lineno"> 855</span> accepts a range of entities to serialize. This version is a bit slower than the</div><div class="line"><a name="l00856"></a><span class="lineno"> 856</span> other one, mainly because it iterates the range of entities more than once for</div><div class="line"><a name="l00857"></a><span class="lineno"> 857</span> internal purposes. However, it can be used to filter out those entities that</div><div class="line"><a name="l00858"></a><span class="lineno"> 858</span> shouldn't be serialized for some reasons.<br/></div><div class="line"><a name="l00859"></a><span class="lineno"> 859</span> As an example:</div><div class="line"><a name="l00860"></a><span class="lineno"> 860</span> </div><div class="line"><a name="l00861"></a><span class="lineno"> 861</span> ```cpp</div><div class="line"><a name="l00862"></a><span class="lineno"> 862</span> const auto view = registry.view<serialize>();</div><div class="line"><a name="l00863"></a><span class="lineno"> 863</span> output_archive output;</div><div class="line"><a name="l00864"></a><span class="lineno"> 864</span> </div><div class="line"><a name="l00865"></a><span class="lineno"> 865</span> registry.snapshot().component<a_component, another_component>(output, view.cbegin(), view.cend());</div><div class="line"><a name="l00866"></a><span class="lineno"> 866</span> ```</div><div class="line"><a name="l00867"></a><span class="lineno"> 867</span> </div><div class="line"><a name="l00868"></a><span class="lineno"> 868</span> Note that `component` stores items along with entities. It means that it works</div><div class="line"><a name="l00869"></a><span class="lineno"> 869</span> properly without a call to the `entities` member function.</div><div class="line"><a name="l00870"></a><span class="lineno"> 870</span> </div><div class="line"><a name="l00871"></a><span class="lineno"> 871</span> Once a snapshot is created, there exist mainly two _ways_ to load it: as a whole</div><div class="line"><a name="l00872"></a><span class="lineno"> 872</span> and in a kind of _continuous mode_.<br/></div><div class="line"><a name="l00873"></a><span class="lineno"> 873</span> The following sections describe both loaders and archives in details.</div><div class="line"><a name="l00874"></a><span class="lineno"> 874</span> </div><div class="line"><a name="l00875"></a><span class="lineno"> 875</span> ### Snapshot loader</div><div class="line"><a name="l00876"></a><span class="lineno"> 876</span> </div><div class="line"><a name="l00877"></a><span class="lineno"> 877</span> A snapshot loader requires that the destination registry be empty and loads all</div><div class="line"><a name="l00878"></a><span class="lineno"> 878</span> the data at once while keeping intact the identifiers that the entities</div><div class="line"><a name="l00879"></a><span class="lineno"> 879</span> originally had.<br/></div><div class="line"><a name="l00880"></a><span class="lineno"> 880</span> To do that, the registry offers a member function named `loader` that returns a</div><div class="line"><a name="l00881"></a><span class="lineno"> 881</span> temporary object properly initialized to _restore_ a snapshot.</div><div class="line"><a name="l00882"></a><span class="lineno"> 882</span> </div><div class="line"><a name="l00883"></a><span class="lineno"> 883</span> Example of use:</div><div class="line"><a name="l00884"></a><span class="lineno"> 884</span> </div><div class="line"><a name="l00885"></a><span class="lineno"> 885</span> ```cpp</div><div class="line"><a name="l00886"></a><span class="lineno"> 886</span> input_archive input;</div><div class="line"><a name="l00887"></a><span class="lineno"> 887</span> </div><div class="line"><a name="l00888"></a><span class="lineno"> 888</span> registry.loader()</div><div class="line"><a name="l00889"></a><span class="lineno"> 889</span>  .entities(input)</div><div class="line"><a name="l00890"></a><span class="lineno"> 890</span>  .destroyed(input)</div><div class="line"><a name="l00891"></a><span class="lineno"> 891</span>  .component<a_component, another_component>(input)</div><div class="line"><a name="l00892"></a><span class="lineno"> 892</span>  .orphans();</div><div class="line"><a name="l00893"></a><span class="lineno"> 893</span> ```</div><div class="line"><a name="l00894"></a><span class="lineno"> 894</span> </div><div class="line"><a name="l00895"></a><span class="lineno"> 895</span> It isn't necessary to invoke all these functions each and every time. What</div><div class="line"><a name="l00896"></a><span class="lineno"> 896</span> functions to use in which case mostly depends on the goal and there is not a</div><div class="line"><a name="l00897"></a><span class="lineno"> 897</span> golden rule to do that. For obvious reasons, what is important is that the data</div><div class="line"><a name="l00898"></a><span class="lineno"> 898</span> are restored in exactly the same order in which they were serialized.</div><div class="line"><a name="l00899"></a><span class="lineno"> 899</span> </div><div class="line"><a name="l00900"></a><span class="lineno"> 900</span> The `entities` and `destroyed` member functions restore the sets of entities and</div><div class="line"><a name="l00901"></a><span class="lineno"> 901</span> the versions that the entities originally had at the source.</div><div class="line"><a name="l00902"></a><span class="lineno"> 902</span> </div><div class="line"><a name="l00903"></a><span class="lineno"> 903</span> The `component` member function restores all and only the components specified</div><div class="line"><a name="l00904"></a><span class="lineno"> 904</span> and assigns them to the right entities. Note that the template parameter list</div><div class="line"><a name="l00905"></a><span class="lineno"> 905</span> must be exactly the same used during the serialization.</div><div class="line"><a name="l00906"></a><span class="lineno"> 906</span> </div><div class="line"><a name="l00907"></a><span class="lineno"> 907</span> The `orphans` member function literally destroys those entities that have no</div><div class="line"><a name="l00908"></a><span class="lineno"> 908</span> components attached. It's usually useless if the snapshot is a full dump of the</div><div class="line"><a name="l00909"></a><span class="lineno"> 909</span> source. However, in case all the entities are serialized but only few components</div><div class="line"><a name="l00910"></a><span class="lineno"> 910</span> are saved, it could happen that some of the entities have no components once</div><div class="line"><a name="l00911"></a><span class="lineno"> 911</span> restored. The best users can do to deal with them is to destroy those entities</div><div class="line"><a name="l00912"></a><span class="lineno"> 912</span> and thus update their versions.</div><div class="line"><a name="l00913"></a><span class="lineno"> 913</span> </div><div class="line"><a name="l00914"></a><span class="lineno"> 914</span> ### Continuous loader</div><div class="line"><a name="l00915"></a><span class="lineno"> 915</span> </div><div class="line"><a name="l00916"></a><span class="lineno"> 916</span> A continuous loader is designed to load data from a source registry to a</div><div class="line"><a name="l00917"></a><span class="lineno"> 917</span> (possibly) non-empty destination. The loader can accommodate in a registry more</div><div class="line"><a name="l00918"></a><span class="lineno"> 918</span> than one snapshot in a sort of _continuous loading_ that updates the</div><div class="line"><a name="l00919"></a><span class="lineno"> 919</span> destination one step at a time.<br/></div><div class="line"><a name="l00920"></a><span class="lineno"> 920</span> Identifiers that entities originally had are not transferred to the target.</div><div class="line"><a name="l00921"></a><span class="lineno"> 921</span> Instead, the loader maps remote identifiers to local ones while restoring a</div><div class="line"><a name="l00922"></a><span class="lineno"> 922</span> snapshot. Because of that, this kind of loader offers a way to update</div><div class="line"><a name="l00923"></a><span class="lineno"> 923</span> automatically identifiers that are part of components (as an example, as data</div><div class="line"><a name="l00924"></a><span class="lineno"> 924</span> members or gathered in a container).<br/></div><div class="line"><a name="l00925"></a><span class="lineno"> 925</span> Another difference with the snapshot loader is that the continuous loader does</div><div class="line"><a name="l00926"></a><span class="lineno"> 926</span> not need to work with the private data structures of a registry. Furthermore, it</div><div class="line"><a name="l00927"></a><span class="lineno"> 927</span> has an internal state that must persist over time. Therefore, there is no reason</div><div class="line"><a name="l00928"></a><span class="lineno"> 928</span> to create it by means of a registry, or to limit its lifetime to that of a</div><div class="line"><a name="l00929"></a><span class="lineno"> 929</span> temporary object.</div><div class="line"><a name="l00930"></a><span class="lineno"> 930</span> </div><div class="line"><a name="l00931"></a><span class="lineno"> 931</span> Example of use:</div><div class="line"><a name="l00932"></a><span class="lineno"> 932</span> </div><div class="line"><a name="l00933"></a><span class="lineno"> 933</span> ```cpp</div><div class="line"><a name="l00934"></a><span class="lineno"> 934</span> entt::continuous_loader<entt::entity> loader{registry};</div><div class="line"><a name="l00935"></a><span class="lineno"> 935</span> input_archive input;</div><div class="line"><a name="l00936"></a><span class="lineno"> 936</span> </div><div class="line"><a name="l00937"></a><span class="lineno"> 937</span> loader.entities(input)</div><div class="line"><a name="l00938"></a><span class="lineno"> 938</span>  .destroyed(input)</div><div class="line"><a name="l00939"></a><span class="lineno"> 939</span>  .component<a_component, another_component, dirty_component>(input, &dirty_component::parent, &dirty_component::child)</div><div class="line"><a name="l00940"></a><span class="lineno"> 940</span>  .orphans()</div><div class="line"><a name="l00941"></a><span class="lineno"> 941</span>  .shrink();</div><div class="line"><a name="l00942"></a><span class="lineno"> 942</span> ```</div><div class="line"><a name="l00943"></a><span class="lineno"> 943</span> </div><div class="line"><a name="l00944"></a><span class="lineno"> 944</span> It isn't necessary to invoke all these functions each and every time. What</div><div class="line"><a name="l00945"></a><span class="lineno"> 945</span> functions to use in which case mostly depends on the goal and there is not a</div><div class="line"><a name="l00946"></a><span class="lineno"> 946</span> golden rule to do that. For obvious reasons, what is important is that the data</div><div class="line"><a name="l00947"></a><span class="lineno"> 947</span> are restored in exactly the same order in which they were serialized.</div><div class="line"><a name="l00948"></a><span class="lineno"> 948</span> </div><div class="line"><a name="l00949"></a><span class="lineno"> 949</span> The `entities` and `destroyed` member functions restore groups of entities and</div><div class="line"><a name="l00950"></a><span class="lineno"> 950</span> map each entity to a local counterpart when required. In other terms, for each</div><div class="line"><a name="l00951"></a><span class="lineno"> 951</span> remote entity identifier not yet registered by the loader, the latter creates a</div><div class="line"><a name="l00952"></a><span class="lineno"> 952</span> local identifier so that it can keep the local entity in sync with the remote</div><div class="line"><a name="l00953"></a><span class="lineno"> 953</span> one.</div><div class="line"><a name="l00954"></a><span class="lineno"> 954</span> </div><div class="line"><a name="l00955"></a><span class="lineno"> 955</span> The `component` member function restores all and only the components specified</div><div class="line"><a name="l00956"></a><span class="lineno"> 956</span> and assigns them to the right entities.<br/></div><div class="line"><a name="l00957"></a><span class="lineno"> 957</span> In case the component contains entities itself (either as data members of type</div><div class="line"><a name="l00958"></a><span class="lineno"> 958</span> `entt::entity` or as containers of entities), the loader can update them</div><div class="line"><a name="l00959"></a><span class="lineno"> 959</span> automatically. To do that, it's enough to specify the data members to update as</div><div class="line"><a name="l00960"></a><span class="lineno"> 960</span> shown in the example.</div><div class="line"><a name="l00961"></a><span class="lineno"> 961</span> </div><div class="line"><a name="l00962"></a><span class="lineno"> 962</span> The `orphans` member function literally destroys those entities that have no</div><div class="line"><a name="l00963"></a><span class="lineno"> 963</span> components after a restore. It has exactly the same purpose described in the</div><div class="line"><a name="l00964"></a><span class="lineno"> 964</span> previous section and works the same way.</div><div class="line"><a name="l00965"></a><span class="lineno"> 965</span> </div><div class="line"><a name="l00966"></a><span class="lineno"> 966</span> Finally, `shrink` helps to purge local entities that no longer have a remote</div><div class="line"><a name="l00967"></a><span class="lineno"> 967</span> conterpart. Users should invoke this member function after restoring each</div><div class="line"><a name="l00968"></a><span class="lineno"> 968</span> snapshot, unless they know exactly what they are doing.</div><div class="line"><a name="l00969"></a><span class="lineno"> 969</span> </div><div class="line"><a name="l00970"></a><span class="lineno"> 970</span> ### Archives</div><div class="line"><a name="l00971"></a><span class="lineno"> 971</span> </div><div class="line"><a name="l00972"></a><span class="lineno"> 972</span> Archives must publicly expose a predefined set of member functions. The API is</div><div class="line"><a name="l00973"></a><span class="lineno"> 973</span> straightforward and consists only of a group of function call operators that</div><div class="line"><a name="l00974"></a><span class="lineno"> 974</span> are invoked by the snapshot class and the loaders.</div><div class="line"><a name="l00975"></a><span class="lineno"> 975</span> </div><div class="line"><a name="l00976"></a><span class="lineno"> 976</span> In particular:</div><div class="line"><a name="l00977"></a><span class="lineno"> 977</span> </div><div class="line"><a name="l00978"></a><span class="lineno"> 978</span> * An output archive, the one used when creating a snapshot, must expose a</div><div class="line"><a name="l00979"></a><span class="lineno"> 979</span>  function call operator with the following signature to store entities:</div><div class="line"><a name="l00980"></a><span class="lineno"> 980</span> </div><div class="line"><a name="l00981"></a><span class="lineno"> 981</span>  ```cpp</div><div class="line"><a name="l00982"></a><span class="lineno"> 982</span>  void operator()(entt::entity);</div><div class="line"><a name="l00983"></a><span class="lineno"> 983</span>  ```</div><div class="line"><a name="l00984"></a><span class="lineno"> 984</span> </div><div class="line"><a name="l00985"></a><span class="lineno"> 985</span>  Where `entt::entity` is the type of the entities used by the registry. Note</div><div class="line"><a name="l00986"></a><span class="lineno"> 986</span>  that all the member functions of the snapshot class make also an initial call</div><div class="line"><a name="l00987"></a><span class="lineno"> 987</span>  to this endpoint to save the _size_ of the set they are going to store.<br/></div><div class="line"><a name="l00988"></a><span class="lineno"> 988</span>  In addition, an archive must accept a pair of entity and component for each</div><div class="line"><a name="l00989"></a><span class="lineno"> 989</span>  type to be serialized. Therefore, given a type `T`, the archive must contain a</div><div class="line"><a name="l00990"></a><span class="lineno"> 990</span>  function call operator with the following signature:</div><div class="line"><a name="l00991"></a><span class="lineno"> 991</span> </div><div class="line"><a name="l00992"></a><span class="lineno"> 992</span>  ```cpp</div><div class="line"><a name="l00993"></a><span class="lineno"> 993</span>  void operator()(entt::entity, const T &);</div><div class="line"><a name="l00994"></a><span class="lineno"> 994</span>  ```</div><div class="line"><a name="l00995"></a><span class="lineno"> 995</span> </div><div class="line"><a name="l00996"></a><span class="lineno"> 996</span>  The output archive can freely decide how to serialize the data. The register</div><div class="line"><a name="l00997"></a><span class="lineno"> 997</span>  is not affected at all by the decision.</div><div class="line"><a name="l00998"></a><span class="lineno"> 998</span> </div><div class="line"><a name="l00999"></a><span class="lineno"> 999</span> * An input archive, the one used when restoring a snapshot, must expose a</div><div class="line"><a name="l01000"></a><span class="lineno"> 1000</span>  function call operator with the following signature to load entities:</div><div class="line"><a name="l01001"></a><span class="lineno"> 1001</span> </div><div class="line"><a name="l01002"></a><span class="lineno"> 1002</span>  ```cpp</div><div class="line"><a name="l01003"></a><span class="lineno"> 1003</span>  void operator()(entt::entity &);</div><div class="line"><a name="l01004"></a><span class="lineno"> 1004</span>  ```</div><div class="line"><a name="l01005"></a><span class="lineno"> 1005</span> </div><div class="line"><a name="l01006"></a><span class="lineno"> 1006</span>  Where `entt::entity` is the type of the entities used by the registry. Each</div><div class="line"><a name="l01007"></a><span class="lineno"> 1007</span>  time the function is invoked, the archive must read the next element from the</div><div class="line"><a name="l01008"></a><span class="lineno"> 1008</span>  underlying storage and copy it in the given variable. Note that all the member</div><div class="line"><a name="l01009"></a><span class="lineno"> 1009</span>  functions of a loader class make also an initial call to this endpoint to read</div><div class="line"><a name="l01010"></a><span class="lineno"> 1010</span>  the _size_ of the set they are going to load.<br/></div><div class="line"><a name="l01011"></a><span class="lineno"> 1011</span>  In addition, the archive must accept a pair of entity and component for each</div><div class="line"><a name="l01012"></a><span class="lineno"> 1012</span>  type to be restored. Therefore, given a type `T`, the archive must contain a</div><div class="line"><a name="l01013"></a><span class="lineno"> 1013</span>  function call operator with the following signature:</div><div class="line"><a name="l01014"></a><span class="lineno"> 1014</span> </div><div class="line"><a name="l01015"></a><span class="lineno"> 1015</span>  ```cpp</div><div class="line"><a name="l01016"></a><span class="lineno"> 1016</span>  void operator()(entt::entity &, T &);</div><div class="line"><a name="l01017"></a><span class="lineno"> 1017</span>  ```</div><div class="line"><a name="l01018"></a><span class="lineno"> 1018</span> </div><div class="line"><a name="l01019"></a><span class="lineno"> 1019</span>  Every time such an operator is invoked, the archive must read the next</div><div class="line"><a name="l01020"></a><span class="lineno"> 1020</span>  elements from the underlying storage and copy them in the given variables.</div><div class="line"><a name="l01021"></a><span class="lineno"> 1021</span> </div><div class="line"><a name="l01022"></a><span class="lineno"> 1022</span> ### One example to rule them all</div><div class="line"><a name="l01023"></a><span class="lineno"> 1023</span> </div><div class="line"><a name="l01024"></a><span class="lineno"> 1024</span> `EnTT` comes with some examples (actually some tests) that show how to integrate</div><div class="line"><a name="l01025"></a><span class="lineno"> 1025</span> a well known library for serialization as an archive. It uses</div><div class="line"><a name="l01026"></a><span class="lineno"> 1026</span> [`Cereal C++`](https://uscilab.github.io/cereal/) under the hood, mainly</div><div class="line"><a name="l01027"></a><span class="lineno"> 1027</span> because I wanted to learn how it works at the time I was writing the code.</div><div class="line"><a name="l01028"></a><span class="lineno"> 1028</span> </div><div class="line"><a name="l01029"></a><span class="lineno"> 1029</span> The code is not production-ready and it isn't neither the only nor (probably)</div><div class="line"><a name="l01030"></a><span class="lineno"> 1030</span> the best way to do it. However, feel free to use it at your own risk.</div><div class="line"><a name="l01031"></a><span class="lineno"> 1031</span> </div><div class="line"><a name="l01032"></a><span class="lineno"> 1032</span> The basic idea is to store everything in a group of queues in memory, then bring</div><div class="line"><a name="l01033"></a><span class="lineno"> 1033</span> everything back to the registry with different loaders.</div><div class="line"><a name="l01034"></a><span class="lineno"> 1034</span> </div><div class="line"><a name="l01035"></a><span class="lineno"> 1035</span> # Views and Groups</div><div class="line"><a name="l01036"></a><span class="lineno"> 1036</span> </div><div class="line"><a name="l01037"></a><span class="lineno"> 1037</span> First of all, it is worth answering an obvious question: why views and</div><div class="line"><a name="l01038"></a><span class="lineno"> 1038</span> groups?<br/></div><div class="line"><a name="l01039"></a><span class="lineno"> 1039</span> Briefly, they are a good tool to enforce single responsibility. A system that</div><div class="line"><a name="l01040"></a><span class="lineno"> 1040</span> has access to a registry can create and destroy entities, as well as assign and</div><div class="line"><a name="l01041"></a><span class="lineno"> 1041</span> remove components. On the other side, a system that has access to a view or a</div><div class="line"><a name="l01042"></a><span class="lineno"> 1042</span> group can only iterate entities and their components, then read or update the</div><div class="line"><a name="l01043"></a><span class="lineno"> 1043</span> data members of the latter.<br/></div><div class="line"><a name="l01044"></a><span class="lineno"> 1044</span> It is a subtle difference that can help designing a better software sometimes.</div><div class="line"><a name="l01045"></a><span class="lineno"> 1045</span> </div><div class="line"><a name="l01046"></a><span class="lineno"> 1046</span> More in details, views are a non-intrusive tool to access entities and</div><div class="line"><a name="l01047"></a><span class="lineno"> 1047</span> components without affecting other functionalities or increasing the memory</div><div class="line"><a name="l01048"></a><span class="lineno"> 1048</span> consumption. On the other side, groups are an intrusive tool that allows to</div><div class="line"><a name="l01049"></a><span class="lineno"> 1049</span> reach higher performance along critical paths but has also a price to pay for</div><div class="line"><a name="l01050"></a><span class="lineno"> 1050</span> that.</div><div class="line"><a name="l01051"></a><span class="lineno"> 1051</span> </div><div class="line"><a name="l01052"></a><span class="lineno"> 1052</span> There are mainly two kinds of views: _compile-time_ (also known as `view`) and</div><div class="line"><a name="l01053"></a><span class="lineno"> 1053</span> runtime (also known as `runtime_view`).<br/></div><div class="line"><a name="l01054"></a><span class="lineno"> 1054</span> The former require that users indicate at compile-time what are the components</div><div class="line"><a name="l01055"></a><span class="lineno"> 1055</span> involved and can make several optimizations because of that. The latter can be</div><div class="line"><a name="l01056"></a><span class="lineno"> 1056</span> constructed at runtime instead and are a bit slower to iterate entities and</div><div class="line"><a name="l01057"></a><span class="lineno"> 1057</span> components.<br/></div><div class="line"><a name="l01058"></a><span class="lineno"> 1058</span> In both cases, creating and destroying a view isn't expensive at all because</div><div class="line"><a name="l01059"></a><span class="lineno"> 1059</span> views don't have any type of initialization. Moreover, views don't affect any</div><div class="line"><a name="l01060"></a><span class="lineno"> 1060</span> other functionality of the registry and keep memory usage at a minimum.</div><div class="line"><a name="l01061"></a><span class="lineno"> 1061</span> </div><div class="line"><a name="l01062"></a><span class="lineno"> 1062</span> Groups come in three different flavors: _full-owning groups_, _partial-owning</div><div class="line"><a name="l01063"></a><span class="lineno"> 1063</span> groups_ and _non-owning groups_. The main difference between them is in terms of</div><div class="line"><a name="l01064"></a><span class="lineno"> 1064</span> performance.<br/></div><div class="line"><a name="l01065"></a><span class="lineno"> 1065</span> Groups can literally _own_ one or more component types. It means that they will</div><div class="line"><a name="l01066"></a><span class="lineno"> 1066</span> be allowed to rearrange pools so as to speed up iterations. Roughly speaking:</div><div class="line"><a name="l01067"></a><span class="lineno"> 1067</span> the more components a group owns, the faster it is to iterate them. On the other</div><div class="line"><a name="l01068"></a><span class="lineno"> 1068</span> side, a given component can belong to multiple groups only if they are _nested_,</div><div class="line"><a name="l01069"></a><span class="lineno"> 1069</span> so users have to define groups carefully to get the best out of them.</div><div class="line"><a name="l01070"></a><span class="lineno"> 1070</span> </div><div class="line"><a name="l01071"></a><span class="lineno"> 1071</span> Continue reading for more details or refer to the inline documentation.</div><div class="line"><a name="l01072"></a><span class="lineno"> 1072</span> </div><div class="line"><a name="l01073"></a><span class="lineno"> 1073</span> ## Views</div><div class="line"><a name="l01074"></a><span class="lineno"> 1074</span> </div><div class="line"><a name="l01075"></a><span class="lineno"> 1075</span> A view behaves differently if it's constructed for a single component or if it</div><div class="line"><a name="l01076"></a><span class="lineno"> 1076</span> has been created to iterate multiple components. Even the API is slightly</div><div class="line"><a name="l01077"></a><span class="lineno"> 1077</span> different in the two cases.</div><div class="line"><a name="l01078"></a><span class="lineno"> 1078</span> </div><div class="line"><a name="l01079"></a><span class="lineno"> 1079</span> Single component views are specialized in order to give a boost in terms of</div><div class="line"><a name="l01080"></a><span class="lineno"> 1080</span> performance in all the situations. This kind of views can access the underlying</div><div class="line"><a name="l01081"></a><span class="lineno"> 1081</span> data structures directly and avoid superfluous checks. There is nothing as fast</div><div class="line"><a name="l01082"></a><span class="lineno"> 1082</span> as a single component view. In fact, they walk through a packed array of</div><div class="line"><a name="l01083"></a><span class="lineno"> 1083</span> components and return them one at a time.<br/></div><div class="line"><a name="l01084"></a><span class="lineno"> 1084</span> Single component views offer a bunch of functionalities to get the number of</div><div class="line"><a name="l01085"></a><span class="lineno"> 1085</span> entities they are going to return and a raw access to the entity list as well as</div><div class="line"><a name="l01086"></a><span class="lineno"> 1086</span> to the component list. It's also possible to ask a view if it contains a</div><div class="line"><a name="l01087"></a><span class="lineno"> 1087</span> given entity.<br/></div><div class="line"><a name="l01088"></a><span class="lineno"> 1088</span> Refer to the inline documentation for all the details.</div><div class="line"><a name="l01089"></a><span class="lineno"> 1089</span> </div><div class="line"><a name="l01090"></a><span class="lineno"> 1090</span> Multi component views iterate entities that have at least all the given</div><div class="line"><a name="l01091"></a><span class="lineno"> 1091</span> components in their bags. During construction, these views look at the number of</div><div class="line"><a name="l01092"></a><span class="lineno"> 1092</span> entities available for each component and pick up a reference to the smallest</div><div class="line"><a name="l01093"></a><span class="lineno"> 1093</span> set of candidates in order to speed up iterations.<br/></div><div class="line"><a name="l01094"></a><span class="lineno"> 1094</span> They offer fewer functionalities than their companion views for single</div><div class="line"><a name="l01095"></a><span class="lineno"> 1095</span> component. In particular, a multi component view exposes utility functions to</div><div class="line"><a name="l01096"></a><span class="lineno"> 1096</span> get the estimated number of entities it is going to return and to know whether</div><div class="line"><a name="l01097"></a><span class="lineno"> 1097</span> it's empty or not. It's also possible to ask a view if it contains a given</div><div class="line"><a name="l01098"></a><span class="lineno"> 1098</span> entity.<br/></div><div class="line"><a name="l01099"></a><span class="lineno"> 1099</span> Refer to the inline documentation for all the details.</div><div class="line"><a name="l01100"></a><span class="lineno"> 1100</span> </div><div class="line"><a name="l01101"></a><span class="lineno"> 1101</span> There is no need to store views around for they are extremely cheap to</div><div class="line"><a name="l01102"></a><span class="lineno"> 1102</span> construct, even though they can be copied without problems and reused freely.</div><div class="line"><a name="l01103"></a><span class="lineno"> 1103</span> Views also return newly created and correctly initialized iterators whenever</div><div class="line"><a name="l01104"></a><span class="lineno"> 1104</span> `begin` or `end` are invoked.</div><div class="line"><a name="l01105"></a><span class="lineno"> 1105</span> </div><div class="line"><a name="l01106"></a><span class="lineno"> 1106</span> Views share the way they are created by means of a registry:</div><div class="line"><a name="l01107"></a><span class="lineno"> 1107</span> </div><div class="line"><a name="l01108"></a><span class="lineno"> 1108</span> ```cpp</div><div class="line"><a name="l01109"></a><span class="lineno"> 1109</span> // single component view</div><div class="line"><a name="l01110"></a><span class="lineno"> 1110</span> auto single = registry.view<position>();</div><div class="line"><a name="l01111"></a><span class="lineno"> 1111</span> </div><div class="line"><a name="l01112"></a><span class="lineno"> 1112</span> // multi component view</div><div class="line"><a name="l01113"></a><span class="lineno"> 1113</span> auto multi = registry.view<position, velocity>();</div><div class="line"><a name="l01114"></a><span class="lineno"> 1114</span> ```</div><div class="line"><a name="l01115"></a><span class="lineno"> 1115</span> </div><div class="line"><a name="l01116"></a><span class="lineno"> 1116</span> Filtering entities by components is also supported:</div><div class="line"><a name="l01117"></a><span class="lineno"> 1117</span> </div><div class="line"><a name="l01118"></a><span class="lineno"> 1118</span> ```cpp</div><div class="line"><a name="l01119"></a><span class="lineno"> 1119</span> auto view = registry.view<position, velocity>(entt::exclude<renderable>);</div><div class="line"><a name="l01120"></a><span class="lineno"> 1120</span> ```</div><div class="line"><a name="l01121"></a><span class="lineno"> 1121</span> </div><div class="line"><a name="l01122"></a><span class="lineno"> 1122</span> To iterate a view, either use it in a range-for loop:</div><div class="line"><a name="l01123"></a><span class="lineno"> 1123</span> </div><div class="line"><a name="l01124"></a><span class="lineno"> 1124</span> ```cpp</div><div class="line"><a name="l01125"></a><span class="lineno"> 1125</span> auto view = registry.view<position, velocity>();</div><div class="line"><a name="l01126"></a><span class="lineno"> 1126</span> </div><div class="line"><a name="l01127"></a><span class="lineno"> 1127</span> for(auto entity: view) {</div><div class="line"><a name="l01128"></a><span class="lineno"> 1128</span>  // a component at a time ...</div><div class="line"><a name="l01129"></a><span class="lineno"> 1129</span>  auto &position = view.get<position>(entity);</div><div class="line"><a name="l01130"></a><span class="lineno"> 1130</span>  auto &velocity = view.get<velocity>(entity);</div><div class="line"><a name="l01131"></a><span class="lineno"> 1131</span> </div><div class="line"><a name="l01132"></a><span class="lineno"> 1132</span>  // ... or multiple components at once</div><div class="line"><a name="l01133"></a><span class="lineno"> 1133</span>  auto &[pos, vel] = view.get<position, velocity>(entity);</div><div class="line"><a name="l01134"></a><span class="lineno"> 1134</span> </div><div class="line"><a name="l01135"></a><span class="lineno"> 1135</span>  // ...</div><div class="line"><a name="l01136"></a><span class="lineno"> 1136</span> }</div><div class="line"><a name="l01137"></a><span class="lineno"> 1137</span> ```</div><div class="line"><a name="l01138"></a><span class="lineno"> 1138</span> </div><div class="line"><a name="l01139"></a><span class="lineno"> 1139</span> Or rely on the `each` member function to iterate entities and get all their</div><div class="line"><a name="l01140"></a><span class="lineno"> 1140</span> components at once:</div><div class="line"><a name="l01141"></a><span class="lineno"> 1141</span> </div><div class="line"><a name="l01142"></a><span class="lineno"> 1142</span> ```cpp</div><div class="line"><a name="l01143"></a><span class="lineno"> 1143</span> registry.view<position, velocity>().each([](auto entity, auto &pos, auto &vel) {</div><div class="line"><a name="l01144"></a><span class="lineno"> 1144</span>  // ...</div><div class="line"><a name="l01145"></a><span class="lineno"> 1145</span> });</div><div class="line"><a name="l01146"></a><span class="lineno"> 1146</span> ```</div><div class="line"><a name="l01147"></a><span class="lineno"> 1147</span> </div><div class="line"><a name="l01148"></a><span class="lineno"> 1148</span> The `each` member function is highly optimized. Unless users want to iterate</div><div class="line"><a name="l01149"></a><span class="lineno"> 1149</span> only entities or get only some of the components, this should be the preferred</div><div class="line"><a name="l01150"></a><span class="lineno"> 1150</span> approach. Note that the entity can also be excluded from the parameter list if</div><div class="line"><a name="l01151"></a><span class="lineno"> 1151</span> not required, but this won't improve performance for multi component views.<br/></div><div class="line"><a name="l01152"></a><span class="lineno"> 1152</span> There exists also an alternative version of `each` named `less` that works</div><div class="line"><a name="l01153"></a><span class="lineno"> 1153</span> exactly as its counterpart but for the fact that it doesn't return empty</div><div class="line"><a name="l01154"></a><span class="lineno"> 1154</span> components to the caller.</div><div class="line"><a name="l01155"></a><span class="lineno"> 1155</span> </div><div class="line"><a name="l01156"></a><span class="lineno"> 1156</span> As a side note, in the case of single component views, `get` accepts but doesn't</div><div class="line"><a name="l01157"></a><span class="lineno"> 1157</span> strictly require a template parameter, since the type is implicitly defined:</div><div class="line"><a name="l01158"></a><span class="lineno"> 1158</span> </div><div class="line"><a name="l01159"></a><span class="lineno"> 1159</span> ```cpp</div><div class="line"><a name="l01160"></a><span class="lineno"> 1160</span> auto view = registry.view<const renderable>();</div><div class="line"><a name="l01161"></a><span class="lineno"> 1161</span> </div><div class="line"><a name="l01162"></a><span class="lineno"> 1162</span> for(auto entity: view) {</div><div class="line"><a name="l01163"></a><span class="lineno"> 1163</span>  const auto &renderable = view.get(entity);</div><div class="line"><a name="l01164"></a><span class="lineno"> 1164</span>  // ...</div><div class="line"><a name="l01165"></a><span class="lineno"> 1165</span> }</div><div class="line"><a name="l01166"></a><span class="lineno"> 1166</span> ```</div><div class="line"><a name="l01167"></a><span class="lineno"> 1167</span> </div><div class="line"><a name="l01168"></a><span class="lineno"> 1168</span> **Note**: prefer the `get` member function of a view instead of the `get` member</div><div class="line"><a name="l01169"></a><span class="lineno"> 1169</span> function template of a registry during iterations, if possible. However, keep in</div><div class="line"><a name="l01170"></a><span class="lineno"> 1170</span> mind that it works only with the components of the view itself.</div><div class="line"><a name="l01171"></a><span class="lineno"> 1171</span> </div><div class="line"><a name="l01172"></a><span class="lineno"> 1172</span> ## Runtime views</div><div class="line"><a name="l01173"></a><span class="lineno"> 1173</span> </div><div class="line"><a name="l01174"></a><span class="lineno"> 1174</span> Runtime views iterate entities that have at least all the given components in</div><div class="line"><a name="l01175"></a><span class="lineno"> 1175</span> their bags. During construction, these views look at the number of entities</div><div class="line"><a name="l01176"></a><span class="lineno"> 1176</span> available for each component and pick up a reference to the smallest</div><div class="line"><a name="l01177"></a><span class="lineno"> 1177</span> set of candidates in order to speed up iterations.<br/></div><div class="line"><a name="l01178"></a><span class="lineno"> 1178</span> They offer more or less the same functionalities of a multi component view.</div><div class="line"><a name="l01179"></a><span class="lineno"> 1179</span> However, they don't expose a `get` member function and users should refer to the</div><div class="line"><a name="l01180"></a><span class="lineno"> 1180</span> registry that generated the view to access components. In particular, a runtime</div><div class="line"><a name="l01181"></a><span class="lineno"> 1181</span> view exposes utility functions to get the estimated number of entities it is</div><div class="line"><a name="l01182"></a><span class="lineno"> 1182</span> going to return and to know whether it's empty or not. It's also possible to ask</div><div class="line"><a name="l01183"></a><span class="lineno"> 1183</span> a runtime view if it contains a given entity.<br/></div><div class="line"><a name="l01184"></a><span class="lineno"> 1184</span> Refer to the inline documentation for all the details.</div><div class="line"><a name="l01185"></a><span class="lineno"> 1185</span> </div><div class="line"><a name="l01186"></a><span class="lineno"> 1186</span> Runtime view are extremely cheap to construct and should not be stored around in</div><div class="line"><a name="l01187"></a><span class="lineno"> 1187</span> any case. They should be used immediately after creation and then they should be</div><div class="line"><a name="l01188"></a><span class="lineno"> 1188</span> thrown away. The reasons for this go far beyond the scope of this document.<br/></div><div class="line"><a name="l01189"></a><span class="lineno"> 1189</span> To iterate a runtime view, either use it in a range-for loop:</div><div class="line"><a name="l01190"></a><span class="lineno"> 1190</span> </div><div class="line"><a name="l01191"></a><span class="lineno"> 1191</span> ```cpp</div><div class="line"><a name="l01192"></a><span class="lineno"> 1192</span> entt::component types[] = { registry.type<position>(), registry.type<velocity>() };</div><div class="line"><a name="l01193"></a><span class="lineno"> 1193</span> auto view = registry.runtime_view(std::cbegin(types), std::cend(types));</div><div class="line"><a name="l01194"></a><span class="lineno"> 1194</span> </div><div class="line"><a name="l01195"></a><span class="lineno"> 1195</span> for(auto entity: view) {</div><div class="line"><a name="l01196"></a><span class="lineno"> 1196</span>  // a component at a time ...</div><div class="line"><a name="l01197"></a><span class="lineno"> 1197</span>  auto &position = registry.get<position>(entity);</div><div class="line"><a name="l01198"></a><span class="lineno"> 1198</span>  auto &velocity = registry.get<velocity>(entity);</div><div class="line"><a name="l01199"></a><span class="lineno"> 1199</span> </div><div class="line"><a name="l01200"></a><span class="lineno"> 1200</span>  // ... or multiple components at once</div><div class="line"><a name="l01201"></a><span class="lineno"> 1201</span>  auto &[pos, vel] = registry.get<position, velocity>(entity);</div><div class="line"><a name="l01202"></a><span class="lineno"> 1202</span> </div><div class="line"><a name="l01203"></a><span class="lineno"> 1203</span>  // ...</div><div class="line"><a name="l01204"></a><span class="lineno"> 1204</span> }</div><div class="line"><a name="l01205"></a><span class="lineno"> 1205</span> ```</div><div class="line"><a name="l01206"></a><span class="lineno"> 1206</span> </div><div class="line"><a name="l01207"></a><span class="lineno"> 1207</span> Or rely on the `each` member function to iterate entities:</div><div class="line"><a name="l01208"></a><span class="lineno"> 1208</span> </div><div class="line"><a name="l01209"></a><span class="lineno"> 1209</span> ```cpp</div><div class="line"><a name="l01210"></a><span class="lineno"> 1210</span> entt::component types[] = { registry.type<position>(), registry.type<velocity>() };</div><div class="line"><a name="l01211"></a><span class="lineno"> 1211</span> </div><div class="line"><a name="l01212"></a><span class="lineno"> 1212</span> registry.runtime_view(std::cbegin(types), std::cend(types)).each([](auto entity) {</div><div class="line"><a name="l01213"></a><span class="lineno"> 1213</span>  // ...</div><div class="line"><a name="l01214"></a><span class="lineno"> 1214</span> });</div><div class="line"><a name="l01215"></a><span class="lineno"> 1215</span> ```</div><div class="line"><a name="l01216"></a><span class="lineno"> 1216</span> </div><div class="line"><a name="l01217"></a><span class="lineno"> 1217</span> Performance are exactly the same in both cases.</div><div class="line"><a name="l01218"></a><span class="lineno"> 1218</span> </div><div class="line"><a name="l01219"></a><span class="lineno"> 1219</span> **Note**: runtime views are meant for all those cases where users don't know at</div><div class="line"><a name="l01220"></a><span class="lineno"> 1220</span> compile-time what components to use to iterate entities. This is particularly</div><div class="line"><a name="l01221"></a><span class="lineno"> 1221</span> well suited to plugin systems and mods in general. Where possible, don't use</div><div class="line"><a name="l01222"></a><span class="lineno"> 1222</span> runtime views, as their performance are slightly inferior to those of the other</div><div class="line"><a name="l01223"></a><span class="lineno"> 1223</span> views.</div><div class="line"><a name="l01224"></a><span class="lineno"> 1224</span> </div><div class="line"><a name="l01225"></a><span class="lineno"> 1225</span> ## Groups</div><div class="line"><a name="l01226"></a><span class="lineno"> 1226</span> </div><div class="line"><a name="l01227"></a><span class="lineno"> 1227</span> Groups are meant to iterate multiple components at once and offer a (much)</div><div class="line"><a name="l01228"></a><span class="lineno"> 1228</span> faster alternative to views. Roughly speaking, they just play in another league</div><div class="line"><a name="l01229"></a><span class="lineno"> 1229</span> when compared to views.<br/></div><div class="line"><a name="l01230"></a><span class="lineno"> 1230</span> Groups overcome the performance of the other tools available but require to get</div><div class="line"><a name="l01231"></a><span class="lineno"> 1231</span> the ownership of components and this sets some constraints on pools. On the</div><div class="line"><a name="l01232"></a><span class="lineno"> 1232</span> other side, groups aren't an automatism that increases memory consumption,</div><div class="line"><a name="l01233"></a><span class="lineno"> 1233</span> affects functionalities and tries to optimize iterations for all the possible</div><div class="line"><a name="l01234"></a><span class="lineno"> 1234</span> combinations of components. Users can decide when to pay for groups and to what</div><div class="line"><a name="l01235"></a><span class="lineno"> 1235</span> extent.<br/></div><div class="line"><a name="l01236"></a><span class="lineno"> 1236</span> The most interesting aspect of groups is that they fit _usage patterns_. Other</div><div class="line"><a name="l01237"></a><span class="lineno"> 1237</span> solutions around usually try to optimize everything, because it is known that</div><div class="line"><a name="l01238"></a><span class="lineno"> 1238</span> somewhere within the _everything_ there are also our usage patterns. However</div><div class="line"><a name="l01239"></a><span class="lineno"> 1239</span> this has a cost that isn't negligible, both in terms of performance and memory</div><div class="line"><a name="l01240"></a><span class="lineno"> 1240</span> usage. Ironically, users pay the price also for things they don't want and this</div><div class="line"><a name="l01241"></a><span class="lineno"> 1241</span> isn't something I like much. Even worse, one cannot easily disable such a</div><div class="line"><a name="l01242"></a><span class="lineno"> 1242</span> behavior. Groups work differently instead and are designed to optimize only the</div><div class="line"><a name="l01243"></a><span class="lineno"> 1243</span> real use cases when users find they need to.<br/></div><div class="line"><a name="l01244"></a><span class="lineno"> 1244</span> Another nice-to-have feature of groups is that they have no impact on memory</div><div class="line"><a name="l01245"></a><span class="lineno"> 1245</span> consumption, put aside full non-owning groups that are pretty rare and should be</div><div class="line"><a name="l01246"></a><span class="lineno"> 1246</span> avoided as long as possible.</div><div class="line"><a name="l01247"></a><span class="lineno"> 1247</span> </div><div class="line"><a name="l01248"></a><span class="lineno"> 1248</span> All groups affect to an extent the creation and destruction of their components.</div><div class="line"><a name="l01249"></a><span class="lineno"> 1249</span> This is due to the fact that they must _observe_ changes in the pools of</div><div class="line"><a name="l01250"></a><span class="lineno"> 1250</span> interest and arrange data _correctly_ when needed for the types they own.<br/></div><div class="line"><a name="l01251"></a><span class="lineno"> 1251</span> That being said, the way groups operate is beyond the scope of this document.</div><div class="line"><a name="l01252"></a><span class="lineno"> 1252</span> However, it's unlikely that users will be able to appreciate the impact of</div><div class="line"><a name="l01253"></a><span class="lineno"> 1253</span> groups on other functionalities of the registry.</div><div class="line"><a name="l01254"></a><span class="lineno"> 1254</span> </div><div class="line"><a name="l01255"></a><span class="lineno"> 1255</span> Groups offer a bunch of functionalities to get the number of entities they are</div><div class="line"><a name="l01256"></a><span class="lineno"> 1256</span> going to return and a raw access to the entity list as well as to the component</div><div class="line"><a name="l01257"></a><span class="lineno"> 1257</span> list for owned components. It's also possible to ask a group if it contains a</div><div class="line"><a name="l01258"></a><span class="lineno"> 1258</span> given entity.<br/></div><div class="line"><a name="l01259"></a><span class="lineno"> 1259</span> Refer to the inline documentation for all the details.</div><div class="line"><a name="l01260"></a><span class="lineno"> 1260</span> </div><div class="line"><a name="l01261"></a><span class="lineno"> 1261</span> There is no need to store groups around for they are extremely cheap to</div><div class="line"><a name="l01262"></a><span class="lineno"> 1262</span> construct, even though they can be copied without problems and reused freely.</div><div class="line"><a name="l01263"></a><span class="lineno"> 1263</span> A group performs an initialization step the very first time it's requested and</div><div class="line"><a name="l01264"></a><span class="lineno"> 1264</span> this could be quite costly. To avoid it, consider creating the group when no</div><div class="line"><a name="l01265"></a><span class="lineno"> 1265</span> components have been assigned yet. If the registry is empty, preparation is</div><div class="line"><a name="l01266"></a><span class="lineno"> 1266</span> extremely fast. Groups also return newly created and correctly initialized</div><div class="line"><a name="l01267"></a><span class="lineno"> 1267</span> iterators whenever `begin` or `end` are invoked.</div><div class="line"><a name="l01268"></a><span class="lineno"> 1268</span> </div><div class="line"><a name="l01269"></a><span class="lineno"> 1269</span> To iterate groups, either use them in a range-for loop:</div><div class="line"><a name="l01270"></a><span class="lineno"> 1270</span> </div><div class="line"><a name="l01271"></a><span class="lineno"> 1271</span> ```cpp</div><div class="line"><a name="l01272"></a><span class="lineno"> 1272</span> auto group = registry.group<position>(entt::get<velocity>);</div><div class="line"><a name="l01273"></a><span class="lineno"> 1273</span> </div><div class="line"><a name="l01274"></a><span class="lineno"> 1274</span> for(auto entity: group) {</div><div class="line"><a name="l01275"></a><span class="lineno"> 1275</span>  // a component at a time ...</div><div class="line"><a name="l01276"></a><span class="lineno"> 1276</span>  auto &position = group.get<position>(entity);</div><div class="line"><a name="l01277"></a><span class="lineno"> 1277</span>  auto &velocity = group.get<velocity>(entity);</div><div class="line"><a name="l01278"></a><span class="lineno"> 1278</span> </div><div class="line"><a name="l01279"></a><span class="lineno"> 1279</span>  // ... or multiple components at once</div><div class="line"><a name="l01280"></a><span class="lineno"> 1280</span>  auto &[pos, vel] = group.get<position, velocity>(entity);</div><div class="line"><a name="l01281"></a><span class="lineno"> 1281</span> </div><div class="line"><a name="l01282"></a><span class="lineno"> 1282</span>  // ...</div><div class="line"><a name="l01283"></a><span class="lineno"> 1283</span> }</div><div class="line"><a name="l01284"></a><span class="lineno"> 1284</span> ```</div><div class="line"><a name="l01285"></a><span class="lineno"> 1285</span> </div><div class="line"><a name="l01286"></a><span class="lineno"> 1286</span> Or rely on the `each` member function to iterate entities and get all their</div><div class="line"><a name="l01287"></a><span class="lineno"> 1287</span> components at once:</div><div class="line"><a name="l01288"></a><span class="lineno"> 1288</span> </div><div class="line"><a name="l01289"></a><span class="lineno"> 1289</span> ```cpp</div><div class="line"><a name="l01290"></a><span class="lineno"> 1290</span> registry.group<position>(entt::get<velocity>).each([](auto entity, auto &pos, auto &vel) {</div><div class="line"><a name="l01291"></a><span class="lineno"> 1291</span>  // ...</div><div class="line"><a name="l01292"></a><span class="lineno"> 1292</span> });</div><div class="line"><a name="l01293"></a><span class="lineno"> 1293</span> ```</div><div class="line"><a name="l01294"></a><span class="lineno"> 1294</span> </div><div class="line"><a name="l01295"></a><span class="lineno"> 1295</span> The `each` member function is highly optimized. Unless users want to iterate</div><div class="line"><a name="l01296"></a><span class="lineno"> 1296</span> only entities, this should be the preferred approach. Note that the entity can</div><div class="line"><a name="l01297"></a><span class="lineno"> 1297</span> also be excluded from the parameter list if not required and it can improve even</div><div class="line"><a name="l01298"></a><span class="lineno"> 1298</span> further the performance during iterations.</div><div class="line"><a name="l01299"></a><span class="lineno"> 1299</span> </div><div class="line"><a name="l01300"></a><span class="lineno"> 1300</span> **Note**: prefer the `get` member function of a group instead of the `get`</div><div class="line"><a name="l01301"></a><span class="lineno"> 1301</span> member function template of a registry during iterations, if possible. However,</div><div class="line"><a name="l01302"></a><span class="lineno"> 1302</span> keep in mind that it works only with the components of the group itself.</div><div class="line"><a name="l01303"></a><span class="lineno"> 1303</span> </div><div class="line"><a name="l01304"></a><span class="lineno"> 1304</span> Let's go a bit deeper into the different types of groups made available by this</div><div class="line"><a name="l01305"></a><span class="lineno"> 1305</span> library to know how they are constructed and what are the differences between</div><div class="line"><a name="l01306"></a><span class="lineno"> 1306</span> them.</div><div class="line"><a name="l01307"></a><span class="lineno"> 1307</span> </div><div class="line"><a name="l01308"></a><span class="lineno"> 1308</span> ### Full-owning groups</div><div class="line"><a name="l01309"></a><span class="lineno"> 1309</span> </div><div class="line"><a name="l01310"></a><span class="lineno"> 1310</span> A full-owning group is the fastest tool an user can expect to use to iterate</div><div class="line"><a name="l01311"></a><span class="lineno"> 1311</span> multiple components at once. It iterates all the components directly, no</div><div class="line"><a name="l01312"></a><span class="lineno"> 1312</span> indirection required. This type of groups performs more or less as if users are</div><div class="line"><a name="l01313"></a><span class="lineno"> 1313</span> accessing sequentially a bunch of packed arrays of components all sorted</div><div class="line"><a name="l01314"></a><span class="lineno"> 1314</span> identically.</div><div class="line"><a name="l01315"></a><span class="lineno"> 1315</span> </div><div class="line"><a name="l01316"></a><span class="lineno"> 1316</span> A full-owning group is created as:</div><div class="line"><a name="l01317"></a><span class="lineno"> 1317</span> </div><div class="line"><a name="l01318"></a><span class="lineno"> 1318</span> ```cpp</div><div class="line"><a name="l01319"></a><span class="lineno"> 1319</span> auto group = registry.group<position, velocity>();</div><div class="line"><a name="l01320"></a><span class="lineno"> 1320</span> ```</div><div class="line"><a name="l01321"></a><span class="lineno"> 1321</span> </div><div class="line"><a name="l01322"></a><span class="lineno"> 1322</span> Filtering entities by components is also supported:</div><div class="line"><a name="l01323"></a><span class="lineno"> 1323</span> </div><div class="line"><a name="l01324"></a><span class="lineno"> 1324</span> ```cpp</div><div class="line"><a name="l01325"></a><span class="lineno"> 1325</span> auto group = registry.group<position, velocity>(entt::exclude<renderable>);</div><div class="line"><a name="l01326"></a><span class="lineno"> 1326</span> ```</div><div class="line"><a name="l01327"></a><span class="lineno"> 1327</span> </div><div class="line"><a name="l01328"></a><span class="lineno"> 1328</span> Once created, the group gets the ownership of all the components specified in</div><div class="line"><a name="l01329"></a><span class="lineno"> 1329</span> the template parameter list and arranges their pools so as to iterate all of</div><div class="line"><a name="l01330"></a><span class="lineno"> 1330</span> them as fast as possible.</div><div class="line"><a name="l01331"></a><span class="lineno"> 1331</span> </div><div class="line"><a name="l01332"></a><span class="lineno"> 1332</span> Sorting owned components is no longer allowed once the group has been created.</div><div class="line"><a name="l01333"></a><span class="lineno"> 1333</span> However, full-owning groups can be sorted by means of their `sort` member</div><div class="line"><a name="l01334"></a><span class="lineno"> 1334</span> functions, if required. Sorting a full-owning group affects all the instances of</div><div class="line"><a name="l01335"></a><span class="lineno"> 1335</span> the same group (it means that users don't have to call `sort` on each instance</div><div class="line"><a name="l01336"></a><span class="lineno"> 1336</span> to sort all of them because they share the underlying data structure).</div><div class="line"><a name="l01337"></a><span class="lineno"> 1337</span> </div><div class="line"><a name="l01338"></a><span class="lineno"> 1338</span> ### Partial-owning groups</div><div class="line"><a name="l01339"></a><span class="lineno"> 1339</span> </div><div class="line"><a name="l01340"></a><span class="lineno"> 1340</span> A partial-owning group works similarly to a full-owning group for the components</div><div class="line"><a name="l01341"></a><span class="lineno"> 1341</span> it owns, but relies on indirection to get components owned by other groups. This</div><div class="line"><a name="l01342"></a><span class="lineno"> 1342</span> isn't as fast as a full-owning group, but it's already much faster than views</div><div class="line"><a name="l01343"></a><span class="lineno"> 1343</span> when there are only one or two free components to retrieve (the most common</div><div class="line"><a name="l01344"></a><span class="lineno"> 1344</span> cases likely). In the worst case, it's not slower than views anyway.</div><div class="line"><a name="l01345"></a><span class="lineno"> 1345</span> </div><div class="line"><a name="l01346"></a><span class="lineno"> 1346</span> A partial-owning group is created as:</div><div class="line"><a name="l01347"></a><span class="lineno"> 1347</span> </div><div class="line"><a name="l01348"></a><span class="lineno"> 1348</span> ```cpp</div><div class="line"><a name="l01349"></a><span class="lineno"> 1349</span> auto group = registry.group<position>(entt::get<velocity>);</div><div class="line"><a name="l01350"></a><span class="lineno"> 1350</span> ```</div><div class="line"><a name="l01351"></a><span class="lineno"> 1351</span> </div><div class="line"><a name="l01352"></a><span class="lineno"> 1352</span> Filtering entities by components is also supported:</div><div class="line"><a name="l01353"></a><span class="lineno"> 1353</span> </div><div class="line"><a name="l01354"></a><span class="lineno"> 1354</span> ```cpp</div><div class="line"><a name="l01355"></a><span class="lineno"> 1355</span> auto group = registry.group<position>(entt::get<velocity>, entt::exclude<renderable>);</div><div class="line"><a name="l01356"></a><span class="lineno"> 1356</span> ```</div><div class="line"><a name="l01357"></a><span class="lineno"> 1357</span> </div><div class="line"><a name="l01358"></a><span class="lineno"> 1358</span> Once created, the group gets the ownership of all the components specified in</div><div class="line"><a name="l01359"></a><span class="lineno"> 1359</span> the template parameter list and arranges their pools so as to iterate all of</div><div class="line"><a name="l01360"></a><span class="lineno"> 1360</span> them as fast as possible. The ownership of the types provided via `entt::get`</div><div class="line"><a name="l01361"></a><span class="lineno"> 1361</span> doesn't pass to the group instead.</div><div class="line"><a name="l01362"></a><span class="lineno"> 1362</span> </div><div class="line"><a name="l01363"></a><span class="lineno"> 1363</span> Sorting owned components is no longer allowed once the group has been created.</div><div class="line"><a name="l01364"></a><span class="lineno"> 1364</span> However, partial-owning groups can be sorted by means of their `sort` member</div><div class="line"><a name="l01365"></a><span class="lineno"> 1365</span> functions, if required. Sorting a partial-owning group affects all the instances</div><div class="line"><a name="l01366"></a><span class="lineno"> 1366</span> of the same group (it means that users don't have to call `sort` on each</div><div class="line"><a name="l01367"></a><span class="lineno"> 1367</span> instance to sort all of them because they share the underlying data</div><div class="line"><a name="l01368"></a><span class="lineno"> 1368</span> structure).</div><div class="line"><a name="l01369"></a><span class="lineno"> 1369</span> </div><div class="line"><a name="l01370"></a><span class="lineno"> 1370</span> ### Non-owning groups</div><div class="line"><a name="l01371"></a><span class="lineno"> 1371</span> </div><div class="line"><a name="l01372"></a><span class="lineno"> 1372</span> Non-owning groups are usually fast enough, for sure faster than views and well</div><div class="line"><a name="l01373"></a><span class="lineno"> 1373</span> suited for most of the cases. However, they require custom data structures to</div><div class="line"><a name="l01374"></a><span class="lineno"> 1374</span> work properly and they increase memory consumption. As a rule of thumb, users</div><div class="line"><a name="l01375"></a><span class="lineno"> 1375</span> should avoid using non-owning groups, if possible.</div><div class="line"><a name="l01376"></a><span class="lineno"> 1376</span> </div><div class="line"><a name="l01377"></a><span class="lineno"> 1377</span> A non-owning group is created as:</div><div class="line"><a name="l01378"></a><span class="lineno"> 1378</span> </div><div class="line"><a name="l01379"></a><span class="lineno"> 1379</span> ```cpp</div><div class="line"><a name="l01380"></a><span class="lineno"> 1380</span> auto group = registry.group<>(entt::get<position, velocity>);</div><div class="line"><a name="l01381"></a><span class="lineno"> 1381</span> ```</div><div class="line"><a name="l01382"></a><span class="lineno"> 1382</span> </div><div class="line"><a name="l01383"></a><span class="lineno"> 1383</span> Filtering entities by components is also supported:</div><div class="line"><a name="l01384"></a><span class="lineno"> 1384</span> </div><div class="line"><a name="l01385"></a><span class="lineno"> 1385</span> ```cpp</div><div class="line"><a name="l01386"></a><span class="lineno"> 1386</span> auto group = registry.group<>(entt::get<position, velocity>, entt::exclude<renderable>);</div><div class="line"><a name="l01387"></a><span class="lineno"> 1387</span> ```</div><div class="line"><a name="l01388"></a><span class="lineno"> 1388</span> </div><div class="line"><a name="l01389"></a><span class="lineno"> 1389</span> The group doesn't receive the ownership of any type of component in this</div><div class="line"><a name="l01390"></a><span class="lineno"> 1390</span> case. This type of groups is therefore the least performing in general, but also</div><div class="line"><a name="l01391"></a><span class="lineno"> 1391</span> the only one that can be used in any situation to improve a performance where</div><div class="line"><a name="l01392"></a><span class="lineno"> 1392</span> necessary.</div><div class="line"><a name="l01393"></a><span class="lineno"> 1393</span> </div><div class="line"><a name="l01394"></a><span class="lineno"> 1394</span> Non-owning groups can be sorted by means of their `sort` member functions, if</div><div class="line"><a name="l01395"></a><span class="lineno"> 1395</span> required. Sorting a non-owning group affects all the instance of the same group</div><div class="line"><a name="l01396"></a><span class="lineno"> 1396</span> (it means that users don't have to call `sort` on each instance to sort all of</div><div class="line"><a name="l01397"></a><span class="lineno"> 1397</span> them because they share the set of entities).</div><div class="line"><a name="l01398"></a><span class="lineno"> 1398</span> </div><div class="line"><a name="l01399"></a><span class="lineno"> 1399</span> ### Nested groups</div><div class="line"><a name="l01400"></a><span class="lineno"> 1400</span> </div><div class="line"><a name="l01401"></a><span class="lineno"> 1401</span> A type of component cannot be owned by two or more conflicting groups such as:</div><div class="line"><a name="l01402"></a><span class="lineno"> 1402</span> </div><div class="line"><a name="l01403"></a><span class="lineno"> 1403</span> * `registry.group<transform, sprite>()`.</div><div class="line"><a name="l01404"></a><span class="lineno"> 1404</span> * `registry.group<transform, rotation>()`.</div><div class="line"><a name="l01405"></a><span class="lineno"> 1405</span> </div><div class="line"><a name="l01406"></a><span class="lineno"> 1406</span> However, the same type can be owned by groups belonging to the same _family_,</div><div class="line"><a name="l01407"></a><span class="lineno"> 1407</span> also called _nested groups_, such as:</div><div class="line"><a name="l01408"></a><span class="lineno"> 1408</span> </div><div class="line"><a name="l01409"></a><span class="lineno"> 1409</span> * `registry.group<sprite, transform>()`.</div><div class="line"><a name="l01410"></a><span class="lineno"> 1410</span> * `registry.group<sprite, transform, rotation>()`.</div><div class="line"><a name="l01411"></a><span class="lineno"> 1411</span> </div><div class="line"><a name="l01412"></a><span class="lineno"> 1412</span> Fortunately, these are also very common cases if not the most common ones.<br/></div><div class="line"><a name="l01413"></a><span class="lineno"> 1413</span> This allows users to have the highest possible performance on a greater number</div><div class="line"><a name="l01414"></a><span class="lineno"> 1414</span> of component combinations.</div><div class="line"><a name="l01415"></a><span class="lineno"> 1415</span> </div><div class="line"><a name="l01416"></a><span class="lineno"> 1416</span> Two nested groups are such that they own at least one type of component and the</div><div class="line"><a name="l01417"></a><span class="lineno"> 1417</span> list of component types involved by one of them is contained entirely in that of</div><div class="line"><a name="l01418"></a><span class="lineno"> 1418</span> the other. More specifically, this applies independently to all component lists</div><div class="line"><a name="l01419"></a><span class="lineno"> 1419</span> used to define a group.<br/></div><div class="line"><a name="l01420"></a><span class="lineno"> 1420</span> Therefore, the rules for defining whether two or more groups are nested can be</div><div class="line"><a name="l01421"></a><span class="lineno"> 1421</span> summarized as:</div><div class="line"><a name="l01422"></a><span class="lineno"> 1422</span> </div><div class="line"><a name="l01423"></a><span class="lineno"> 1423</span> * One of the groups involves one or more additional component types with respect</div><div class="line"><a name="l01424"></a><span class="lineno"> 1424</span>  to the other, whether they are owned, observed or excluded.</div><div class="line"><a name="l01425"></a><span class="lineno"> 1425</span> </div><div class="line"><a name="l01426"></a><span class="lineno"> 1426</span> * The list of component types owned by the most restrictive group is the same or</div><div class="line"><a name="l01427"></a><span class="lineno"> 1427</span>  contains entirely that of the others. This also applies to the list of</div><div class="line"><a name="l01428"></a><span class="lineno"> 1428</span>  observed and excluded components.</div><div class="line"><a name="l01429"></a><span class="lineno"> 1429</span> </div><div class="line"><a name="l01430"></a><span class="lineno"> 1430</span> It means that more nested groups _extend_ the their parents by adding more</div><div class="line"><a name="l01431"></a><span class="lineno"> 1431</span> conditions in the form of new components.</div><div class="line"><a name="l01432"></a><span class="lineno"> 1432</span> </div><div class="line"><a name="l01433"></a><span class="lineno"> 1433</span> As mentioned, the components don't necessarily have to be all _owned_ so that</div><div class="line"><a name="l01434"></a><span class="lineno"> 1434</span> two groups can be considered nested. In other words, the following definitions</div><div class="line"><a name="l01435"></a><span class="lineno"> 1435</span> are fully valid:</div><div class="line"><a name="l01436"></a><span class="lineno"> 1436</span> </div><div class="line"><a name="l01437"></a><span class="lineno"> 1437</span> * `registry.group<sprite>(entt::get<renderable>)`.</div><div class="line"><a name="l01438"></a><span class="lineno"> 1438</span> * `registry.group<sprite, transform>(entt::get<renderable>)`.</div><div class="line"><a name="l01439"></a><span class="lineno"> 1439</span> * `registry.group<sprite, transform>(entt::get<renderable, rotation>)`.</div><div class="line"><a name="l01440"></a><span class="lineno"> 1440</span> </div><div class="line"><a name="l01441"></a><span class="lineno"> 1441</span> Exclusion lists also play their part in this respect. When it comes to defining</div><div class="line"><a name="l01442"></a><span class="lineno"> 1442</span> nested groups, an excluded type of component `T` is treated as being an observed</div><div class="line"><a name="l01443"></a><span class="lineno"> 1443</span> type `not_T`. Therefore, these two definitions:</div><div class="line"><a name="l01444"></a><span class="lineno"> 1444</span> </div><div class="line"><a name="l01445"></a><span class="lineno"> 1445</span> * `registry.group<sprite, transform>()`.</div><div class="line"><a name="l01446"></a><span class="lineno"> 1446</span> * `registry.group<sprite, transform>(entt::exclude<rotation>)`.</div><div class="line"><a name="l01447"></a><span class="lineno"> 1447</span> </div><div class="line"><a name="l01448"></a><span class="lineno"> 1448</span> Are treated as if users were defining the following groups:</div><div class="line"><a name="l01449"></a><span class="lineno"> 1449</span> </div><div class="line"><a name="l01450"></a><span class="lineno"> 1450</span> * `group<sprite, transform>()`.</div><div class="line"><a name="l01451"></a><span class="lineno"> 1451</span> * `group<sprite, transform>(entt::get<not_rotation>)`.</div><div class="line"><a name="l01452"></a><span class="lineno"> 1452</span> </div><div class="line"><a name="l01453"></a><span class="lineno"> 1453</span> Where `not_rotation` is an empty tag present only when `rotation` is not.</div><div class="line"><a name="l01454"></a><span class="lineno"> 1454</span> </div><div class="line"><a name="l01455"></a><span class="lineno"> 1455</span> Because of this, to define a new group that is more restrictive than an existing</div><div class="line"><a name="l01456"></a><span class="lineno"> 1456</span> one, it's enough to take the list of component types of the latter and extend it</div><div class="line"><a name="l01457"></a><span class="lineno"> 1457</span> by adding new component types either owned, observed or excluded, without any</div><div class="line"><a name="l01458"></a><span class="lineno"> 1458</span> precautions depending on the case.<br/></div><div class="line"><a name="l01459"></a><span class="lineno"> 1459</span> The opposite is also true. To define a _larger_ group, it will be enough to take</div><div class="line"><a name="l01460"></a><span class="lineno"> 1460</span> an existing one and remove _constraints_ from it, in whatever form they are</div><div class="line"><a name="l01461"></a><span class="lineno"> 1461</span> expressed.<br/></div><div class="line"><a name="l01462"></a><span class="lineno"> 1462</span> Note that the greater the number of component types involved by a group, the</div><div class="line"><a name="l01463"></a><span class="lineno"> 1463</span> more restrictive it is.</div><div class="line"><a name="l01464"></a><span class="lineno"> 1464</span> </div><div class="line"><a name="l01465"></a><span class="lineno"> 1465</span> Despite the extreme flexibility of nested groups, which allow to independently</div><div class="line"><a name="l01466"></a><span class="lineno"> 1466</span> use component types either owned, observed or excluded, the real strength of</div><div class="line"><a name="l01467"></a><span class="lineno"> 1467</span> this tool lies in the possibility of defining a greater number of groups that</div><div class="line"><a name="l01468"></a><span class="lineno"> 1468</span> **own** the same components, thus offering the best performance in more</div><div class="line"><a name="l01469"></a><span class="lineno"> 1469</span> cases.<br/></div><div class="line"><a name="l01470"></a><span class="lineno"> 1470</span> In fact, given a list of component types involved by a group, the greater the</div><div class="line"><a name="l01471"></a><span class="lineno"> 1471</span> number of those owned, the greater the performance of the group itself.</div><div class="line"><a name="l01472"></a><span class="lineno"> 1472</span> </div><div class="line"><a name="l01473"></a><span class="lineno"> 1473</span> As a side note, it's no longer possible to sort all groups when defining nested</div><div class="line"><a name="l01474"></a><span class="lineno"> 1474</span> ones. This is because the most restrictive groups share the elements with the</div><div class="line"><a name="l01475"></a><span class="lineno"> 1475</span> less restrictive ones and ordering the latter would invalidate the former.<br/></div><div class="line"><a name="l01476"></a><span class="lineno"> 1476</span> However, given a family of nested groups, it's still possible to sort the most</div><div class="line"><a name="l01477"></a><span class="lineno"> 1477</span> restrictive of them. To prevent users from having to remember which of their</div><div class="line"><a name="l01478"></a><span class="lineno"> 1478</span> groups is the most restrictive, they offer the `sortable` member function to</div><div class="line"><a name="l01479"></a><span class="lineno"> 1479</span> know if their items can be sorted or not.</div><div class="line"><a name="l01480"></a><span class="lineno"> 1480</span> </div><div class="line"><a name="l01481"></a><span class="lineno"> 1481</span> ## Types: const, non-const and all in between</div><div class="line"><a name="l01482"></a><span class="lineno"> 1482</span> </div><div class="line"><a name="l01483"></a><span class="lineno"> 1483</span> The `registry` class offers two overloads when it comes to constructing views</div><div class="line"><a name="l01484"></a><span class="lineno"> 1484</span> and groups: a const version and a non-const one. The former accepts both const</div><div class="line"><a name="l01485"></a><span class="lineno"> 1485</span> and non-const types as template parameters, the latter accepts only const types</div><div class="line"><a name="l01486"></a><span class="lineno"> 1486</span> instead.<br/></div><div class="line"><a name="l01487"></a><span class="lineno"> 1487</span> It means that views and groups can be constructed also from a const registry and</div><div class="line"><a name="l01488"></a><span class="lineno"> 1488</span> they propagate the constness of the registry to the types involved. As an</div><div class="line"><a name="l01489"></a><span class="lineno"> 1489</span> example:</div><div class="line"><a name="l01490"></a><span class="lineno"> 1490</span> </div><div class="line"><a name="l01491"></a><span class="lineno"> 1491</span> ```cpp</div><div class="line"><a name="l01492"></a><span class="lineno"> 1492</span> entt::view<const position, const velocity> view = std::as_const(registry).view<const position, const velocity>();</div><div class="line"><a name="l01493"></a><span class="lineno"> 1493</span> ```</div><div class="line"><a name="l01494"></a><span class="lineno"> 1494</span> </div><div class="line"><a name="l01495"></a><span class="lineno"> 1495</span> Consider the following definition for a non-const view instead:</div><div class="line"><a name="l01496"></a><span class="lineno"> 1496</span> </div><div class="line"><a name="l01497"></a><span class="lineno"> 1497</span> ```cpp</div><div class="line"><a name="l01498"></a><span class="lineno"> 1498</span> entt::view<position, const velocity> view = registry.view<position, const velocity>();</div><div class="line"><a name="l01499"></a><span class="lineno"> 1499</span> ```</div><div class="line"><a name="l01500"></a><span class="lineno"> 1500</span> </div><div class="line"><a name="l01501"></a><span class="lineno"> 1501</span> In the example above, `view` can be used to access either read-only or writable</div><div class="line"><a name="l01502"></a><span class="lineno"> 1502</span> `position` components while `velocity` components are read-only in all</div><div class="line"><a name="l01503"></a><span class="lineno"> 1503</span> cases.<br/></div><div class="line"><a name="l01504"></a><span class="lineno"> 1504</span> In other terms, these statements are all valid:</div><div class="line"><a name="l01505"></a><span class="lineno"> 1505</span> </div><div class="line"><a name="l01506"></a><span class="lineno"> 1506</span> ```cpp</div><div class="line"><a name="l01507"></a><span class="lineno"> 1507</span> position &pos = view.get<position>(entity);</div><div class="line"><a name="l01508"></a><span class="lineno"> 1508</span> const position &cpos = view.get<const position>(entity);</div><div class="line"><a name="l01509"></a><span class="lineno"> 1509</span> const velocity &cpos = view.get<const velocity>(entity);</div><div class="line"><a name="l01510"></a><span class="lineno"> 1510</span> std::tuple<position &, const velocity &> tup = view.get<position, const velocity>(entity);</div><div class="line"><a name="l01511"></a><span class="lineno"> 1511</span> std::tuple<const position &, const velocity &> ctup = view.get<const position, const velocity>(entity);</div><div class="line"><a name="l01512"></a><span class="lineno"> 1512</span> ```</div><div class="line"><a name="l01513"></a><span class="lineno"> 1513</span> </div><div class="line"><a name="l01514"></a><span class="lineno"> 1514</span> It's not possible to get non-const references to `velocity` components from the</div><div class="line"><a name="l01515"></a><span class="lineno"> 1515</span> same view instead and these will result in compilation errors:</div><div class="line"><a name="l01516"></a><span class="lineno"> 1516</span> </div><div class="line"><a name="l01517"></a><span class="lineno"> 1517</span> ```cpp</div><div class="line"><a name="l01518"></a><span class="lineno"> 1518</span> velocity &cpos = view.get<velocity>(entity);</div><div class="line"><a name="l01519"></a><span class="lineno"> 1519</span> std::tuple<position &, velocity &> tup = view.get<position, velocity>(entity);</div><div class="line"><a name="l01520"></a><span class="lineno"> 1520</span> std::tuple<const position &, velocity &> ctup = view.get<const position, velocity>(entity);</div><div class="line"><a name="l01521"></a><span class="lineno"> 1521</span> ```</div><div class="line"><a name="l01522"></a><span class="lineno"> 1522</span> </div><div class="line"><a name="l01523"></a><span class="lineno"> 1523</span> Similarly, the `each` member functions will propagate constness to the type of</div><div class="line"><a name="l01524"></a><span class="lineno"> 1524</span> the components returned during iterations:</div><div class="line"><a name="l01525"></a><span class="lineno"> 1525</span> </div><div class="line"><a name="l01526"></a><span class="lineno"> 1526</span> ```cpp</div><div class="line"><a name="l01527"></a><span class="lineno"> 1527</span> view.each([](auto entity, position &pos, const velocity &vel) {</div><div class="line"><a name="l01528"></a><span class="lineno"> 1528</span>  // ...</div><div class="line"><a name="l01529"></a><span class="lineno"> 1529</span> });</div><div class="line"><a name="l01530"></a><span class="lineno"> 1530</span> ```</div><div class="line"><a name="l01531"></a><span class="lineno"> 1531</span> </div><div class="line"><a name="l01532"></a><span class="lineno"> 1532</span> Obviously, a caller can still refer to the `position` components through a const</div><div class="line"><a name="l01533"></a><span class="lineno"> 1533</span> reference because of the rules of the language that fortunately already allow</div><div class="line"><a name="l01534"></a><span class="lineno"> 1534</span> it.</div><div class="line"><a name="l01535"></a><span class="lineno"> 1535</span> </div><div class="line"><a name="l01536"></a><span class="lineno"> 1536</span> The same concepts apply to groups as well.</div><div class="line"><a name="l01537"></a><span class="lineno"> 1537</span> </div><div class="line"><a name="l01538"></a><span class="lineno"> 1538</span> ## Give me everything</div><div class="line"><a name="l01539"></a><span class="lineno"> 1539</span> </div><div class="line"><a name="l01540"></a><span class="lineno"> 1540</span> Views and groups are narrow windows on the entire list of entities. They work by</div><div class="line"><a name="l01541"></a><span class="lineno"> 1541</span> filtering entities according to their components.<br/></div><div class="line"><a name="l01542"></a><span class="lineno"> 1542</span> In some cases there may be the need to iterate all the entities still in use</div><div class="line"><a name="l01543"></a><span class="lineno"> 1543</span> regardless of their components. The registry offers a specific member function</div><div class="line"><a name="l01544"></a><span class="lineno"> 1544</span> to do that:</div><div class="line"><a name="l01545"></a><span class="lineno"> 1545</span> </div><div class="line"><a name="l01546"></a><span class="lineno"> 1546</span> ```cpp</div><div class="line"><a name="l01547"></a><span class="lineno"> 1547</span> registry.each([](auto entity) {</div><div class="line"><a name="l01548"></a><span class="lineno"> 1548</span>  // ...</div><div class="line"><a name="l01549"></a><span class="lineno"> 1549</span> });</div><div class="line"><a name="l01550"></a><span class="lineno"> 1550</span> ```</div><div class="line"><a name="l01551"></a><span class="lineno"> 1551</span> </div><div class="line"><a name="l01552"></a><span class="lineno"> 1552</span> It returns to the caller all the entities that are still in use by means of the</div><div class="line"><a name="l01553"></a><span class="lineno"> 1553</span> given function.<br/></div><div class="line"><a name="l01554"></a><span class="lineno"> 1554</span> As a rule of thumb, consider using a view or a group if the goal is to iterate</div><div class="line"><a name="l01555"></a><span class="lineno"> 1555</span> entities that have a determinate set of components. These tools are usually much</div><div class="line"><a name="l01556"></a><span class="lineno"> 1556</span> faster than combining this function with a bunch of custom tests.<br/></div><div class="line"><a name="l01557"></a><span class="lineno"> 1557</span> In all the other cases, this is the way to go.</div><div class="line"><a name="l01558"></a><span class="lineno"> 1558</span> </div><div class="line"><a name="l01559"></a><span class="lineno"> 1559</span> There exists also another member function to use to retrieve orphans. An orphan</div><div class="line"><a name="l01560"></a><span class="lineno"> 1560</span> is an entity that is still in use and has no assigned components.<br/></div><div class="line"><a name="l01561"></a><span class="lineno"> 1561</span> The signature of the function is the same of `each`:</div><div class="line"><a name="l01562"></a><span class="lineno"> 1562</span> </div><div class="line"><a name="l01563"></a><span class="lineno"> 1563</span> ```cpp</div><div class="line"><a name="l01564"></a><span class="lineno"> 1564</span> registry.orphans([](auto entity) {</div><div class="line"><a name="l01565"></a><span class="lineno"> 1565</span>  // ...</div><div class="line"><a name="l01566"></a><span class="lineno"> 1566</span> });</div><div class="line"><a name="l01567"></a><span class="lineno"> 1567</span> ```</div><div class="line"><a name="l01568"></a><span class="lineno"> 1568</span> </div><div class="line"><a name="l01569"></a><span class="lineno"> 1569</span> To test the _orphanity_ of a single entity, use the member function `orphan`</div><div class="line"><a name="l01570"></a><span class="lineno"> 1570</span> instead. It accepts a valid entity identifer as an argument and returns true in</div><div class="line"><a name="l01571"></a><span class="lineno"> 1571</span> case the entity is an orphan, false otherwise.</div><div class="line"><a name="l01572"></a><span class="lineno"> 1572</span> </div><div class="line"><a name="l01573"></a><span class="lineno"> 1573</span> In general, all these functions can result in poor performance.<br/></div><div class="line"><a name="l01574"></a><span class="lineno"> 1574</span> `each` is fairly slow because of some checks it performs on each and every</div><div class="line"><a name="l01575"></a><span class="lineno"> 1575</span> entity. For similar reasons, `orphans` can be even slower. Both functions should</div><div class="line"><a name="l01576"></a><span class="lineno"> 1576</span> not be used frequently to avoid the risk of a performance hit.</div><div class="line"><a name="l01577"></a><span class="lineno"> 1577</span> </div><div class="line"><a name="l01578"></a><span class="lineno"> 1578</span> ## What is allowed and what is not</div><div class="line"><a name="l01579"></a><span class="lineno"> 1579</span> </div><div class="line"><a name="l01580"></a><span class="lineno"> 1580</span> Most of the _ECS_ available out there don't allow to create and destroy entities</div><div class="line"><a name="l01581"></a><span class="lineno"> 1581</span> and components during iterations.<br/></div><div class="line"><a name="l01582"></a><span class="lineno"> 1582</span> `EnTT` partially solves the problem with a few limitations:</div><div class="line"><a name="l01583"></a><span class="lineno"> 1583</span> </div><div class="line"><a name="l01584"></a><span class="lineno"> 1584</span> * Creating entities and components is allowed during iterations in almost all</div><div class="line"><a name="l01585"></a><span class="lineno"> 1585</span>  cases.</div><div class="line"><a name="l01586"></a><span class="lineno"> 1586</span> </div><div class="line"><a name="l01587"></a><span class="lineno"> 1587</span> * Deleting the current entity or removing its components is allowed during</div><div class="line"><a name="l01588"></a><span class="lineno"> 1588</span>  iterations. For all the other entities, destroying them or removing their</div><div class="line"><a name="l01589"></a><span class="lineno"> 1589</span>  components isn't allowed and can result in undefined behavior.</div><div class="line"><a name="l01590"></a><span class="lineno"> 1590</span> </div><div class="line"><a name="l01591"></a><span class="lineno"> 1591</span> In these cases, iterators aren't invalidated. To be clear, it doesn't mean that</div><div class="line"><a name="l01592"></a><span class="lineno"> 1592</span> also references will continue to be valid.<br/></div><div class="line"><a name="l01593"></a><span class="lineno"> 1593</span> Consider the following example:</div><div class="line"><a name="l01594"></a><span class="lineno"> 1594</span> </div><div class="line"><a name="l01595"></a><span class="lineno"> 1595</span> ```cpp</div><div class="line"><a name="l01596"></a><span class="lineno"> 1596</span> registry.view<position>([&](const auto entity, auto &pos) {</div><div class="line"><a name="l01597"></a><span class="lineno"> 1597</span>  registry.assign<position>(registry.create(), 0., 0.);</div><div class="line"><a name="l01598"></a><span class="lineno"> 1598</span>  pos.x = 0.; // warning: dangling pointer</div><div class="line"><a name="l01599"></a><span class="lineno"> 1599</span> });</div><div class="line"><a name="l01600"></a><span class="lineno"> 1600</span> ```</div><div class="line"><a name="l01601"></a><span class="lineno"> 1601</span> </div><div class="line"><a name="l01602"></a><span class="lineno"> 1602</span> The `each` member function won't break (because iterators aren't invalidated)</div><div class="line"><a name="l01603"></a><span class="lineno"> 1603</span> but there are no guarantees on references. Use a common range-for loop and get</div><div class="line"><a name="l01604"></a><span class="lineno"> 1604</span> components directly from the view or move the creation of components at the end</div><div class="line"><a name="l01605"></a><span class="lineno"> 1605</span> of the function to avoid dangling pointers.</div><div class="line"><a name="l01606"></a><span class="lineno"> 1606</span> </div><div class="line"><a name="l01607"></a><span class="lineno"> 1607</span> Iterators are invalidated instead and the behavior is undefined if an entity is</div><div class="line"><a name="l01608"></a><span class="lineno"> 1608</span> modified or destroyed and it's not the one currently returned by the iterator</div><div class="line"><a name="l01609"></a><span class="lineno"> 1609</span> nor a newly created one.<br/></div><div class="line"><a name="l01610"></a><span class="lineno"> 1610</span> To work around it, possible approaches are:</div><div class="line"><a name="l01611"></a><span class="lineno"> 1611</span> </div><div class="line"><a name="l01612"></a><span class="lineno"> 1612</span> * Store aside the entities and the components to be removed and perform the</div><div class="line"><a name="l01613"></a><span class="lineno"> 1613</span>  operations at the end of the iteration.</div><div class="line"><a name="l01614"></a><span class="lineno"> 1614</span> </div><div class="line"><a name="l01615"></a><span class="lineno"> 1615</span> * Mark entities and components with a proper tag component that indicates they</div><div class="line"><a name="l01616"></a><span class="lineno"> 1616</span>  must be purged, then perform a second iteration to clean them up one by one.</div><div class="line"><a name="l01617"></a><span class="lineno"> 1617</span> </div><div class="line"><a name="l01618"></a><span class="lineno"> 1618</span> A notable side effect of this feature is that the number of required allocations</div><div class="line"><a name="l01619"></a><span class="lineno"> 1619</span> is further reduced in most of the cases.</div><div class="line"><a name="l01620"></a><span class="lineno"> 1620</span> </div><div class="line"><a name="l01621"></a><span class="lineno"> 1621</span> ### More performance, more constraints</div><div class="line"><a name="l01622"></a><span class="lineno"> 1622</span> </div><div class="line"><a name="l01623"></a><span class="lineno"> 1623</span> Groups are a (much) faster alternative to views. However, the higher the</div><div class="line"><a name="l01624"></a><span class="lineno"> 1624</span> performance, the greater the constraints on what is allowed and what is</div><div class="line"><a name="l01625"></a><span class="lineno"> 1625</span> not.<br/></div><div class="line"><a name="l01626"></a><span class="lineno"> 1626</span> In particular, groups add in some rare cases a limitation on the creation of</div><div class="line"><a name="l01627"></a><span class="lineno"> 1627</span> components during iterations. It happens in quite particular cases. Given the</div><div class="line"><a name="l01628"></a><span class="lineno"> 1628</span> nature and the scope of the groups, it isn't something in which it will happen</div><div class="line"><a name="l01629"></a><span class="lineno"> 1629</span> to come across probably, but it's good to know it anyway.</div><div class="line"><a name="l01630"></a><span class="lineno"> 1630</span> </div><div class="line"><a name="l01631"></a><span class="lineno"> 1631</span> First of all, it must be said that creating components while iterating a group</div><div class="line"><a name="l01632"></a><span class="lineno"> 1632</span> isn't a problem at all and can be done freely as it happens with the views. The</div><div class="line"><a name="l01633"></a><span class="lineno"> 1633</span> same applies to the destruction of components and entities, for which the rules</div><div class="line"><a name="l01634"></a><span class="lineno"> 1634</span> mentioned above apply.</div><div class="line"><a name="l01635"></a><span class="lineno"> 1635</span> </div><div class="line"><a name="l01636"></a><span class="lineno"> 1636</span> The additional limitation pops out instead when a given component that is owned</div><div class="line"><a name="l01637"></a><span class="lineno"> 1637</span> by a group is iterated outside of it. In this case, adding components that are</div><div class="line"><a name="l01638"></a><span class="lineno"> 1638</span> part of the group itself may invalidate the iterators. There are no further</div><div class="line"><a name="l01639"></a><span class="lineno"> 1639</span> limitations to the destruction of components and entities.<br/></div><div class="line"><a name="l01640"></a><span class="lineno"> 1640</span> Fortunately, this isn't always true. In fact, it almost never is and this</div><div class="line"><a name="l01641"></a><span class="lineno"> 1641</span> happens only under certain conditions. In particular:</div><div class="line"><a name="l01642"></a><span class="lineno"> 1642</span> </div><div class="line"><a name="l01643"></a><span class="lineno"> 1643</span> * Iterating a type of component that is part of a group with a single component</div><div class="line"><a name="l01644"></a><span class="lineno"> 1644</span>  view and adding to an entity all the components required to get it into the</div><div class="line"><a name="l01645"></a><span class="lineno"> 1645</span>  group may invalidate the iterators.</div><div class="line"><a name="l01646"></a><span class="lineno"> 1646</span> </div><div class="line"><a name="l01647"></a><span class="lineno"> 1647</span> * Iterating a type of component that is part of a group with a multi component</div><div class="line"><a name="l01648"></a><span class="lineno"> 1648</span>  view and adding to an entity all the components required to get it into the</div><div class="line"><a name="l01649"></a><span class="lineno"> 1649</span>  group can invalidate the iterators, unless users specify another type of</div><div class="line"><a name="l01650"></a><span class="lineno"> 1650</span>  component to use to induce the order of iteration of the view (in this case,</div><div class="line"><a name="l01651"></a><span class="lineno"> 1651</span>  the former is treated as a free type and isn't affected by the limitation).</div><div class="line"><a name="l01652"></a><span class="lineno"> 1652</span> </div><div class="line"><a name="l01653"></a><span class="lineno"> 1653</span> In other words, the limitation doesn't exist as long as a type is treated as a</div><div class="line"><a name="l01654"></a><span class="lineno"> 1654</span> free type (as an example with multi component views and partial- or non-owning</div><div class="line"><a name="l01655"></a><span class="lineno"> 1655</span> groups) or iterated with its own group, but it can occur if the type is used as</div><div class="line"><a name="l01656"></a><span class="lineno"> 1656</span> a main type to rule on an iteration.<br/></div><div class="line"><a name="l01657"></a><span class="lineno"> 1657</span> This happens because groups own the pools of their components and organize the</div><div class="line"><a name="l01658"></a><span class="lineno"> 1658</span> data internally to maximize performance. Because of that, full consistency for</div><div class="line"><a name="l01659"></a><span class="lineno"> 1659</span> owned components is guaranteed only when they are iterated as part of their</div><div class="line"><a name="l01660"></a><span class="lineno"> 1660</span> groups or as free types with multi component views and groups in general.</div><div class="line"><a name="l01661"></a><span class="lineno"> 1661</span> </div><div class="line"><a name="l01662"></a><span class="lineno"> 1662</span> # Empty type optimization</div><div class="line"><a name="l01663"></a><span class="lineno"> 1663</span> </div><div class="line"><a name="l01664"></a><span class="lineno"> 1664</span> An empty type `T` is such that `std::is_empty_v<T>` returns true. They are also</div><div class="line"><a name="l01665"></a><span class="lineno"> 1665</span> the same types for which _empty base optimization_ (EBO) is possibile.<br/></div><div class="line"><a name="l01666"></a><span class="lineno"> 1666</span> `EnTT` handles these types in a special way, optimizing both in terms of</div><div class="line"><a name="l01667"></a><span class="lineno"> 1667</span> performance and memory usage. However, this also has consequences that are worth</div><div class="line"><a name="l01668"></a><span class="lineno"> 1668</span> mentioning.</div><div class="line"><a name="l01669"></a><span class="lineno"> 1669</span> </div><div class="line"><a name="l01670"></a><span class="lineno"> 1670</span> When an empty type is detected, it's not instantiated in any case. Therefore,</div><div class="line"><a name="l01671"></a><span class="lineno"> 1671</span> only the entities to which it's assigned are made available. All the iterators</div><div class="line"><a name="l01672"></a><span class="lineno"> 1672</span> as well as the `get` member functions of the registry, the views and the groups</div><div class="line"><a name="l01673"></a><span class="lineno"> 1673</span> will return temporary objects. Similarly, some functions such as `try_get` or</div><div class="line"><a name="l01674"></a><span class="lineno"> 1674</span> the raw access to the list of components aren't available for this kind of</div><div class="line"><a name="l01675"></a><span class="lineno"> 1675</span> types.<br/></div><div class="line"><a name="l01676"></a><span class="lineno"> 1676</span> On the other hand, iterations are faster because only the entities to which the</div><div class="line"><a name="l01677"></a><span class="lineno"> 1677</span> type is assigned are considered. Moreover, less memory is used, since there</div><div class="line"><a name="l01678"></a><span class="lineno"> 1678</span> doesn't exist any instance of the component, no matter how many entities it is</div><div class="line"><a name="l01679"></a><span class="lineno"> 1679</span> assigned to.</div><div class="line"><a name="l01680"></a><span class="lineno"> 1680</span> </div><div class="line"><a name="l01681"></a><span class="lineno"> 1681</span> For similar reasons, wherever a function type of a listener accepts a component,</div><div class="line"><a name="l01682"></a><span class="lineno"> 1682</span> it cannot be caught by a non-const reference. Capture it by copy or by const</div><div class="line"><a name="l01683"></a><span class="lineno"> 1683</span> reference instead.</div><div class="line"><a name="l01684"></a><span class="lineno"> 1684</span> </div><div class="line"><a name="l01685"></a><span class="lineno"> 1685</span> More in general, none of the features offered by the library is affected, but</div><div class="line"><a name="l01686"></a><span class="lineno"> 1686</span> for the ones that require to return actual instances.<br/></div><div class="line"><a name="l01687"></a><span class="lineno"> 1687</span> This optimization can be disabled by defining the `ENTT_DISABLE_ETO` macro. In</div><div class="line"><a name="l01688"></a><span class="lineno"> 1688</span> this case, the empty types will be treated like all other types, no matter what.</div><div class="line"><a name="l01689"></a><span class="lineno"> 1689</span> </div><div class="line"><a name="l01690"></a><span class="lineno"> 1690</span> # Multithreading</div><div class="line"><a name="l01691"></a><span class="lineno"> 1691</span> </div><div class="line"><a name="l01692"></a><span class="lineno"> 1692</span> In general, the entire registry isn't thread safe as it is. Thread safety isn't</div><div class="line"><a name="l01693"></a><span class="lineno"> 1693</span> something that users should want out of the box for several reasons. Just to</div><div class="line"><a name="l01694"></a><span class="lineno"> 1694</span> mention one of them: performance.<br/></div><div class="line"><a name="l01695"></a><span class="lineno"> 1695</span> Views, groups and consequently the approach adopted by `EnTT` are the great</div><div class="line"><a name="l01696"></a><span class="lineno"> 1696</span> exception to the rule. It's true that views, groups and iterators in general</div><div class="line"><a name="l01697"></a><span class="lineno"> 1697</span> aren't thread safe by themselves. Because of this users shouldn't try to iterate</div><div class="line"><a name="l01698"></a><span class="lineno"> 1698</span> a set of components and modify the same set concurrently. However:</div><div class="line"><a name="l01699"></a><span class="lineno"> 1699</span> </div><div class="line"><a name="l01700"></a><span class="lineno"> 1700</span> * As long as a thread iterates the entities that have the component `X` or</div><div class="line"><a name="l01701"></a><span class="lineno"> 1701</span>  assign and removes that component from a set of entities, another thread can</div><div class="line"><a name="l01702"></a><span class="lineno"> 1702</span>  safely do the same with components `Y` and `Z` and everything will work like a</div><div class="line"><a name="l01703"></a><span class="lineno"> 1703</span>  charm. As a trivial example, users can freely execute the rendering system and</div><div class="line"><a name="l01704"></a><span class="lineno"> 1704</span>  iterate the renderable entities while updating a physic component concurrently</div><div class="line"><a name="l01705"></a><span class="lineno"> 1705</span>  on a separate thread.</div><div class="line"><a name="l01706"></a><span class="lineno"> 1706</span> </div><div class="line"><a name="l01707"></a><span class="lineno"> 1707</span> * Similarly, a single set of components can be iterated by multiple threads as</div><div class="line"><a name="l01708"></a><span class="lineno"> 1708</span>  long as the components are neither assigned nor removed in the meantime. In</div><div class="line"><a name="l01709"></a><span class="lineno"> 1709</span>  other words, a hypothetical movement system can start multiple threads, each</div><div class="line"><a name="l01710"></a><span class="lineno"> 1710</span>  of which will access the components that carry information about velocity and</div><div class="line"><a name="l01711"></a><span class="lineno"> 1711</span>  position for its entities.</div><div class="line"><a name="l01712"></a><span class="lineno"> 1712</span> </div><div class="line"><a name="l01713"></a><span class="lineno"> 1713</span> This kind of entity-component systems can be used in single threaded</div><div class="line"><a name="l01714"></a><span class="lineno"> 1714</span> applications as well as along with async stuff or multiple threads. Moreover,</div><div class="line"><a name="l01715"></a><span class="lineno"> 1715</span> typical thread based models for _ECS_ don't require a fully thread safe registry</div><div class="line"><a name="l01716"></a><span class="lineno"> 1716</span> to work. Actually, users can reach the goal with the registry as it is while</div><div class="line"><a name="l01717"></a><span class="lineno"> 1717</span> working with most of the common models.</div><div class="line"><a name="l01718"></a><span class="lineno"> 1718</span> </div><div class="line"><a name="l01719"></a><span class="lineno"> 1719</span> Because of the few reasons mentioned above and many others not mentioned, users</div><div class="line"><a name="l01720"></a><span class="lineno"> 1720</span> are completely responsible for synchronization whether required. On the other</div><div class="line"><a name="l01721"></a><span class="lineno"> 1721</span> hand, they could get away with it without having to resort to particular</div><div class="line"><a name="l01722"></a><span class="lineno"> 1722</span> expedients.</div><div class="line"><a name="l01723"></a><span class="lineno"> 1723</span> </div><div class="line"><a name="l01724"></a><span class="lineno"> 1724</span> ## Iterators</div><div class="line"><a name="l01725"></a><span class="lineno"> 1725</span> </div><div class="line"><a name="l01726"></a><span class="lineno"> 1726</span> A special mention is needed for the iterators returned by the views and the</div><div class="line"><a name="l01727"></a><span class="lineno"> 1727</span> groups. Most of the time they meet the requirements of random access iterators,</div><div class="line"><a name="l01728"></a><span class="lineno"> 1728</span> in all cases they meet at least the requirements of forward iterators.<br/></div><div class="line"><a name="l01729"></a><span class="lineno"> 1729</span> In other terms, they are suitable for use with the parallel algorithms of the</div><div class="line"><a name="l01730"></a><span class="lineno"> 1730</span> standard library. If it's not clear, this is a great thing.</div><div class="line"><a name="l01731"></a><span class="lineno"> 1731</span> </div><div class="line"><a name="l01732"></a><span class="lineno"> 1732</span> As an example, this kind of iterators can be used in combination with</div><div class="line"><a name="l01733"></a><span class="lineno"> 1733</span> `std::for_each` and `std::execution::par` to parallelize the visit and therefore</div><div class="line"><a name="l01734"></a><span class="lineno"> 1734</span> the update of the components returned by a view or a group, as long as the</div><div class="line"><a name="l01735"></a><span class="lineno"> 1735</span> constraints previously discussed are respected:</div><div class="line"><a name="l01736"></a><span class="lineno"> 1736</span> </div><div class="line"><a name="l01737"></a><span class="lineno"> 1737</span> ```cpp</div><div class="line"><a name="l01738"></a><span class="lineno"> 1738</span> auto view = registry.view<position, const velocity>();</div><div class="line"><a name="l01739"></a><span class="lineno"> 1739</span> </div><div class="line"><a name="l01740"></a><span class="lineno"> 1740</span> std::for_each(std::execution::par_unseq, view.begin(), view.end(), [&view](auto entity) {</div><div class="line"><a name="l01741"></a><span class="lineno"> 1741</span>  // ...</div><div class="line"><a name="l01742"></a><span class="lineno"> 1742</span> });</div><div class="line"><a name="l01743"></a><span class="lineno"> 1743</span> ```</div><div class="line"><a name="l01744"></a><span class="lineno"> 1744</span> </div><div class="line"><a name="l01745"></a><span class="lineno"> 1745</span> This can increase the throughput considerably, even without resorting to who</div><div class="line"><a name="l01746"></a><span class="lineno"> 1746</span> knows what artifacts that are difficult to maintain over time.</div><div class="line"><a name="l01747"></a><span class="lineno"> 1747</span> </div><div class="line"><a name="l01748"></a><span class="lineno"> 1748</span> Unfortunately, because of the limitations of the current revision of the</div><div class="line"><a name="l01749"></a><span class="lineno"> 1749</span> standard, the parallel `std::for_each` accepts only forward iterators. This</div><div class="line"><a name="l01750"></a><span class="lineno"> 1750</span> means that the iterators provided by the library cannot return proxy objects as</div><div class="line"><a name="l01751"></a><span class="lineno"> 1751</span> references and **must** return actual reference types instead.<br/></div><div class="line"><a name="l01752"></a><span class="lineno"> 1752</span> This may change in the future and the iterators will almost certainly return</div><div class="line"><a name="l01753"></a><span class="lineno"> 1753</span> both the entities and a list of references to their components sooner or later.</div><div class="line"><a name="l01754"></a><span class="lineno"> 1754</span> Multi-pass guarantee won't break in any case and the performance should even</div><div class="line"><a name="l01755"></a><span class="lineno"> 1755</span> benefit from it further.</div><div class="line"><a name="l01756"></a><span class="lineno"> 1756</span> </div><div class="line"><a name="l01757"></a><span class="lineno"> 1757</span> # Beyond this document</div><div class="line"><a name="l01758"></a><span class="lineno"> 1758</span> </div><div class="line"><a name="l01759"></a><span class="lineno"> 1759</span> There are many other features and functions not listed in this document.<br/></div><div class="line"><a name="l01760"></a><span class="lineno"> 1760</span> `EnTT` and in particular its ECS part is in continuous development and some</div><div class="line"><a name="l01761"></a><span class="lineno"> 1761</span> things could be forgotten, others could have been omitted on purpose to reduce</div><div class="line"><a name="l01762"></a><span class="lineno"> 1762</span> the size of this file. Unfortunately, some parts may even be outdated and still</div><div class="line"><a name="l01763"></a><span class="lineno"> 1763</span> to be updated.</div><div class="line"><a name="l01764"></a><span class="lineno"> 1764</span> </div><div class="line"><a name="l01765"></a><span class="lineno"> 1765</span> For further information, it's recommended to refer to the documentation included</div><div class="line"><a name="l01766"></a><span class="lineno"> 1766</span> in the code itself or join the official channels to ask a question.</div></div><!-- fragment --></div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.13
|
|
</small></address>
|
|
</body>
|
|
</html>
|