75 lines
315 KiB
HTML
75 lines
315 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: README.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">2.6.1</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">README.md</div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="fragment"><div class="line"><a name="l00001"></a><span class="lineno"> 1</span> # EnTT Framework</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> [](https://travis-ci.org/skypjack/entt)</div><div class="line"><a name="l00004"></a><span class="lineno"> 4</span> [](https://ci.appveyor.com/project/skypjack/entt)</div><div class="line"><a name="l00005"></a><span class="lineno"> 5</span> [](https://coveralls.io/github/skypjack/entt?branch=master)</div><div class="line"><a name="l00006"></a><span class="lineno"> 6</span> [](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)</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> # Table of Contents</div><div class="line"><a name="l00009"></a><span class="lineno"> 9</span> </div><div class="line"><a name="l00010"></a><span class="lineno"> 10</span> * [Introduction](#introduction)</div><div class="line"><a name="l00011"></a><span class="lineno"> 11</span> * [Build Instructions](#build-instructions)</div><div class="line"><a name="l00012"></a><span class="lineno"> 12</span> * [Crash Course: entity-component system](#crash-course-entity-component-system)</div><div class="line"><a name="l00013"></a><span class="lineno"> 13</span>  * [Design choices](#design-choices)</div><div class="line"><a name="l00014"></a><span class="lineno"> 14</span>  * [A bitset-free entity-component system](#a-bitset-free-entity-component-system)</div><div class="line"><a name="l00015"></a><span class="lineno"> 15</span>  * [Pay per use](#pay-per-use)</div><div class="line"><a name="l00016"></a><span class="lineno"> 16</span>  * [Vademecum](#vademecum)</div><div class="line"><a name="l00017"></a><span class="lineno"> 17</span>  * [The Registry, the Entity and the Component](#the-registry-the-entity-and-the-component)</div><div class="line"><a name="l00018"></a><span class="lineno"> 18</span>  * [Single instance components](#single-instance-components)</div><div class="line"><a name="l00019"></a><span class="lineno"> 19</span>  * [Observe changes](#observe-changes)</div><div class="line"><a name="l00020"></a><span class="lineno"> 20</span>  * [Who let the tags out?](#who-let-the-tags-out)</div><div class="line"><a name="l00021"></a><span class="lineno"> 21</span>  * [Runtime components](#runtime-components)</div><div class="line"><a name="l00022"></a><span class="lineno"> 22</span>  * [A journey through a plugin](#a-journey-through-a-plugin)</div><div class="line"><a name="l00023"></a><span class="lineno"> 23</span>  * [Sorting: is it possible?](#sorting-is-it-possible)</div><div class="line"><a name="l00024"></a><span class="lineno"> 24</span>  * [Snapshot: complete vs continuous](#snapshot-complete-vs-continuous)</div><div class="line"><a name="l00025"></a><span class="lineno"> 25</span>  * [Snapshot loader](#snapshot-loader)</div><div class="line"><a name="l00026"></a><span class="lineno"> 26</span>  * [Continuous loader](#continuous-loader)</div><div class="line"><a name="l00027"></a><span class="lineno"> 27</span>  * [Archives](#archives)</div><div class="line"><a name="l00028"></a><span class="lineno"> 28</span>  * [One example to rule them all](#one-example-to-rule-them-all)</div><div class="line"><a name="l00029"></a><span class="lineno"> 29</span>  * [Prototype](#prototype)</div><div class="line"><a name="l00030"></a><span class="lineno"> 30</span>  * [Helpers](#helpers)</div><div class="line"><a name="l00031"></a><span class="lineno"> 31</span>  * [Dependency function](#dependency-function)</div><div class="line"><a name="l00032"></a><span class="lineno"> 32</span>  * [View: to persist or not to persist?](#view-to-persist-or-not-to-persist)</div><div class="line"><a name="l00033"></a><span class="lineno"> 33</span>  * [Standard View](#standard-view)</div><div class="line"><a name="l00034"></a><span class="lineno"> 34</span>  * [Single component standard view](#single-component-standard-view)</div><div class="line"><a name="l00035"></a><span class="lineno"> 35</span>  * [Multi component standard view](#multi-component-standard-view)</div><div class="line"><a name="l00036"></a><span class="lineno"> 36</span>  * [Persistent View](#persistent-view)</div><div class="line"><a name="l00037"></a><span class="lineno"> 37</span>  * [Raw View](#raw-view)</div><div class="line"><a name="l00038"></a><span class="lineno"> 38</span>  * [Give me everything](#give-me-everything)</div><div class="line"><a name="l00039"></a><span class="lineno"> 39</span>  * [Side notes](#side-notes)</div><div class="line"><a name="l00040"></a><span class="lineno"> 40</span> * [Crash Course: core functionalities](#crash-course-core-functionalities)</div><div class="line"><a name="l00041"></a><span class="lineno"> 41</span>  * [Compile-time identifiers](#compile-time-identifiers)</div><div class="line"><a name="l00042"></a><span class="lineno"> 42</span>  * [Runtime identifiers](#runtime-identifiers)</div><div class="line"><a name="l00043"></a><span class="lineno"> 43</span>  * [Hashed strings](#hashed-strings)</div><div class="line"><a name="l00044"></a><span class="lineno"> 44</span> * [Crash Course: service locator](#crash-course-service-locator)</div><div class="line"><a name="l00045"></a><span class="lineno"> 45</span> * [Crash Course: cooperative scheduler](#crash-course-cooperative-scheduler)</div><div class="line"><a name="l00046"></a><span class="lineno"> 46</span>  * [The process](#the-process)</div><div class="line"><a name="l00047"></a><span class="lineno"> 47</span>  * [The scheduler](#the-scheduler)</div><div class="line"><a name="l00048"></a><span class="lineno"> 48</span> * [Crash Course: resource management](#crash-course-resource-management)</div><div class="line"><a name="l00049"></a><span class="lineno"> 49</span>  * [The resource, the loader and the cache](#the-resource-the-loader-and-the-cache)</div><div class="line"><a name="l00050"></a><span class="lineno"> 50</span> * [Crash Course: events, signals and everything in between](#crash-course-events-signals-and-everything-in-between)</div><div class="line"><a name="l00051"></a><span class="lineno"> 51</span>  * [Signals](#signals)</div><div class="line"><a name="l00052"></a><span class="lineno"> 52</span>  * [Delegate](#delegate)</div><div class="line"><a name="l00053"></a><span class="lineno"> 53</span>  * [Event dispatcher](#event-dispatcher)</div><div class="line"><a name="l00054"></a><span class="lineno"> 54</span>  * [Event emitter](#event-emitter)</div><div class="line"><a name="l00055"></a><span class="lineno"> 55</span> * [Packaging Tools](#packaging-tools)</div><div class="line"><a name="l00056"></a><span class="lineno"> 56</span> * [EnTT in Action](#entt-in-action)</div><div class="line"><a name="l00057"></a><span class="lineno"> 57</span> * [License](#license)</div><div class="line"><a name="l00058"></a><span class="lineno"> 58</span> * [Support](#support)</div><div class="line"><a name="l00059"></a><span class="lineno"> 59</span>  * [Donation](#donation)</div><div class="line"><a name="l00060"></a><span class="lineno"> 60</span>  * [Hire me](#hire-me)</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> # Introduction</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` is a header-only, tiny and easy to use framework written in modern</div><div class="line"><a name="l00065"></a><span class="lineno"> 65</span> C++.<br/></div><div class="line"><a name="l00066"></a><span class="lineno"> 66</span> It was originally designed entirely around an architectural pattern called _ECS_</div><div class="line"><a name="l00067"></a><span class="lineno"> 67</span> that is used mostly in game development. For further details:</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> * [Entity Systems Wiki](http://entity-systems.wikidot.com/)</div><div class="line"><a name="l00070"></a><span class="lineno"> 70</span> * [Evolve Your Hierarchy](http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/)</div><div class="line"><a name="l00071"></a><span class="lineno"> 71</span> * [ECS on Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system)</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> A long time ago, the sole entity-component system was part of the project. After</div><div class="line"><a name="l00074"></a><span class="lineno"> 74</span> a while the codebase has grown and more and more classes have become part of the</div><div class="line"><a name="l00075"></a><span class="lineno"> 75</span> repository.<br/></div><div class="line"><a name="l00076"></a><span class="lineno"> 76</span> That's why today it's called _the EnTT Framework_.</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> Currently, `EnTT` is tested on Linux, Microsoft Windows and OS X. It has proven</div><div class="line"><a name="l00079"></a><span class="lineno"> 79</span> to work also on both Android and iOS.<br/></div><div class="line"><a name="l00080"></a><span class="lineno"> 80</span> Most likely it will not be problematic on other systems as well, but has not</div><div class="line"><a name="l00081"></a><span class="lineno"> 81</span> been sufficiently tested so far.</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> ## The framework</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` was written initially as a faster alternative to other well known and</div><div class="line"><a name="l00086"></a><span class="lineno"> 86</span> open source entity-component systems. Nowadays the `EnTT` framework is moving</div><div class="line"><a name="l00087"></a><span class="lineno"> 87</span> its first steps. Much more will come in the future and hopefully I'm going to</div><div class="line"><a name="l00088"></a><span class="lineno"> 88</span> work on it for a long time.<br/></div><div class="line"><a name="l00089"></a><span class="lineno"> 89</span> Requests for feature, PR, suggestions ad feedback are highly appreciated.</div><div class="line"><a name="l00090"></a><span class="lineno"> 90</span> </div><div class="line"><a name="l00091"></a><span class="lineno"> 91</span> If you find you can help me and want to contribute to the `EnTT` framework with</div><div class="line"><a name="l00092"></a><span class="lineno"> 92</span> your experience or you do want to get part of the project for some other</div><div class="line"><a name="l00093"></a><span class="lineno"> 93</span> reasons, feel free to contact me directly (you can find the mail in the</div><div class="line"><a name="l00094"></a><span class="lineno"> 94</span> [profile](https://github.com/skypjack)).<br/></div><div class="line"><a name="l00095"></a><span class="lineno"> 95</span> I can't promise that each and every contribution will be accepted, but I can</div><div class="line"><a name="l00096"></a><span class="lineno"> 96</span> assure that I'll do my best to take them all seriously.</div><div class="line"><a name="l00097"></a><span class="lineno"> 97</span> </div><div class="line"><a name="l00098"></a><span class="lineno"> 98</span> ### State of the art</div><div class="line"><a name="l00099"></a><span class="lineno"> 99</span> </div><div class="line"><a name="l00100"></a><span class="lineno"> 100</span> Here is a brief list of what it offers today:</div><div class="line"><a name="l00101"></a><span class="lineno"> 101</span> </div><div class="line"><a name="l00102"></a><span class="lineno"> 102</span> * Statically generated integer identifiers for types (assigned either at</div><div class="line"><a name="l00103"></a><span class="lineno"> 103</span>  compile-time or at runtime).</div><div class="line"><a name="l00104"></a><span class="lineno"> 104</span> * A constexpr utility for human readable resource identifiers.</div><div class="line"><a name="l00105"></a><span class="lineno"> 105</span> * An incredibly fast entity-component system based on sparse sets, with its own</div><div class="line"><a name="l00106"></a><span class="lineno"> 106</span>  views and a _pay for what you use_ policy to adjust performance and memory</div><div class="line"><a name="l00107"></a><span class="lineno"> 107</span>  usage according to users' requirements.</div><div class="line"><a name="l00108"></a><span class="lineno"> 108</span> * Actor class for those who aren't confident with entity-component systems.</div><div class="line"><a name="l00109"></a><span class="lineno"> 109</span> * The smallest and most basic implementation of a service locator ever seen.</div><div class="line"><a name="l00110"></a><span class="lineno"> 110</span> * A cooperative scheduler for processes of any type.</div><div class="line"><a name="l00111"></a><span class="lineno"> 111</span> * All what is needed for resource management (cache, loaders, handles).</div><div class="line"><a name="l00112"></a><span class="lineno"> 112</span> * Delegates, signal handlers (with built-in support for collectors) and a tiny</div><div class="line"><a name="l00113"></a><span class="lineno"> 113</span>  event dispatcher.</div><div class="line"><a name="l00114"></a><span class="lineno"> 114</span> * A general purpose event emitter, that is a CRTP idiom based class template.</div><div class="line"><a name="l00115"></a><span class="lineno"> 115</span> * An event dispatcher for immediate and delayed events to integrate in loops.</div><div class="line"><a name="l00116"></a><span class="lineno"> 116</span> * ...</div><div class="line"><a name="l00117"></a><span class="lineno"> 117</span> * Any other business.</div><div class="line"><a name="l00118"></a><span class="lineno"> 118</span> </div><div class="line"><a name="l00119"></a><span class="lineno"> 119</span> Consider it a work in progress. For more details and an updated list, please</div><div class="line"><a name="l00120"></a><span class="lineno"> 120</span> refer to the [online documentation](https://skypjack.github.io/entt/). It</div><div class="line"><a name="l00121"></a><span class="lineno"> 121</span> probably contains much more. Moreover, the whole API is fully documented in-code</div><div class="line"><a name="l00122"></a><span class="lineno"> 122</span> for those who are brave enough to read it.<br/></div><div class="line"><a name="l00123"></a><span class="lineno"> 123</span> Continue reading to know how the different parts of the project work or follow</div><div class="line"><a name="l00124"></a><span class="lineno"> 124</span> the link above to take a look at the API reference.</div><div class="line"><a name="l00125"></a><span class="lineno"> 125</span> </div><div class="line"><a name="l00126"></a><span class="lineno"> 126</span> ## Code Example</div><div class="line"><a name="l00127"></a><span class="lineno"> 127</span> </div><div class="line"><a name="l00128"></a><span class="lineno"> 128</span> ```cpp</div><div class="line"><a name="l00129"></a><span class="lineno"> 129</span> #include <entt/entt.hpp></div><div class="line"><a name="l00130"></a><span class="lineno"> 130</span> #include <cstdint></div><div class="line"><a name="l00131"></a><span class="lineno"> 131</span> </div><div class="line"><a name="l00132"></a><span class="lineno"> 132</span> struct Position {</div><div class="line"><a name="l00133"></a><span class="lineno"> 133</span>  float x;</div><div class="line"><a name="l00134"></a><span class="lineno"> 134</span>  float y;</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> </div><div class="line"><a name="l00137"></a><span class="lineno"> 137</span> struct Velocity {</div><div class="line"><a name="l00138"></a><span class="lineno"> 138</span>  float dx;</div><div class="line"><a name="l00139"></a><span class="lineno"> 139</span>  float dy;</div><div class="line"><a name="l00140"></a><span class="lineno"> 140</span> };</div><div class="line"><a name="l00141"></a><span class="lineno"> 141</span> </div><div class="line"><a name="l00142"></a><span class="lineno"> 142</span> void update(entt::DefaultRegistry &registry) {</div><div class="line"><a name="l00143"></a><span class="lineno"> 143</span>  auto view = registry.view<Position, Velocity>();</div><div class="line"><a name="l00144"></a><span class="lineno"> 144</span> </div><div class="line"><a name="l00145"></a><span class="lineno"> 145</span>  for(auto entity: view) {</div><div class="line"><a name="l00146"></a><span class="lineno"> 146</span>  // gets only the components that are going to be used ...</div><div class="line"><a name="l00147"></a><span class="lineno"> 147</span> </div><div class="line"><a name="l00148"></a><span class="lineno"> 148</span>  auto &velocity = view.get<Velocity>(entity);</div><div class="line"><a name="l00149"></a><span class="lineno"> 149</span> </div><div class="line"><a name="l00150"></a><span class="lineno"> 150</span>  velocity.dx = 0.;</div><div class="line"><a name="l00151"></a><span class="lineno"> 151</span>  velocity.dy = 0.;</div><div class="line"><a name="l00152"></a><span class="lineno"> 152</span> </div><div class="line"><a name="l00153"></a><span class="lineno"> 153</span>  // ...</div><div class="line"><a name="l00154"></a><span class="lineno"> 154</span>  }</div><div class="line"><a name="l00155"></a><span class="lineno"> 155</span> }</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> void update(std::uint64_t dt, entt::DefaultRegistry &registry) {</div><div class="line"><a name="l00158"></a><span class="lineno"> 158</span>  registry.view<Position, Velocity>().each([dt](auto entity, auto &position, auto &velocity) {</div><div class="line"><a name="l00159"></a><span class="lineno"> 159</span>  // gets all the components of the view at once ...</div><div class="line"><a name="l00160"></a><span class="lineno"> 160</span> </div><div class="line"><a name="l00161"></a><span class="lineno"> 161</span>  position.x += velocity.dx * dt;</div><div class="line"><a name="l00162"></a><span class="lineno"> 162</span>  position.y += velocity.dy * dt;</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>  // ...</div><div class="line"><a name="l00165"></a><span class="lineno"> 165</span>  });</div><div class="line"><a name="l00166"></a><span class="lineno"> 166</span> }</div><div class="line"><a name="l00167"></a><span class="lineno"> 167</span> </div><div class="line"><a name="l00168"></a><span class="lineno"> 168</span> int main() {</div><div class="line"><a name="l00169"></a><span class="lineno"> 169</span>  entt::DefaultRegistry registry;</div><div class="line"><a name="l00170"></a><span class="lineno"> 170</span>  std::uint64_t dt = 16;</div><div class="line"><a name="l00171"></a><span class="lineno"> 171</span> </div><div class="line"><a name="l00172"></a><span class="lineno"> 172</span>  for(auto i = 0; i < 10; ++i) {</div><div class="line"><a name="l00173"></a><span class="lineno"> 173</span>  auto entity = registry.create();</div><div class="line"><a name="l00174"></a><span class="lineno"> 174</span>  registry.assign<Position>(entity, i * 1.f, i * 1.f);</div><div class="line"><a name="l00175"></a><span class="lineno"> 175</span>  if(i % 2 == 0) { registry.assign<Velocity>(entity, i * .1f, i * .1f); }</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> </div><div class="line"><a name="l00178"></a><span class="lineno"> 178</span>  update(dt, registry);</div><div class="line"><a name="l00179"></a><span class="lineno"> 179</span>  update(registry);</div><div class="line"><a name="l00180"></a><span class="lineno"> 180</span> </div><div class="line"><a name="l00181"></a><span class="lineno"> 181</span>  // ...</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> ```</div><div class="line"><a name="l00184"></a><span class="lineno"> 184</span> </div><div class="line"><a name="l00185"></a><span class="lineno"> 185</span> ## Motivation</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> I started working on `EnTT` because of the wrong reason: my goal was to design</div><div class="line"><a name="l00188"></a><span class="lineno"> 188</span> an entity-component system that beated another well known open source solution</div><div class="line"><a name="l00189"></a><span class="lineno"> 189</span> in terms of performance and used (possibly) less memory in the average</div><div class="line"><a name="l00190"></a><span class="lineno"> 190</span> case.<br/></div><div class="line"><a name="l00191"></a><span class="lineno"> 191</span> In the end, I did it, but it wasn't much satisfying. Actually it wasn't</div><div class="line"><a name="l00192"></a><span class="lineno"> 192</span> satisfying at all. The fastest and nothing more, fairly little indeed. When I</div><div class="line"><a name="l00193"></a><span class="lineno"> 193</span> realized it, I tried hard to keep intact the great performance of `EnTT` and to</div><div class="line"><a name="l00194"></a><span class="lineno"> 194</span> add all the features I wanted to see in *my own library* at the same time.</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> Today `EnTT` is finally what I was looking for: still faster than its</div><div class="line"><a name="l00197"></a><span class="lineno"> 197</span> _competitors_, lower memory usage in the average case, a really good API and an</div><div class="line"><a name="l00198"></a><span class="lineno"> 198</span> amazing set of features. And even more, of course.</div><div class="line"><a name="l00199"></a><span class="lineno"> 199</span> </div><div class="line"><a name="l00200"></a><span class="lineno"> 200</span> ## Performance</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> As it stands right now, `EnTT` is just fast enough for my requirements if</div><div class="line"><a name="l00203"></a><span class="lineno"> 203</span> compared to my first choice (it was already amazingly fast actually).<br/></div><div class="line"><a name="l00204"></a><span class="lineno"> 204</span> Below is a comparison between the two (both of them compiled with GCC 7.3.0 on a</div><div class="line"><a name="l00205"></a><span class="lineno"> 205</span> Dell XPS 13 out of the mid 2014):</div><div class="line"><a name="l00206"></a><span class="lineno"> 206</span> </div><div class="line"><a name="l00207"></a><span class="lineno"> 207</span> | Benchmark | EntityX (compile-time) | EnTT |</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> | Create 1M entities | 0.0147s | **0.0046s** |</div><div class="line"><a name="l00210"></a><span class="lineno"> 210</span> | Destroy 1M entities | 0.0053s | **0.0045s** |</div><div class="line"><a name="l00211"></a><span class="lineno"> 211</span> | Standard view, 1M entities, one component | 0.0012s | **1.9e-07s** |</div><div class="line"><a name="l00212"></a><span class="lineno"> 212</span> | Standard view, 1M entities, two components | 0.0012s | **3.8e-07s** |</div><div class="line"><a name="l00213"></a><span class="lineno"> 213</span> | Standard view, 1M entities, two components<br/>Half of the entities have all the components | 0.0009s | **3.8e-07s** |</div><div class="line"><a name="l00214"></a><span class="lineno"> 214</span> | Standard view, 1M entities, two components<br/>One of the entities has all the components | 0.0008s | **1.0e-06s** |</div><div class="line"><a name="l00215"></a><span class="lineno"> 215</span> | Persistent view, 1M entities, two components | 0.0012s | **2.8e-07s** |</div><div class="line"><a name="l00216"></a><span class="lineno"> 216</span> | Standard view, 1M entities, five components | 0.0010s | **7.0e-07s** |</div><div class="line"><a name="l00217"></a><span class="lineno"> 217</span> | Persistent view, 1M entities, five components | 0.0010s | **2.8e-07s** |</div><div class="line"><a name="l00218"></a><span class="lineno"> 218</span> | Standard view, 1M entities, ten components | 0.0011s | **1.2e-06s** |</div><div class="line"><a name="l00219"></a><span class="lineno"> 219</span> | Standard view, 1M entities, ten components<br/>Half of the entities have all the components | 0.0010s | **1.2e-06s** |</div><div class="line"><a name="l00220"></a><span class="lineno"> 220</span> | Standard view, 1M entities, ten components<br/>One of the entities has all the components | 0.0008s | **1.2e-06s** |</div><div class="line"><a name="l00221"></a><span class="lineno"> 221</span> | Persistent view, 1M entities, ten components | 0.0011s | **3.0e-07s** |</div><div class="line"><a name="l00222"></a><span class="lineno"> 222</span> | Raw view, 1M entities | - | **2.2e-07s** |</div><div class="line"><a name="l00223"></a><span class="lineno"> 223</span> | Sort 150k entities, one component<br/>Arrays are in reverse order | - | **0.0036s** |</div><div class="line"><a name="l00224"></a><span class="lineno"> 224</span> | Sort 150k entities, enforce permutation<br/>Arrays are in reverse order | - | **0.0005s** |</div><div class="line"><a name="l00225"></a><span class="lineno"> 225</span> | Sort 150k entities, one component<br/>Arrays are almost sorted, std::sort | - | **0.0035s** |</div><div class="line"><a name="l00226"></a><span class="lineno"> 226</span> | Sort 150k entities, one component<br/>Arrays are almost sorted, insertion sort | - | **0.0007s** |</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> Note: The default version of `EntityX` (`master` branch) wasn't added to the</div><div class="line"><a name="l00229"></a><span class="lineno"> 229</span> comparison because it's already much slower than its compile-time counterpart.</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> Pretty interesting, aren't them? In fact, these benchmarks are the same used by</div><div class="line"><a name="l00232"></a><span class="lineno"> 232</span> `EntityX` to show _how fast it is_. To be honest, they aren't so good and these</div><div class="line"><a name="l00233"></a><span class="lineno"> 233</span> results shouldn't be taken much seriously (they are completely unrealistic</div><div class="line"><a name="l00234"></a><span class="lineno"> 234</span> indeed).<br/></div><div class="line"><a name="l00235"></a><span class="lineno"> 235</span> The proposed entity-component system is incredibly fast to iterate entities,</div><div class="line"><a name="l00236"></a><span class="lineno"> 236</span> this is a fact. The compiler can make a lot of optimizations because of how</div><div class="line"><a name="l00237"></a><span class="lineno"> 237</span> `EnTT` works, even more when components aren't used at all. This is exactly the</div><div class="line"><a name="l00238"></a><span class="lineno"> 238</span> case for these benchmarks. On the other hand and if we consider real world</div><div class="line"><a name="l00239"></a><span class="lineno"> 239</span> cases, `EnTT` is in the middle between a bit and much faster than the other</div><div class="line"><a name="l00240"></a><span class="lineno"> 240</span> solutions around when users also access the components and not just the</div><div class="line"><a name="l00241"></a><span class="lineno"> 241</span> entities, although it is not as fast as reported by these benchmarks.<br/></div><div class="line"><a name="l00242"></a><span class="lineno"> 242</span> This is why they are completely wrong and cannot be used to evaluate any of the</div><div class="line"><a name="l00243"></a><span class="lineno"> 243</span> entity-component systems.</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> If you decide to use `EnTT`, choose it because of its API, features and</div><div class="line"><a name="l00246"></a><span class="lineno"> 246</span> performance, not because there is a benchmark somewhere that makes it seem the</div><div class="line"><a name="l00247"></a><span class="lineno"> 247</span> fastest.</div><div class="line"><a name="l00248"></a><span class="lineno"> 248</span> </div><div class="line"><a name="l00249"></a><span class="lineno"> 249</span> Probably I'll try to get out of `EnTT` more features and even better performance</div><div class="line"><a name="l00250"></a><span class="lineno"> 250</span> in the future, mainly for fun.<br/></div><div class="line"><a name="l00251"></a><span class="lineno"> 251</span> If you want to contribute and/or have any suggestion, feel free to make a PR or</div><div class="line"><a name="l00252"></a><span class="lineno"> 252</span> open an issue to discuss your idea.</div><div class="line"><a name="l00253"></a><span class="lineno"> 253</span> </div><div class="line"><a name="l00254"></a><span class="lineno"> 254</span> # Build Instructions</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> ## Requirements</div><div class="line"><a name="l00257"></a><span class="lineno"> 257</span> </div><div class="line"><a name="l00258"></a><span class="lineno"> 258</span> To be able to use `EnTT`, users must provide a full-featured compiler that</div><div class="line"><a name="l00259"></a><span class="lineno"> 259</span> supports at least C++14.<br/></div><div class="line"><a name="l00260"></a><span class="lineno"> 260</span> The requirements below are mandatory to compile the tests and to extract the</div><div class="line"><a name="l00261"></a><span class="lineno"> 261</span> documentation:</div><div class="line"><a name="l00262"></a><span class="lineno"> 262</span> </div><div class="line"><a name="l00263"></a><span class="lineno"> 263</span> * CMake version 3.2 or later.</div><div class="line"><a name="l00264"></a><span class="lineno"> 264</span> * Doxygen version 1.8 or later.</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> ## Library</div><div class="line"><a name="l00267"></a><span class="lineno"> 267</span> </div><div class="line"><a name="l00268"></a><span class="lineno"> 268</span> `EnTT` is a header-only library. This means that including the `entt.hpp`</div><div class="line"><a name="l00269"></a><span class="lineno"> 269</span> header is enough to include the whole framework and use it. For those who are</div><div class="line"><a name="l00270"></a><span class="lineno"> 270</span> interested only in the entity-component system, consider to include the sole</div><div class="line"><a name="l00271"></a><span class="lineno"> 271</span> `entity/registry.hpp` header instead.<br/></div><div class="line"><a name="l00272"></a><span class="lineno"> 272</span> It's a matter of adding the following line to the top of a file:</div><div class="line"><a name="l00273"></a><span class="lineno"> 273</span> </div><div class="line"><a name="l00274"></a><span class="lineno"> 274</span> ```cpp</div><div class="line"><a name="l00275"></a><span class="lineno"> 275</span> #include <entt/entt.hpp></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> </div><div class="line"><a name="l00278"></a><span class="lineno"> 278</span> Use the line below to include only the entity-component system instead:</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> #include <entt/entity/registry.hpp></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> Then pass the proper `-I` argument to the compiler to add the `src` directory to</div><div class="line"><a name="l00285"></a><span class="lineno"> 285</span> the include paths.</div><div class="line"><a name="l00286"></a><span class="lineno"> 286</span> </div><div class="line"><a name="l00287"></a><span class="lineno"> 287</span> ## Documentation</div><div class="line"><a name="l00288"></a><span class="lineno"> 288</span> </div><div class="line"><a name="l00289"></a><span class="lineno"> 289</span> The documentation is based on [doxygen](http://www.stack.nl/~dimitri/doxygen/).</div><div class="line"><a name="l00290"></a><span class="lineno"> 290</span> To build it:</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>  $ cd build</div><div class="line"><a name="l00293"></a><span class="lineno"> 293</span>  $ cmake ..</div><div class="line"><a name="l00294"></a><span class="lineno"> 294</span>  $ make docs</div><div class="line"><a name="l00295"></a><span class="lineno"> 295</span> </div><div class="line"><a name="l00296"></a><span class="lineno"> 296</span> The API reference will be created in HTML format within the directory</div><div class="line"><a name="l00297"></a><span class="lineno"> 297</span> `build/docs/html`. To navigate it with your favorite browser:</div><div class="line"><a name="l00298"></a><span class="lineno"> 298</span> </div><div class="line"><a name="l00299"></a><span class="lineno"> 299</span>  $ cd build</div><div class="line"><a name="l00300"></a><span class="lineno"> 300</span>  $ your_favorite_browser docs/html/index.html</div><div class="line"><a name="l00301"></a><span class="lineno"> 301</span> </div><div class="line"><a name="l00302"></a><span class="lineno"> 302</span> The API reference is also available [online](https://skypjack.github.io/entt/)</div><div class="line"><a name="l00303"></a><span class="lineno"> 303</span> for the latest version.</div><div class="line"><a name="l00304"></a><span class="lineno"> 304</span> </div><div class="line"><a name="l00305"></a><span class="lineno"> 305</span> ## Tests</div><div class="line"><a name="l00306"></a><span class="lineno"> 306</span> </div><div class="line"><a name="l00307"></a><span class="lineno"> 307</span> To compile and run the tests, `EnTT` requires *googletest*.<br/></div><div class="line"><a name="l00308"></a><span class="lineno"> 308</span> `cmake` will download and compile the library before to compile anything else.</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> To build the most basic set of tests:</div><div class="line"><a name="l00311"></a><span class="lineno"> 311</span> </div><div class="line"><a name="l00312"></a><span class="lineno"> 312</span> * `$ cd build`</div><div class="line"><a name="l00313"></a><span class="lineno"> 313</span> * `$ cmake ..`</div><div class="line"><a name="l00314"></a><span class="lineno"> 314</span> * `$ make`</div><div class="line"><a name="l00315"></a><span class="lineno"> 315</span> * `$ make test`</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> Note that benchmarks are not part of this set.</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> # Crash Course: entity-component system</div><div class="line"><a name="l00320"></a><span class="lineno"> 320</span> </div><div class="line"><a name="l00321"></a><span class="lineno"> 321</span> ## Design choices</div><div class="line"><a name="l00322"></a><span class="lineno"> 322</span> </div><div class="line"><a name="l00323"></a><span class="lineno"> 323</span> ### A bitset-free entity-component system</div><div class="line"><a name="l00324"></a><span class="lineno"> 324</span> </div><div class="line"><a name="l00325"></a><span class="lineno"> 325</span> `EnTT` is a _bitset-free_ entity-component system that doesn't require users to</div><div class="line"><a name="l00326"></a><span class="lineno"> 326</span> specify the component set at compile-time.<br/></div><div class="line"><a name="l00327"></a><span class="lineno"> 327</span> This is why users can instantiate the core class simply like:</div><div class="line"><a name="l00328"></a><span class="lineno"> 328</span> </div><div class="line"><a name="l00329"></a><span class="lineno"> 329</span> ```cpp</div><div class="line"><a name="l00330"></a><span class="lineno"> 330</span> entt::DefaultRegistry registry;</div><div class="line"><a name="l00331"></a><span class="lineno"> 331</span> ```</div><div class="line"><a name="l00332"></a><span class="lineno"> 332</span> </div><div class="line"><a name="l00333"></a><span class="lineno"> 333</span> In place of its more annoying and error-prone counterpart:</div><div class="line"><a name="l00334"></a><span class="lineno"> 334</span> </div><div class="line"><a name="l00335"></a><span class="lineno"> 335</span> ```cpp</div><div class="line"><a name="l00336"></a><span class="lineno"> 336</span> entt::DefaultRegistry<Comp0, Comp1, ..., CompN> registry;</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> </div><div class="line"><a name="l00339"></a><span class="lineno"> 339</span> ### Pay per use</div><div class="line"><a name="l00340"></a><span class="lineno"> 340</span> </div><div class="line"><a name="l00341"></a><span class="lineno"> 341</span> `EnTT` is entirely designed around the principle that users have to pay only for</div><div class="line"><a name="l00342"></a><span class="lineno"> 342</span> what they want.</div><div class="line"><a name="l00343"></a><span class="lineno"> 343</span> </div><div class="line"><a name="l00344"></a><span class="lineno"> 344</span> When it comes to using an entity-component system, the tradeoff is usually</div><div class="line"><a name="l00345"></a><span class="lineno"> 345</span> between performance and memory usage. The faster it is, the more memory it uses.</div><div class="line"><a name="l00346"></a><span class="lineno"> 346</span> However, slightly worse performance along non-critical paths are the right price</div><div class="line"><a name="l00347"></a><span class="lineno"> 347</span> to pay to reduce memory usage and I've always wondered why this kind of tools do</div><div class="line"><a name="l00348"></a><span class="lineno"> 348</span> not leave me the choice.<br/></div><div class="line"><a name="l00349"></a><span class="lineno"> 349</span> `EnTT` follows a completely different approach. It squeezes the best from the</div><div class="line"><a name="l00350"></a><span class="lineno"> 350</span> basic data structures and gives users the possibility to pay more for higher</div><div class="line"><a name="l00351"></a><span class="lineno"> 351</span> performance where needed.<br/></div><div class="line"><a name="l00352"></a><span class="lineno"> 352</span> The disadvantage of this approach is that users need to know the systems they</div><div class="line"><a name="l00353"></a><span class="lineno"> 353</span> are working on and the tools they are using. Otherwise, the risk to ruin the</div><div class="line"><a name="l00354"></a><span class="lineno"> 354</span> performance along critical paths is high.</div><div class="line"><a name="l00355"></a><span class="lineno"> 355</span> </div><div class="line"><a name="l00356"></a><span class="lineno"> 356</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="l00357"></a><span class="lineno"> 357</span> many others besides me.</div><div class="line"><a name="l00358"></a><span class="lineno"> 358</span> </div><div class="line"><a name="l00359"></a><span class="lineno"> 359</span> ## Vademecum</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> The `Registry` to store, the views to iterate. That's all.</div><div class="line"><a name="l00362"></a><span class="lineno"> 362</span> </div><div class="line"><a name="l00363"></a><span class="lineno"> 363</span> An entity (the _E_ of an _ECS_) is an opaque identifier that users should just</div><div class="line"><a name="l00364"></a><span class="lineno"> 364</span> use as-is and store around if needed. Do not try to inspect an entity</div><div class="line"><a name="l00365"></a><span class="lineno"> 365</span> identifier, its format can change in future and a registry offers all the</div><div class="line"><a name="l00366"></a><span class="lineno"> 366</span> functionalities to query them out-of-the-box. The underlying type of an entity</div><div class="line"><a name="l00367"></a><span class="lineno"> 367</span> (either `std::uint16_t`, `std::uint32_t` or `std::uint64_t`) can be specified</div><div class="line"><a name="l00368"></a><span class="lineno"> 368</span> when defining a registry (actually the `DefaultRegistry` is nothing more than a</div><div class="line"><a name="l00369"></a><span class="lineno"> 369</span> `Registry` where the type of the entities is `std::uint32_t`).<br/></div><div class="line"><a name="l00370"></a><span class="lineno"> 370</span> Components (the _C_ of an _ECS_) should be plain old data structures or more</div><div class="line"><a name="l00371"></a><span class="lineno"> 371</span> complex and movable data structures with a proper constructor. Actually, the</div><div class="line"><a name="l00372"></a><span class="lineno"> 372</span> sole requirement of a component type is that it must be both move constructible</div><div class="line"><a name="l00373"></a><span class="lineno"> 373</span> and move assignable. They are list initialized by using the parameters provided</div><div class="line"><a name="l00374"></a><span class="lineno"> 374</span> to construct the component itself. No need to register components or their types</div><div class="line"><a name="l00375"></a><span class="lineno"> 375</span> neither with the registry nor with the entity-component system at all.<br/></div><div class="line"><a name="l00376"></a><span class="lineno"> 376</span> Systems (the _S_ of an _ECS_) are just plain functions, functors, lambdas or</div><div class="line"><a name="l00377"></a><span class="lineno"> 377</span> whatever users want. They can accept a `Registry` or a view of any type and use</div><div class="line"><a name="l00378"></a><span class="lineno"> 378</span> them the way they prefer. No need to register systems or their types neither</div><div class="line"><a name="l00379"></a><span class="lineno"> 379</span> with the registry nor with the entity-component system at all.</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> The following sections will explain in short how to use the entity-component</div><div class="line"><a name="l00382"></a><span class="lineno"> 382</span> system, the core part of the whole framework.<br/></div><div class="line"><a name="l00383"></a><span class="lineno"> 383</span> In fact, the framework is composed of many other classes in addition to those</div><div class="line"><a name="l00384"></a><span class="lineno"> 384</span> describe below. For more details, please refer to the inline documentation.</div><div class="line"><a name="l00385"></a><span class="lineno"> 385</span> </div><div class="line"><a name="l00386"></a><span class="lineno"> 386</span> ## The Registry, the Entity and the Component</div><div class="line"><a name="l00387"></a><span class="lineno"> 387</span> </div><div class="line"><a name="l00388"></a><span class="lineno"> 388</span> A registry can store and manage entities, as well as create views to iterate the</div><div class="line"><a name="l00389"></a><span class="lineno"> 389</span> underlying data structures.<br/></div><div class="line"><a name="l00390"></a><span class="lineno"> 390</span> `Registry` is a class template that lets users decide what's the preferred type</div><div class="line"><a name="l00391"></a><span class="lineno"> 391</span> to represent an entity. Because `std::uint32_t` is large enough for almost all</div><div class="line"><a name="l00392"></a><span class="lineno"> 392</span> the cases, there exists also an alias named `DefaultRegistry` for</div><div class="line"><a name="l00393"></a><span class="lineno"> 393</span> `Registry<std::uint32_t>`.</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> Entities are represented by _entity identifiers_. An entity identifier is an</div><div class="line"><a name="l00396"></a><span class="lineno"> 396</span> opaque type that users should not inspect or modify in any way. It carries</div><div class="line"><a name="l00397"></a><span class="lineno"> 397</span> information about the entity itself and its version.</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> A registry can be used both to construct and destroy entities:</div><div class="line"><a name="l00400"></a><span class="lineno"> 400</span> </div><div class="line"><a name="l00401"></a><span class="lineno"> 401</span> ```cpp</div><div class="line"><a name="l00402"></a><span class="lineno"> 402</span> // constructs a naked entity with no components and returns its identifier</div><div class="line"><a name="l00403"></a><span class="lineno"> 403</span> auto entity = registry.create();</div><div class="line"><a name="l00404"></a><span class="lineno"> 404</span> </div><div class="line"><a name="l00405"></a><span class="lineno"> 405</span> // destroys an entity and all its components</div><div class="line"><a name="l00406"></a><span class="lineno"> 406</span> registry.destroy(entity);</div><div class="line"><a name="l00407"></a><span class="lineno"> 407</span> ```</div><div class="line"><a name="l00408"></a><span class="lineno"> 408</span> </div><div class="line"><a name="l00409"></a><span class="lineno"> 409</span> When an entity is destroyed, the registry can freely reuse it internally with a</div><div class="line"><a name="l00410"></a><span class="lineno"> 410</span> slightly different identifier. In particular, the version of an entity is</div><div class="line"><a name="l00411"></a><span class="lineno"> 411</span> increased each and every time it's discarded.<br/></div><div class="line"><a name="l00412"></a><span class="lineno"> 412</span> In case entity identifiers are stored around, the registry offers all the</div><div class="line"><a name="l00413"></a><span class="lineno"> 413</span> functionalities required to test them and get out of the them all the</div><div class="line"><a name="l00414"></a><span class="lineno"> 414</span> information they carry:</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> ```cpp</div><div class="line"><a name="l00417"></a><span class="lineno"> 417</span> // returns true if the entity is still valid, false otherwise</div><div class="line"><a name="l00418"></a><span class="lineno"> 418</span> bool b = registry.valid(entity);</div><div class="line"><a name="l00419"></a><span class="lineno"> 419</span> </div><div class="line"><a name="l00420"></a><span class="lineno"> 420</span> // gets the version contained in the entity identifier</div><div class="line"><a name="l00421"></a><span class="lineno"> 421</span> auto version = registry.version(entity);</div><div class="line"><a name="l00422"></a><span class="lineno"> 422</span> </div><div class="line"><a name="l00423"></a><span class="lineno"> 423</span> // gets the actual version for the given entity</div><div class="line"><a name="l00424"></a><span class="lineno"> 424</span> auto curr = registry.current(entity);</div><div class="line"><a name="l00425"></a><span class="lineno"> 425</span> ```</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> Finally, there is also a sort of _null identifier_ made available to users. It's</div><div class="line"><a name="l00428"></a><span class="lineno"> 428</span> treated as if it were a _null pointer_ that doesn't identify any entity. A</div><div class="line"><a name="l00429"></a><span class="lineno"> 429</span> registry will reject this identifier in all cases because it isn't considered</div><div class="line"><a name="l00430"></a><span class="lineno"> 430</span> valid.<br/></div><div class="line"><a name="l00431"></a><span class="lineno"> 431</span> The rules that define a _null identifier_ are a bit tricky to explain. However,</div><div class="line"><a name="l00432"></a><span class="lineno"> 432</span> being `Entity` the type of the entities (for example, `std::uint32_t`), users</div><div class="line"><a name="l00433"></a><span class="lineno"> 433</span> can easily construct a _null identifier_ by flipping all the bits of the _zero_:</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> ```cpp</div><div class="line"><a name="l00436"></a><span class="lineno"> 436</span> using Entity = std::uint32_t;</div><div class="line"><a name="l00437"></a><span class="lineno"> 437</span> const auto null = ~Entity{};</div><div class="line"><a name="l00438"></a><span class="lineno"> 438</span> ```</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> Components can be assigned to or removed from entities at any time with a few</div><div class="line"><a name="l00441"></a><span class="lineno"> 441</span> calls to member functions of the registry. As for the entities, the registry</div><div class="line"><a name="l00442"></a><span class="lineno"> 442</span> offers also a set of functionalities users can use to work with the components.</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> The `assign` member function template creates, initializes and assigns to an</div><div class="line"><a name="l00445"></a><span class="lineno"> 445</span> entity the given component. It accepts a variable number of arguments to</div><div class="line"><a name="l00446"></a><span class="lineno"> 446</span> construct the component itself if present:</div><div class="line"><a name="l00447"></a><span class="lineno"> 447</span> </div><div class="line"><a name="l00448"></a><span class="lineno"> 448</span> ```cpp</div><div class="line"><a name="l00449"></a><span class="lineno"> 449</span> registry.assign<Position>(entity, 0., 0.);</div><div class="line"><a name="l00450"></a><span class="lineno"> 450</span> </div><div class="line"><a name="l00451"></a><span class="lineno"> 451</span> // ...</div><div class="line"><a name="l00452"></a><span class="lineno"> 452</span> </div><div class="line"><a name="l00453"></a><span class="lineno"> 453</span> Velocity &velocity = registry.assign<Velocity>(entity);</div><div class="line"><a name="l00454"></a><span class="lineno"> 454</span> velocity.dx = 0.;</div><div class="line"><a name="l00455"></a><span class="lineno"> 455</span> velocity.dy = 0.;</div><div class="line"><a name="l00456"></a><span class="lineno"> 456</span> ```</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> If an entity already has the given component, the `replace` member function</div><div class="line"><a name="l00459"></a><span class="lineno"> 459</span> template can be used to replace it:</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> ```cpp</div><div class="line"><a name="l00462"></a><span class="lineno"> 462</span> registry.replace<Position>(entity, 0., 0.);</div><div class="line"><a name="l00463"></a><span class="lineno"> 463</span> </div><div class="line"><a name="l00464"></a><span class="lineno"> 464</span> // ...</div><div class="line"><a name="l00465"></a><span class="lineno"> 465</span> </div><div class="line"><a name="l00466"></a><span class="lineno"> 466</span> Velocity &velocity = registry.replace<Velocity>(entity);</div><div class="line"><a name="l00467"></a><span class="lineno"> 467</span> velocity.dx = 0.;</div><div class="line"><a name="l00468"></a><span class="lineno"> 468</span> velocity.dy = 0.;</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> </div><div class="line"><a name="l00471"></a><span class="lineno"> 471</span> In case users want to assign a component to an entity, but it's unknown whether</div><div class="line"><a name="l00472"></a><span class="lineno"> 472</span> the entity already has it or not, `accommodate` does the work in a single call</div><div class="line"><a name="l00473"></a><span class="lineno"> 473</span> (there is a performance penalty to pay for this mainly due to the fact that it</div><div class="line"><a name="l00474"></a><span class="lineno"> 474</span> has to check if the entity already has the given component or not):</div><div class="line"><a name="l00475"></a><span class="lineno"> 475</span> </div><div class="line"><a name="l00476"></a><span class="lineno"> 476</span> ```cpp</div><div class="line"><a name="l00477"></a><span class="lineno"> 477</span> registry.accommodate<Position>(entity, 0., 0.);</div><div class="line"><a name="l00478"></a><span class="lineno"> 478</span> </div><div class="line"><a name="l00479"></a><span class="lineno"> 479</span> // ...</div><div class="line"><a name="l00480"></a><span class="lineno"> 480</span> </div><div class="line"><a name="l00481"></a><span class="lineno"> 481</span> Velocity &velocity = registry.accommodate<Velocity>(entity);</div><div class="line"><a name="l00482"></a><span class="lineno"> 482</span> velocity.dx = 0.;</div><div class="line"><a name="l00483"></a><span class="lineno"> 483</span> velocity.dy = 0.;</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> Note that `accommodate` is a slightly faster alternative for the following</div><div class="line"><a name="l00487"></a><span class="lineno"> 487</span> `if/else` statement and nothing more:</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> ```cpp</div><div class="line"><a name="l00490"></a><span class="lineno"> 490</span> if(registry.has<Comp>(entity)) {</div><div class="line"><a name="l00491"></a><span class="lineno"> 491</span>  registry.replace<Comp>(entity, arg1, argN);</div><div class="line"><a name="l00492"></a><span class="lineno"> 492</span> } else {</div><div class="line"><a name="l00493"></a><span class="lineno"> 493</span>  registry.assign<Comp>(entity, arg1, argN);</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> As already shown, if in doubt about whether or not an entity has one or more</div><div class="line"><a name="l00498"></a><span class="lineno"> 498</span> components, the `has` member function template may be useful:</div><div class="line"><a name="l00499"></a><span class="lineno"> 499</span> </div><div class="line"><a name="l00500"></a><span class="lineno"> 500</span> ```cpp</div><div class="line"><a name="l00501"></a><span class="lineno"> 501</span> bool b = registry.has<Position, Velocity>(entity);</div><div class="line"><a name="l00502"></a><span class="lineno"> 502</span> ```</div><div class="line"><a name="l00503"></a><span class="lineno"> 503</span> </div><div class="line"><a name="l00504"></a><span class="lineno"> 504</span> On the other side, if the goal is to delete a single component, the `remove`</div><div class="line"><a name="l00505"></a><span class="lineno"> 505</span> member function template is the way to go when it's certain that the entity owns</div><div class="line"><a name="l00506"></a><span class="lineno"> 506</span> a copy of the component:</div><div class="line"><a name="l00507"></a><span class="lineno"> 507</span> </div><div class="line"><a name="l00508"></a><span class="lineno"> 508</span> ```cpp</div><div class="line"><a name="l00509"></a><span class="lineno"> 509</span> registry.remove<Position>(entity);</div><div class="line"><a name="l00510"></a><span class="lineno"> 510</span> ```</div><div class="line"><a name="l00511"></a><span class="lineno"> 511</span> </div><div class="line"><a name="l00512"></a><span class="lineno"> 512</span> Otherwise consider to use the `reset` member function. It behaves similarly to</div><div class="line"><a name="l00513"></a><span class="lineno"> 513</span> `remove` but with a strictly defined behavior (and a performance penalty is the</div><div class="line"><a name="l00514"></a><span class="lineno"> 514</span> price to pay for this). In particular it removes the component if and only if it</div><div class="line"><a name="l00515"></a><span class="lineno"> 515</span> exists, otherwise it returns safely to the caller:</div><div class="line"><a name="l00516"></a><span class="lineno"> 516</span> </div><div class="line"><a name="l00517"></a><span class="lineno"> 517</span> ```cpp</div><div class="line"><a name="l00518"></a><span class="lineno"> 518</span> registry.reset<Position>(entity);</div><div class="line"><a name="l00519"></a><span class="lineno"> 519</span> ```</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> There exist also two other _versions_ of the `reset` member function:</div><div class="line"><a name="l00522"></a><span class="lineno"> 522</span> </div><div class="line"><a name="l00523"></a><span class="lineno"> 523</span> * If no entity is passed to it, `reset` will remove the given component from</div><div class="line"><a name="l00524"></a><span class="lineno"> 524</span>  each entity that has it:</div><div class="line"><a name="l00525"></a><span class="lineno"> 525</span> </div><div class="line"><a name="l00526"></a><span class="lineno"> 526</span>  ```cpp</div><div class="line"><a name="l00527"></a><span class="lineno"> 527</span>  registry.reset<Position>();</div><div class="line"><a name="l00528"></a><span class="lineno"> 528</span>  ```</div><div class="line"><a name="l00529"></a><span class="lineno"> 529</span> </div><div class="line"><a name="l00530"></a><span class="lineno"> 530</span> * If neither the entity nor the component are specified, all the entities still</div><div class="line"><a name="l00531"></a><span class="lineno"> 531</span>  in use and their components are destroyed:</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>  registry.reset();</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> Finally, references to components can be retrieved simply by doing this:</div><div class="line"><a name="l00538"></a><span class="lineno"> 538</span> </div><div class="line"><a name="l00539"></a><span class="lineno"> 539</span> ```cpp</div><div class="line"><a name="l00540"></a><span class="lineno"> 540</span> const auto &cregistry = registry;</div><div class="line"><a name="l00541"></a><span class="lineno"> 541</span> </div><div class="line"><a name="l00542"></a><span class="lineno"> 542</span> // const and non-const reference</div><div class="line"><a name="l00543"></a><span class="lineno"> 543</span> const Position &position = cregistry.get<Position>(entity);</div><div class="line"><a name="l00544"></a><span class="lineno"> 544</span> Position &position = registry.get<Position>(entity);</div><div class="line"><a name="l00545"></a><span class="lineno"> 545</span> </div><div class="line"><a name="l00546"></a><span class="lineno"> 546</span> // const and non-const references</div><div class="line"><a name="l00547"></a><span class="lineno"> 547</span> std::tuple<const Position &, const Velocity &> tup = cregistry.get<Position, Velocity>(entity);</div><div class="line"><a name="l00548"></a><span class="lineno"> 548</span> std::tuple<Position &, Velocity &> tup = registry.get<Position, Velocity>(entity);</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> </div><div class="line"><a name="l00551"></a><span class="lineno"> 551</span> The `get` member function template gives direct access to the component of an</div><div class="line"><a name="l00552"></a><span class="lineno"> 552</span> entity stored in the underlying data structures of the registry.</div><div class="line"><a name="l00553"></a><span class="lineno"> 553</span> </div><div class="line"><a name="l00554"></a><span class="lineno"> 554</span> ### Single instance components</div><div class="line"><a name="l00555"></a><span class="lineno"> 555</span> </div><div class="line"><a name="l00556"></a><span class="lineno"> 556</span> In those cases where all what is needed is a single instance component, tags are</div><div class="line"><a name="l00557"></a><span class="lineno"> 557</span> the right tool to achieve the purpose.<br/></div><div class="line"><a name="l00558"></a><span class="lineno"> 558</span> Tags undergo the same requirements of components. They can be either plain old</div><div class="line"><a name="l00559"></a><span class="lineno"> 559</span> data structures or more complex and movable data structures with a proper</div><div class="line"><a name="l00560"></a><span class="lineno"> 560</span> constructor.<br/></div><div class="line"><a name="l00561"></a><span class="lineno"> 561</span> Actually, the same type can be used both as a tag and as a component and the</div><div class="line"><a name="l00562"></a><span class="lineno"> 562</span> registry will not complain about it. It is up to users to properly manage their</div><div class="line"><a name="l00563"></a><span class="lineno"> 563</span> own types. In some cases, the tag `tag_t` must also be used in order to</div><div class="line"><a name="l00564"></a><span class="lineno"> 564</span> disambiguate overloads of member functions.</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> Attaching tags to entities and removing them is trivial:</div><div class="line"><a name="l00567"></a><span class="lineno"> 567</span> </div><div class="line"><a name="l00568"></a><span class="lineno"> 568</span> ```cpp</div><div class="line"><a name="l00569"></a><span class="lineno"> 569</span> auto player = registry.create();</div><div class="line"><a name="l00570"></a><span class="lineno"> 570</span> auto camera = registry.create();</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> // attaches a default-initialized tag to an entity</div><div class="line"><a name="l00573"></a><span class="lineno"> 573</span> registry.assign<PlayingCharacter>(entt::tag_t{}, player);</div><div class="line"><a name="l00574"></a><span class="lineno"> 574</span> </div><div class="line"><a name="l00575"></a><span class="lineno"> 575</span> // attaches a tag to an entity and initializes it</div><div class="line"><a name="l00576"></a><span class="lineno"> 576</span> registry.assign<Camera>(entt::tag_t{}, camera, player);</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> // removes tags from their owners</div><div class="line"><a name="l00579"></a><span class="lineno"> 579</span> registry.remove<PlayingCharacter>();</div><div class="line"><a name="l00580"></a><span class="lineno"> 580</span> registry.remove<Camera>();</div><div class="line"><a name="l00581"></a><span class="lineno"> 581</span> ```</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> In case a tag already has an owner, its content can be updated by means of the</div><div class="line"><a name="l00584"></a><span class="lineno"> 584</span> `replace` member function template and the ownership of the tag can be</div><div class="line"><a name="l00585"></a><span class="lineno"> 585</span> transferred to another entity using the `move` member function template:</div><div class="line"><a name="l00586"></a><span class="lineno"> 586</span> </div><div class="line"><a name="l00587"></a><span class="lineno"> 587</span> ```</div><div class="line"><a name="l00588"></a><span class="lineno"> 588</span> // replaces the content of the given tag</div><div class="line"><a name="l00589"></a><span class="lineno"> 589</span> Point &point = registry.replace<Point>(entt::tag_t{}, 1.f, 1.f);</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> // transfers the ownership of the tag to another entity</div><div class="line"><a name="l00592"></a><span class="lineno"> 592</span> entity_type prev = registry.move<Point>(next);</div><div class="line"><a name="l00593"></a><span class="lineno"> 593</span> ```</div><div class="line"><a name="l00594"></a><span class="lineno"> 594</span> </div><div class="line"><a name="l00595"></a><span class="lineno"> 595</span> If in doubt about whether or not a tag already has an owner, the `has` member</div><div class="line"><a name="l00596"></a><span class="lineno"> 596</span> function template may be useful:</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> ```cpp</div><div class="line"><a name="l00599"></a><span class="lineno"> 599</span> bool b = registry.has<PlayingCharacter>();</div><div class="line"><a name="l00600"></a><span class="lineno"> 600</span> ```</div><div class="line"><a name="l00601"></a><span class="lineno"> 601</span> </div><div class="line"><a name="l00602"></a><span class="lineno"> 602</span> References to tags can be retrieved simply by doing this:</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> ```cpp</div><div class="line"><a name="l00605"></a><span class="lineno"> 605</span> const auto &cregistry = registry;</div><div class="line"><a name="l00606"></a><span class="lineno"> 606</span> </div><div class="line"><a name="l00607"></a><span class="lineno"> 607</span> // either a non-const reference ...</div><div class="line"><a name="l00608"></a><span class="lineno"> 608</span> PlayingCharacter &player = registry.get<PlayingCharacter>();</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> // ... or a const one</div><div class="line"><a name="l00611"></a><span class="lineno"> 611</span> const Camera &camera = cregistry.get<Camera>();</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> </div><div class="line"><a name="l00614"></a><span class="lineno"> 614</span> The `get` member function template gives direct access to the tag as stored in</div><div class="line"><a name="l00615"></a><span class="lineno"> 615</span> the underlying data structures of the registry.</div><div class="line"><a name="l00616"></a><span class="lineno"> 616</span> </div><div class="line"><a name="l00617"></a><span class="lineno"> 617</span> As shown above, in almost all the cases the entity identifier isn't required.</div><div class="line"><a name="l00618"></a><span class="lineno"> 618</span> Since a single instance component can have only one associated entity, it</div><div class="line"><a name="l00619"></a><span class="lineno"> 619</span> doesn't make much sense to mention it explicitly.<br/></div><div class="line"><a name="l00620"></a><span class="lineno"> 620</span> To find out who the owner is, just do the following:</div><div class="line"><a name="l00621"></a><span class="lineno"> 621</span> </div><div class="line"><a name="l00622"></a><span class="lineno"> 622</span> ```cpp</div><div class="line"><a name="l00623"></a><span class="lineno"> 623</span> auto player = registry.attachee<PlayingCharacter>();</div><div class="line"><a name="l00624"></a><span class="lineno"> 624</span> ```</div><div class="line"><a name="l00625"></a><span class="lineno"> 625</span> </div><div class="line"><a name="l00626"></a><span class="lineno"> 626</span> Note that iterating tags isn't possible for obvious reasons. Tags give direct</div><div class="line"><a name="l00627"></a><span class="lineno"> 627</span> access to single entities and nothing more.</div><div class="line"><a name="l00628"></a><span class="lineno"> 628</span> </div><div class="line"><a name="l00629"></a><span class="lineno"> 629</span> ### Observe changes</div><div class="line"><a name="l00630"></a><span class="lineno"> 630</span> </div><div class="line"><a name="l00631"></a><span class="lineno"> 631</span> Because of how the registry works internally, it stores a couple of signal</div><div class="line"><a name="l00632"></a><span class="lineno"> 632</span> handlers for each pool in order to notify some of its data structures on the</div><div class="line"><a name="l00633"></a><span class="lineno"> 633</span> construction and destruction of components.<br/></div><div class="line"><a name="l00634"></a><span class="lineno"> 634</span> These signal handlers are also exposed and made available to users. This is the</div><div class="line"><a name="l00635"></a><span class="lineno"> 635</span> basic brick to build fancy things like dependencies and reactive systems.</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> To get a sink to be used to connect and disconnect listeners so as to be</div><div class="line"><a name="l00638"></a><span class="lineno"> 638</span> notified on the creation of a component, use the `construction` member function:</div><div class="line"><a name="l00639"></a><span class="lineno"> 639</span> </div><div class="line"><a name="l00640"></a><span class="lineno"> 640</span> ```cpp</div><div class="line"><a name="l00641"></a><span class="lineno"> 641</span> // connects a free function</div><div class="line"><a name="l00642"></a><span class="lineno"> 642</span> registry.construction<Position>().connect<&MyFreeFunction>();</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> // connects a member function</div><div class="line"><a name="l00645"></a><span class="lineno"> 645</span> registry.construction<Position>().connect<MyClass, &MyClass::member>(&instance);</div><div class="line"><a name="l00646"></a><span class="lineno"> 646</span> </div><div class="line"><a name="l00647"></a><span class="lineno"> 647</span> // disconnects a free function</div><div class="line"><a name="l00648"></a><span class="lineno"> 648</span> registry.construction<Position>().disconnect<&MyFreeFunction>();</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> // disconnects a member function</div><div class="line"><a name="l00651"></a><span class="lineno"> 651</span> registry.construction<Position>().disconnect<MyClass, &MyClass::member>(&instance);</div><div class="line"><a name="l00652"></a><span class="lineno"> 652</span> ```</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> To be notified when components are destroyed, use the `destruction` member</div><div class="line"><a name="l00655"></a><span class="lineno"> 655</span> function instead.</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> The function type of a listener is the same in both cases:</div><div class="line"><a name="l00658"></a><span class="lineno"> 658</span> </div><div class="line"><a name="l00659"></a><span class="lineno"> 659</span> ```cpp</div><div class="line"><a name="l00660"></a><span class="lineno"> 660</span> void(Registry<Entity> &, Entity);</div><div class="line"><a name="l00661"></a><span class="lineno"> 661</span> ```</div><div class="line"><a name="l00662"></a><span class="lineno"> 662</span> </div><div class="line"><a name="l00663"></a><span class="lineno"> 663</span> In other terms, a listener is provided with the registry that triggered the</div><div class="line"><a name="l00664"></a><span class="lineno"> 664</span> notification and the entity affected by the change. Note also that:</div><div class="line"><a name="l00665"></a><span class="lineno"> 665</span> </div><div class="line"><a name="l00666"></a><span class="lineno"> 666</span> * Listeners are invoked **after** components have been assigned to entities.</div><div class="line"><a name="l00667"></a><span class="lineno"> 667</span> * Listeners are invoked **before** components have been removed from entities.</div><div class="line"><a name="l00668"></a><span class="lineno"> 668</span> * The order of invocation of the listeners isn't guaranteed in any case.</div><div class="line"><a name="l00669"></a><span class="lineno"> 669</span> </div><div class="line"><a name="l00670"></a><span class="lineno"> 670</span> There are also some limitations on what a listener can and cannot do. In</div><div class="line"><a name="l00671"></a><span class="lineno"> 671</span> particular:</div><div class="line"><a name="l00672"></a><span class="lineno"> 672</span> </div><div class="line"><a name="l00673"></a><span class="lineno"> 673</span> * Connecting and disconnecting other functions from within the body of a</div><div class="line"><a name="l00674"></a><span class="lineno"> 674</span>  listener should be avoided. It can lead to undefined behavior in some cases.</div><div class="line"><a name="l00675"></a><span class="lineno"> 675</span> * Assigning and removing components and tags from within the body of a listener</div><div class="line"><a name="l00676"></a><span class="lineno"> 676</span>  that observes the destruction of instances of a given type should be avoided.</div><div class="line"><a name="l00677"></a><span class="lineno"> 677</span>  It can lead to undefined behavior in some cases. This type of listeners is</div><div class="line"><a name="l00678"></a><span class="lineno"> 678</span>  intended to provide users with an easy way to perform cleanup and nothing</div><div class="line"><a name="l00679"></a><span class="lineno"> 679</span>  more.</div><div class="line"><a name="l00680"></a><span class="lineno"> 680</span> </div><div class="line"><a name="l00681"></a><span class="lineno"> 681</span> To a certain extent, these limitations do not apply. However, it is risky to try</div><div class="line"><a name="l00682"></a><span class="lineno"> 682</span> to force them and users should respect the limitations unless they know exactly</div><div class="line"><a name="l00683"></a><span class="lineno"> 683</span> what they are doing. Subtle bugs are the price to pay in case of errors</div><div class="line"><a name="l00684"></a><span class="lineno"> 684</span> otherwise.</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> In general, events and therefore listeners must not be used as replacements for</div><div class="line"><a name="l00687"></a><span class="lineno"> 687</span> systems. They should not contain much logic and interactions with a registry</div><div class="line"><a name="l00688"></a><span class="lineno"> 688</span> should be kept to a minimum, if possible. Note also that the greater the number</div><div class="line"><a name="l00689"></a><span class="lineno"> 689</span> of listeners, the greater the performance hit when components are created or</div><div class="line"><a name="l00690"></a><span class="lineno"> 690</span> destroyed.</div><div class="line"><a name="l00691"></a><span class="lineno"> 691</span> </div><div class="line"><a name="l00692"></a><span class="lineno"> 692</span> #### Who let the tags out?</div><div class="line"><a name="l00693"></a><span class="lineno"> 693</span> </div><div class="line"><a name="l00694"></a><span class="lineno"> 694</span> As an extension, signals are also provided with tags. Although they are not</div><div class="line"><a name="l00695"></a><span class="lineno"> 695</span> strictly required internally, it makes sense that a user expects signal support</div><div class="line"><a name="l00696"></a><span class="lineno"> 696</span> even when it comes to tags actually.<br/></div><div class="line"><a name="l00697"></a><span class="lineno"> 697</span> Signals for tags undergo exactly the same requirements of those introduced for</div><div class="line"><a name="l00698"></a><span class="lineno"> 698</span> components. Also the function type for a listener is the same and it's invoked</div><div class="line"><a name="l00699"></a><span class="lineno"> 699</span> with the same guarantees discussed above.</div><div class="line"><a name="l00700"></a><span class="lineno"> 700</span> </div><div class="line"><a name="l00701"></a><span class="lineno"> 701</span> To get the sinks for a tag just use tag `tag_t` to disambiguate overloads of</div><div class="line"><a name="l00702"></a><span class="lineno"> 702</span> member functions as in the following example:</div><div class="line"><a name="l00703"></a><span class="lineno"> 703</span> </div><div class="line"><a name="l00704"></a><span class="lineno"> 704</span> ```cpp</div><div class="line"><a name="l00705"></a><span class="lineno"> 705</span> registry.construction<MyTag>(entt::tag_t{}).connect<&MyFreeFunction>();</div><div class="line"><a name="l00706"></a><span class="lineno"> 706</span> registry.destruction<MyTag>(entt::tag_t{}).connect<MyClass, &MyClass::member>(&instance);</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> </div><div class="line"><a name="l00709"></a><span class="lineno"> 709</span> Listeners for tags and components are managed separately and do not influence</div><div class="line"><a name="l00710"></a><span class="lineno"> 710</span> each other in any case. Therefore, note that the greater the number of listeners</div><div class="line"><a name="l00711"></a><span class="lineno"> 711</span> for a type, the greater the performance hit when a tag of the given type is</div><div class="line"><a name="l00712"></a><span class="lineno"> 712</span> created or destroyed.</div><div class="line"><a name="l00713"></a><span class="lineno"> 713</span> </div><div class="line"><a name="l00714"></a><span class="lineno"> 714</span> ### Runtime components</div><div class="line"><a name="l00715"></a><span class="lineno"> 715</span> </div><div class="line"><a name="l00716"></a><span class="lineno"> 716</span> Defining components at runtime is useful to support plugins and mods in general.</div><div class="line"><a name="l00717"></a><span class="lineno"> 717</span> However, it seems impossible with a tool designed around a bunch of templates.</div><div class="line"><a name="l00718"></a><span class="lineno"> 718</span> Indeed it's not that difficult.<br/></div><div class="line"><a name="l00719"></a><span class="lineno"> 719</span> Of course, some features cannot be easily exported into a runtime</div><div class="line"><a name="l00720"></a><span class="lineno"> 720</span> environment. As an example, sorting a group of components defined at runtime</div><div class="line"><a name="l00721"></a><span class="lineno"> 721</span> isn't for free if compared to most of the other operations. However, the basic</div><div class="line"><a name="l00722"></a><span class="lineno"> 722</span> functionalities of an entity-component system such as `EnTT` fit the problem</div><div class="line"><a name="l00723"></a><span class="lineno"> 723</span> perfectly and can also be used to manage runtime components if required.<br/></div><div class="line"><a name="l00724"></a><span class="lineno"> 724</span> All that is necessary to do it is to know the identifiers of the components. An</div><div class="line"><a name="l00725"></a><span class="lineno"> 725</span> identifier is nothing more than a number or similar that can be used at runtime</div><div class="line"><a name="l00726"></a><span class="lineno"> 726</span> to work with the type system.</div><div class="line"><a name="l00727"></a><span class="lineno"> 727</span> </div><div class="line"><a name="l00728"></a><span class="lineno"> 728</span> In `EnTT`, identifiers are easily accessible:</div><div class="line"><a name="l00729"></a><span class="lineno"> 729</span> </div><div class="line"><a name="l00730"></a><span class="lineno"> 730</span> ```cpp</div><div class="line"><a name="l00731"></a><span class="lineno"> 731</span> entt::DefaultRegistry registry;</div><div class="line"><a name="l00732"></a><span class="lineno"> 732</span> </div><div class="line"><a name="l00733"></a><span class="lineno"> 733</span> // standard component identifier</div><div class="line"><a name="l00734"></a><span class="lineno"> 734</span> auto ctype = registry.component<Position>();</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> // single instance component identifier</div><div class="line"><a name="l00737"></a><span class="lineno"> 737</span> auto ttype = registry.tag<PlayingCharacter>();</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> </div><div class="line"><a name="l00740"></a><span class="lineno"> 740</span> Once the identifiers are made available, almost everything becomes pretty</div><div class="line"><a name="l00741"></a><span class="lineno"> 741</span> simple.</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> #### A journey through a plugin</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> `EnTT` comes with an example (actually a test) that shows how to integrate</div><div class="line"><a name="l00746"></a><span class="lineno"> 746</span> compile-time and runtime components in a stack based JavaScript environment. It</div><div class="line"><a name="l00747"></a><span class="lineno"> 747</span> uses [`Duktape`](https://github.com/svaarala/duktape) under the hood, mainly</div><div class="line"><a name="l00748"></a><span class="lineno"> 748</span> because I wanted to learn how it works at the time I was writing the code.</div><div class="line"><a name="l00749"></a><span class="lineno"> 749</span> </div><div class="line"><a name="l00750"></a><span class="lineno"> 750</span> The code is not production-ready and overall performance can be highly improved.</div><div class="line"><a name="l00751"></a><span class="lineno"> 751</span> However, I sacrificed optimizations in favor of a more readable piece of code. I</div><div class="line"><a name="l00752"></a><span class="lineno"> 752</span> hope I succeeded.<br/></div><div class="line"><a name="l00753"></a><span class="lineno"> 753</span> Note also that this isn't neither the only nor (probably) the best way to do it.</div><div class="line"><a name="l00754"></a><span class="lineno"> 754</span> In fact, the right way depends on the scripting language and the problem one is</div><div class="line"><a name="l00755"></a><span class="lineno"> 755</span> facing in general.<br/></div><div class="line"><a name="l00756"></a><span class="lineno"> 756</span> That being said, feel free to use it at your own risk.</div><div class="line"><a name="l00757"></a><span class="lineno"> 757</span> </div><div class="line"><a name="l00758"></a><span class="lineno"> 758</span> The basic idea is that of creating a compile-time component aimed to map all the</div><div class="line"><a name="l00759"></a><span class="lineno"> 759</span> runtime components assigned to an entity.<br/></div><div class="line"><a name="l00760"></a><span class="lineno"> 760</span> Identifiers come in use to address the right function from a map when invoked</div><div class="line"><a name="l00761"></a><span class="lineno"> 761</span> from the runtime environment and to filter entities when iterating.<br/></div><div class="line"><a name="l00762"></a><span class="lineno"> 762</span> With a bit of gymnastic, one can narrow views and improve the performance to</div><div class="line"><a name="l00763"></a><span class="lineno"> 763</span> some extent but it was not the goal of the example.</div><div class="line"><a name="l00764"></a><span class="lineno"> 764</span> </div><div class="line"><a name="l00765"></a><span class="lineno"> 765</span> ### Sorting: is it possible?</div><div class="line"><a name="l00766"></a><span class="lineno"> 766</span> </div><div class="line"><a name="l00767"></a><span class="lineno"> 767</span> It goes without saying that sorting entities and components is possible with</div><div class="line"><a name="l00768"></a><span class="lineno"> 768</span> `EnTT`.<br/></div><div class="line"><a name="l00769"></a><span class="lineno"> 769</span> In fact, there are two functions that respond to slightly different needs:</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> * Components can be sorted directly:</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>  registry.sort<Renderable>([](const auto &lhs, const auto &rhs) {</div><div class="line"><a name="l00775"></a><span class="lineno"> 775</span>  return lhs.z < rhs.z;</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>  });</div><div class="line"><a name="l00778"></a><span class="lineno"> 778</span>  ```</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>  There exists also the possibility to use a custom sort function object, as</div><div class="line"><a name="l00781"></a><span class="lineno"> 781</span>  long as it adheres to the requirements described in the inline</div><div class="line"><a name="l00782"></a><span class="lineno"> 782</span>  documentation.<br/></div><div class="line"><a name="l00783"></a><span class="lineno"> 783</span>  This is possible mainly because users can get much more with a custom sort</div><div class="line"><a name="l00784"></a><span class="lineno"> 784</span>  function object if the pattern of usage is known. As an example, in case of an</div><div class="line"><a name="l00785"></a><span class="lineno"> 785</span>  almost sorted pool, quick sort could be much, much slower than insertion sort.</div><div class="line"><a name="l00786"></a><span class="lineno"> 786</span> </div><div class="line"><a name="l00787"></a><span class="lineno"> 787</span> * Components can be sorted according to the order imposed by another component:</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>  ```cpp</div><div class="line"><a name="l00790"></a><span class="lineno"> 790</span>  registry.sort<Movement, Physics>();</div><div class="line"><a name="l00791"></a><span class="lineno"> 791</span>  ```</div><div class="line"><a name="l00792"></a><span class="lineno"> 792</span> </div><div class="line"><a name="l00793"></a><span class="lineno"> 793</span>  In this case, instances of `Movement` are arranged in memory so that cache</div><div class="line"><a name="l00794"></a><span class="lineno"> 794</span>  misses are minimized when the two components are iterated together.</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 and tags to bytes directly, there wasn't the need</div><div class="line"><a name="l00800"></a><span class="lineno"> 800</span> of another tool for serialization out there. Instead, it accepts an opaque</div><div class="line"><a name="l00801"></a><span class="lineno"> 801</span> object with a suitable interface (namely an _archive_) to serialize its internal</div><div class="line"><a name="l00802"></a><span class="lineno"> 802</span> data structures and restore them later. The way types and instances are</div><div class="line"><a name="l00803"></a><span class="lineno"> 803</span> converted to a bunch of bytes is completely in charge to the archive and thus to</div><div class="line"><a name="l00804"></a><span class="lineno"> 804</span> final users.</div><div class="line"><a name="l00805"></a><span class="lineno"> 805</span> </div><div class="line"><a name="l00806"></a><span class="lineno"> 806</span> The goal of the serialization part is to allow users to make both a dump of the</div><div class="line"><a name="l00807"></a><span class="lineno"> 807</span> entire registry or a narrower snapshot, that is to select only the components</div><div class="line"><a name="l00808"></a><span class="lineno"> 808</span> and the tags in which they are interested.<br/></div><div class="line"><a name="l00809"></a><span class="lineno"> 809</span> Intuitively, the use cases are different. As an example, the first approach is</div><div class="line"><a name="l00810"></a><span class="lineno"> 810</span> suitable for local save/restore functionalities while the latter is suitable for</div><div class="line"><a name="l00811"></a><span class="lineno"> 811</span> creating client-server applications and for transferring somehow parts of the</div><div class="line"><a name="l00812"></a><span class="lineno"> 812</span> representation side to side.</div><div class="line"><a name="l00813"></a><span class="lineno"> 813</span> </div><div class="line"><a name="l00814"></a><span class="lineno"> 814</span> To take a snapshot of the registry, use the `snapshot` member function. It</div><div class="line"><a name="l00815"></a><span class="lineno"> 815</span> returns a temporary object properly initialized to _save_ the whole registry or</div><div class="line"><a name="l00816"></a><span class="lineno"> 816</span> parts of it.</div><div class="line"><a name="l00817"></a><span class="lineno"> 817</span> </div><div class="line"><a name="l00818"></a><span class="lineno"> 818</span> Example of use:</div><div class="line"><a name="l00819"></a><span class="lineno"> 819</span> </div><div class="line"><a name="l00820"></a><span class="lineno"> 820</span> ```cpp</div><div class="line"><a name="l00821"></a><span class="lineno"> 821</span> OutputArchive output;</div><div class="line"><a name="l00822"></a><span class="lineno"> 822</span> </div><div class="line"><a name="l00823"></a><span class="lineno"> 823</span> registry.snapshot()</div><div class="line"><a name="l00824"></a><span class="lineno"> 824</span>  .entities(output)</div><div class="line"><a name="l00825"></a><span class="lineno"> 825</span>  .destroyed(output)</div><div class="line"><a name="l00826"></a><span class="lineno"> 826</span>  .component<AComponent, AnotherComponent>(output)</div><div class="line"><a name="l00827"></a><span class="lineno"> 827</span>  .tag<MyTag>(output);</div><div class="line"><a name="l00828"></a><span class="lineno"> 828</span> ```</div><div class="line"><a name="l00829"></a><span class="lineno"> 829</span> </div><div class="line"><a name="l00830"></a><span class="lineno"> 830</span> It isn't necessary to invoke all these functions each and every time. What</div><div class="line"><a name="l00831"></a><span class="lineno"> 831</span> functions to use in which case mostly depends on the goal and there is not a</div><div class="line"><a name="l00832"></a><span class="lineno"> 832</span> golden rule to do that.</div><div class="line"><a name="l00833"></a><span class="lineno"> 833</span> </div><div class="line"><a name="l00834"></a><span class="lineno"> 834</span> The `entities` member function asks the registry to serialize all the entities</div><div class="line"><a name="l00835"></a><span class="lineno"> 835</span> that are still in use along with their versions. On the other side, the</div><div class="line"><a name="l00836"></a><span class="lineno"> 836</span> `destroyed` member function tells to the registry to serialize the entities that</div><div class="line"><a name="l00837"></a><span class="lineno"> 837</span> have been destroyed and are no longer in use.<br/></div><div class="line"><a name="l00838"></a><span class="lineno"> 838</span> These two functions can be used to save and restore the whole set of entities</div><div class="line"><a name="l00839"></a><span class="lineno"> 839</span> with the versions they had during serialization.</div><div class="line"><a name="l00840"></a><span class="lineno"> 840</span> </div><div class="line"><a name="l00841"></a><span class="lineno"> 841</span> The `component` member function is a function template the aim of which is to</div><div class="line"><a name="l00842"></a><span class="lineno"> 842</span> store aside components. The presence of a template parameter list is a</div><div class="line"><a name="l00843"></a><span class="lineno"> 843</span> consequence of a couple of design choices from the past and in the present:</div><div class="line"><a name="l00844"></a><span class="lineno"> 844</span> </div><div class="line"><a name="l00845"></a><span class="lineno"> 845</span> * First of all, there is no reason to force a user to serialize all the</div><div class="line"><a name="l00846"></a><span class="lineno"> 846</span>  components at once and most of the times it isn't desiderable. As an example,</div><div class="line"><a name="l00847"></a><span class="lineno"> 847</span>  in case the stuff for the HUD in a game is put into the registry for some</div><div class="line"><a name="l00848"></a><span class="lineno"> 848</span>  reasons, its components can be freely discarded during a serialization step</div><div class="line"><a name="l00849"></a><span class="lineno"> 849</span>  because probably the software already knows how to reconstruct the HUD</div><div class="line"><a name="l00850"></a><span class="lineno"> 850</span>  correctly from scratch.</div><div class="line"><a name="l00851"></a><span class="lineno"> 851</span> </div><div class="line"><a name="l00852"></a><span class="lineno"> 852</span> * Furthermore, the registry makes heavy use of _type-erasure_ techniques</div><div class="line"><a name="l00853"></a><span class="lineno"> 853</span>  internally and doesn't know at any time what types of components it contains.</div><div class="line"><a name="l00854"></a><span class="lineno"> 854</span>  Therefore being explicit at the call point is mandatory.</div><div class="line"><a name="l00855"></a><span class="lineno"> 855</span> </div><div class="line"><a name="l00856"></a><span class="lineno"> 856</span> There exists also another version of the `component` member function that</div><div class="line"><a name="l00857"></a><span class="lineno"> 857</span> accepts a range of entities to serialize. This version is a bit slower than the</div><div class="line"><a name="l00858"></a><span class="lineno"> 858</span> other one, mainly because it iterates the range of entities more than once for</div><div class="line"><a name="l00859"></a><span class="lineno"> 859</span> internal purposes. However, it can be used to filter out those entities that</div><div class="line"><a name="l00860"></a><span class="lineno"> 860</span> shouldn't be serialized for some reasons.<br/></div><div class="line"><a name="l00861"></a><span class="lineno"> 861</span> As an example:</div><div class="line"><a name="l00862"></a><span class="lineno"> 862</span> </div><div class="line"><a name="l00863"></a><span class="lineno"> 863</span> ```cpp</div><div class="line"><a name="l00864"></a><span class="lineno"> 864</span> const auto view = registry.view<Serialize>();</div><div class="line"><a name="l00865"></a><span class="lineno"> 865</span> OutputArchive output;</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> registry.snapshot()</div><div class="line"><a name="l00868"></a><span class="lineno"> 868</span>  .component<AComponent, AnotherComponent>(output, view.cbegin(), view.cend());</div><div class="line"><a name="l00869"></a><span class="lineno"> 869</span> ```</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> The `tag` member function is similar to the previous one, apart from the fact</div><div class="line"><a name="l00872"></a><span class="lineno"> 872</span> that it works with tags and not with components.<br/></div><div class="line"><a name="l00873"></a><span class="lineno"> 873</span> Note also that both `component` and `tag` store items along with entities. It</div><div class="line"><a name="l00874"></a><span class="lineno"> 874</span> means that they work properly without a call to the `entities` member function.</div><div class="line"><a name="l00875"></a><span class="lineno"> 875</span> </div><div class="line"><a name="l00876"></a><span class="lineno"> 876</span> Once a snapshot is created, there exist mainly two _ways_ to load it: as a whole</div><div class="line"><a name="l00877"></a><span class="lineno"> 877</span> and in a kind of _continuous mode_.<br/></div><div class="line"><a name="l00878"></a><span class="lineno"> 878</span> The following sections describe both loaders and archives in details.</div><div class="line"><a name="l00879"></a><span class="lineno"> 879</span> </div><div class="line"><a name="l00880"></a><span class="lineno"> 880</span> #### Snapshot loader</div><div class="line"><a name="l00881"></a><span class="lineno"> 881</span> </div><div class="line"><a name="l00882"></a><span class="lineno"> 882</span> A snapshot loader requires that the destination registry be empty and loads all</div><div class="line"><a name="l00883"></a><span class="lineno"> 883</span> the data at once while keeping intact the identifiers that the entities</div><div class="line"><a name="l00884"></a><span class="lineno"> 884</span> originally had.<br/></div><div class="line"><a name="l00885"></a><span class="lineno"> 885</span> To do that, the registry offers a member function named `restore` that returns a</div><div class="line"><a name="l00886"></a><span class="lineno"> 886</span> temporary object properly initialized to _restore_ a snapshot.</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> Example of use:</div><div class="line"><a name="l00889"></a><span class="lineno"> 889</span> </div><div class="line"><a name="l00890"></a><span class="lineno"> 890</span> ```cpp</div><div class="line"><a name="l00891"></a><span class="lineno"> 891</span> InputArchive input;</div><div class="line"><a name="l00892"></a><span class="lineno"> 892</span> </div><div class="line"><a name="l00893"></a><span class="lineno"> 893</span> registry.restore()</div><div class="line"><a name="l00894"></a><span class="lineno"> 894</span>  .entities(input)</div><div class="line"><a name="l00895"></a><span class="lineno"> 895</span>  .destroyed(input)</div><div class="line"><a name="l00896"></a><span class="lineno"> 896</span>  .component<AComponent, AnotherComponent>(input)</div><div class="line"><a name="l00897"></a><span class="lineno"> 897</span>  .tag<MyTag>(input)</div><div class="line"><a name="l00898"></a><span class="lineno"> 898</span>  .orphans();</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> </div><div class="line"><a name="l00901"></a><span class="lineno"> 901</span> It isn't necessary to invoke all these functions each and every time. What</div><div class="line"><a name="l00902"></a><span class="lineno"> 902</span> functions to use in which case mostly depends on the goal and there is not a</div><div class="line"><a name="l00903"></a><span class="lineno"> 903</span> golden rule to do that. For obvious reasons, what is important is that the data</div><div class="line"><a name="l00904"></a><span class="lineno"> 904</span> are restored in exactly the same order in which they were serialized.</div><div class="line"><a name="l00905"></a><span class="lineno"> 905</span> </div><div class="line"><a name="l00906"></a><span class="lineno"> 906</span> The `entities` and `destroyed` member functions restore the sets of entities and</div><div class="line"><a name="l00907"></a><span class="lineno"> 907</span> the versions that the entities originally had at the source.</div><div class="line"><a name="l00908"></a><span class="lineno"> 908</span> </div><div class="line"><a name="l00909"></a><span class="lineno"> 909</span> The `component` member function restores all and only the components specified</div><div class="line"><a name="l00910"></a><span class="lineno"> 910</span> and assigns them to the right entities. Note that the template parameter list</div><div class="line"><a name="l00911"></a><span class="lineno"> 911</span> must be exactly the same used during the serialization. The same applies to the</div><div class="line"><a name="l00912"></a><span class="lineno"> 912</span> `tag` member function.</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> The `orphans` member function literally destroys those entities that have</div><div class="line"><a name="l00915"></a><span class="lineno"> 915</span> neither components nor tags. It's usually useless if the snapshot is a full dump</div><div class="line"><a name="l00916"></a><span class="lineno"> 916</span> of the source. However, in case all the entities are serialized but only few</div><div class="line"><a name="l00917"></a><span class="lineno"> 917</span> components and tags are saved, it could happen that some of the entities have</div><div class="line"><a name="l00918"></a><span class="lineno"> 918</span> neither components nor tags once restored. The best users can do to deal with</div><div class="line"><a name="l00919"></a><span class="lineno"> 919</span> them is to destroy those entities and thus update their versions.</div><div class="line"><a name="l00920"></a><span class="lineno"> 920</span> </div><div class="line"><a name="l00921"></a><span class="lineno"> 921</span> #### Continuous loader</div><div class="line"><a name="l00922"></a><span class="lineno"> 922</span> </div><div class="line"><a name="l00923"></a><span class="lineno"> 923</span> A continuous loader is designed to load data from a source registry to a</div><div class="line"><a name="l00924"></a><span class="lineno"> 924</span> (possibly) non-empty destination. The loader can accommodate in a registry more</div><div class="line"><a name="l00925"></a><span class="lineno"> 925</span> than one snapshot in a sort of _continuous loading_ that updates the</div><div class="line"><a name="l00926"></a><span class="lineno"> 926</span> destination one step at a time.<br/></div><div class="line"><a name="l00927"></a><span class="lineno"> 927</span> Identifiers that entities originally had are not transferred to the target.</div><div class="line"><a name="l00928"></a><span class="lineno"> 928</span> Instead, the loader maps remote identifiers to local ones while restoring a</div><div class="line"><a name="l00929"></a><span class="lineno"> 929</span> snapshot. Because of that, this kind of loader offers a way to update</div><div class="line"><a name="l00930"></a><span class="lineno"> 930</span> automatically identifiers that are part of components or tags (as an example, as</div><div class="line"><a name="l00931"></a><span class="lineno"> 931</span> data members or gathered in a container).<br/></div><div class="line"><a name="l00932"></a><span class="lineno"> 932</span> Another difference with the snapshot loader is that the continuous loader does</div><div class="line"><a name="l00933"></a><span class="lineno"> 933</span> not need to work with the private data structures of a registry. Furthermore, it</div><div class="line"><a name="l00934"></a><span class="lineno"> 934</span> has an internal state that must persist over time. Therefore, there is no reason</div><div class="line"><a name="l00935"></a><span class="lineno"> 935</span> to create it by means of a registry, or to limit its lifetime to that of a</div><div class="line"><a name="l00936"></a><span class="lineno"> 936</span> temporary object.</div><div class="line"><a name="l00937"></a><span class="lineno"> 937</span> </div><div class="line"><a name="l00938"></a><span class="lineno"> 938</span> Example of use:</div><div class="line"><a name="l00939"></a><span class="lineno"> 939</span> </div><div class="line"><a name="l00940"></a><span class="lineno"> 940</span> ```cpp</div><div class="line"><a name="l00941"></a><span class="lineno"> 941</span> entt::ContinuousLoader<entity_type> loader{registry};</div><div class="line"><a name="l00942"></a><span class="lineno"> 942</span> InputArchive input;</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> loader.entities(input)</div><div class="line"><a name="l00945"></a><span class="lineno"> 945</span>  .destroyed(input)</div><div class="line"><a name="l00946"></a><span class="lineno"> 946</span>  .component<AComponent, AnotherComponent, DirtyComponent>(input, &DirtyComponent::parent, &DirtyComponent::child)</div><div class="line"><a name="l00947"></a><span class="lineno"> 947</span>  .tag<MyTag, DirtyTag>(input, &DirtyTag::container)</div><div class="line"><a name="l00948"></a><span class="lineno"> 948</span>  .orphans()</div><div class="line"><a name="l00949"></a><span class="lineno"> 949</span>  .shrink();</div><div class="line"><a name="l00950"></a><span class="lineno"> 950</span> ```</div><div class="line"><a name="l00951"></a><span class="lineno"> 951</span> </div><div class="line"><a name="l00952"></a><span class="lineno"> 952</span> It isn't necessary to invoke all these functions each and every time. What</div><div class="line"><a name="l00953"></a><span class="lineno"> 953</span> functions to use in which case mostly depends on the goal and there is not a</div><div class="line"><a name="l00954"></a><span class="lineno"> 954</span> golden rule to do that. For obvious reasons, what is important is that the data</div><div class="line"><a name="l00955"></a><span class="lineno"> 955</span> are restored in exactly the same order in which they were serialized.</div><div class="line"><a name="l00956"></a><span class="lineno"> 956</span> </div><div class="line"><a name="l00957"></a><span class="lineno"> 957</span> The `entities` and `destroyed` member functions restore groups of entities and</div><div class="line"><a name="l00958"></a><span class="lineno"> 958</span> map each entity to a local counterpart when required. In other terms, for each</div><div class="line"><a name="l00959"></a><span class="lineno"> 959</span> remote entity identifier not yet registered by the loader, the latter creates a</div><div class="line"><a name="l00960"></a><span class="lineno"> 960</span> local identifier so that it can keep the local entity in sync with the remote</div><div class="line"><a name="l00961"></a><span class="lineno"> 961</span> one.</div><div class="line"><a name="l00962"></a><span class="lineno"> 962</span> </div><div class="line"><a name="l00963"></a><span class="lineno"> 963</span> The `component` and `tag` member functions restore all and only the components</div><div class="line"><a name="l00964"></a><span class="lineno"> 964</span> and the tags specified and assign them to the right entities.<br/></div><div class="line"><a name="l00965"></a><span class="lineno"> 965</span> In case the component or the tag contains entities itself (either as data</div><div class="line"><a name="l00966"></a><span class="lineno"> 966</span> members of type `entity_type` or as containers of entities), the loader can</div><div class="line"><a name="l00967"></a><span class="lineno"> 967</span> update them automatically. To do that, it's enough to specify the data members</div><div class="line"><a name="l00968"></a><span class="lineno"> 968</span> to update as shown in the example.</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> The `orphans` member function literally destroys those entities that have</div><div class="line"><a name="l00971"></a><span class="lineno"> 971</span> neither components nor tags after a restore. It has exactly the same purpose</div><div class="line"><a name="l00972"></a><span class="lineno"> 972</span> described in the previous section and works the same way.</div><div class="line"><a name="l00973"></a><span class="lineno"> 973</span> </div><div class="line"><a name="l00974"></a><span class="lineno"> 974</span> Finally, `shrink` helps to purge local entities that no longer have a remote</div><div class="line"><a name="l00975"></a><span class="lineno"> 975</span> conterpart. Users should invoke this member function after restoring each</div><div class="line"><a name="l00976"></a><span class="lineno"> 976</span> snapshot, unless they know exactly what they are doing.</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> #### Archives</div><div class="line"><a name="l00979"></a><span class="lineno"> 979</span> </div><div class="line"><a name="l00980"></a><span class="lineno"> 980</span> Archives must publicly expose a predefined set of member functions. The API is</div><div class="line"><a name="l00981"></a><span class="lineno"> 981</span> straightforward and consists only of a group of function call operators that</div><div class="line"><a name="l00982"></a><span class="lineno"> 982</span> are invoked by the snapshot class and the loaders.</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> In particular:</div><div class="line"><a name="l00985"></a><span class="lineno"> 985</span> </div><div class="line"><a name="l00986"></a><span class="lineno"> 986</span> * An output archive, the one used when creating a snapshot, must expose a</div><div class="line"><a name="l00987"></a><span class="lineno"> 987</span>  function call operator with the following signature to store entities:</div><div class="line"><a name="l00988"></a><span class="lineno"> 988</span> </div><div class="line"><a name="l00989"></a><span class="lineno"> 989</span>  ```cpp</div><div class="line"><a name="l00990"></a><span class="lineno"> 990</span>  void operator()(Entity);</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> </div><div class="line"><a name="l00993"></a><span class="lineno"> 993</span>  Where `Entity` is the type of the entities used by the registry. Note that all</div><div class="line"><a name="l00994"></a><span class="lineno"> 994</span>  the member functions of the snapshot class make also an initial call to this</div><div class="line"><a name="l00995"></a><span class="lineno"> 995</span>  endpoint to save the _size_ of the set they are going to store.<br/></div><div class="line"><a name="l00996"></a><span class="lineno"> 996</span>  In addition, an archive must accept a pair of entity and either component or</div><div class="line"><a name="l00997"></a><span class="lineno"> 997</span>  tag for each type to be serialized. Therefore, given a type `T`, the archive</div><div class="line"><a name="l00998"></a><span class="lineno"> 998</span>  must contain a function call operator with the following signature:</div><div class="line"><a name="l00999"></a><span class="lineno"> 999</span> </div><div class="line"><a name="l01000"></a><span class="lineno"> 1000</span>  ```cpp</div><div class="line"><a name="l01001"></a><span class="lineno"> 1001</span>  void operator()(Entity, const T &);</div><div class="line"><a name="l01002"></a><span class="lineno"> 1002</span>  ```</div><div class="line"><a name="l01003"></a><span class="lineno"> 1003</span> </div><div class="line"><a name="l01004"></a><span class="lineno"> 1004</span>  The output archive can freely decide how to serialize the data. The register</div><div class="line"><a name="l01005"></a><span class="lineno"> 1005</span>  is not affected at all by the decision.</div><div class="line"><a name="l01006"></a><span class="lineno"> 1006</span> </div><div class="line"><a name="l01007"></a><span class="lineno"> 1007</span> * An input archive, the one used when restoring a snapshot, must expose a</div><div class="line"><a name="l01008"></a><span class="lineno"> 1008</span>  function call operator with the following signature to load entities:</div><div class="line"><a name="l01009"></a><span class="lineno"> 1009</span> </div><div class="line"><a name="l01010"></a><span class="lineno"> 1010</span>  ```cpp</div><div class="line"><a name="l01011"></a><span class="lineno"> 1011</span>  void operator()(Entity &);</div><div class="line"><a name="l01012"></a><span class="lineno"> 1012</span>  ```</div><div class="line"><a name="l01013"></a><span class="lineno"> 1013</span> </div><div class="line"><a name="l01014"></a><span class="lineno"> 1014</span>  Where `Entity` is the type of the entities used by the registry. Each time the</div><div class="line"><a name="l01015"></a><span class="lineno"> 1015</span>  function is invoked, the archive must read the next element from the</div><div class="line"><a name="l01016"></a><span class="lineno"> 1016</span>  underlying storage and copy it in the given variable. Note that all the member</div><div class="line"><a name="l01017"></a><span class="lineno"> 1017</span>  functions of a loader class make also an initial call to this endpoint to read</div><div class="line"><a name="l01018"></a><span class="lineno"> 1018</span>  the _size_ of the set they are going to load.<br/></div><div class="line"><a name="l01019"></a><span class="lineno"> 1019</span>  In addition, the archive must accept a pair of entity and either component or</div><div class="line"><a name="l01020"></a><span class="lineno"> 1020</span>  tag for each type to be restored. Therefore, given a type `T`, the archive</div><div class="line"><a name="l01021"></a><span class="lineno"> 1021</span>  must contain a function call operator with the following signature:</div><div class="line"><a name="l01022"></a><span class="lineno"> 1022</span> </div><div class="line"><a name="l01023"></a><span class="lineno"> 1023</span>  ```cpp</div><div class="line"><a name="l01024"></a><span class="lineno"> 1024</span>  void operator()(Entity &, T &);</div><div class="line"><a name="l01025"></a><span class="lineno"> 1025</span>  ```</div><div class="line"><a name="l01026"></a><span class="lineno"> 1026</span> </div><div class="line"><a name="l01027"></a><span class="lineno"> 1027</span>  Every time such an operator is invoked, the archive must read the next</div><div class="line"><a name="l01028"></a><span class="lineno"> 1028</span>  elements from the underlying storage and copy them in the given variables.</div><div class="line"><a name="l01029"></a><span class="lineno"> 1029</span> </div><div class="line"><a name="l01030"></a><span class="lineno"> 1030</span> #### One example to rule them all</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> `EnTT` comes with some examples (actually some tests) that show how to integrate</div><div class="line"><a name="l01033"></a><span class="lineno"> 1033</span> a well known library for serialization as an archive. It uses</div><div class="line"><a name="l01034"></a><span class="lineno"> 1034</span> [`Cereal C++`](https://uscilab.github.io/cereal/) under the hood, mainly</div><div class="line"><a name="l01035"></a><span class="lineno"> 1035</span> because I wanted to learn how it works at the time I was writing the code.</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> The code is not production-ready and it isn't neither the only nor (probably)</div><div class="line"><a name="l01038"></a><span class="lineno"> 1038</span> the best way to do it. However, feel free to use it at your own risk.</div><div class="line"><a name="l01039"></a><span class="lineno"> 1039</span> </div><div class="line"><a name="l01040"></a><span class="lineno"> 1040</span> The basic idea is to store everything in a group of queues in memory, then bring</div><div class="line"><a name="l01041"></a><span class="lineno"> 1041</span> everything back to the registry with different loaders.</div><div class="line"><a name="l01042"></a><span class="lineno"> 1042</span> </div><div class="line"><a name="l01043"></a><span class="lineno"> 1043</span> ### Prototype</div><div class="line"><a name="l01044"></a><span class="lineno"> 1044</span> </div><div class="line"><a name="l01045"></a><span class="lineno"> 1045</span> A prototype defines a type of an application in terms of its parts. They can be</div><div class="line"><a name="l01046"></a><span class="lineno"> 1046</span> used to assign components to entities of a registry at once.<br/></div><div class="line"><a name="l01047"></a><span class="lineno"> 1047</span> Roughly speaking, in most cases prototypes can be considered just as templates</div><div class="line"><a name="l01048"></a><span class="lineno"> 1048</span> to use to initialize entities according to _concepts_. In fact, users can create</div><div class="line"><a name="l01049"></a><span class="lineno"> 1049</span> how many prototypes they want, each one initialized differently from the others.</div><div class="line"><a name="l01050"></a><span class="lineno"> 1050</span> </div><div class="line"><a name="l01051"></a><span class="lineno"> 1051</span> The following is an example of use of a prototype:</div><div class="line"><a name="l01052"></a><span class="lineno"> 1052</span> </div><div class="line"><a name="l01053"></a><span class="lineno"> 1053</span> ```cpp</div><div class="line"><a name="l01054"></a><span class="lineno"> 1054</span> entt::DefaultRegistry registry;</div><div class="line"><a name="l01055"></a><span class="lineno"> 1055</span> entt::DefaultPrototype prototype{registry};</div><div class="line"><a name="l01056"></a><span class="lineno"> 1056</span> </div><div class="line"><a name="l01057"></a><span class="lineno"> 1057</span> prototype.set<Position>(100.f, 100.f);</div><div class="line"><a name="l01058"></a><span class="lineno"> 1058</span> prototype.set<Velocity>(0.f, 0.f);</div><div class="line"><a name="l01059"></a><span class="lineno"> 1059</span> </div><div class="line"><a name="l01060"></a><span class="lineno"> 1060</span> // ...</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> const auto entity = prototype();</div><div class="line"><a name="l01063"></a><span class="lineno"> 1063</span> ```</div><div class="line"><a name="l01064"></a><span class="lineno"> 1064</span> </div><div class="line"><a name="l01065"></a><span class="lineno"> 1065</span> To assign and remove components from a prototype, it offers two dedicated member</div><div class="line"><a name="l01066"></a><span class="lineno"> 1066</span> functions named `set` and `unset`. The `has` member function can be used to know</div><div class="line"><a name="l01067"></a><span class="lineno"> 1067</span> if a given prototype contains one or more components and the `get` member</div><div class="line"><a name="l01068"></a><span class="lineno"> 1068</span> function can be used to retrieve the components.</div><div class="line"><a name="l01069"></a><span class="lineno"> 1069</span> </div><div class="line"><a name="l01070"></a><span class="lineno"> 1070</span> Creating an entity from a prototype is straightforward:</div><div class="line"><a name="l01071"></a><span class="lineno"> 1071</span> </div><div class="line"><a name="l01072"></a><span class="lineno"> 1072</span> * To create a new entity from scratch and assign it a prototype, this is the way</div><div class="line"><a name="l01073"></a><span class="lineno"> 1073</span>  to go:</div><div class="line"><a name="l01074"></a><span class="lineno"> 1074</span>  ```cpp</div><div class="line"><a name="l01075"></a><span class="lineno"> 1075</span>  const auto entity = prototype();</div><div class="line"><a name="l01076"></a><span class="lineno"> 1076</span>  ```</div><div class="line"><a name="l01077"></a><span class="lineno"> 1077</span>  It is equivalent to the following invokation:</div><div class="line"><a name="l01078"></a><span class="lineno"> 1078</span>  ```cpp</div><div class="line"><a name="l01079"></a><span class="lineno"> 1079</span>  const auto entity = prototype.create();</div><div class="line"><a name="l01080"></a><span class="lineno"> 1080</span>  ```</div><div class="line"><a name="l01081"></a><span class="lineno"> 1081</span> </div><div class="line"><a name="l01082"></a><span class="lineno"> 1082</span> * In case we want to initialize an already existing entity, we can provide the</div><div class="line"><a name="l01083"></a><span class="lineno"> 1083</span>  `operator()` directly with the entity identifier:</div><div class="line"><a name="l01084"></a><span class="lineno"> 1084</span>  ```cpp</div><div class="line"><a name="l01085"></a><span class="lineno"> 1085</span>  prototype(entity);</div><div class="line"><a name="l01086"></a><span class="lineno"> 1086</span>  ```</div><div class="line"><a name="l01087"></a><span class="lineno"> 1087</span>  It is equivalent to the following invokation:</div><div class="line"><a name="l01088"></a><span class="lineno"> 1088</span>  ```cpp</div><div class="line"><a name="l01089"></a><span class="lineno"> 1089</span>  prototype.assign(entity);</div><div class="line"><a name="l01090"></a><span class="lineno"> 1090</span>  ```</div><div class="line"><a name="l01091"></a><span class="lineno"> 1091</span>  Note that existing components aren't overwritten in this case. Only those</div><div class="line"><a name="l01092"></a><span class="lineno"> 1092</span>  components that the entity doesn't own yet are copied over. All the other</div><div class="line"><a name="l01093"></a><span class="lineno"> 1093</span>  components remain unchanged.</div><div class="line"><a name="l01094"></a><span class="lineno"> 1094</span> </div><div class="line"><a name="l01095"></a><span class="lineno"> 1095</span> * Finally, to assign or replace all the components for an entity, thus</div><div class="line"><a name="l01096"></a><span class="lineno"> 1096</span>  overwriting existing ones:</div><div class="line"><a name="l01097"></a><span class="lineno"> 1097</span>  ```cpp</div><div class="line"><a name="l01098"></a><span class="lineno"> 1098</span>  prototype.accommodate(entity);</div><div class="line"><a name="l01099"></a><span class="lineno"> 1099</span>  ```</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> In the examples above, the prototype uses its underlying registry to create</div><div class="line"><a name="l01102"></a><span class="lineno"> 1102</span> entities and components both for its purposes and when it's cloned. To use a</div><div class="line"><a name="l01103"></a><span class="lineno"> 1103</span> different repository to clone a prototype, all the member functions accept also</div><div class="line"><a name="l01104"></a><span class="lineno"> 1104</span> a reference to a valid registry as a first argument.</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> Prototypes are a very useful tool that can save a lot of typing sometimes.</div><div class="line"><a name="l01107"></a><span class="lineno"> 1107</span> Furthermore, the codebase may be easier to maintain, since updating a prototype</div><div class="line"><a name="l01108"></a><span class="lineno"> 1108</span> is much less error prone than jumping around in the codebase to update all the</div><div class="line"><a name="l01109"></a><span class="lineno"> 1109</span> snippets copied and pasted around to initialize entities and components.</div><div class="line"><a name="l01110"></a><span class="lineno"> 1110</span> </div><div class="line"><a name="l01111"></a><span class="lineno"> 1111</span> ### Helpers</div><div class="line"><a name="l01112"></a><span class="lineno"> 1112</span> </div><div class="line"><a name="l01113"></a><span class="lineno"> 1113</span> The so called _helpers_ are small classes and functions mainly designed to offer</div><div class="line"><a name="l01114"></a><span class="lineno"> 1114</span> built-in support for the most basic functionalities.<br/></div><div class="line"><a name="l01115"></a><span class="lineno"> 1115</span> The list of helpers will grow longer as time passes and new ideas come out.</div><div class="line"><a name="l01116"></a><span class="lineno"> 1116</span> </div><div class="line"><a name="l01117"></a><span class="lineno"> 1117</span> #### Dependency function</div><div class="line"><a name="l01118"></a><span class="lineno"> 1118</span> </div><div class="line"><a name="l01119"></a><span class="lineno"> 1119</span> A _dependency function_ is a predefined listener, actually a function template</div><div class="line"><a name="l01120"></a><span class="lineno"> 1120</span> to use to automatically assign components to an entity when a type has a</div><div class="line"><a name="l01121"></a><span class="lineno"> 1121</span> dependency on some other types.<br/></div><div class="line"><a name="l01122"></a><span class="lineno"> 1122</span> The following adds components `AType` and `AnotherType` whenever `MyType` is</div><div class="line"><a name="l01123"></a><span class="lineno"> 1123</span> assigned to an entity:</div><div class="line"><a name="l01124"></a><span class="lineno"> 1124</span> </div><div class="line"><a name="l01125"></a><span class="lineno"> 1125</span> ```cpp</div><div class="line"><a name="l01126"></a><span class="lineno"> 1126</span> entt::dependency<AType, AnotherType>(registry.construction<MyType>());</div><div class="line"><a name="l01127"></a><span class="lineno"> 1127</span> ```</div><div class="line"><a name="l01128"></a><span class="lineno"> 1128</span> </div><div class="line"><a name="l01129"></a><span class="lineno"> 1129</span> A component is assigned to an entity and thus default initialized only in case</div><div class="line"><a name="l01130"></a><span class="lineno"> 1130</span> the entity itself hasn't it yet. It means that already existent components won't</div><div class="line"><a name="l01131"></a><span class="lineno"> 1131</span> be overriden.<br/></div><div class="line"><a name="l01132"></a><span class="lineno"> 1132</span> A dependency can easily be broken by means of the same function template:</div><div class="line"><a name="l01133"></a><span class="lineno"> 1133</span> </div><div class="line"><a name="l01134"></a><span class="lineno"> 1134</span> ```cpp</div><div class="line"><a name="l01135"></a><span class="lineno"> 1135</span> entt::dependency<AType, AnotherType>(entt::break_t{}, registry.construction<MyType>());</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> ## View: to persist or not to persist?</div><div class="line"><a name="l01139"></a><span class="lineno"> 1139</span> </div><div class="line"><a name="l01140"></a><span class="lineno"> 1140</span> First of all, it is worth answering an obvious question: why views?<br/></div><div class="line"><a name="l01141"></a><span class="lineno"> 1141</span> Roughly speaking, they are a good tool to enforce single responsibility. A</div><div class="line"><a name="l01142"></a><span class="lineno"> 1142</span> system that has access to a registry can create and destroy entities, as well as</div><div class="line"><a name="l01143"></a><span class="lineno"> 1143</span> assign and remove components. On the other side, a system that has access to a</div><div class="line"><a name="l01144"></a><span class="lineno"> 1144</span> view can only iterate entities and their components, then read or update the</div><div class="line"><a name="l01145"></a><span class="lineno"> 1145</span> data members of the latter.<br/></div><div class="line"><a name="l01146"></a><span class="lineno"> 1146</span> It is a subtle difference that can help designing a better software sometimes.</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> There are mainly three kinds of views: standard (also known as `View`),</div><div class="line"><a name="l01149"></a><span class="lineno"> 1149</span> persistent (also known as `PersistentView`) and raw (also known as</div><div class="line"><a name="l01150"></a><span class="lineno"> 1150</span> `RawView`).<br/></div><div class="line"><a name="l01151"></a><span class="lineno"> 1151</span> All of them have pros and cons to take in consideration. In particular:</div><div class="line"><a name="l01152"></a><span class="lineno"> 1152</span> </div><div class="line"><a name="l01153"></a><span class="lineno"> 1153</span> * Standard views:</div><div class="line"><a name="l01154"></a><span class="lineno"> 1154</span> </div><div class="line"><a name="l01155"></a><span class="lineno"> 1155</span>  Pros:</div><div class="line"><a name="l01156"></a><span class="lineno"> 1156</span> </div><div class="line"><a name="l01157"></a><span class="lineno"> 1157</span>  * They work out-of-the-box and don't require any dedicated data structure.</div><div class="line"><a name="l01158"></a><span class="lineno"> 1158</span>  * Creating and destroying them isn't expensive at all because they don't have</div><div class="line"><a name="l01159"></a><span class="lineno"> 1159</span>  any type of initialization.</div><div class="line"><a name="l01160"></a><span class="lineno"> 1160</span>  * They are the best tool for iterating entities for a single component.</div><div class="line"><a name="l01161"></a><span class="lineno"> 1161</span>  * They are the best tool for iterating entities for multiple components when</div><div class="line"><a name="l01162"></a><span class="lineno"> 1162</span>  one of the components is assigned to a significantly low number of entities.</div><div class="line"><a name="l01163"></a><span class="lineno"> 1163</span>  * They don't affect any other operations of the registry.</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>  Cons:</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>  * Their performance tend to degenerate when the number of components to</div><div class="line"><a name="l01168"></a><span class="lineno"> 1168</span>  iterate grows up and the most of the entities have all of them.</div><div class="line"><a name="l01169"></a><span class="lineno"> 1169</span> </div><div class="line"><a name="l01170"></a><span class="lineno"> 1170</span> * Persistent views:</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>  Pros:</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>  * Once prepared, creating and destroying them isn't expensive at all because</div><div class="line"><a name="l01175"></a><span class="lineno"> 1175</span>  they don't have any type of initialization.</div><div class="line"><a name="l01176"></a><span class="lineno"> 1176</span>  * They are the best tool for iterating entities for multiple components when</div><div class="line"><a name="l01177"></a><span class="lineno"> 1177</span>  most entities have them all.</div><div class="line"><a name="l01178"></a><span class="lineno"> 1178</span> </div><div class="line"><a name="l01179"></a><span class="lineno"> 1179</span>  Cons:</div><div class="line"><a name="l01180"></a><span class="lineno"> 1180</span> </div><div class="line"><a name="l01181"></a><span class="lineno"> 1181</span>  * They have dedicated data structures and thus affect the memory usage to a</div><div class="line"><a name="l01182"></a><span class="lineno"> 1182</span>  minimal extent.</div><div class="line"><a name="l01183"></a><span class="lineno"> 1183</span>  * If not previously prepared, the first time they are used they go through an</div><div class="line"><a name="l01184"></a><span class="lineno"> 1184</span>  initialization step that could take a while.</div><div class="line"><a name="l01185"></a><span class="lineno"> 1185</span>  * They affect to a minimum the creation and destruction of entities and</div><div class="line"><a name="l01186"></a><span class="lineno"> 1186</span>  components. In other terms: the more persistent views there will be, the</div><div class="line"><a name="l01187"></a><span class="lineno"> 1187</span>  less performing will be creating and destroying entities and components.</div><div class="line"><a name="l01188"></a><span class="lineno"> 1188</span> </div><div class="line"><a name="l01189"></a><span class="lineno"> 1189</span> * Raw views:</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>  Pros:</div><div class="line"><a name="l01192"></a><span class="lineno"> 1192</span> </div><div class="line"><a name="l01193"></a><span class="lineno"> 1193</span>  * They work out-of-the-box and don't require any dedicated data structure.</div><div class="line"><a name="l01194"></a><span class="lineno"> 1194</span>  * Creating and destroying them isn't expensive at all because they don't have</div><div class="line"><a name="l01195"></a><span class="lineno"> 1195</span>  any type of initialization.</div><div class="line"><a name="l01196"></a><span class="lineno"> 1196</span>  * They are the best tool for iterating components when it is not necessary to</div><div class="line"><a name="l01197"></a><span class="lineno"> 1197</span>  know which entities they belong to.</div><div class="line"><a name="l01198"></a><span class="lineno"> 1198</span>  * They don't affect any other operations of the registry.</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>  Cons:</div><div class="line"><a name="l01201"></a><span class="lineno"> 1201</span> </div><div class="line"><a name="l01202"></a><span class="lineno"> 1202</span>  * They can be used to iterate only one type of component at a time.</div><div class="line"><a name="l01203"></a><span class="lineno"> 1203</span>  * They don't return the entity to which a component belongs to the caller.</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> To sum up and as a rule of thumb:</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> * Use a raw view to iterate components only (no entities) for a given type.</div><div class="line"><a name="l01208"></a><span class="lineno"> 1208</span> * Use a standard view to iterate entities and components for a single type.</div><div class="line"><a name="l01209"></a><span class="lineno"> 1209</span> * Use a standard view to iterate entities and components for multiple types when</div><div class="line"><a name="l01210"></a><span class="lineno"> 1210</span>  the number of types is low. Standard views are really optimized and persistent</div><div class="line"><a name="l01211"></a><span class="lineno"> 1211</span>  views won't add much in this case.</div><div class="line"><a name="l01212"></a><span class="lineno"> 1212</span> * Use a standard view to iterate entities and components for multiple types when</div><div class="line"><a name="l01213"></a><span class="lineno"> 1213</span>  a significantly low number of entities have one of the components.</div><div class="line"><a name="l01214"></a><span class="lineno"> 1214</span> * Use a standard view in all those cases where a persistent view would give a</div><div class="line"><a name="l01215"></a><span class="lineno"> 1215</span>  boost to performance but the iteration isn't performed frequently.</div><div class="line"><a name="l01216"></a><span class="lineno"> 1216</span> * Prepare and use a persistent view when you want to iterate only entities for</div><div class="line"><a name="l01217"></a><span class="lineno"> 1217</span>  multiple components.</div><div class="line"><a name="l01218"></a><span class="lineno"> 1218</span> * Prepare and use a persistent view when you want to iterate entities for</div><div class="line"><a name="l01219"></a><span class="lineno"> 1219</span>  multiple components and each component is assigned to a great number of</div><div class="line"><a name="l01220"></a><span class="lineno"> 1220</span>  entities but the intersection between the sets of entities is small.</div><div class="line"><a name="l01221"></a><span class="lineno"> 1221</span> * Prepare and use a persistent view in all the cases where a standard view</div><div class="line"><a name="l01222"></a><span class="lineno"> 1222</span>  wouldn't fit well otherwise.</div><div class="line"><a name="l01223"></a><span class="lineno"> 1223</span> </div><div class="line"><a name="l01224"></a><span class="lineno"> 1224</span> To easily iterate entities and components, all the views offer the common</div><div class="line"><a name="l01225"></a><span class="lineno"> 1225</span> `begin` and `end` member functions that allow users to use a view in a typical</div><div class="line"><a name="l01226"></a><span class="lineno"> 1226</span> range-for loop. Almost all the views offer also a *more functional* `each`</div><div class="line"><a name="l01227"></a><span class="lineno"> 1227</span> member function that accepts a callback for convenience.<br/></div><div class="line"><a name="l01228"></a><span class="lineno"> 1228</span> Continue reading for more details or refer to the inline documentation.</div><div class="line"><a name="l01229"></a><span class="lineno"> 1229</span> </div><div class="line"><a name="l01230"></a><span class="lineno"> 1230</span> ### Standard View</div><div class="line"><a name="l01231"></a><span class="lineno"> 1231</span> </div><div class="line"><a name="l01232"></a><span class="lineno"> 1232</span> A standard view behaves differently if it's constructed for a single component</div><div class="line"><a name="l01233"></a><span class="lineno"> 1233</span> or if it has been requested to iterate multiple components. Even the API is</div><div class="line"><a name="l01234"></a><span class="lineno"> 1234</span> different in the two cases.<br/></div><div class="line"><a name="l01235"></a><span class="lineno"> 1235</span> All that they share is the way they are created by means of a registry:</div><div class="line"><a name="l01236"></a><span class="lineno"> 1236</span> </div><div class="line"><a name="l01237"></a><span class="lineno"> 1237</span> ```cpp</div><div class="line"><a name="l01238"></a><span class="lineno"> 1238</span> // single component standard view</div><div class="line"><a name="l01239"></a><span class="lineno"> 1239</span> auto single = registry.view<Position>();</div><div class="line"><a name="l01240"></a><span class="lineno"> 1240</span> </div><div class="line"><a name="l01241"></a><span class="lineno"> 1241</span> // multi component standard view</div><div class="line"><a name="l01242"></a><span class="lineno"> 1242</span> auto multi = registry.view<Position, Velocity>();</div><div class="line"><a name="l01243"></a><span class="lineno"> 1243</span> ```</div><div class="line"><a name="l01244"></a><span class="lineno"> 1244</span> </div><div class="line"><a name="l01245"></a><span class="lineno"> 1245</span> For all that remains, it's worth discussing them separately.<br/></div><div class="line"><a name="l01246"></a><span class="lineno"> 1246</span> </div><div class="line"><a name="l01247"></a><span class="lineno"> 1247</span> #### Single component standard view</div><div class="line"><a name="l01248"></a><span class="lineno"> 1248</span> </div><div class="line"><a name="l01249"></a><span class="lineno"> 1249</span> Single component standard views are specialized in order to give a boost in</div><div class="line"><a name="l01250"></a><span class="lineno"> 1250</span> terms of performance in all the situation. This kind of views can access the</div><div class="line"><a name="l01251"></a><span class="lineno"> 1251</span> underlying data structures directly and avoid superfluous checks.<br/></div><div class="line"><a name="l01252"></a><span class="lineno"> 1252</span> They offer a bunch of functionalities to get the number of entities they are</div><div class="line"><a name="l01253"></a><span class="lineno"> 1253</span> going to return and a raw access to the entity list as well as to the component</div><div class="line"><a name="l01254"></a><span class="lineno"> 1254</span> list. It's also possible to ask a view if it contains a given entity.<br/></div><div class="line"><a name="l01255"></a><span class="lineno"> 1255</span> Refer to the inline documentation for all the details.</div><div class="line"><a name="l01256"></a><span class="lineno"> 1256</span> </div><div class="line"><a name="l01257"></a><span class="lineno"> 1257</span> There is no need to store views around for they are extremely cheap to</div><div class="line"><a name="l01258"></a><span class="lineno"> 1258</span> construct, even though they can be copied without problems and reused freely. In</div><div class="line"><a name="l01259"></a><span class="lineno"> 1259</span> fact, they return newly created and correctly initialized iterators whenever</div><div class="line"><a name="l01260"></a><span class="lineno"> 1260</span> `begin` or `end` are invoked.<br/></div><div class="line"><a name="l01261"></a><span class="lineno"> 1261</span> To iterate a single component standard view, either use it in range-for loop:</div><div class="line"><a name="l01262"></a><span class="lineno"> 1262</span> </div><div class="line"><a name="l01263"></a><span class="lineno"> 1263</span> ```cpp</div><div class="line"><a name="l01264"></a><span class="lineno"> 1264</span> auto view = registry.view<Renderable>();</div><div class="line"><a name="l01265"></a><span class="lineno"> 1265</span> </div><div class="line"><a name="l01266"></a><span class="lineno"> 1266</span> for(auto entity: view) {</div><div class="line"><a name="l01267"></a><span class="lineno"> 1267</span>  Renderable &renderable = view.get(entity);</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>  // ...</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> ```</div><div class="line"><a name="l01272"></a><span class="lineno"> 1272</span> </div><div class="line"><a name="l01273"></a><span class="lineno"> 1273</span> Or rely on the `each` member function to iterate entities and get all their</div><div class="line"><a name="l01274"></a><span class="lineno"> 1274</span> components at once:</div><div class="line"><a name="l01275"></a><span class="lineno"> 1275</span> </div><div class="line"><a name="l01276"></a><span class="lineno"> 1276</span> ```cpp</div><div class="line"><a name="l01277"></a><span class="lineno"> 1277</span> registry.view<Renderable>().each([](auto entity, auto &renderable) {</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> });</div><div class="line"><a name="l01280"></a><span class="lineno"> 1280</span> ```</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> Performance are more or less the same. The best approach depends mainly on</div><div class="line"><a name="l01283"></a><span class="lineno"> 1283</span> whether all the components have to be accessed or not.</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> **Note**: prefer the `get` member function of a view instead of the `get` member</div><div class="line"><a name="l01286"></a><span class="lineno"> 1286</span> function template of a registry during iterations, if possible. However, keep in</div><div class="line"><a name="l01287"></a><span class="lineno"> 1287</span> mind that it works only with the components of the view itself.</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> #### Multi component standard view</div><div class="line"><a name="l01290"></a><span class="lineno"> 1290</span> </div><div class="line"><a name="l01291"></a><span class="lineno"> 1291</span> Multi component standard views iterate entities that have at least all the given</div><div class="line"><a name="l01292"></a><span class="lineno"> 1292</span> components in their bags. During construction, these views look at the number of</div><div class="line"><a name="l01293"></a><span class="lineno"> 1293</span> entities available for each component and pick up a reference to the smallest</div><div class="line"><a name="l01294"></a><span class="lineno"> 1294</span> set of candidates in order to speed up iterations.<br/></div><div class="line"><a name="l01295"></a><span class="lineno"> 1295</span> They offer fewer functionalities than their companion views for single</div><div class="line"><a name="l01296"></a><span class="lineno"> 1296</span> component. In particular, a multi component standard view exposes utility</div><div class="line"><a name="l01297"></a><span class="lineno"> 1297</span> functions to get the estimated number of entities it is going to return and to</div><div class="line"><a name="l01298"></a><span class="lineno"> 1298</span> know whether it's empty or not. It's also possible to ask a view if it contains</div><div class="line"><a name="l01299"></a><span class="lineno"> 1299</span> a given entity.<br/></div><div class="line"><a name="l01300"></a><span class="lineno"> 1300</span> Refer to the inline documentation for all the details.</div><div class="line"><a name="l01301"></a><span class="lineno"> 1301</span> </div><div class="line"><a name="l01302"></a><span class="lineno"> 1302</span> There is no need to store views around for they are extremely cheap to</div><div class="line"><a name="l01303"></a><span class="lineno"> 1303</span> construct, even though they can be copied without problems and reused freely. In</div><div class="line"><a name="l01304"></a><span class="lineno"> 1304</span> fact, they return newly created and correctly initialized iterators whenever</div><div class="line"><a name="l01305"></a><span class="lineno"> 1305</span> `begin` or `end` are invoked.<br/></div><div class="line"><a name="l01306"></a><span class="lineno"> 1306</span> To iterate a multi component standard view, either use it in range-for loop:</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> ```cpp</div><div class="line"><a name="l01309"></a><span class="lineno"> 1309</span> auto view = registry.view<Position, Velocity>();</div><div class="line"><a name="l01310"></a><span class="lineno"> 1310</span> </div><div class="line"><a name="l01311"></a><span class="lineno"> 1311</span> for(auto entity: view) {</div><div class="line"><a name="l01312"></a><span class="lineno"> 1312</span>  // a component at a time ...</div><div class="line"><a name="l01313"></a><span class="lineno"> 1313</span>  Position &position = view.get<Position>(entity);</div><div class="line"><a name="l01314"></a><span class="lineno"> 1314</span>  Velocity &velocity = view.get<Velocity>(entity);</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>  // ... or multiple components at once</div><div class="line"><a name="l01317"></a><span class="lineno"> 1317</span>  std::tuple<Position &, Velocity &> tup = view.get<Position, Velocity>(entity);</div><div class="line"><a name="l01318"></a><span class="lineno"> 1318</span> </div><div class="line"><a name="l01319"></a><span class="lineno"> 1319</span>  // ...</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> </div><div class="line"><a name="l01323"></a><span class="lineno"> 1323</span> Or rely on the `each` member function to iterate entities and get all their</div><div class="line"><a name="l01324"></a><span class="lineno"> 1324</span> components at once:</div><div class="line"><a name="l01325"></a><span class="lineno"> 1325</span> </div><div class="line"><a name="l01326"></a><span class="lineno"> 1326</span> ```cpp</div><div class="line"><a name="l01327"></a><span class="lineno"> 1327</span> registry.view<Position, Velocity>().each([](auto entity, auto &position, auto &velocity) {</div><div class="line"><a name="l01328"></a><span class="lineno"> 1328</span>  // ...</div><div class="line"><a name="l01329"></a><span class="lineno"> 1329</span> });</div><div class="line"><a name="l01330"></a><span class="lineno"> 1330</span> ```</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> Performance are more or less the same. The best approach depends mainly on</div><div class="line"><a name="l01333"></a><span class="lineno"> 1333</span> whether all the components have to be accessed or not.</div><div class="line"><a name="l01334"></a><span class="lineno"> 1334</span> </div><div class="line"><a name="l01335"></a><span class="lineno"> 1335</span> **Note**: prefer the `get` member function of a view instead of the `get` member</div><div class="line"><a name="l01336"></a><span class="lineno"> 1336</span> function template of a registry during iterations, if possible. However, keep in</div><div class="line"><a name="l01337"></a><span class="lineno"> 1337</span> mind that it works only with the components of the view itself.</div><div class="line"><a name="l01338"></a><span class="lineno"> 1338</span> </div><div class="line"><a name="l01339"></a><span class="lineno"> 1339</span> ### Persistent View</div><div class="line"><a name="l01340"></a><span class="lineno"> 1340</span> </div><div class="line"><a name="l01341"></a><span class="lineno"> 1341</span> A persistent view returns all the entities and only the entities that have at</div><div class="line"><a name="l01342"></a><span class="lineno"> 1342</span> least the given components. Moreover, it's guaranteed that the entity list is</div><div class="line"><a name="l01343"></a><span class="lineno"> 1343</span> tightly packed in memory for fast iterations.<br/></div><div class="line"><a name="l01344"></a><span class="lineno"> 1344</span> In general, persistent views don't stay true to the order of any set of</div><div class="line"><a name="l01345"></a><span class="lineno"> 1345</span> components unless users explicitly sort them.</div><div class="line"><a name="l01346"></a><span class="lineno"> 1346</span> </div><div class="line"><a name="l01347"></a><span class="lineno"> 1347</span> Persistent views can be used only to iterate multiple components. To create this</div><div class="line"><a name="l01348"></a><span class="lineno"> 1348</span> kind of views, the tag `persistent_t` must also be used in order to disambiguate</div><div class="line"><a name="l01349"></a><span class="lineno"> 1349</span> overloads of the `view` member function:</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> ```cpp</div><div class="line"><a name="l01352"></a><span class="lineno"> 1352</span> auto view = registry.view<Position, Velocity>(entt::persistent_t{});</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> </div><div class="line"><a name="l01355"></a><span class="lineno"> 1355</span> There is no need to store views around for they are extremely cheap to</div><div class="line"><a name="l01356"></a><span class="lineno"> 1356</span> construct, even though they can be copied without problems and reused freely. In</div><div class="line"><a name="l01357"></a><span class="lineno"> 1357</span> fact, they return newly created and correctly initialized iterators whenever</div><div class="line"><a name="l01358"></a><span class="lineno"> 1358</span> `begin` or `end` are invoked.<br/></div><div class="line"><a name="l01359"></a><span class="lineno"> 1359</span> That being said, persistent views perform an initialization step the very first</div><div class="line"><a name="l01360"></a><span class="lineno"> 1360</span> time they are constructed and this could be quite costly. To avoid it, consider</div><div class="line"><a name="l01361"></a><span class="lineno"> 1361</span> asking to the registry to _prepare_ them when no entities have been created yet:</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> ```cpp</div><div class="line"><a name="l01364"></a><span class="lineno"> 1364</span> registry.prepare<Position, Velocity>();</div><div class="line"><a name="l01365"></a><span class="lineno"> 1365</span> ```</div><div class="line"><a name="l01366"></a><span class="lineno"> 1366</span> </div><div class="line"><a name="l01367"></a><span class="lineno"> 1367</span> If the registry is empty, preparation is extremely fast. Moreover the `prepare`</div><div class="line"><a name="l01368"></a><span class="lineno"> 1368</span> member function template is idempotent. Feel free to invoke it even more than</div><div class="line"><a name="l01369"></a><span class="lineno"> 1369</span> once: if the view has been already prepared before, the function returns</div><div class="line"><a name="l01370"></a><span class="lineno"> 1370</span> immediately and does nothing.</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> A persistent view offers a bunch of functionalities to get the number of</div><div class="line"><a name="l01373"></a><span class="lineno"> 1373</span> entities it's going to return, a raw access to the entity list and the</div><div class="line"><a name="l01374"></a><span class="lineno"> 1374</span> possibility to sort the underlying data structures according to the order of one</div><div class="line"><a name="l01375"></a><span class="lineno"> 1375</span> of the components for which it has been constructed. It's also possible to ask a</div><div class="line"><a name="l01376"></a><span class="lineno"> 1376</span> view if it contains a given entity.<br/></div><div class="line"><a name="l01377"></a><span class="lineno"> 1377</span> Refer to the inline documentation for all the details.</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> To iterate a persistent view, either use it in range-for loop:</div><div class="line"><a name="l01380"></a><span class="lineno"> 1380</span> </div><div class="line"><a name="l01381"></a><span class="lineno"> 1381</span> ```cpp</div><div class="line"><a name="l01382"></a><span class="lineno"> 1382</span> auto view = registry.view<Position, Velocity>(entt::persistent_t{});</div><div class="line"><a name="l01383"></a><span class="lineno"> 1383</span> </div><div class="line"><a name="l01384"></a><span class="lineno"> 1384</span> for(auto entity: view) {</div><div class="line"><a name="l01385"></a><span class="lineno"> 1385</span>  // a component at a time ...</div><div class="line"><a name="l01386"></a><span class="lineno"> 1386</span>  Position &position = view.get<Position>(entity);</div><div class="line"><a name="l01387"></a><span class="lineno"> 1387</span>  Velocity &velocity = view.get<Velocity>(entity);</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>  // ... or multiple components at once</div><div class="line"><a name="l01390"></a><span class="lineno"> 1390</span>  std::tuple<Position &, Velocity &> tup = view.get<Position, Velocity>(entity);</div><div class="line"><a name="l01391"></a><span class="lineno"> 1391</span> </div><div class="line"><a name="l01392"></a><span class="lineno"> 1392</span>  // ...</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> ```</div><div class="line"><a name="l01395"></a><span class="lineno"> 1395</span> </div><div class="line"><a name="l01396"></a><span class="lineno"> 1396</span> Or rely on the `each` member function to iterate entities and get all their</div><div class="line"><a name="l01397"></a><span class="lineno"> 1397</span> components at once:</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> ```cpp</div><div class="line"><a name="l01400"></a><span class="lineno"> 1400</span> registry.view<Position, Velocity>(entt::persistent_t{}).each([](auto entity, auto &position, auto &velocity) {</div><div class="line"><a name="l01401"></a><span class="lineno"> 1401</span>  // ...</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> ```</div><div class="line"><a name="l01404"></a><span class="lineno"> 1404</span> </div><div class="line"><a name="l01405"></a><span class="lineno"> 1405</span> Performance are more or less the same. The best approach depends mainly on</div><div class="line"><a name="l01406"></a><span class="lineno"> 1406</span> whether all the components have to be accessed or not.</div><div class="line"><a name="l01407"></a><span class="lineno"> 1407</span> </div><div class="line"><a name="l01408"></a><span class="lineno"> 1408</span> **Note**: prefer the `get` member function of a view instead of the `get` member</div><div class="line"><a name="l01409"></a><span class="lineno"> 1409</span> function template of a registry during iterations, if possible. However, keep in</div><div class="line"><a name="l01410"></a><span class="lineno"> 1410</span> mind that it works only with the components of the view itself.</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> ### Raw View</div><div class="line"><a name="l01413"></a><span class="lineno"> 1413</span> </div><div class="line"><a name="l01414"></a><span class="lineno"> 1414</span> Raw views return all the components of a given type. This kind of views can</div><div class="line"><a name="l01415"></a><span class="lineno"> 1415</span> access components directly and avoid extra indirections like when components are</div><div class="line"><a name="l01416"></a><span class="lineno"> 1416</span> accessed via an entity identifier.<br/></div><div class="line"><a name="l01417"></a><span class="lineno"> 1417</span> They offer a bunch of functionalities to get the number of instances they are</div><div class="line"><a name="l01418"></a><span class="lineno"> 1418</span> going to return and a raw access to the entity list as well as to the component</div><div class="line"><a name="l01419"></a><span class="lineno"> 1419</span> list.<br/></div><div class="line"><a name="l01420"></a><span class="lineno"> 1420</span> Refer to the inline documentation for all the details.</div><div class="line"><a name="l01421"></a><span class="lineno"> 1421</span> </div><div class="line"><a name="l01422"></a><span class="lineno"> 1422</span> Raw views can be used only to iterate components for a single type. To create</div><div class="line"><a name="l01423"></a><span class="lineno"> 1423</span> this kind of views, the tag `raw_t` must also be used in order to disambiguate</div><div class="line"><a name="l01424"></a><span class="lineno"> 1424</span> overloads of the `view` member function:</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> ```cpp</div><div class="line"><a name="l01427"></a><span class="lineno"> 1427</span> auto view = registry.view<Renderable>(entt::raw_t{});</div><div class="line"><a name="l01428"></a><span class="lineno"> 1428</span> ```</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> There is no need to store views around for they are extremely cheap to</div><div class="line"><a name="l01431"></a><span class="lineno"> 1431</span> construct, even though they can be copied without problems and reused freely. In</div><div class="line"><a name="l01432"></a><span class="lineno"> 1432</span> fact, they return newly created and correctly initialized iterators whenever</div><div class="line"><a name="l01433"></a><span class="lineno"> 1433</span> `begin` or `end` are invoked.<br/></div><div class="line"><a name="l01434"></a><span class="lineno"> 1434</span> To iterate a raw view, use it in range-for loop:</div><div class="line"><a name="l01435"></a><span class="lineno"> 1435</span> </div><div class="line"><a name="l01436"></a><span class="lineno"> 1436</span> ```cpp</div><div class="line"><a name="l01437"></a><span class="lineno"> 1437</span> auto view = registry.view<Renderable>(entt::raw_t{});</div><div class="line"><a name="l01438"></a><span class="lineno"> 1438</span> </div><div class="line"><a name="l01439"></a><span class="lineno"> 1439</span> for(auto &&component: raw) {</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> }</div><div class="line"><a name="l01442"></a><span class="lineno"> 1442</span> ```</div><div class="line"><a name="l01443"></a><span class="lineno"> 1443</span> </div><div class="line"><a name="l01444"></a><span class="lineno"> 1444</span> **Note**: raw views don't have the `each` nor the `get` member function for</div><div class="line"><a name="l01445"></a><span class="lineno"> 1445</span> obvious reasons. The former would only return the components and therefore it</div><div class="line"><a name="l01446"></a><span class="lineno"> 1446</span> would be redundant, the latter isn't required at all.</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> ### Give me everything</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> Views are narrow windows on the entire list of entities. They work by filtering</div><div class="line"><a name="l01451"></a><span class="lineno"> 1451</span> entities according to their components.<br/></div><div class="line"><a name="l01452"></a><span class="lineno"> 1452</span> In some cases there may be the need to iterate all the entities still in use</div><div class="line"><a name="l01453"></a><span class="lineno"> 1453</span> regardless of their components. The registry offers a specific member function</div><div class="line"><a name="l01454"></a><span class="lineno"> 1454</span> to do that:</div><div class="line"><a name="l01455"></a><span class="lineno"> 1455</span> </div><div class="line"><a name="l01456"></a><span class="lineno"> 1456</span> ```cpp</div><div class="line"><a name="l01457"></a><span class="lineno"> 1457</span> registry.each([](auto entity) {</div><div class="line"><a name="l01458"></a><span class="lineno"> 1458</span>  // ...</div><div class="line"><a name="l01459"></a><span class="lineno"> 1459</span> });</div><div class="line"><a name="l01460"></a><span class="lineno"> 1460</span> ```</div><div class="line"><a name="l01461"></a><span class="lineno"> 1461</span> </div><div class="line"><a name="l01462"></a><span class="lineno"> 1462</span> It returns to the caller all the entities that are still in use by means of the</div><div class="line"><a name="l01463"></a><span class="lineno"> 1463</span> given function.<br/></div><div class="line"><a name="l01464"></a><span class="lineno"> 1464</span> As a rule of thumb, consider using a view if the goal is to iterate entities</div><div class="line"><a name="l01465"></a><span class="lineno"> 1465</span> that have a determinate set of components. A view is usually much faster than</div><div class="line"><a name="l01466"></a><span class="lineno"> 1466</span> combining this function with a bunch of custom tests.<br/></div><div class="line"><a name="l01467"></a><span class="lineno"> 1467</span> In all the other cases, this is the way to go.</div><div class="line"><a name="l01468"></a><span class="lineno"> 1468</span> </div><div class="line"><a name="l01469"></a><span class="lineno"> 1469</span> There exists also another member function to use to retrieve orphans. An orphan</div><div class="line"><a name="l01470"></a><span class="lineno"> 1470</span> is an entity that is still in use and has neither assigned components nor</div><div class="line"><a name="l01471"></a><span class="lineno"> 1471</span> tags.<br/></div><div class="line"><a name="l01472"></a><span class="lineno"> 1472</span> The signature of the function is the same of `each`:</div><div class="line"><a name="l01473"></a><span class="lineno"> 1473</span> </div><div class="line"><a name="l01474"></a><span class="lineno"> 1474</span> ```cpp</div><div class="line"><a name="l01475"></a><span class="lineno"> 1475</span> registry.orphans([](auto entity) {</div><div class="line"><a name="l01476"></a><span class="lineno"> 1476</span>  // ...</div><div class="line"><a name="l01477"></a><span class="lineno"> 1477</span> });</div><div class="line"><a name="l01478"></a><span class="lineno"> 1478</span> ```</div><div class="line"><a name="l01479"></a><span class="lineno"> 1479</span> </div><div class="line"><a name="l01480"></a><span class="lineno"> 1480</span> To test the _orphanity_ of a single entity, use the member function `orphan`</div><div class="line"><a name="l01481"></a><span class="lineno"> 1481</span> instead. It accepts a valid entity identifer as an argument and returns true in</div><div class="line"><a name="l01482"></a><span class="lineno"> 1482</span> case the entity is an orphan, false otherwise.</div><div class="line"><a name="l01483"></a><span class="lineno"> 1483</span> </div><div class="line"><a name="l01484"></a><span class="lineno"> 1484</span> In general, all these functions can result in poor performance.<br/></div><div class="line"><a name="l01485"></a><span class="lineno"> 1485</span> `each` is fairly slow because of some checks it performs on each and every</div><div class="line"><a name="l01486"></a><span class="lineno"> 1486</span> entity. For similar reasons, `orphans` can be even slower. Both functions should</div><div class="line"><a name="l01487"></a><span class="lineno"> 1487</span> not be used frequently to avoid the risk of a performance hit.</div><div class="line"><a name="l01488"></a><span class="lineno"> 1488</span> </div><div class="line"><a name="l01489"></a><span class="lineno"> 1489</span> ## Side notes</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> * Entity identifiers are numbers and nothing more. They are not classes and they</div><div class="line"><a name="l01492"></a><span class="lineno"> 1492</span>  have no member functions at all. As already mentioned, do no try to inspect or</div><div class="line"><a name="l01493"></a><span class="lineno"> 1493</span>  modify an entity descriptor in any way.</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> * As shown in the examples above, the preferred way to get references to the</div><div class="line"><a name="l01496"></a><span class="lineno"> 1496</span>  components while iterating a view is by using the view itself. It's a faster</div><div class="line"><a name="l01497"></a><span class="lineno"> 1497</span>  alternative to the `get` member function template that is part of the API of</div><div class="line"><a name="l01498"></a><span class="lineno"> 1498</span>  the `Registry`. This is because the registry must ensure that a pool for the</div><div class="line"><a name="l01499"></a><span class="lineno"> 1499</span>  given component exists before to use it; on the other side, views force the</div><div class="line"><a name="l01500"></a><span class="lineno"> 1500</span>  construction of the pools for all their components and access them directly,</div><div class="line"><a name="l01501"></a><span class="lineno"> 1501</span>  thus avoiding all the checks.</div><div class="line"><a name="l01502"></a><span class="lineno"> 1502</span> </div><div class="line"><a name="l01503"></a><span class="lineno"> 1503</span> * Most of the _ECS_ available out there have some annoying limitations (at least</div><div class="line"><a name="l01504"></a><span class="lineno"> 1504</span>  from my point of view): entities and components cannot be created and/or</div><div class="line"><a name="l01505"></a><span class="lineno"> 1505</span>  destroyed during iterations.<br/></div><div class="line"><a name="l01506"></a><span class="lineno"> 1506</span>  `EnTT` partially solves the problem with a few limitations:</div><div class="line"><a name="l01507"></a><span class="lineno"> 1507</span> </div><div class="line"><a name="l01508"></a><span class="lineno"> 1508</span>  * Creating entities and components is allowed during iterations.</div><div class="line"><a name="l01509"></a><span class="lineno"> 1509</span>  * Deleting an entity or removing its components is allowed during iterations</div><div class="line"><a name="l01510"></a><span class="lineno"> 1510</span>  if it's the one currently returned by a view. For all the other entities,</div><div class="line"><a name="l01511"></a><span class="lineno"> 1511</span>  destroying them or removing their components isn't allowed and it can result</div><div class="line"><a name="l01512"></a><span class="lineno"> 1512</span>  in undefined behavior.</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>  Iterators are invalidated and the behavior is undefined if an entity is</div><div class="line"><a name="l01515"></a><span class="lineno"> 1515</span>  modified or destroyed and it's not the one currently returned by the</div><div class="line"><a name="l01516"></a><span class="lineno"> 1516</span>  view.<br/></div><div class="line"><a name="l01517"></a><span class="lineno"> 1517</span>  To work around it, possible approaches are:</div><div class="line"><a name="l01518"></a><span class="lineno"> 1518</span> </div><div class="line"><a name="l01519"></a><span class="lineno"> 1519</span>  * Store aside the entities and the components to be removed and perform the</div><div class="line"><a name="l01520"></a><span class="lineno"> 1520</span>  operations at the end of the iteration.</div><div class="line"><a name="l01521"></a><span class="lineno"> 1521</span>  * Mark entities and components with a proper tag component that indicates</div><div class="line"><a name="l01522"></a><span class="lineno"> 1522</span>  they must be purged, then perform a second iteration to clean them up one</div><div class="line"><a name="l01523"></a><span class="lineno"> 1523</span>  by one.</div><div class="line"><a name="l01524"></a><span class="lineno"> 1524</span> </div><div class="line"><a name="l01525"></a><span class="lineno"> 1525</span> * Views and thus their iterators aren't thread safe. Do no try to iterate a set</div><div class="line"><a name="l01526"></a><span class="lineno"> 1526</span>  of components and modify the same set concurrently.<br/></div><div class="line"><a name="l01527"></a><span class="lineno"> 1527</span>  That being said, as long as a thread iterates the entities that have the</div><div class="line"><a name="l01528"></a><span class="lineno"> 1528</span>  component `X` or assign and removes that component from a set of entities,</div><div class="line"><a name="l01529"></a><span class="lineno"> 1529</span>  another thread can safely do the same with components `Y` and `Z` and</div><div class="line"><a name="l01530"></a><span class="lineno"> 1530</span>  everything will work like a charm.<br/></div><div class="line"><a name="l01531"></a><span class="lineno"> 1531</span>  As a trivial example, users can freely execute the rendering system and</div><div class="line"><a name="l01532"></a><span class="lineno"> 1532</span>  iterate the renderable entities while updating a physic component concurrently</div><div class="line"><a name="l01533"></a><span class="lineno"> 1533</span>  on a separate thread.</div><div class="line"><a name="l01534"></a><span class="lineno"> 1534</span> </div><div class="line"><a name="l01535"></a><span class="lineno"> 1535</span> * In general, the entire registry isn't thread safe as it is. Thread safety</div><div class="line"><a name="l01536"></a><span class="lineno"> 1536</span>  isn't something that users should want out of the box for several reasons.</div><div class="line"><a name="l01537"></a><span class="lineno"> 1537</span>  Just to mention one of them: performance.<br/></div><div class="line"><a name="l01538"></a><span class="lineno"> 1538</span>  This kind of entity-component systems can be used in single threaded</div><div class="line"><a name="l01539"></a><span class="lineno"> 1539</span>  applications as well as along with async stuff. Moreover, typical thread based</div><div class="line"><a name="l01540"></a><span class="lineno"> 1540</span>  models for ECS don't require a fully thread safe registry to work. Actually</div><div class="line"><a name="l01541"></a><span class="lineno"> 1541</span>  one could reach the goal with the registry as it is while working with most of</div><div class="line"><a name="l01542"></a><span class="lineno"> 1542</span>  the common models, after all.<br/></div><div class="line"><a name="l01543"></a><span class="lineno"> 1543</span>  Because of the few reasons mentioned above and many others not mentioned,</div><div class="line"><a name="l01544"></a><span class="lineno"> 1544</span>  users are completely responsible for synchronization whether required.</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> # Crash Course: core functionalities</div><div class="line"><a name="l01547"></a><span class="lineno"> 1547</span> </div><div class="line"><a name="l01548"></a><span class="lineno"> 1548</span> The `EnTT` framework comes with a bunch of core functionalities mostly used by</div><div class="line"><a name="l01549"></a><span class="lineno"> 1549</span> the other parts of the library itself.<br/></div><div class="line"><a name="l01550"></a><span class="lineno"> 1550</span> Hardly users of the framework will include these features in their code, but</div><div class="line"><a name="l01551"></a><span class="lineno"> 1551</span> it's worth describing what `EnTT` offers so as not to reinvent the wheel in case</div><div class="line"><a name="l01552"></a><span class="lineno"> 1552</span> of need.</div><div class="line"><a name="l01553"></a><span class="lineno"> 1553</span> </div><div class="line"><a name="l01554"></a><span class="lineno"> 1554</span> ## Compile-time identifiers</div><div class="line"><a name="l01555"></a><span class="lineno"> 1555</span> </div><div class="line"><a name="l01556"></a><span class="lineno"> 1556</span> Sometimes it's useful to be able to give unique identifiers to types at</div><div class="line"><a name="l01557"></a><span class="lineno"> 1557</span> compile-time.<br/></div><div class="line"><a name="l01558"></a><span class="lineno"> 1558</span> There are plenty of different solutions out there and I could have used one of</div><div class="line"><a name="l01559"></a><span class="lineno"> 1559</span> them. However, I decided to spend my time to define a compact and versatile tool</div><div class="line"><a name="l01560"></a><span class="lineno"> 1560</span> that fully embraces what the modern C++ has to offer.</div><div class="line"><a name="l01561"></a><span class="lineno"> 1561</span> </div><div class="line"><a name="l01562"></a><span class="lineno"> 1562</span> The _result of my efforts_ is the `ident` `constexpr` variable:</div><div class="line"><a name="l01563"></a><span class="lineno"> 1563</span> </div><div class="line"><a name="l01564"></a><span class="lineno"> 1564</span> ```cpp</div><div class="line"><a name="l01565"></a><span class="lineno"> 1565</span> #include <ident.hpp></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> // defines the identifiers for the given types</div><div class="line"><a name="l01568"></a><span class="lineno"> 1568</span> constexpr auto identifiers = entt::ident<AType, AnotherType>;</div><div class="line"><a name="l01569"></a><span class="lineno"> 1569</span> </div><div class="line"><a name="l01570"></a><span class="lineno"> 1570</span> // ...</div><div class="line"><a name="l01571"></a><span class="lineno"> 1571</span> </div><div class="line"><a name="l01572"></a><span class="lineno"> 1572</span> switch(aTypeIdentifier) {</div><div class="line"><a name="l01573"></a><span class="lineno"> 1573</span> case identifers.get<AType>():</div><div class="line"><a name="l01574"></a><span class="lineno"> 1574</span>  // ...</div><div class="line"><a name="l01575"></a><span class="lineno"> 1575</span>  break;</div><div class="line"><a name="l01576"></a><span class="lineno"> 1576</span> case identifers.get<AnotherType>():</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>  break;</div><div class="line"><a name="l01579"></a><span class="lineno"> 1579</span> default:</div><div class="line"><a name="l01580"></a><span class="lineno"> 1580</span>  // ...</div><div class="line"><a name="l01581"></a><span class="lineno"> 1581</span> }</div><div class="line"><a name="l01582"></a><span class="lineno"> 1582</span> ```</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> This is all what the variable has to offer: a `get` member function that returns</div><div class="line"><a name="l01585"></a><span class="lineno"> 1585</span> a numerical identifier for the given type. It can be used in any context where</div><div class="line"><a name="l01586"></a><span class="lineno"> 1586</span> constant expressions are required.</div><div class="line"><a name="l01587"></a><span class="lineno"> 1587</span> </div><div class="line"><a name="l01588"></a><span class="lineno"> 1588</span> As long as the list remains unchanged, identifiers are also guaranteed to be the</div><div class="line"><a name="l01589"></a><span class="lineno"> 1589</span> same for every run. In case they have been used in a production environment and</div><div class="line"><a name="l01590"></a><span class="lineno"> 1590</span> a type has to be removed, one can just use a placeholder to left the other</div><div class="line"><a name="l01591"></a><span class="lineno"> 1591</span> identifiers unchanged:</div><div class="line"><a name="l01592"></a><span class="lineno"> 1592</span> </div><div class="line"><a name="l01593"></a><span class="lineno"> 1593</span> ```cpp</div><div class="line"><a name="l01594"></a><span class="lineno"> 1594</span> template<typename> struct IgnoreType {};</div><div class="line"><a name="l01595"></a><span class="lineno"> 1595</span> </div><div class="line"><a name="l01596"></a><span class="lineno"> 1596</span> constexpr auto identifiers = entt::ident<</div><div class="line"><a name="l01597"></a><span class="lineno"> 1597</span>  ATypeStillValid,</div><div class="line"><a name="l01598"></a><span class="lineno"> 1598</span>  IgnoreType<ATypeNoLongerValid>,</div><div class="line"><a name="l01599"></a><span class="lineno"> 1599</span>  AnotherTypeStillValid</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> </div><div class="line"><a name="l01603"></a><span class="lineno"> 1603</span> A bit ugly to see, but it works at least.</div><div class="line"><a name="l01604"></a><span class="lineno"> 1604</span> </div><div class="line"><a name="l01605"></a><span class="lineno"> 1605</span> ## Runtime identifiers</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> Sometimes it's useful to be able to give unique identifiers to types at</div><div class="line"><a name="l01608"></a><span class="lineno"> 1608</span> runtime.<br/></div><div class="line"><a name="l01609"></a><span class="lineno"> 1609</span> There are plenty of different solutions out there and I could have used one of</div><div class="line"><a name="l01610"></a><span class="lineno"> 1610</span> them. In fact, I adapted the most common one to my requirements and used it</div><div class="line"><a name="l01611"></a><span class="lineno"> 1611</span> extensively within the entire framework.</div><div class="line"><a name="l01612"></a><span class="lineno"> 1612</span> </div><div class="line"><a name="l01613"></a><span class="lineno"> 1613</span> It's the `Family` class. Here is an example of use directly from the</div><div class="line"><a name="l01614"></a><span class="lineno"> 1614</span> entity-component system:</div><div class="line"><a name="l01615"></a><span class="lineno"> 1615</span> </div><div class="line"><a name="l01616"></a><span class="lineno"> 1616</span> ```cpp</div><div class="line"><a name="l01617"></a><span class="lineno"> 1617</span> using component_family = entt::Family<struct InternalRegistryComponentFamily>;</div><div class="line"><a name="l01618"></a><span class="lineno"> 1618</span> </div><div class="line"><a name="l01619"></a><span class="lineno"> 1619</span> // ...</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> template<typename Component></div><div class="line"><a name="l01622"></a><span class="lineno"> 1622</span> component_type component() const noexcept {</div><div class="line"><a name="l01623"></a><span class="lineno"> 1623</span>  return component_family::type<Component>();</div><div class="line"><a name="l01624"></a><span class="lineno"> 1624</span> }</div><div class="line"><a name="l01625"></a><span class="lineno"> 1625</span> ```</div><div class="line"><a name="l01626"></a><span class="lineno"> 1626</span> </div><div class="line"><a name="l01627"></a><span class="lineno"> 1627</span> This is all what a _family_ has to offer: a `type` member function that returns</div><div class="line"><a name="l01628"></a><span class="lineno"> 1628</span> a numerical identifier for the given type.</div><div class="line"><a name="l01629"></a><span class="lineno"> 1629</span> </div><div class="line"><a name="l01630"></a><span class="lineno"> 1630</span> Please, note that identifiers aren't guaranteed to be the same for every run.</div><div class="line"><a name="l01631"></a><span class="lineno"> 1631</span> Indeed it mostly depends on the flow of execution.</div><div class="line"><a name="l01632"></a><span class="lineno"> 1632</span> </div><div class="line"><a name="l01633"></a><span class="lineno"> 1633</span> ## Hashed strings</div><div class="line"><a name="l01634"></a><span class="lineno"> 1634</span> </div><div class="line"><a name="l01635"></a><span class="lineno"> 1635</span> A hashed string is a zero overhead resource identifier. Users can use</div><div class="line"><a name="l01636"></a><span class="lineno"> 1636</span> human-readable identifiers in the codebase while using their numeric</div><div class="line"><a name="l01637"></a><span class="lineno"> 1637</span> counterparts at runtime, thus without affecting performance.<br/></div><div class="line"><a name="l01638"></a><span class="lineno"> 1638</span> The class has an implicit `constexpr` constructor that chews a bunch of</div><div class="line"><a name="l01639"></a><span class="lineno"> 1639</span> characters. Once created, all what one can do with it is getting back the</div><div class="line"><a name="l01640"></a><span class="lineno"> 1640</span> original string or converting it into a number.<br/></div><div class="line"><a name="l01641"></a><span class="lineno"> 1641</span> The good part is that a hashed string can be used wherever a constant expression</div><div class="line"><a name="l01642"></a><span class="lineno"> 1642</span> is required and no _string-to-number_ conversion will take place at runtime if</div><div class="line"><a name="l01643"></a><span class="lineno"> 1643</span> used carefully.</div><div class="line"><a name="l01644"></a><span class="lineno"> 1644</span> </div><div class="line"><a name="l01645"></a><span class="lineno"> 1645</span> Example of use:</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> ```cpp</div><div class="line"><a name="l01648"></a><span class="lineno"> 1648</span> auto load(entt::HashedString::hash_type resource) {</div><div class="line"><a name="l01649"></a><span class="lineno"> 1649</span>  // uses the numeric representation of the resource to load and return it</div><div class="line"><a name="l01650"></a><span class="lineno"> 1650</span> }</div><div class="line"><a name="l01651"></a><span class="lineno"> 1651</span> </div><div class="line"><a name="l01652"></a><span class="lineno"> 1652</span> auto resource = load(entt::HashedString{"gui/background"});</div><div class="line"><a name="l01653"></a><span class="lineno"> 1653</span> ```</div><div class="line"><a name="l01654"></a><span class="lineno"> 1654</span> </div><div class="line"><a name="l01655"></a><span class="lineno"> 1655</span> ### Conflicts</div><div class="line"><a name="l01656"></a><span class="lineno"> 1656</span> </div><div class="line"><a name="l01657"></a><span class="lineno"> 1657</span> The hashed string class uses internally FNV-1a to compute the numeric</div><div class="line"><a name="l01658"></a><span class="lineno"> 1658</span> counterpart of a string. Because of the _pigeonhole principle_, conflicts are</div><div class="line"><a name="l01659"></a><span class="lineno"> 1659</span> possible. This is a fact.<br/></div><div class="line"><a name="l01660"></a><span class="lineno"> 1660</span> There is no silver bullet to solve the problem of conflicts when dealing with</div><div class="line"><a name="l01661"></a><span class="lineno"> 1661</span> hashing functions. In this case, the best solution seemed to be to give up.</div><div class="line"><a name="l01662"></a><span class="lineno"> 1662</span> That's all.<br/></div><div class="line"><a name="l01663"></a><span class="lineno"> 1663</span> After all, human-readable resource identifiers aren't something strictly defined</div><div class="line"><a name="l01664"></a><span class="lineno"> 1664</span> and over which users have not the control. Choosing a slightly different</div><div class="line"><a name="l01665"></a><span class="lineno"> 1665</span> identifier is probably the best solution to make the conflict disappear in this</div><div class="line"><a name="l01666"></a><span class="lineno"> 1666</span> case.</div><div class="line"><a name="l01667"></a><span class="lineno"> 1667</span> </div><div class="line"><a name="l01668"></a><span class="lineno"> 1668</span> # Crash Course: service locator</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> Usually service locators are tightly bound to the services they expose and it's</div><div class="line"><a name="l01671"></a><span class="lineno"> 1671</span> hard to define a general purpose solution. This template based implementation</div><div class="line"><a name="l01672"></a><span class="lineno"> 1672</span> tries to fill the gap and to get rid of the burden of defining a different</div><div class="line"><a name="l01673"></a><span class="lineno"> 1673</span> specific locator for each application.<br/></div><div class="line"><a name="l01674"></a><span class="lineno"> 1674</span> This class is tiny, partially unsafe and thus risky to use. Moreover it doesn't</div><div class="line"><a name="l01675"></a><span class="lineno"> 1675</span> fit probably most of the scenarios in which a service locator is required. Look</div><div class="line"><a name="l01676"></a><span class="lineno"> 1676</span> at it as a small tool that can sometimes be useful if the user knows how to</div><div class="line"><a name="l01677"></a><span class="lineno"> 1677</span> handle it.</div><div class="line"><a name="l01678"></a><span class="lineno"> 1678</span> </div><div class="line"><a name="l01679"></a><span class="lineno"> 1679</span> The API is straightforward. The basic idea is that services are implemented by</div><div class="line"><a name="l01680"></a><span class="lineno"> 1680</span> means of interfaces and rely on polymorphism.<br/></div><div class="line"><a name="l01681"></a><span class="lineno"> 1681</span> The locator is instantiated with the base type of the service if any and a</div><div class="line"><a name="l01682"></a><span class="lineno"> 1682</span> concrete implementation is provided along with all the parameters required to</div><div class="line"><a name="l01683"></a><span class="lineno"> 1683</span> initialize it. As an example:</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> ```cpp</div><div class="line"><a name="l01686"></a><span class="lineno"> 1686</span> // the service has no base type, a locator is used to treat it as a kind of singleton</div><div class="line"><a name="l01687"></a><span class="lineno"> 1687</span> entt::ServiceLocator<MyService>::set(params...);</div><div class="line"><a name="l01688"></a><span class="lineno"> 1688</span> </div><div class="line"><a name="l01689"></a><span class="lineno"> 1689</span> // sets up an opaque service</div><div class="line"><a name="l01690"></a><span class="lineno"> 1690</span> entt::ServiceLocator<AudioInterface>::set<AudioImplementation>(params...);</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> // resets (destroys) the service</div><div class="line"><a name="l01693"></a><span class="lineno"> 1693</span> entt::ServiceLocator<AudioInterface>::reset();</div><div class="line"><a name="l01694"></a><span class="lineno"> 1694</span> ```</div><div class="line"><a name="l01695"></a><span class="lineno"> 1695</span> </div><div class="line"><a name="l01696"></a><span class="lineno"> 1696</span> The locator can also be queried to know if an active service is currently set</div><div class="line"><a name="l01697"></a><span class="lineno"> 1697</span> and to retrieve it if necessary (either as a pointer or as a reference):</div><div class="line"><a name="l01698"></a><span class="lineno"> 1698</span> </div><div class="line"><a name="l01699"></a><span class="lineno"> 1699</span> ```cpp</div><div class="line"><a name="l01700"></a><span class="lineno"> 1700</span> // no service currently set</div><div class="line"><a name="l01701"></a><span class="lineno"> 1701</span> auto empty = entt::ServiceLocator<AudioInterface>::empty();</div><div class="line"><a name="l01702"></a><span class="lineno"> 1702</span> </div><div class="line"><a name="l01703"></a><span class="lineno"> 1703</span> // gets a (possibly empty) shared pointer to the service ...</div><div class="line"><a name="l01704"></a><span class="lineno"> 1704</span> std::shared_ptr<AudioInterface> ptr = entt::ServiceLocator<AudioInterface>::get();</div><div class="line"><a name="l01705"></a><span class="lineno"> 1705</span> </div><div class="line"><a name="l01706"></a><span class="lineno"> 1706</span> // ... or a reference, but it's undefined behaviour if the service isn't set yet</div><div class="line"><a name="l01707"></a><span class="lineno"> 1707</span> AudioInterface &ref = entt::ServiceLocator<AudioInterface>::ref();</div><div class="line"><a name="l01708"></a><span class="lineno"> 1708</span> ```</div><div class="line"><a name="l01709"></a><span class="lineno"> 1709</span> </div><div class="line"><a name="l01710"></a><span class="lineno"> 1710</span> A common use is to wrap the different locators in a container class, creating</div><div class="line"><a name="l01711"></a><span class="lineno"> 1711</span> aliases for the various services:</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> ```cpp</div><div class="line"><a name="l01714"></a><span class="lineno"> 1714</span> struct Locator {</div><div class="line"><a name="l01715"></a><span class="lineno"> 1715</span>  using Camera = entt::ServiceLocator<CameraInterface>;</div><div class="line"><a name="l01716"></a><span class="lineno"> 1716</span>  using Audio = entt::ServiceLocator<AudioInterface>;</div><div class="line"><a name="l01717"></a><span class="lineno"> 1717</span>  // ...</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> </div><div class="line"><a name="l01720"></a><span class="lineno"> 1720</span> // ...</div><div class="line"><a name="l01721"></a><span class="lineno"> 1721</span> </div><div class="line"><a name="l01722"></a><span class="lineno"> 1722</span> void init() {</div><div class="line"><a name="l01723"></a><span class="lineno"> 1723</span>  Locator::Camera::set<CameraNull>();</div><div class="line"><a name="l01724"></a><span class="lineno"> 1724</span>  Locator::Audio::set<AudioImplementation>(params...);</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> }</div><div class="line"><a name="l01727"></a><span class="lineno"> 1727</span> ```</div><div class="line"><a name="l01728"></a><span class="lineno"> 1728</span> </div><div class="line"><a name="l01729"></a><span class="lineno"> 1729</span> # Crash Course: cooperative scheduler</div><div class="line"><a name="l01730"></a><span class="lineno"> 1730</span> </div><div class="line"><a name="l01731"></a><span class="lineno"> 1731</span> Sometimes processes are a useful tool to work around the strict definition of a</div><div class="line"><a name="l01732"></a><span class="lineno"> 1732</span> system and introduce logic in a different way, usually without resorting to the</div><div class="line"><a name="l01733"></a><span class="lineno"> 1733</span> introduction of other components.</div><div class="line"><a name="l01734"></a><span class="lineno"> 1734</span> </div><div class="line"><a name="l01735"></a><span class="lineno"> 1735</span> The `EnTT` framework offers a minimal support to this paradigm by introducing a</div><div class="line"><a name="l01736"></a><span class="lineno"> 1736</span> few classes that users can use to define and execute cooperative processes.</div><div class="line"><a name="l01737"></a><span class="lineno"> 1737</span> </div><div class="line"><a name="l01738"></a><span class="lineno"> 1738</span> ## The process</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> A typical process must inherit from the `Process` class template that stays true</div><div class="line"><a name="l01741"></a><span class="lineno"> 1741</span> to the CRTP idiom. Moreover, derived classes must specify what's the intended</div><div class="line"><a name="l01742"></a><span class="lineno"> 1742</span> type for elapsed times.</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> A process should expose publicly the following member functions whether</div><div class="line"><a name="l01745"></a><span class="lineno"> 1745</span> required (note that it isn't required to define a function unless the derived</div><div class="line"><a name="l01746"></a><span class="lineno"> 1746</span> class wants to _override_ the default behavior):</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> * `void update(Delta, void *);`</div><div class="line"><a name="l01749"></a><span class="lineno"> 1749</span> </div><div class="line"><a name="l01750"></a><span class="lineno"> 1750</span>  It's invoked once per tick until a process is explicitly aborted or it</div><div class="line"><a name="l01751"></a><span class="lineno"> 1751</span>  terminates either with or without errors. Even though it's not mandatory to</div><div class="line"><a name="l01752"></a><span class="lineno"> 1752</span>  declare this member function, as a rule of thumb each process should at</div><div class="line"><a name="l01753"></a><span class="lineno"> 1753</span>  least define it to work properly. The `void *` parameter is an opaque pointer</div><div class="line"><a name="l01754"></a><span class="lineno"> 1754</span>  to user data (if any) forwarded directly to the process during an update.</div><div class="line"><a name="l01755"></a><span class="lineno"> 1755</span> </div><div class="line"><a name="l01756"></a><span class="lineno"> 1756</span> * `void init(void *);`</div><div class="line"><a name="l01757"></a><span class="lineno"> 1757</span> </div><div class="line"><a name="l01758"></a><span class="lineno"> 1758</span>  It's invoked at the first tick, immediately before an update. The `void *`</div><div class="line"><a name="l01759"></a><span class="lineno"> 1759</span>  parameter is an opaque pointer to user data (if any) forwarded directly to the</div><div class="line"><a name="l01760"></a><span class="lineno"> 1760</span>  process during an update.</div><div class="line"><a name="l01761"></a><span class="lineno"> 1761</span> </div><div class="line"><a name="l01762"></a><span class="lineno"> 1762</span> * `void succeeded();`</div><div class="line"><a name="l01763"></a><span class="lineno"> 1763</span> </div><div class="line"><a name="l01764"></a><span class="lineno"> 1764</span>  It's invoked in case of success, immediately after an update and during the</div><div class="line"><a name="l01765"></a><span class="lineno"> 1765</span>  same tick.</div><div class="line"><a name="l01766"></a><span class="lineno"> 1766</span> </div><div class="line"><a name="l01767"></a><span class="lineno"> 1767</span> * `void failed();`</div><div class="line"><a name="l01768"></a><span class="lineno"> 1768</span> </div><div class="line"><a name="l01769"></a><span class="lineno"> 1769</span>  It's invoked in case of errors, immediately after an update and during the</div><div class="line"><a name="l01770"></a><span class="lineno"> 1770</span>  same tick.</div><div class="line"><a name="l01771"></a><span class="lineno"> 1771</span> </div><div class="line"><a name="l01772"></a><span class="lineno"> 1772</span> * `void aborted();`</div><div class="line"><a name="l01773"></a><span class="lineno"> 1773</span> </div><div class="line"><a name="l01774"></a><span class="lineno"> 1774</span>  It's invoked only if a process is explicitly aborted. There is no guarantee</div><div class="line"><a name="l01775"></a><span class="lineno"> 1775</span>  that it executes in the same tick, this depends solely on whether the</div><div class="line"><a name="l01776"></a><span class="lineno"> 1776</span>  process is aborted immediately or not.</div><div class="line"><a name="l01777"></a><span class="lineno"> 1777</span> </div><div class="line"><a name="l01778"></a><span class="lineno"> 1778</span> Derived classes can also change the internal state of a process by invoking</div><div class="line"><a name="l01779"></a><span class="lineno"> 1779</span> `succeed` and `fail`, as well as `pause` and `unpause` the process itself. All</div><div class="line"><a name="l01780"></a><span class="lineno"> 1780</span> these are protected member functions made available to be able to manage the</div><div class="line"><a name="l01781"></a><span class="lineno"> 1781</span> life cycle of a process from a derived class.</div><div class="line"><a name="l01782"></a><span class="lineno"> 1782</span> </div><div class="line"><a name="l01783"></a><span class="lineno"> 1783</span> Here is a minimal example for the sake of curiosity:</div><div class="line"><a name="l01784"></a><span class="lineno"> 1784</span> </div><div class="line"><a name="l01785"></a><span class="lineno"> 1785</span> ```cpp</div><div class="line"><a name="l01786"></a><span class="lineno"> 1786</span> struct MyProcess: entt::Process<MyProcess, std::uint32_t> {</div><div class="line"><a name="l01787"></a><span class="lineno"> 1787</span>  using delta_type = std::uint32_t;</div><div class="line"><a name="l01788"></a><span class="lineno"> 1788</span> </div><div class="line"><a name="l01789"></a><span class="lineno"> 1789</span>  void update(delta_type delta, void *) {</div><div class="line"><a name="l01790"></a><span class="lineno"> 1790</span>  remaining = delta > remaining ? delta_type{] : (remaining - delta);</div><div class="line"><a name="l01791"></a><span class="lineno"> 1791</span> </div><div class="line"><a name="l01792"></a><span class="lineno"> 1792</span>  // ...</div><div class="line"><a name="l01793"></a><span class="lineno"> 1793</span> </div><div class="line"><a name="l01794"></a><span class="lineno"> 1794</span>  if(!remaining) {</div><div class="line"><a name="l01795"></a><span class="lineno"> 1795</span>  succeed();</div><div class="line"><a name="l01796"></a><span class="lineno"> 1796</span>  }</div><div class="line"><a name="l01797"></a><span class="lineno"> 1797</span>  }</div><div class="line"><a name="l01798"></a><span class="lineno"> 1798</span> </div><div class="line"><a name="l01799"></a><span class="lineno"> 1799</span>  void init(void *data) {</div><div class="line"><a name="l01800"></a><span class="lineno"> 1800</span>  remaining = *static_cast<delta_type *>(data);</div><div class="line"><a name="l01801"></a><span class="lineno"> 1801</span>  }</div><div class="line"><a name="l01802"></a><span class="lineno"> 1802</span> </div><div class="line"><a name="l01803"></a><span class="lineno"> 1803</span> private:</div><div class="line"><a name="l01804"></a><span class="lineno"> 1804</span>  delta_type remaining;</div><div class="line"><a name="l01805"></a><span class="lineno"> 1805</span> };</div><div class="line"><a name="l01806"></a><span class="lineno"> 1806</span> ```</div><div class="line"><a name="l01807"></a><span class="lineno"> 1807</span> </div><div class="line"><a name="l01808"></a><span class="lineno"> 1808</span> ### Adaptor</div><div class="line"><a name="l01809"></a><span class="lineno"> 1809</span> </div><div class="line"><a name="l01810"></a><span class="lineno"> 1810</span> Lambdas and functors can't be used directly with a scheduler for they are not</div><div class="line"><a name="l01811"></a><span class="lineno"> 1811</span> properly defined processes with managed life cycles.<br/></div><div class="line"><a name="l01812"></a><span class="lineno"> 1812</span> This class helps in filling the gap and turning lambdas and functors into</div><div class="line"><a name="l01813"></a><span class="lineno"> 1813</span> full featured processes usable by a scheduler.</div><div class="line"><a name="l01814"></a><span class="lineno"> 1814</span> </div><div class="line"><a name="l01815"></a><span class="lineno"> 1815</span> The function call operator has a signature similar to the one of the `update`</div><div class="line"><a name="l01816"></a><span class="lineno"> 1816</span> function of a process but for the fact that it receives two extra arguments to</div><div class="line"><a name="l01817"></a><span class="lineno"> 1817</span> call whenever a process is terminated with success or with an error:</div><div class="line"><a name="l01818"></a><span class="lineno"> 1818</span> </div><div class="line"><a name="l01819"></a><span class="lineno"> 1819</span> ```cpp</div><div class="line"><a name="l01820"></a><span class="lineno"> 1820</span> void(Delta delta, void *data, auto succeed, auto fail);</div><div class="line"><a name="l01821"></a><span class="lineno"> 1821</span> ```</div><div class="line"><a name="l01822"></a><span class="lineno"> 1822</span> </div><div class="line"><a name="l01823"></a><span class="lineno"> 1823</span> Parameters have the following meaning:</div><div class="line"><a name="l01824"></a><span class="lineno"> 1824</span> </div><div class="line"><a name="l01825"></a><span class="lineno"> 1825</span> * `delta` is the elapsed time.</div><div class="line"><a name="l01826"></a><span class="lineno"> 1826</span> * `data` is an opaque pointer to user data if any, `nullptr` otherwise.</div><div class="line"><a name="l01827"></a><span class="lineno"> 1827</span> * `succeed` is a function to call when a process terminates with success.</div><div class="line"><a name="l01828"></a><span class="lineno"> 1828</span> * `fail` is a function to call when a process terminates with errors.</div><div class="line"><a name="l01829"></a><span class="lineno"> 1829</span> </div><div class="line"><a name="l01830"></a><span class="lineno"> 1830</span> Both `succeed` and `fail` accept no parameters at all.</div><div class="line"><a name="l01831"></a><span class="lineno"> 1831</span> </div><div class="line"><a name="l01832"></a><span class="lineno"> 1832</span> Note that usually users shouldn't worry about creating adaptors at all. A</div><div class="line"><a name="l01833"></a><span class="lineno"> 1833</span> scheduler creates them internally each and every time a lambda or a functor is</div><div class="line"><a name="l01834"></a><span class="lineno"> 1834</span> used as a process.</div><div class="line"><a name="l01835"></a><span class="lineno"> 1835</span> </div><div class="line"><a name="l01836"></a><span class="lineno"> 1836</span> ## The scheduler</div><div class="line"><a name="l01837"></a><span class="lineno"> 1837</span> </div><div class="line"><a name="l01838"></a><span class="lineno"> 1838</span> A cooperative scheduler runs different processes and helps managing their life</div><div class="line"><a name="l01839"></a><span class="lineno"> 1839</span> cycles.</div><div class="line"><a name="l01840"></a><span class="lineno"> 1840</span> </div><div class="line"><a name="l01841"></a><span class="lineno"> 1841</span> Each process is invoked once per tick. If it terminates, it's removed</div><div class="line"><a name="l01842"></a><span class="lineno"> 1842</span> automatically from the scheduler and it's never invoked again. Otherwise it's</div><div class="line"><a name="l01843"></a><span class="lineno"> 1843</span> a good candidate to run once more the next tick.<br/></div><div class="line"><a name="l01844"></a><span class="lineno"> 1844</span> A process can also have a child. In this case, the process is replaced with</div><div class="line"><a name="l01845"></a><span class="lineno"> 1845</span> its child when it terminates if it returns with success. In case of errors,</div><div class="line"><a name="l01846"></a><span class="lineno"> 1846</span> both the process and its child are discarded. This way, it's easy to create</div><div class="line"><a name="l01847"></a><span class="lineno"> 1847</span> chain of processes to run sequentially.</div><div class="line"><a name="l01848"></a><span class="lineno"> 1848</span> </div><div class="line"><a name="l01849"></a><span class="lineno"> 1849</span> Using a scheduler is straightforward. To create it, users must provide only the</div><div class="line"><a name="l01850"></a><span class="lineno"> 1850</span> type for the elapsed times and no arguments at all:</div><div class="line"><a name="l01851"></a><span class="lineno"> 1851</span> </div><div class="line"><a name="l01852"></a><span class="lineno"> 1852</span> ```cpp</div><div class="line"><a name="l01853"></a><span class="lineno"> 1853</span> Scheduler<std::uint32_t> scheduler;</div><div class="line"><a name="l01854"></a><span class="lineno"> 1854</span> ```</div><div class="line"><a name="l01855"></a><span class="lineno"> 1855</span> </div><div class="line"><a name="l01856"></a><span class="lineno"> 1856</span> It has member functions to query its internal data structures, like `empty` or</div><div class="line"><a name="l01857"></a><span class="lineno"> 1857</span> `size`, as well as a `clear` utility to reset it to a clean state:</div><div class="line"><a name="l01858"></a><span class="lineno"> 1858</span> </div><div class="line"><a name="l01859"></a><span class="lineno"> 1859</span> ```cpp</div><div class="line"><a name="l01860"></a><span class="lineno"> 1860</span> // checks if there are processes still running</div><div class="line"><a name="l01861"></a><span class="lineno"> 1861</span> bool empty = scheduler.empty();</div><div class="line"><a name="l01862"></a><span class="lineno"> 1862</span> </div><div class="line"><a name="l01863"></a><span class="lineno"> 1863</span> // gets the number of processes still running</div><div class="line"><a name="l01864"></a><span class="lineno"> 1864</span> Scheduler<std::uint32_t>::size_type size = scheduler.size();</div><div class="line"><a name="l01865"></a><span class="lineno"> 1865</span> </div><div class="line"><a name="l01866"></a><span class="lineno"> 1866</span> // resets the scheduler to its initial state and discards all the processes</div><div class="line"><a name="l01867"></a><span class="lineno"> 1867</span> scheduler.clear();</div><div class="line"><a name="l01868"></a><span class="lineno"> 1868</span> ```</div><div class="line"><a name="l01869"></a><span class="lineno"> 1869</span> </div><div class="line"><a name="l01870"></a><span class="lineno"> 1870</span> To attach a process to a scheduler there are mainly two ways:</div><div class="line"><a name="l01871"></a><span class="lineno"> 1871</span> </div><div class="line"><a name="l01872"></a><span class="lineno"> 1872</span> * If the process inherits from the `Process` class template, it's enough to</div><div class="line"><a name="l01873"></a><span class="lineno"> 1873</span>  indicate its type and submit all the parameters required to construct it to</div><div class="line"><a name="l01874"></a><span class="lineno"> 1874</span>  the `attach` member function:</div><div class="line"><a name="l01875"></a><span class="lineno"> 1875</span> </div><div class="line"><a name="l01876"></a><span class="lineno"> 1876</span>  ```cpp</div><div class="line"><a name="l01877"></a><span class="lineno"> 1877</span>  scheduler.attach<MyProcess>("foobar");</div><div class="line"><a name="l01878"></a><span class="lineno"> 1878</span>  ```</div><div class="line"><a name="l01879"></a><span class="lineno"> 1879</span> </div><div class="line"><a name="l01880"></a><span class="lineno"> 1880</span> * Otherwise, in case of a lambda or a functor, it's enough to provide an</div><div class="line"><a name="l01881"></a><span class="lineno"> 1881</span>  instance of the class to the `attach` member function:</div><div class="line"><a name="l01882"></a><span class="lineno"> 1882</span> </div><div class="line"><a name="l01883"></a><span class="lineno"> 1883</span>  ```cpp</div><div class="line"><a name="l01884"></a><span class="lineno"> 1884</span>  scheduler.attach([](auto...){ /* ... */ });</div><div class="line"><a name="l01885"></a><span class="lineno"> 1885</span>  ```</div><div class="line"><a name="l01886"></a><span class="lineno"> 1886</span> </div><div class="line"><a name="l01887"></a><span class="lineno"> 1887</span> In both cases, the return value is an opaque object that offers a `then` member</div><div class="line"><a name="l01888"></a><span class="lineno"> 1888</span> function to use to create chains of processes to run sequentially.<br/></div><div class="line"><a name="l01889"></a><span class="lineno"> 1889</span> As a minimal example of use:</div><div class="line"><a name="l01890"></a><span class="lineno"> 1890</span> </div><div class="line"><a name="l01891"></a><span class="lineno"> 1891</span> ```cpp</div><div class="line"><a name="l01892"></a><span class="lineno"> 1892</span> // schedules a task in the form of a lambda function</div><div class="line"><a name="l01893"></a><span class="lineno"> 1893</span> scheduler.attach([](auto delta, void *, auto succeed, auto fail) {</div><div class="line"><a name="l01894"></a><span class="lineno"> 1894</span>  // ...</div><div class="line"><a name="l01895"></a><span class="lineno"> 1895</span> })</div><div class="line"><a name="l01896"></a><span class="lineno"> 1896</span> // appends a child in the form of another lambda function</div><div class="line"><a name="l01897"></a><span class="lineno"> 1897</span> .then([](auto delta, void *, auto succeed, auto fail) {</div><div class="line"><a name="l01898"></a><span class="lineno"> 1898</span>  // ...</div><div class="line"><a name="l01899"></a><span class="lineno"> 1899</span> })</div><div class="line"><a name="l01900"></a><span class="lineno"> 1900</span> // appends a child in the form of a process class</div><div class="line"><a name="l01901"></a><span class="lineno"> 1901</span> .then<MyProcess>();</div><div class="line"><a name="l01902"></a><span class="lineno"> 1902</span> ```</div><div class="line"><a name="l01903"></a><span class="lineno"> 1903</span> </div><div class="line"><a name="l01904"></a><span class="lineno"> 1904</span> To update a scheduler and thus all its processes, the `update` member function</div><div class="line"><a name="l01905"></a><span class="lineno"> 1905</span> is the way to go:</div><div class="line"><a name="l01906"></a><span class="lineno"> 1906</span> </div><div class="line"><a name="l01907"></a><span class="lineno"> 1907</span> ```cpp</div><div class="line"><a name="l01908"></a><span class="lineno"> 1908</span> // updates all the processes, no user data are provided</div><div class="line"><a name="l01909"></a><span class="lineno"> 1909</span> scheduler.update(delta);</div><div class="line"><a name="l01910"></a><span class="lineno"> 1910</span> </div><div class="line"><a name="l01911"></a><span class="lineno"> 1911</span> // updates all the processes and provides them with custom data</div><div class="line"><a name="l01912"></a><span class="lineno"> 1912</span> scheduler.update(delta, &data);</div><div class="line"><a name="l01913"></a><span class="lineno"> 1913</span> ```</div><div class="line"><a name="l01914"></a><span class="lineno"> 1914</span> </div><div class="line"><a name="l01915"></a><span class="lineno"> 1915</span> In addition to these functions, the scheduler offers an `abort` member function</div><div class="line"><a name="l01916"></a><span class="lineno"> 1916</span> that can be used to discard all the running processes at once:</div><div class="line"><a name="l01917"></a><span class="lineno"> 1917</span> </div><div class="line"><a name="l01918"></a><span class="lineno"> 1918</span> ```cpp</div><div class="line"><a name="l01919"></a><span class="lineno"> 1919</span> // aborts all the processes abruptly ...</div><div class="line"><a name="l01920"></a><span class="lineno"> 1920</span> scheduler.abort(true);</div><div class="line"><a name="l01921"></a><span class="lineno"> 1921</span> </div><div class="line"><a name="l01922"></a><span class="lineno"> 1922</span> // ... or gracefully during the next tick</div><div class="line"><a name="l01923"></a><span class="lineno"> 1923</span> scheduler.abort();</div><div class="line"><a name="l01924"></a><span class="lineno"> 1924</span> ```</div><div class="line"><a name="l01925"></a><span class="lineno"> 1925</span> </div><div class="line"><a name="l01926"></a><span class="lineno"> 1926</span> # Crash Course: resource management</div><div class="line"><a name="l01927"></a><span class="lineno"> 1927</span> </div><div class="line"><a name="l01928"></a><span class="lineno"> 1928</span> Resource management is usually one of the most critical part of a software like</div><div class="line"><a name="l01929"></a><span class="lineno"> 1929</span> a game. Solutions are often tuned to the particular application. There exist</div><div class="line"><a name="l01930"></a><span class="lineno"> 1930</span> several approaches and all of them are perfectly fine as long as they fit the</div><div class="line"><a name="l01931"></a><span class="lineno"> 1931</span> requirements of the piece of software in which they are used.<br/></div><div class="line"><a name="l01932"></a><span class="lineno"> 1932</span> Examples are loading everything on start, loading on request, predictive</div><div class="line"><a name="l01933"></a><span class="lineno"> 1933</span> loading, and so on.</div><div class="line"><a name="l01934"></a><span class="lineno"> 1934</span> </div><div class="line"><a name="l01935"></a><span class="lineno"> 1935</span> The `EnTT` framework doesn't pretend to offer a _one-fits-all_ solution for the</div><div class="line"><a name="l01936"></a><span class="lineno"> 1936</span> different cases. Instead, it offers a minimal and perhaps trivial cache that can</div><div class="line"><a name="l01937"></a><span class="lineno"> 1937</span> be useful most of the time during prototyping and sometimes even in a production</div><div class="line"><a name="l01938"></a><span class="lineno"> 1938</span> environment.<br/></div><div class="line"><a name="l01939"></a><span class="lineno"> 1939</span> For those interested in the subject, the plan is to improve it considerably over</div><div class="line"><a name="l01940"></a><span class="lineno"> 1940</span> time in terms of performance, memory usage and functionalities. Hoping to make</div><div class="line"><a name="l01941"></a><span class="lineno"> 1941</span> it, of course, one step at a time.</div><div class="line"><a name="l01942"></a><span class="lineno"> 1942</span> </div><div class="line"><a name="l01943"></a><span class="lineno"> 1943</span> ## The resource, the loader and the cache</div><div class="line"><a name="l01944"></a><span class="lineno"> 1944</span> </div><div class="line"><a name="l01945"></a><span class="lineno"> 1945</span> There are three main actors in the model: the resource, the loader and the</div><div class="line"><a name="l01946"></a><span class="lineno"> 1946</span> cache.</div><div class="line"><a name="l01947"></a><span class="lineno"> 1947</span> </div><div class="line"><a name="l01948"></a><span class="lineno"> 1948</span> The _resource_ is whatever the user wants it to be. An image, a video, an audio,</div><div class="line"><a name="l01949"></a><span class="lineno"> 1949</span> whatever. There are no limits.<br/></div><div class="line"><a name="l01950"></a><span class="lineno"> 1950</span> As a minimal example:</div><div class="line"><a name="l01951"></a><span class="lineno"> 1951</span> </div><div class="line"><a name="l01952"></a><span class="lineno"> 1952</span> ```cpp</div><div class="line"><a name="l01953"></a><span class="lineno"> 1953</span> struct MyResource { const int value; };</div><div class="line"><a name="l01954"></a><span class="lineno"> 1954</span> ```</div><div class="line"><a name="l01955"></a><span class="lineno"> 1955</span> </div><div class="line"><a name="l01956"></a><span class="lineno"> 1956</span> A _loader_ is a class the aim of which is to load a specific resource. It has to</div><div class="line"><a name="l01957"></a><span class="lineno"> 1957</span> inherit directly from the dedicated base class as in the following example:</div><div class="line"><a name="l01958"></a><span class="lineno"> 1958</span> </div><div class="line"><a name="l01959"></a><span class="lineno"> 1959</span> ```cpp</div><div class="line"><a name="l01960"></a><span class="lineno"> 1960</span> struct MyLoader final: entt::ResourceLoader<MyLoader, MyResource> {</div><div class="line"><a name="l01961"></a><span class="lineno"> 1961</span>  // ...</div><div class="line"><a name="l01962"></a><span class="lineno"> 1962</span> };</div><div class="line"><a name="l01963"></a><span class="lineno"> 1963</span> ```</div><div class="line"><a name="l01964"></a><span class="lineno"> 1964</span> </div><div class="line"><a name="l01965"></a><span class="lineno"> 1965</span> Where `MyResource` is the type of resources it creates.<br/></div><div class="line"><a name="l01966"></a><span class="lineno"> 1966</span> A resource loader must also expose a public const member function named `load`</div><div class="line"><a name="l01967"></a><span class="lineno"> 1967</span> that accepts a variable number of arguments and returns a shared pointer to a</div><div class="line"><a name="l01968"></a><span class="lineno"> 1968</span> resource.<br/></div><div class="line"><a name="l01969"></a><span class="lineno"> 1969</span> As an example:</div><div class="line"><a name="l01970"></a><span class="lineno"> 1970</span> </div><div class="line"><a name="l01971"></a><span class="lineno"> 1971</span> ```cpp</div><div class="line"><a name="l01972"></a><span class="lineno"> 1972</span> struct MyLoader: entt::ResourceLoader<MyLoader, MyResource> {</div><div class="line"><a name="l01973"></a><span class="lineno"> 1973</span>  std::shared_ptr<MyResource> load(int value) const {</div><div class="line"><a name="l01974"></a><span class="lineno"> 1974</span>  // ...</div><div class="line"><a name="l01975"></a><span class="lineno"> 1975</span>  return std::shared_ptr<MyResource>(new MyResource{ value });</div><div class="line"><a name="l01976"></a><span class="lineno"> 1976</span>  }</div><div class="line"><a name="l01977"></a><span class="lineno"> 1977</span> };</div><div class="line"><a name="l01978"></a><span class="lineno"> 1978</span> ```</div><div class="line"><a name="l01979"></a><span class="lineno"> 1979</span> </div><div class="line"><a name="l01980"></a><span class="lineno"> 1980</span> In general, resource loaders should not have a state or retain data of any type.</div><div class="line"><a name="l01981"></a><span class="lineno"> 1981</span> They should let the cache manage their resources instead.<br/></div><div class="line"><a name="l01982"></a><span class="lineno"> 1982</span> As a side note, base class and CRTP idiom aren't strictly required with the</div><div class="line"><a name="l01983"></a><span class="lineno"> 1983</span> current implementation. One could argue that a cache can easily work with</div><div class="line"><a name="l01984"></a><span class="lineno"> 1984</span> loaders of any type. However, future changes won't be breaking ones by forcing</div><div class="line"><a name="l01985"></a><span class="lineno"> 1985</span> the use of a base class today and that's why the model is already in its place.</div><div class="line"><a name="l01986"></a><span class="lineno"> 1986</span> </div><div class="line"><a name="l01987"></a><span class="lineno"> 1987</span> Finally, a cache is a specialization of a class template tailored to a specific</div><div class="line"><a name="l01988"></a><span class="lineno"> 1988</span> resource:</div><div class="line"><a name="l01989"></a><span class="lineno"> 1989</span> </div><div class="line"><a name="l01990"></a><span class="lineno"> 1990</span> ```cpp</div><div class="line"><a name="l01991"></a><span class="lineno"> 1991</span> using MyResourceCache = entt::ResourceCache<MyResource>;</div><div class="line"><a name="l01992"></a><span class="lineno"> 1992</span> </div><div class="line"><a name="l01993"></a><span class="lineno"> 1993</span> // ...</div><div class="line"><a name="l01994"></a><span class="lineno"> 1994</span> </div><div class="line"><a name="l01995"></a><span class="lineno"> 1995</span> MyResourceCache cache{};</div><div class="line"><a name="l01996"></a><span class="lineno"> 1996</span> ```</div><div class="line"><a name="l01997"></a><span class="lineno"> 1997</span> </div><div class="line"><a name="l01998"></a><span class="lineno"> 1998</span> The idea is to create different caches for different types of resources and to</div><div class="line"><a name="l01999"></a><span class="lineno"> 1999</span> manage each one independently and in the most appropriate way.<br/></div><div class="line"><a name="l02000"></a><span class="lineno"> 2000</span> As a (very) trivial example, audio tracks can survive in most of the scenes of</div><div class="line"><a name="l02001"></a><span class="lineno"> 2001</span> an application while meshes can be associated with a single scene and then</div><div class="line"><a name="l02002"></a><span class="lineno"> 2002</span> discarded when the user leaves it.</div><div class="line"><a name="l02003"></a><span class="lineno"> 2003</span> </div><div class="line"><a name="l02004"></a><span class="lineno"> 2004</span> A cache offers a set of basic functionalities to query its internal state and to</div><div class="line"><a name="l02005"></a><span class="lineno"> 2005</span> _organize_ it:</div><div class="line"><a name="l02006"></a><span class="lineno"> 2006</span> </div><div class="line"><a name="l02007"></a><span class="lineno"> 2007</span> ```cpp</div><div class="line"><a name="l02008"></a><span class="lineno"> 2008</span> // gets the number of resources managed by a cache</div><div class="line"><a name="l02009"></a><span class="lineno"> 2009</span> auto size = cache.size();</div><div class="line"><a name="l02010"></a><span class="lineno"> 2010</span> </div><div class="line"><a name="l02011"></a><span class="lineno"> 2011</span> // checks if a cache contains at least a valid resource</div><div class="line"><a name="l02012"></a><span class="lineno"> 2012</span> auto empty = cache.empty();</div><div class="line"><a name="l02013"></a><span class="lineno"> 2013</span> </div><div class="line"><a name="l02014"></a><span class="lineno"> 2014</span> // clears a cache and discards its content</div><div class="line"><a name="l02015"></a><span class="lineno"> 2015</span> cache.clear();</div><div class="line"><a name="l02016"></a><span class="lineno"> 2016</span> ```</div><div class="line"><a name="l02017"></a><span class="lineno"> 2017</span> </div><div class="line"><a name="l02018"></a><span class="lineno"> 2018</span> Besides these member functions, it contains what is needed to load, use and</div><div class="line"><a name="l02019"></a><span class="lineno"> 2019</span> discard resources of the given type.<br/></div><div class="line"><a name="l02020"></a><span class="lineno"> 2020</span> Before to explore this part of the interface, it makes sense to mention how</div><div class="line"><a name="l02021"></a><span class="lineno"> 2021</span> resources are identified. The type of the identifiers to use is defined as:</div><div class="line"><a name="l02022"></a><span class="lineno"> 2022</span> </div><div class="line"><a name="l02023"></a><span class="lineno"> 2023</span> ```cpp</div><div class="line"><a name="l02024"></a><span class="lineno"> 2024</span> entt::ResourceCache<Resource>::resource_type</div><div class="line"><a name="l02025"></a><span class="lineno"> 2025</span> ```</div><div class="line"><a name="l02026"></a><span class="lineno"> 2026</span> </div><div class="line"><a name="l02027"></a><span class="lineno"> 2027</span> Where `resource_type` is an alias for `entt::HashedString`. Therefore, resource</div><div class="line"><a name="l02028"></a><span class="lineno"> 2028</span> identifiers are created explicitly as in the following example:</div><div class="line"><a name="l02029"></a><span class="lineno"> 2029</span> </div><div class="line"><a name="l02030"></a><span class="lineno"> 2030</span> ```cpp</div><div class="line"><a name="l02031"></a><span class="lineno"> 2031</span> constexpr auto identifier = entt::ResourceCache<Resource>::resource_type{"my/resource/identifier"};</div><div class="line"><a name="l02032"></a><span class="lineno"> 2032</span> // this is equivalent to the following</div><div class="line"><a name="l02033"></a><span class="lineno"> 2033</span> constexpr auto hs = entt::HashedString{"my/resource/identifier"};</div><div class="line"><a name="l02034"></a><span class="lineno"> 2034</span> ```</div><div class="line"><a name="l02035"></a><span class="lineno"> 2035</span> </div><div class="line"><a name="l02036"></a><span class="lineno"> 2036</span> The class `HashedString` is described in a dedicated section, so I won't do in</div><div class="line"><a name="l02037"></a><span class="lineno"> 2037</span> details here.</div><div class="line"><a name="l02038"></a><span class="lineno"> 2038</span> </div><div class="line"><a name="l02039"></a><span class="lineno"> 2039</span> Resources are loaded and thus stored in a cache through the `load` member</div><div class="line"><a name="l02040"></a><span class="lineno"> 2040</span> function. It accepts the loader to use as a template parameter, the resource</div><div class="line"><a name="l02041"></a><span class="lineno"> 2041</span> identifier and the parameters used to construct the resource as arguments:</div><div class="line"><a name="l02042"></a><span class="lineno"> 2042</span> </div><div class="line"><a name="l02043"></a><span class="lineno"> 2043</span> ```cpp</div><div class="line"><a name="l02044"></a><span class="lineno"> 2044</span> // uses the identifier declared above</div><div class="line"><a name="l02045"></a><span class="lineno"> 2045</span> cache.load<MyLoader>(identifier, 0);</div><div class="line"><a name="l02046"></a><span class="lineno"> 2046</span> </div><div class="line"><a name="l02047"></a><span class="lineno"> 2047</span> // uses a const char * directly as an identifier</div><div class="line"><a name="l02048"></a><span class="lineno"> 2048</span> cache.load<MyLoader>("another/identifier", 42);</div><div class="line"><a name="l02049"></a><span class="lineno"> 2049</span> ```</div><div class="line"><a name="l02050"></a><span class="lineno"> 2050</span> </div><div class="line"><a name="l02051"></a><span class="lineno"> 2051</span> The return value can be used to know if the resource has been loaded correctly.</div><div class="line"><a name="l02052"></a><span class="lineno"> 2052</span> In case the loader returns an invalid pointer or the resource already exists in</div><div class="line"><a name="l02053"></a><span class="lineno"> 2053</span> the cache, a false value is returned:</div><div class="line"><a name="l02054"></a><span class="lineno"> 2054</span> </div><div class="line"><a name="l02055"></a><span class="lineno"> 2055</span> ```cpp</div><div class="line"><a name="l02056"></a><span class="lineno"> 2056</span> if(!cache.load<MyLoader>("another/identifier", 42)) {</div><div class="line"><a name="l02057"></a><span class="lineno"> 2057</span>  // ...</div><div class="line"><a name="l02058"></a><span class="lineno"> 2058</span> }</div><div class="line"><a name="l02059"></a><span class="lineno"> 2059</span> ```</div><div class="line"><a name="l02060"></a><span class="lineno"> 2060</span> </div><div class="line"><a name="l02061"></a><span class="lineno"> 2061</span> Unfortunately, in this case there is no way to know what was the problem</div><div class="line"><a name="l02062"></a><span class="lineno"> 2062</span> exactly. However, before trying to load a resource or after an error, one can</div><div class="line"><a name="l02063"></a><span class="lineno"> 2063</span> use the `contains` member function to know if a cache already contains a</div><div class="line"><a name="l02064"></a><span class="lineno"> 2064</span> specific resource:</div><div class="line"><a name="l02065"></a><span class="lineno"> 2065</span> </div><div class="line"><a name="l02066"></a><span class="lineno"> 2066</span> ```cpp</div><div class="line"><a name="l02067"></a><span class="lineno"> 2067</span> auto exists = cache.contains("my/identifier");</div><div class="line"><a name="l02068"></a><span class="lineno"> 2068</span> ```</div><div class="line"><a name="l02069"></a><span class="lineno"> 2069</span> </div><div class="line"><a name="l02070"></a><span class="lineno"> 2070</span> There exists also a member function to use to force a reload of an already</div><div class="line"><a name="l02071"></a><span class="lineno"> 2071</span> existing resource if needed:</div><div class="line"><a name="l02072"></a><span class="lineno"> 2072</span> </div><div class="line"><a name="l02073"></a><span class="lineno"> 2073</span> ```cpp</div><div class="line"><a name="l02074"></a><span class="lineno"> 2074</span> auto result = cache.reload<MyLoader>("another/identifier", 42);</div><div class="line"><a name="l02075"></a><span class="lineno"> 2075</span> ```</div><div class="line"><a name="l02076"></a><span class="lineno"> 2076</span> </div><div class="line"><a name="l02077"></a><span class="lineno"> 2077</span> As above, the function returns true in case of success, false otherwise. The</div><div class="line"><a name="l02078"></a><span class="lineno"> 2078</span> sole difference in this case is that an error necessarily means that the loader</div><div class="line"><a name="l02079"></a><span class="lineno"> 2079</span> has failed for some reasons to load the resource.<br/></div><div class="line"><a name="l02080"></a><span class="lineno"> 2080</span> Note that the `reload` member function is a kind of alias of the following</div><div class="line"><a name="l02081"></a><span class="lineno"> 2081</span> snippet:</div><div class="line"><a name="l02082"></a><span class="lineno"> 2082</span> </div><div class="line"><a name="l02083"></a><span class="lineno"> 2083</span> ```cpp</div><div class="line"><a name="l02084"></a><span class="lineno"> 2084</span> cache.discard(identifier);</div><div class="line"><a name="l02085"></a><span class="lineno"> 2085</span> cache.load<MyLoader>(identifier, 42);</div><div class="line"><a name="l02086"></a><span class="lineno"> 2086</span> ```</div><div class="line"><a name="l02087"></a><span class="lineno"> 2087</span> </div><div class="line"><a name="l02088"></a><span class="lineno"> 2088</span> Where the `discard` member function is used to get rid of a resource if loaded.</div><div class="line"><a name="l02089"></a><span class="lineno"> 2089</span> In case the cache doesn't contain a resource for the given identifier, the</div><div class="line"><a name="l02090"></a><span class="lineno"> 2090</span> function does nothing and returns immediately.</div><div class="line"><a name="l02091"></a><span class="lineno"> 2091</span> </div><div class="line"><a name="l02092"></a><span class="lineno"> 2092</span> So far, so good. Resources are finally loaded and stored within the cache.<br/></div><div class="line"><a name="l02093"></a><span class="lineno"> 2093</span> They are returned to users in the form of handles. To get one of them:</div><div class="line"><a name="l02094"></a><span class="lineno"> 2094</span> </div><div class="line"><a name="l02095"></a><span class="lineno"> 2095</span> ```cpp</div><div class="line"><a name="l02096"></a><span class="lineno"> 2096</span> auto handle = cache.handle("my/identifier");</div><div class="line"><a name="l02097"></a><span class="lineno"> 2097</span> ```</div><div class="line"><a name="l02098"></a><span class="lineno"> 2098</span> </div><div class="line"><a name="l02099"></a><span class="lineno"> 2099</span> The idea behind a handle is the same of the flyweight pattern. In other terms,</div><div class="line"><a name="l02100"></a><span class="lineno"> 2100</span> resources aren't copied around. Instead, instances are shared between handles.</div><div class="line"><a name="l02101"></a><span class="lineno"> 2101</span> Users of a resource owns a handle and it guarantees that a resource isn't</div><div class="line"><a name="l02102"></a><span class="lineno"> 2102</span> destroyed until all the handles are destroyed, even if the resource itself is</div><div class="line"><a name="l02103"></a><span class="lineno"> 2103</span> removed from the cache.<br/></div><div class="line"><a name="l02104"></a><span class="lineno"> 2104</span> Handles are tiny objects both movable and copyable. They returns the contained</div><div class="line"><a name="l02105"></a><span class="lineno"> 2105</span> resource as a const reference on request:</div><div class="line"><a name="l02106"></a><span class="lineno"> 2106</span> </div><div class="line"><a name="l02107"></a><span class="lineno"> 2107</span> * By means of the `get` member function:</div><div class="line"><a name="l02108"></a><span class="lineno"> 2108</span> </div><div class="line"><a name="l02109"></a><span class="lineno"> 2109</span>  ```cpp</div><div class="line"><a name="l02110"></a><span class="lineno"> 2110</span>  const auto &resource = handle.get();</div><div class="line"><a name="l02111"></a><span class="lineno"> 2111</span>  ```</div><div class="line"><a name="l02112"></a><span class="lineno"> 2112</span> </div><div class="line"><a name="l02113"></a><span class="lineno"> 2113</span> * Using the proper cast operator:</div><div class="line"><a name="l02114"></a><span class="lineno"> 2114</span> </div><div class="line"><a name="l02115"></a><span class="lineno"> 2115</span>  ```cpp</div><div class="line"><a name="l02116"></a><span class="lineno"> 2116</span>  const auto &resource = handle;</div><div class="line"><a name="l02117"></a><span class="lineno"> 2117</span>  ```</div><div class="line"><a name="l02118"></a><span class="lineno"> 2118</span> </div><div class="line"><a name="l02119"></a><span class="lineno"> 2119</span> * Through the dereference operator:</div><div class="line"><a name="l02120"></a><span class="lineno"> 2120</span> </div><div class="line"><a name="l02121"></a><span class="lineno"> 2121</span>  ```cpp</div><div class="line"><a name="l02122"></a><span class="lineno"> 2122</span>  const auto &resource = *handle;</div><div class="line"><a name="l02123"></a><span class="lineno"> 2123</span>  ```</div><div class="line"><a name="l02124"></a><span class="lineno"> 2124</span> </div><div class="line"><a name="l02125"></a><span class="lineno"> 2125</span> The resource can also be accessed directly using the arrow operator if required:</div><div class="line"><a name="l02126"></a><span class="lineno"> 2126</span> </div><div class="line"><a name="l02127"></a><span class="lineno"> 2127</span> ```cpp</div><div class="line"><a name="l02128"></a><span class="lineno"> 2128</span> auto value = handle->value;</div><div class="line"><a name="l02129"></a><span class="lineno"> 2129</span> ```</div><div class="line"><a name="l02130"></a><span class="lineno"> 2130</span> </div><div class="line"><a name="l02131"></a><span class="lineno"> 2131</span> To test if a handle is still valid, the cast operator to `bool` allows users to</div><div class="line"><a name="l02132"></a><span class="lineno"> 2132</span> use it in a guard:</div><div class="line"><a name="l02133"></a><span class="lineno"> 2133</span> </div><div class="line"><a name="l02134"></a><span class="lineno"> 2134</span> ```cpp</div><div class="line"><a name="l02135"></a><span class="lineno"> 2135</span> if(handle) {</div><div class="line"><a name="l02136"></a><span class="lineno"> 2136</span>  // ...</div><div class="line"><a name="l02137"></a><span class="lineno"> 2137</span> }</div><div class="line"><a name="l02138"></a><span class="lineno"> 2138</span> ```</div><div class="line"><a name="l02139"></a><span class="lineno"> 2139</span> </div><div class="line"><a name="l02140"></a><span class="lineno"> 2140</span> Finally, in case there is the need to load a resource and thus to get a handle</div><div class="line"><a name="l02141"></a><span class="lineno"> 2141</span> without storing the resource itself in the cache, users can rely on the `temp`</div><div class="line"><a name="l02142"></a><span class="lineno"> 2142</span> member function template.<br/></div><div class="line"><a name="l02143"></a><span class="lineno"> 2143</span> The declaration is similar to the one of `load` but for the fact that it doesn't</div><div class="line"><a name="l02144"></a><span class="lineno"> 2144</span> return a boolean value. Instead, it returns a (possibly invalid) handle for the</div><div class="line"><a name="l02145"></a><span class="lineno"> 2145</span> resource:</div><div class="line"><a name="l02146"></a><span class="lineno"> 2146</span> </div><div class="line"><a name="l02147"></a><span class="lineno"> 2147</span> ```cpp</div><div class="line"><a name="l02148"></a><span class="lineno"> 2148</span> auto handle = cache.temp<MyLoader>("another/identifier", 42);</div><div class="line"><a name="l02149"></a><span class="lineno"> 2149</span> ```</div><div class="line"><a name="l02150"></a><span class="lineno"> 2150</span> </div><div class="line"><a name="l02151"></a><span class="lineno"> 2151</span> Do not forget to test the handle for validity. Otherwise, getting the reference</div><div class="line"><a name="l02152"></a><span class="lineno"> 2152</span> to the resource it points may result in undefined behavior.</div><div class="line"><a name="l02153"></a><span class="lineno"> 2153</span> </div><div class="line"><a name="l02154"></a><span class="lineno"> 2154</span> # Crash Course: events, signals and everything in between</div><div class="line"><a name="l02155"></a><span class="lineno"> 2155</span> </div><div class="line"><a name="l02156"></a><span class="lineno"> 2156</span> Signals are usually a core part of games and software architectures in</div><div class="line"><a name="l02157"></a><span class="lineno"> 2157</span> general.<br/></div><div class="line"><a name="l02158"></a><span class="lineno"> 2158</span> Roughly speaking, they help to decouple the various parts of a system while</div><div class="line"><a name="l02159"></a><span class="lineno"> 2159</span> allowing them to communicate with each other somehow.</div><div class="line"><a name="l02160"></a><span class="lineno"> 2160</span> </div><div class="line"><a name="l02161"></a><span class="lineno"> 2161</span> The so called _modern C++_ comes with a tool that can be useful in these terms,</div><div class="line"><a name="l02162"></a><span class="lineno"> 2162</span> the `std::function`. As an example, it can be used to create delegates.<br/></div><div class="line"><a name="l02163"></a><span class="lineno"> 2163</span> However, there is no guarantee that an `std::function` does not perform</div><div class="line"><a name="l02164"></a><span class="lineno"> 2164</span> allocations under the hood and this could be problematic sometimes. Furthermore,</div><div class="line"><a name="l02165"></a><span class="lineno"> 2165</span> it solves a problem but may not adapt well to other requirements that may arise</div><div class="line"><a name="l02166"></a><span class="lineno"> 2166</span> from time to time.</div><div class="line"><a name="l02167"></a><span class="lineno"> 2167</span> </div><div class="line"><a name="l02168"></a><span class="lineno"> 2168</span> In case that the flexibility and potential of an `std::function` are not</div><div class="line"><a name="l02169"></a><span class="lineno"> 2169</span> required or where you are looking for something different, the `EnTT` framework</div><div class="line"><a name="l02170"></a><span class="lineno"> 2170</span> offers a full set of classes to solve completely different problems.</div><div class="line"><a name="l02171"></a><span class="lineno"> 2171</span> </div><div class="line"><a name="l02172"></a><span class="lineno"> 2172</span> ## Signals</div><div class="line"><a name="l02173"></a><span class="lineno"> 2173</span> </div><div class="line"><a name="l02174"></a><span class="lineno"> 2174</span> Signal handlers work with naked pointers, function pointers and pointers to</div><div class="line"><a name="l02175"></a><span class="lineno"> 2175</span> member functions. Listeners can be any kind of objects and the user is in charge</div><div class="line"><a name="l02176"></a><span class="lineno"> 2176</span> of connecting and disconnecting them from a signal to avoid crashes due to</div><div class="line"><a name="l02177"></a><span class="lineno"> 2177</span> different lifetimes. On the other side, performance shouldn't be affected that</div><div class="line"><a name="l02178"></a><span class="lineno"> 2178</span> much by the presence of such a signal handler.<br/></div><div class="line"><a name="l02179"></a><span class="lineno"> 2179</span> A signal handler can be used as a private data member without exposing any</div><div class="line"><a name="l02180"></a><span class="lineno"> 2180</span> _publish_ functionality to the clients of a class. The basic idea is to impose a</div><div class="line"><a name="l02181"></a><span class="lineno"> 2181</span> clear separation between the signal itself and its _sink_ class, that is a tool</div><div class="line"><a name="l02182"></a><span class="lineno"> 2182</span> to be used to connect and disconnect listeners on the fly.</div><div class="line"><a name="l02183"></a><span class="lineno"> 2183</span> </div><div class="line"><a name="l02184"></a><span class="lineno"> 2184</span> The API of a signal handler is straightforward. The most important thing is that</div><div class="line"><a name="l02185"></a><span class="lineno"> 2185</span> it comes in two forms: with and without a collector. In case a signal is</div><div class="line"><a name="l02186"></a><span class="lineno"> 2186</span> associated with a collector, all the values returned by the listeners can be</div><div class="line"><a name="l02187"></a><span class="lineno"> 2187</span> literally _collected_ and used later by the caller. Otherwise it works just like</div><div class="line"><a name="l02188"></a><span class="lineno"> 2188</span> a plain signal that emits events from time to time.<br/></div><div class="line"><a name="l02189"></a><span class="lineno"> 2189</span> </div><div class="line"><a name="l02190"></a><span class="lineno"> 2190</span> **Note**: collectors are allowed only in case of function types whose the return</div><div class="line"><a name="l02191"></a><span class="lineno"> 2191</span> type isn't `void` for obvious reasons.</div><div class="line"><a name="l02192"></a><span class="lineno"> 2192</span> </div><div class="line"><a name="l02193"></a><span class="lineno"> 2193</span> To create instances of signal handlers there exist mainly two ways:</div><div class="line"><a name="l02194"></a><span class="lineno"> 2194</span> </div><div class="line"><a name="l02195"></a><span class="lineno"> 2195</span> ```cpp</div><div class="line"><a name="l02196"></a><span class="lineno"> 2196</span> // no collector type</div><div class="line"><a name="l02197"></a><span class="lineno"> 2197</span> entt::SigH<void(int, char)> signal;</div><div class="line"><a name="l02198"></a><span class="lineno"> 2198</span> </div><div class="line"><a name="l02199"></a><span class="lineno"> 2199</span> // explicit collector type</div><div class="line"><a name="l02200"></a><span class="lineno"> 2200</span> entt::SigH<void(int, char), MyCollector<bool>> collector;</div><div class="line"><a name="l02201"></a><span class="lineno"> 2201</span> ```</div><div class="line"><a name="l02202"></a><span class="lineno"> 2202</span> </div><div class="line"><a name="l02203"></a><span class="lineno"> 2203</span> As expected, they offer all the basic functionalities required to know how many</div><div class="line"><a name="l02204"></a><span class="lineno"> 2204</span> listeners they contain (`size`) or if they contain at least a listener (`empty`)</div><div class="line"><a name="l02205"></a><span class="lineno"> 2205</span> and even to swap two signal handlers (`swap`).</div><div class="line"><a name="l02206"></a><span class="lineno"> 2206</span> </div><div class="line"><a name="l02207"></a><span class="lineno"> 2207</span> Besides them, there are member functions to use both to connect and disconnect</div><div class="line"><a name="l02208"></a><span class="lineno"> 2208</span> listeners in all their forms by means of a sink::</div><div class="line"><a name="l02209"></a><span class="lineno"> 2209</span> </div><div class="line"><a name="l02210"></a><span class="lineno"> 2210</span> ```cpp</div><div class="line"><a name="l02211"></a><span class="lineno"> 2211</span> void foo(int, char) { /* ... */ }</div><div class="line"><a name="l02212"></a><span class="lineno"> 2212</span> </div><div class="line"><a name="l02213"></a><span class="lineno"> 2213</span> struct S {</div><div class="line"><a name="l02214"></a><span class="lineno"> 2214</span>  void bar(int, char) { /* ... */ }</div><div class="line"><a name="l02215"></a><span class="lineno"> 2215</span> };</div><div class="line"><a name="l02216"></a><span class="lineno"> 2216</span> </div><div class="line"><a name="l02217"></a><span class="lineno"> 2217</span> // ...</div><div class="line"><a name="l02218"></a><span class="lineno"> 2218</span> </div><div class="line"><a name="l02219"></a><span class="lineno"> 2219</span> S instance;</div><div class="line"><a name="l02220"></a><span class="lineno"> 2220</span> </div><div class="line"><a name="l02221"></a><span class="lineno"> 2221</span> signal.sink().connect<&foo>();</div><div class="line"><a name="l02222"></a><span class="lineno"> 2222</span> signal.sink().connect<S, &S::bar>(&instance);</div><div class="line"><a name="l02223"></a><span class="lineno"> 2223</span> </div><div class="line"><a name="l02224"></a><span class="lineno"> 2224</span> // ...</div><div class="line"><a name="l02225"></a><span class="lineno"> 2225</span> </div><div class="line"><a name="l02226"></a><span class="lineno"> 2226</span> // disconnects a free function</div><div class="line"><a name="l02227"></a><span class="lineno"> 2227</span> signal.sink().disconnect<&foo>();</div><div class="line"><a name="l02228"></a><span class="lineno"> 2228</span> </div><div class="line"><a name="l02229"></a><span class="lineno"> 2229</span> // disconnect a specific member function of an instance ...</div><div class="line"><a name="l02230"></a><span class="lineno"> 2230</span> signal.sink().disconnect<S, &S::bar>(&instance);</div><div class="line"><a name="l02231"></a><span class="lineno"> 2231</span> </div><div class="line"><a name="l02232"></a><span class="lineno"> 2232</span> // ... or an instance as a whole</div><div class="line"><a name="l02233"></a><span class="lineno"> 2233</span> signal.sink().disconnect(&instance);</div><div class="line"><a name="l02234"></a><span class="lineno"> 2234</span> </div><div class="line"><a name="l02235"></a><span class="lineno"> 2235</span> // discards all the listeners at once</div><div class="line"><a name="l02236"></a><span class="lineno"> 2236</span> signal.sink().disconnect();</div><div class="line"><a name="l02237"></a><span class="lineno"> 2237</span> ```</div><div class="line"><a name="l02238"></a><span class="lineno"> 2238</span> </div><div class="line"><a name="l02239"></a><span class="lineno"> 2239</span> Once listeners are attached (or even if there are no listeners at all), events</div><div class="line"><a name="l02240"></a><span class="lineno"> 2240</span> and data in general can be published through a signal by means of the `publish`</div><div class="line"><a name="l02241"></a><span class="lineno"> 2241</span> member function:</div><div class="line"><a name="l02242"></a><span class="lineno"> 2242</span> </div><div class="line"><a name="l02243"></a><span class="lineno"> 2243</span> ```cpp</div><div class="line"><a name="l02244"></a><span class="lineno"> 2244</span> signal.publish(42, 'c');</div><div class="line"><a name="l02245"></a><span class="lineno"> 2245</span> ```</div><div class="line"><a name="l02246"></a><span class="lineno"> 2246</span> </div><div class="line"><a name="l02247"></a><span class="lineno"> 2247</span> To collect data, the `collect` member function should be used instead. Below is</div><div class="line"><a name="l02248"></a><span class="lineno"> 2248</span> a minimal example to show how to use it:</div><div class="line"><a name="l02249"></a><span class="lineno"> 2249</span> </div><div class="line"><a name="l02250"></a><span class="lineno"> 2250</span> ```cpp</div><div class="line"><a name="l02251"></a><span class="lineno"> 2251</span> struct MyCollector {</div><div class="line"><a name="l02252"></a><span class="lineno"> 2252</span>  std::vector<int> vec{};</div><div class="line"><a name="l02253"></a><span class="lineno"> 2253</span> </div><div class="line"><a name="l02254"></a><span class="lineno"> 2254</span>  bool operator()(int v) noexcept {</div><div class="line"><a name="l02255"></a><span class="lineno"> 2255</span>  vec.push_back(v);</div><div class="line"><a name="l02256"></a><span class="lineno"> 2256</span>  return true;</div><div class="line"><a name="l02257"></a><span class="lineno"> 2257</span>  }</div><div class="line"><a name="l02258"></a><span class="lineno"> 2258</span> };</div><div class="line"><a name="l02259"></a><span class="lineno"> 2259</span> </div><div class="line"><a name="l02260"></a><span class="lineno"> 2260</span> int f() { return 0; }</div><div class="line"><a name="l02261"></a><span class="lineno"> 2261</span> int g() { return 1; }</div><div class="line"><a name="l02262"></a><span class="lineno"> 2262</span> </div><div class="line"><a name="l02263"></a><span class="lineno"> 2263</span> // ...</div><div class="line"><a name="l02264"></a><span class="lineno"> 2264</span> </div><div class="line"><a name="l02265"></a><span class="lineno"> 2265</span> entt::SigH<int(), MyCollector<int>> signal;</div><div class="line"><a name="l02266"></a><span class="lineno"> 2266</span> </div><div class="line"><a name="l02267"></a><span class="lineno"> 2267</span> signal.sink().connect<&f>();</div><div class="line"><a name="l02268"></a><span class="lineno"> 2268</span> signal.sink().connect<&g>();</div><div class="line"><a name="l02269"></a><span class="lineno"> 2269</span> </div><div class="line"><a name="l02270"></a><span class="lineno"> 2270</span> MyCollector collector = signal.collect();</div><div class="line"><a name="l02271"></a><span class="lineno"> 2271</span> </div><div class="line"><a name="l02272"></a><span class="lineno"> 2272</span> assert(collector.vec[0] == 0);</div><div class="line"><a name="l02273"></a><span class="lineno"> 2273</span> assert(collector.vec[1] == 1);</div><div class="line"><a name="l02274"></a><span class="lineno"> 2274</span> ```</div><div class="line"><a name="l02275"></a><span class="lineno"> 2275</span> </div><div class="line"><a name="l02276"></a><span class="lineno"> 2276</span> As shown above, a collector must expose a function operator that accepts as an</div><div class="line"><a name="l02277"></a><span class="lineno"> 2277</span> argument a type to which the return type of the listeners can be converted.</div><div class="line"><a name="l02278"></a><span class="lineno"> 2278</span> Moreover, it has to return a boolean value that is false to stop collecting</div><div class="line"><a name="l02279"></a><span class="lineno"> 2279</span> data, true otherwise. This way one can avoid calling all the listeners in case</div><div class="line"><a name="l02280"></a><span class="lineno"> 2280</span> it isn't necessary.</div><div class="line"><a name="l02281"></a><span class="lineno"> 2281</span> </div><div class="line"><a name="l02282"></a><span class="lineno"> 2282</span> ## Delegate</div><div class="line"><a name="l02283"></a><span class="lineno"> 2283</span> </div><div class="line"><a name="l02284"></a><span class="lineno"> 2284</span> A delegate can be used as general purpose invoker with no memory overhead for</div><div class="line"><a name="l02285"></a><span class="lineno"> 2285</span> free functions and member functions provided along with an instance on which</div><div class="line"><a name="l02286"></a><span class="lineno"> 2286</span> to invoke them.<br/></div><div class="line"><a name="l02287"></a><span class="lineno"> 2287</span> It does not claim to be a drop-in replacement for an `std::function`, so do not</div><div class="line"><a name="l02288"></a><span class="lineno"> 2288</span> expect to use it whenever an `std::function` fits well. However, it can be used</div><div class="line"><a name="l02289"></a><span class="lineno"> 2289</span> to send opaque delegates around to be used to invoke functions as needed.</div><div class="line"><a name="l02290"></a><span class="lineno"> 2290</span> </div><div class="line"><a name="l02291"></a><span class="lineno"> 2291</span> The interface is trivial. It offers a default constructor to create empty</div><div class="line"><a name="l02292"></a><span class="lineno"> 2292</span> delegates:</div><div class="line"><a name="l02293"></a><span class="lineno"> 2293</span> </div><div class="line"><a name="l02294"></a><span class="lineno"> 2294</span> ```cpp</div><div class="line"><a name="l02295"></a><span class="lineno"> 2295</span> entt::Delegate<int(int)> delegate{};</div><div class="line"><a name="l02296"></a><span class="lineno"> 2296</span> ```</div><div class="line"><a name="l02297"></a><span class="lineno"> 2297</span> </div><div class="line"><a name="l02298"></a><span class="lineno"> 2298</span> All what is needed to create an instance is to specify the type of the function</div><div class="line"><a name="l02299"></a><span class="lineno"> 2299</span> the delegate will _contain_, that is the signature of the free function or the</div><div class="line"><a name="l02300"></a><span class="lineno"> 2300</span> member function one wants to assign to it.</div><div class="line"><a name="l02301"></a><span class="lineno"> 2301</span> </div><div class="line"><a name="l02302"></a><span class="lineno"> 2302</span> Attempting to use an empty delegate by invoking its function call operator</div><div class="line"><a name="l02303"></a><span class="lineno"> 2303</span> results in undefined behavior, most likely a crash actually. Before to use a</div><div class="line"><a name="l02304"></a><span class="lineno"> 2304</span> delegate, it must be initialized.<br/></div><div class="line"><a name="l02305"></a><span class="lineno"> 2305</span> There exist two functions to do that, both named `connect`:</div><div class="line"><a name="l02306"></a><span class="lineno"> 2306</span> </div><div class="line"><a name="l02307"></a><span class="lineno"> 2307</span> ```cpp</div><div class="line"><a name="l02308"></a><span class="lineno"> 2308</span> int f(int i) { return i; }</div><div class="line"><a name="l02309"></a><span class="lineno"> 2309</span> </div><div class="line"><a name="l02310"></a><span class="lineno"> 2310</span> struct MyStruct {</div><div class="line"><a name="l02311"></a><span class="lineno"> 2311</span>  int f(int i) { return i }</div><div class="line"><a name="l02312"></a><span class="lineno"> 2312</span> };</div><div class="line"><a name="l02313"></a><span class="lineno"> 2313</span> </div><div class="line"><a name="l02314"></a><span class="lineno"> 2314</span> // bind a free function to the delegate</div><div class="line"><a name="l02315"></a><span class="lineno"> 2315</span> delegate.connect<&f>();</div><div class="line"><a name="l02316"></a><span class="lineno"> 2316</span> </div><div class="line"><a name="l02317"></a><span class="lineno"> 2317</span> // bind a member function to the delegate</div><div class="line"><a name="l02318"></a><span class="lineno"> 2318</span> MyStruct instance;</div><div class="line"><a name="l02319"></a><span class="lineno"> 2319</span> delegate.connect<MyStruct, &MyStruct::f>(&instance);</div><div class="line"><a name="l02320"></a><span class="lineno"> 2320</span> ```</div><div class="line"><a name="l02321"></a><span class="lineno"> 2321</span> </div><div class="line"><a name="l02322"></a><span class="lineno"> 2322</span> It hasn't a `disconnect` counterpart. Instead, there exists a `reset` member</div><div class="line"><a name="l02323"></a><span class="lineno"> 2323</span> function to clear it.<br/></div><div class="line"><a name="l02324"></a><span class="lineno"> 2324</span> Finally, to invoke a delegate, the function call operator is the way to go as</div><div class="line"><a name="l02325"></a><span class="lineno"> 2325</span> usual:</div><div class="line"><a name="l02326"></a><span class="lineno"> 2326</span> </div><div class="line"><a name="l02327"></a><span class="lineno"> 2327</span> ```cpp</div><div class="line"><a name="l02328"></a><span class="lineno"> 2328</span> auto ret = delegate(42);</div><div class="line"><a name="l02329"></a><span class="lineno"> 2329</span> ```</div><div class="line"><a name="l02330"></a><span class="lineno"> 2330</span> </div><div class="line"><a name="l02331"></a><span class="lineno"> 2331</span> Probably too much small and pretty poor of functionalities, but the delegate</div><div class="line"><a name="l02332"></a><span class="lineno"> 2332</span> class can help in a lot of cases and it has shown that it is worth keeping it</div><div class="line"><a name="l02333"></a><span class="lineno"> 2333</span> within the framework.</div><div class="line"><a name="l02334"></a><span class="lineno"> 2334</span> </div><div class="line"><a name="l02335"></a><span class="lineno"> 2335</span> ## Event dispatcher</div><div class="line"><a name="l02336"></a><span class="lineno"> 2336</span> </div><div class="line"><a name="l02337"></a><span class="lineno"> 2337</span> The event dispatcher class is designed so as to be used in a loop. It allows</div><div class="line"><a name="l02338"></a><span class="lineno"> 2338</span> users both to trigger immediate events or to queue events to be published all</div><div class="line"><a name="l02339"></a><span class="lineno"> 2339</span> together once per tick.<br/></div><div class="line"><a name="l02340"></a><span class="lineno"> 2340</span> This class shares part of its API with the one of the signal handler, but it</div><div class="line"><a name="l02341"></a><span class="lineno"> 2341</span> doesn't require that all the types of events are specified when declared:</div><div class="line"><a name="l02342"></a><span class="lineno"> 2342</span> </div><div class="line"><a name="l02343"></a><span class="lineno"> 2343</span> ```cpp</div><div class="line"><a name="l02344"></a><span class="lineno"> 2344</span> // define a general purpose dispatcher that works with naked pointers</div><div class="line"><a name="l02345"></a><span class="lineno"> 2345</span> entt::Dispatcher dispatcher{};</div><div class="line"><a name="l02346"></a><span class="lineno"> 2346</span> ```</div><div class="line"><a name="l02347"></a><span class="lineno"> 2347</span> </div><div class="line"><a name="l02348"></a><span class="lineno"> 2348</span> In order to register an instance of a class to a dispatcher, its type must</div><div class="line"><a name="l02349"></a><span class="lineno"> 2349</span> expose one or more member functions of which the return types are `void` and the</div><div class="line"><a name="l02350"></a><span class="lineno"> 2350</span> argument lists are `const E &`, for each type of event `E`.<br/></div><div class="line"><a name="l02351"></a><span class="lineno"> 2351</span> To ease the development, member functions that are named `receive` are</div><div class="line"><a name="l02352"></a><span class="lineno"> 2352</span> automatically detected and have not to be explicitly specified when registered.</div><div class="line"><a name="l02353"></a><span class="lineno"> 2353</span> In all the other cases, the name of the member function aimed to receive the</div><div class="line"><a name="l02354"></a><span class="lineno"> 2354</span> event must be provided to the `connect` member function of the sink bound to the</div><div class="line"><a name="l02355"></a><span class="lineno"> 2355</span> specific event:</div><div class="line"><a name="l02356"></a><span class="lineno"> 2356</span> </div><div class="line"><a name="l02357"></a><span class="lineno"> 2357</span> ```cpp</div><div class="line"><a name="l02358"></a><span class="lineno"> 2358</span> struct AnEvent { int value; };</div><div class="line"><a name="l02359"></a><span class="lineno"> 2359</span> struct AnotherEvent {};</div><div class="line"><a name="l02360"></a><span class="lineno"> 2360</span> </div><div class="line"><a name="l02361"></a><span class="lineno"> 2361</span> struct Listener</div><div class="line"><a name="l02362"></a><span class="lineno"> 2362</span> {</div><div class="line"><a name="l02363"></a><span class="lineno"> 2363</span>  void receive(const AnEvent &) { /* ... */ }</div><div class="line"><a name="l02364"></a><span class="lineno"> 2364</span>  void method(const AnotherEvent &) { /* ... */ }</div><div class="line"><a name="l02365"></a><span class="lineno"> 2365</span> };</div><div class="line"><a name="l02366"></a><span class="lineno"> 2366</span> </div><div class="line"><a name="l02367"></a><span class="lineno"> 2367</span> // ...</div><div class="line"><a name="l02368"></a><span class="lineno"> 2368</span> </div><div class="line"><a name="l02369"></a><span class="lineno"> 2369</span> Listener listener;</div><div class="line"><a name="l02370"></a><span class="lineno"> 2370</span> dispatcher.sink<AnEvent>().connect(&listener);</div><div class="line"><a name="l02371"></a><span class="lineno"> 2371</span> dispatcher.sink<AnotherEvent>().connect<Listener, &Listener::method>(&listener);</div><div class="line"><a name="l02372"></a><span class="lineno"> 2372</span> ```</div><div class="line"><a name="l02373"></a><span class="lineno"> 2373</span> </div><div class="line"><a name="l02374"></a><span class="lineno"> 2374</span> The `disconnect` member function follows the same pattern and can be used to</div><div class="line"><a name="l02375"></a><span class="lineno"> 2375</span> selectively remove listeners:</div><div class="line"><a name="l02376"></a><span class="lineno"> 2376</span> </div><div class="line"><a name="l02377"></a><span class="lineno"> 2377</span> ```cpp</div><div class="line"><a name="l02378"></a><span class="lineno"> 2378</span> dispatcher.sink<AnEvent>().disconnect(&listener);</div><div class="line"><a name="l02379"></a><span class="lineno"> 2379</span> dispatcher.sink<AnotherEvent>().disconnect<Listener, &Listener::method>(&listener);</div><div class="line"><a name="l02380"></a><span class="lineno"> 2380</span> ```</div><div class="line"><a name="l02381"></a><span class="lineno"> 2381</span> </div><div class="line"><a name="l02382"></a><span class="lineno"> 2382</span> The `trigger` member function serves the purpose of sending an immediate event</div><div class="line"><a name="l02383"></a><span class="lineno"> 2383</span> to all the listeners registered so far. It offers a convenient approach that</div><div class="line"><a name="l02384"></a><span class="lineno"> 2384</span> relieves the user from having to create the event itself. Instead, it's enough</div><div class="line"><a name="l02385"></a><span class="lineno"> 2385</span> to specify the type of event and provide all the parameters required to</div><div class="line"><a name="l02386"></a><span class="lineno"> 2386</span> construct it.<br/></div><div class="line"><a name="l02387"></a><span class="lineno"> 2387</span> As an example:</div><div class="line"><a name="l02388"></a><span class="lineno"> 2388</span> </div><div class="line"><a name="l02389"></a><span class="lineno"> 2389</span> ```cpp</div><div class="line"><a name="l02390"></a><span class="lineno"> 2390</span> dispatcher.trigger<AnEvent>(42);</div><div class="line"><a name="l02391"></a><span class="lineno"> 2391</span> dispatcher.trigger<AnotherEvent>();</div><div class="line"><a name="l02392"></a><span class="lineno"> 2392</span> ```</div><div class="line"><a name="l02393"></a><span class="lineno"> 2393</span> </div><div class="line"><a name="l02394"></a><span class="lineno"> 2394</span> Listeners are invoked immediately, order of execution isn't guaranteed. This</div><div class="line"><a name="l02395"></a><span class="lineno"> 2395</span> method can be used to push around urgent messages like an _is terminating_</div><div class="line"><a name="l02396"></a><span class="lineno"> 2396</span> notification on a mobile app.</div><div class="line"><a name="l02397"></a><span class="lineno"> 2397</span> </div><div class="line"><a name="l02398"></a><span class="lineno"> 2398</span> On the other hand, the `enqueue` member function queues messages together and</div><div class="line"><a name="l02399"></a><span class="lineno"> 2399</span> allows to maintain control over the moment they are sent to listeners. The</div><div class="line"><a name="l02400"></a><span class="lineno"> 2400</span> signature of this method is more or less the same of `trigger`:</div><div class="line"><a name="l02401"></a><span class="lineno"> 2401</span> </div><div class="line"><a name="l02402"></a><span class="lineno"> 2402</span> ```cpp</div><div class="line"><a name="l02403"></a><span class="lineno"> 2403</span> dispatcher.enqueue<AnEvent>(42);</div><div class="line"><a name="l02404"></a><span class="lineno"> 2404</span> dispatcher.enqueue<AnotherEvent>();</div><div class="line"><a name="l02405"></a><span class="lineno"> 2405</span> ```</div><div class="line"><a name="l02406"></a><span class="lineno"> 2406</span> </div><div class="line"><a name="l02407"></a><span class="lineno"> 2407</span> Events are stored aside until the `update` member function is invoked, then all</div><div class="line"><a name="l02408"></a><span class="lineno"> 2408</span> the messages that are still pending are sent to the listeners at once:</div><div class="line"><a name="l02409"></a><span class="lineno"> 2409</span> </div><div class="line"><a name="l02410"></a><span class="lineno"> 2410</span> ```cpp</div><div class="line"><a name="l02411"></a><span class="lineno"> 2411</span> // emits all the events of the given type at once</div><div class="line"><a name="l02412"></a><span class="lineno"> 2412</span> dispatcher.update<MyEvent>();</div><div class="line"><a name="l02413"></a><span class="lineno"> 2413</span> </div><div class="line"><a name="l02414"></a><span class="lineno"> 2414</span> // emits all the events queued so far at once</div><div class="line"><a name="l02415"></a><span class="lineno"> 2415</span> dispatcher.update();</div><div class="line"><a name="l02416"></a><span class="lineno"> 2416</span> ```</div><div class="line"><a name="l02417"></a><span class="lineno"> 2417</span> </div><div class="line"><a name="l02418"></a><span class="lineno"> 2418</span> This way users can embed the dispatcher in a loop and literally dispatch events</div><div class="line"><a name="l02419"></a><span class="lineno"> 2419</span> once per tick to their systems.</div><div class="line"><a name="l02420"></a><span class="lineno"> 2420</span> </div><div class="line"><a name="l02421"></a><span class="lineno"> 2421</span> ## Event emitter</div><div class="line"><a name="l02422"></a><span class="lineno"> 2422</span> </div><div class="line"><a name="l02423"></a><span class="lineno"> 2423</span> A general purpose event emitter thought mainly for those cases where it comes to</div><div class="line"><a name="l02424"></a><span class="lineno"> 2424</span> working with asynchronous stuff.<br/></div><div class="line"><a name="l02425"></a><span class="lineno"> 2425</span> Originally designed to fit the requirements of</div><div class="line"><a name="l02426"></a><span class="lineno"> 2426</span> [`uvw`](https://github.com/skypjack/uvw) (a wrapper for `libuv` written in</div><div class="line"><a name="l02427"></a><span class="lineno"> 2427</span> modern C++), it was adapted later to be included in this library.</div><div class="line"><a name="l02428"></a><span class="lineno"> 2428</span> </div><div class="line"><a name="l02429"></a><span class="lineno"> 2429</span> To create a custom emitter type, derived classes must inherit directly from the</div><div class="line"><a name="l02430"></a><span class="lineno"> 2430</span> base class as:</div><div class="line"><a name="l02431"></a><span class="lineno"> 2431</span> </div><div class="line"><a name="l02432"></a><span class="lineno"> 2432</span> ```cpp</div><div class="line"><a name="l02433"></a><span class="lineno"> 2433</span> struct MyEmitter: Emitter<MyEmitter> {</div><div class="line"><a name="l02434"></a><span class="lineno"> 2434</span>  // ...</div><div class="line"><a name="l02435"></a><span class="lineno"> 2435</span> }</div><div class="line"><a name="l02436"></a><span class="lineno"> 2436</span> ```</div><div class="line"><a name="l02437"></a><span class="lineno"> 2437</span> </div><div class="line"><a name="l02438"></a><span class="lineno"> 2438</span> The full list of accepted types of events isn't required. Handlers are created</div><div class="line"><a name="l02439"></a><span class="lineno"> 2439</span> internally on the fly and thus each type of event is accepted by default.</div><div class="line"><a name="l02440"></a><span class="lineno"> 2440</span> </div><div class="line"><a name="l02441"></a><span class="lineno"> 2441</span> Whenever an event is published, an emitter provides the listeners with a</div><div class="line"><a name="l02442"></a><span class="lineno"> 2442</span> reference to itself along with a const reference to the event. Therefore</div><div class="line"><a name="l02443"></a><span class="lineno"> 2443</span> listeners have an handy way to work with it without incurring in the need of</div><div class="line"><a name="l02444"></a><span class="lineno"> 2444</span> capturing a reference to the emitter itself.<br/></div><div class="line"><a name="l02445"></a><span class="lineno"> 2445</span> In addition, an opaque object is returned each time a connection is established</div><div class="line"><a name="l02446"></a><span class="lineno"> 2446</span> between an emitter and a listener, allowing the caller to disconnect them at a</div><div class="line"><a name="l02447"></a><span class="lineno"> 2447</span> later time.<br/></div><div class="line"><a name="l02448"></a><span class="lineno"> 2448</span> The opaque object used to handle connections is both movable and copyable. On</div><div class="line"><a name="l02449"></a><span class="lineno"> 2449</span> the other side, an event emitter is movable but not copyable by default.</div><div class="line"><a name="l02450"></a><span class="lineno"> 2450</span> </div><div class="line"><a name="l02451"></a><span class="lineno"> 2451</span> To create new instances of an emitter, no arguments are required:</div><div class="line"><a name="l02452"></a><span class="lineno"> 2452</span> </div><div class="line"><a name="l02453"></a><span class="lineno"> 2453</span> ```cpp</div><div class="line"><a name="l02454"></a><span class="lineno"> 2454</span> MyEmitter emitter{};</div><div class="line"><a name="l02455"></a><span class="lineno"> 2455</span> ```</div><div class="line"><a name="l02456"></a><span class="lineno"> 2456</span> </div><div class="line"><a name="l02457"></a><span class="lineno"> 2457</span> Listeners must be movable and callable objects (free functions, lambdas,</div><div class="line"><a name="l02458"></a><span class="lineno"> 2458</span> functors, `std::function`s, whatever) whose function type is:</div><div class="line"><a name="l02459"></a><span class="lineno"> 2459</span> </div><div class="line"><a name="l02460"></a><span class="lineno"> 2460</span> ```cpp</div><div class="line"><a name="l02461"></a><span class="lineno"> 2461</span> void(const Event &, MyEmitter &)</div><div class="line"><a name="l02462"></a><span class="lineno"> 2462</span> ```</div><div class="line"><a name="l02463"></a><span class="lineno"> 2463</span> </div><div class="line"><a name="l02464"></a><span class="lineno"> 2464</span> Where `Event` is the type of event they want to listen.<br/></div><div class="line"><a name="l02465"></a><span class="lineno"> 2465</span> There are two ways to attach a listener to an event emitter that differ</div><div class="line"><a name="l02466"></a><span class="lineno"> 2466</span> slightly from each other:</div><div class="line"><a name="l02467"></a><span class="lineno"> 2467</span> </div><div class="line"><a name="l02468"></a><span class="lineno"> 2468</span> * To register a long-lived listener, use the `on` member function. It is meant</div><div class="line"><a name="l02469"></a><span class="lineno"> 2469</span>  to register a listener designed to be invoked more than once for the given</div><div class="line"><a name="l02470"></a><span class="lineno"> 2470</span>  event type.<br/></div><div class="line"><a name="l02471"></a><span class="lineno"> 2471</span>  As an example:</div><div class="line"><a name="l02472"></a><span class="lineno"> 2472</span> </div><div class="line"><a name="l02473"></a><span class="lineno"> 2473</span>  ```cpp</div><div class="line"><a name="l02474"></a><span class="lineno"> 2474</span>  auto conn = emitter.on<MyEvent>([](const MyEvent &event, MyEmitter &emitter) {</div><div class="line"><a name="l02475"></a><span class="lineno"> 2475</span>  // ...</div><div class="line"><a name="l02476"></a><span class="lineno"> 2476</span>  });</div><div class="line"><a name="l02477"></a><span class="lineno"> 2477</span>  ```</div><div class="line"><a name="l02478"></a><span class="lineno"> 2478</span> </div><div class="line"><a name="l02479"></a><span class="lineno"> 2479</span>  The connection object can be freely discarded. Otherwise, it can be used later</div><div class="line"><a name="l02480"></a><span class="lineno"> 2480</span>  to disconnect the listener if required.</div><div class="line"><a name="l02481"></a><span class="lineno"> 2481</span> </div><div class="line"><a name="l02482"></a><span class="lineno"> 2482</span> * To register a short-lived listener, use the `once` member function. It is</div><div class="line"><a name="l02483"></a><span class="lineno"> 2483</span>  meant to register a listener designed to be invoked only once for the given</div><div class="line"><a name="l02484"></a><span class="lineno"> 2484</span>  event type. The listener is automatically disconnected after the first</div><div class="line"><a name="l02485"></a><span class="lineno"> 2485</span>  invocation.<br/></div><div class="line"><a name="l02486"></a><span class="lineno"> 2486</span>  As an example:</div><div class="line"><a name="l02487"></a><span class="lineno"> 2487</span> </div><div class="line"><a name="l02488"></a><span class="lineno"> 2488</span>  ```cpp</div><div class="line"><a name="l02489"></a><span class="lineno"> 2489</span>  auto conn = emitter.once<MyEvent>([](const MyEvent &event, MyEmitter &emitter) {</div><div class="line"><a name="l02490"></a><span class="lineno"> 2490</span>  // ...</div><div class="line"><a name="l02491"></a><span class="lineno"> 2491</span>  });</div><div class="line"><a name="l02492"></a><span class="lineno"> 2492</span>  ```</div><div class="line"><a name="l02493"></a><span class="lineno"> 2493</span> </div><div class="line"><a name="l02494"></a><span class="lineno"> 2494</span>  The connection object can be freely discarded. Otherwise, it can be used later</div><div class="line"><a name="l02495"></a><span class="lineno"> 2495</span>  to disconnect the listener if required.</div><div class="line"><a name="l02496"></a><span class="lineno"> 2496</span> </div><div class="line"><a name="l02497"></a><span class="lineno"> 2497</span> In both cases, the connection object can be used with the `erase` member</div><div class="line"><a name="l02498"></a><span class="lineno"> 2498</span> function:</div><div class="line"><a name="l02499"></a><span class="lineno"> 2499</span> </div><div class="line"><a name="l02500"></a><span class="lineno"> 2500</span> ```cpp</div><div class="line"><a name="l02501"></a><span class="lineno"> 2501</span> emitter.erase(conn);</div><div class="line"><a name="l02502"></a><span class="lineno"> 2502</span> ```</div><div class="line"><a name="l02503"></a><span class="lineno"> 2503</span> </div><div class="line"><a name="l02504"></a><span class="lineno"> 2504</span> There are also two member functions to use either to disconnect all the</div><div class="line"><a name="l02505"></a><span class="lineno"> 2505</span> listeners for a given type of event or to clear the emitter:</div><div class="line"><a name="l02506"></a><span class="lineno"> 2506</span> </div><div class="line"><a name="l02507"></a><span class="lineno"> 2507</span> ```cpp</div><div class="line"><a name="l02508"></a><span class="lineno"> 2508</span> // removes all the listener for the specific event</div><div class="line"><a name="l02509"></a><span class="lineno"> 2509</span> emitter.clear<MyEvent>();</div><div class="line"><a name="l02510"></a><span class="lineno"> 2510</span> </div><div class="line"><a name="l02511"></a><span class="lineno"> 2511</span> // removes all the listeners registered so far</div><div class="line"><a name="l02512"></a><span class="lineno"> 2512</span> emitter.clear();</div><div class="line"><a name="l02513"></a><span class="lineno"> 2513</span> ```</div><div class="line"><a name="l02514"></a><span class="lineno"> 2514</span> </div><div class="line"><a name="l02515"></a><span class="lineno"> 2515</span> To send an event to all the listeners that are interested in it, the `publish`</div><div class="line"><a name="l02516"></a><span class="lineno"> 2516</span> member function offers a convenient approach that relieves the user from having</div><div class="line"><a name="l02517"></a><span class="lineno"> 2517</span> to create the event:</div><div class="line"><a name="l02518"></a><span class="lineno"> 2518</span> </div><div class="line"><a name="l02519"></a><span class="lineno"> 2519</span> ```cpp</div><div class="line"><a name="l02520"></a><span class="lineno"> 2520</span> struct MyEvent { int i; };</div><div class="line"><a name="l02521"></a><span class="lineno"> 2521</span> </div><div class="line"><a name="l02522"></a><span class="lineno"> 2522</span> // ...</div><div class="line"><a name="l02523"></a><span class="lineno"> 2523</span> </div><div class="line"><a name="l02524"></a><span class="lineno"> 2524</span> emitter.publish<MyEvent>(42);</div><div class="line"><a name="l02525"></a><span class="lineno"> 2525</span> ```</div><div class="line"><a name="l02526"></a><span class="lineno"> 2526</span> </div><div class="line"><a name="l02527"></a><span class="lineno"> 2527</span> Finally, the `empty` member function tests if there exists at least either a</div><div class="line"><a name="l02528"></a><span class="lineno"> 2528</span> listener registered with the event emitter or to a given type of event:</div><div class="line"><a name="l02529"></a><span class="lineno"> 2529</span> </div><div class="line"><a name="l02530"></a><span class="lineno"> 2530</span> ```cpp</div><div class="line"><a name="l02531"></a><span class="lineno"> 2531</span> bool empty;</div><div class="line"><a name="l02532"></a><span class="lineno"> 2532</span> </div><div class="line"><a name="l02533"></a><span class="lineno"> 2533</span> // checks if there is any listener registered for the specific event</div><div class="line"><a name="l02534"></a><span class="lineno"> 2534</span> empty = emitter.empty<MyEvent>();</div><div class="line"><a name="l02535"></a><span class="lineno"> 2535</span> </div><div class="line"><a name="l02536"></a><span class="lineno"> 2536</span> // checks it there are listeners registered with the event emitter</div><div class="line"><a name="l02537"></a><span class="lineno"> 2537</span> empty = emitter.empty();</div><div class="line"><a name="l02538"></a><span class="lineno"> 2538</span> ```</div><div class="line"><a name="l02539"></a><span class="lineno"> 2539</span> </div><div class="line"><a name="l02540"></a><span class="lineno"> 2540</span> In general, the event emitter is a handy tool when the derived classes _wrap_</div><div class="line"><a name="l02541"></a><span class="lineno"> 2541</span> asynchronous operations, because it introduces a _nice-to-have_ model based on</div><div class="line"><a name="l02542"></a><span class="lineno"> 2542</span> events and listeners that kindly hides the complexity behind the scenes. However</div><div class="line"><a name="l02543"></a><span class="lineno"> 2543</span> it is not limited to such uses.</div><div class="line"><a name="l02544"></a><span class="lineno"> 2544</span> </div><div class="line"><a name="l02545"></a><span class="lineno"> 2545</span> # Packaging Tools</div><div class="line"><a name="l02546"></a><span class="lineno"> 2546</span> </div><div class="line"><a name="l02547"></a><span class="lineno"> 2547</span> `EnTT` is available for some of the most known packaging tools. In particular:</div><div class="line"><a name="l02548"></a><span class="lineno"> 2548</span> </div><div class="line"><a name="l02549"></a><span class="lineno"> 2549</span> * [`vcpkg`](https://github.com/Microsoft/vcpkg/tree/master/ports/entt),</div><div class="line"><a name="l02550"></a><span class="lineno"> 2550</span>  Microsoft VC++ Packaging Tool.</div><div class="line"><a name="l02551"></a><span class="lineno"> 2551</span> * [`Homebrew`](https://github.com/skypjack/homebrew-entt), the missing package</div><div class="line"><a name="l02552"></a><span class="lineno"> 2552</span>  manager for macOS.<br/></div><div class="line"><a name="l02553"></a><span class="lineno"> 2553</span>  Available as a homebrew formula. Just type the following to install it:</div><div class="line"><a name="l02554"></a><span class="lineno"> 2554</span>  ```</div><div class="line"><a name="l02555"></a><span class="lineno"> 2555</span>  brew install skypjack/entt/entt</div><div class="line"><a name="l02556"></a><span class="lineno"> 2556</span>  ```</div><div class="line"><a name="l02557"></a><span class="lineno"> 2557</span> </div><div class="line"><a name="l02558"></a><span class="lineno"> 2558</span> Consider this list a work in progress and help me to make it longer.</div><div class="line"><a name="l02559"></a><span class="lineno"> 2559</span> </div><div class="line"><a name="l02560"></a><span class="lineno"> 2560</span> # EnTT in Action</div><div class="line"><a name="l02561"></a><span class="lineno"> 2561</span> </div><div class="line"><a name="l02562"></a><span class="lineno"> 2562</span> `EnTT` is widely used in private and commercial applications. I cannot even</div><div class="line"><a name="l02563"></a><span class="lineno"> 2563</span> mention most of them because of some signatures I put on some documents time</div><div class="line"><a name="l02564"></a><span class="lineno"> 2564</span> ago.<br/></div><div class="line"><a name="l02565"></a><span class="lineno"> 2565</span> Fortunately, there are also people who took the time to implement open source</div><div class="line"><a name="l02566"></a><span class="lineno"> 2566</span> projects based on EnTT and did not hold back when it came to documenting them.</div><div class="line"><a name="l02567"></a><span class="lineno"> 2567</span> </div><div class="line"><a name="l02568"></a><span class="lineno"> 2568</span> Below an incomplete list of projects and articles:</div><div class="line"><a name="l02569"></a><span class="lineno"> 2569</span> </div><div class="line"><a name="l02570"></a><span class="lineno"> 2570</span> * [EnttPong](https://github.com/reworks/EnttPong): example game for `EnTT`</div><div class="line"><a name="l02571"></a><span class="lineno"> 2571</span>  framework.</div><div class="line"><a name="l02572"></a><span class="lineno"> 2572</span> * [ECS_SpaceBattle](https://github.com/vblanco20-1/ECS_SpaceBattle): huge space</div><div class="line"><a name="l02573"></a><span class="lineno"> 2573</span>  battle built on `UE4`.</div><div class="line"><a name="l02574"></a><span class="lineno"> 2574</span> * [Experimenting with ECS in UE4](http://victor.madtriangles.com/code%20experiment/2018/03/25/post-ue4-ecs-battle.html):</div><div class="line"><a name="l02575"></a><span class="lineno"> 2575</span>  interesting article about `UE4` and `EnTT`.</div><div class="line"><a name="l02576"></a><span class="lineno"> 2576</span> * [Implementing ECS architecture in UE4](https://forums.unrealengine.com/development-discussion/c-gameplay-programming/1449913-implementing-ecs-architecture-in-ue4-giant-space-battle):</div><div class="line"><a name="l02577"></a><span class="lineno"> 2577</span>  giant space battle.</div><div class="line"><a name="l02578"></a><span class="lineno"> 2578</span> * [MatchOneEntt](https://github.com/mhaemmerle/MatchOneEntt): port of</div><div class="line"><a name="l02579"></a><span class="lineno"> 2579</span>  [Match One](https://github.com/sschmid/Match-One) for `Entitas-CSharp`.</div><div class="line"><a name="l02580"></a><span class="lineno"> 2580</span> * [Randballs](https://github.com/gale93/randballs): simple `SFML` and `EnTT`</div><div class="line"><a name="l02581"></a><span class="lineno"> 2581</span>  playground.</div><div class="line"><a name="l02582"></a><span class="lineno"> 2582</span> * ...</div><div class="line"><a name="l02583"></a><span class="lineno"> 2583</span> </div><div class="line"><a name="l02584"></a><span class="lineno"> 2584</span> If you know of other resources out there that are about `EnTT`, feel free to</div><div class="line"><a name="l02585"></a><span class="lineno"> 2585</span> open an issue or a PR and I'll be glad to add them to the list.</div><div class="line"><a name="l02586"></a><span class="lineno"> 2586</span> </div><div class="line"><a name="l02587"></a><span class="lineno"> 2587</span> # Contributors</div><div class="line"><a name="l02588"></a><span class="lineno"> 2588</span> </div><div class="line"><a name="l02589"></a><span class="lineno"> 2589</span> If you want to participate, please see the guidelines for</div><div class="line"><a name="l02590"></a><span class="lineno"> 2590</span> [contributing](https://github.com/skypjack/entt/blob/master/CONTRIBUTING)</div><div class="line"><a name="l02591"></a><span class="lineno"> 2591</span> before to create issues or pull requests.<br/></div><div class="line"><a name="l02592"></a><span class="lineno"> 2592</span> Take also a look at the</div><div class="line"><a name="l02593"></a><span class="lineno"> 2593</span> [contributors list](https://github.com/skypjack/entt/blob/master/AUTHORS) to</div><div class="line"><a name="l02594"></a><span class="lineno"> 2594</span> know who has participated so far.</div><div class="line"><a name="l02595"></a><span class="lineno"> 2595</span> </div><div class="line"><a name="l02596"></a><span class="lineno"> 2596</span> # License</div><div class="line"><a name="l02597"></a><span class="lineno"> 2597</span> </div><div class="line"><a name="l02598"></a><span class="lineno"> 2598</span> Code and documentation Copyright (c) 2018 Michele Caini.<br/></div><div class="line"><a name="l02599"></a><span class="lineno"> 2599</span> Code released under</div><div class="line"><a name="l02600"></a><span class="lineno"> 2600</span> [the MIT license](https://github.com/skypjack/entt/blob/master/LICENSE).</div><div class="line"><a name="l02601"></a><span class="lineno"> 2601</span> Docs released under</div><div class="line"><a name="l02602"></a><span class="lineno"> 2602</span> [Creative Commons](https://github.com/skypjack/entt/blob/master/docs/LICENSE).</div><div class="line"><a name="l02603"></a><span class="lineno"> 2603</span> </div><div class="line"><a name="l02604"></a><span class="lineno"> 2604</span> # Support</div><div class="line"><a name="l02605"></a><span class="lineno"> 2605</span> </div><div class="line"><a name="l02606"></a><span class="lineno"> 2606</span> ## Donation</div><div class="line"><a name="l02607"></a><span class="lineno"> 2607</span> </div><div class="line"><a name="l02608"></a><span class="lineno"> 2608</span> Developing and maintaining `EnTT` takes some time and lots of coffee. I'd like</div><div class="line"><a name="l02609"></a><span class="lineno"> 2609</span> to add more and more functionalities in future and turn it in a full-featured</div><div class="line"><a name="l02610"></a><span class="lineno"> 2610</span> framework.<br/></div><div class="line"><a name="l02611"></a><span class="lineno"> 2611</span> If you want to support this project, you can offer me an espresso. I'm from</div><div class="line"><a name="l02612"></a><span class="lineno"> 2612</span> Italy, we're used to turning the best coffee ever in code. If you find that</div><div class="line"><a name="l02613"></a><span class="lineno"> 2613</span> it's not enough, feel free to support me the way you prefer.<br/></div><div class="line"><a name="l02614"></a><span class="lineno"> 2614</span> Take a look at the donation button at the top of the page for more details or</div><div class="line"><a name="l02615"></a><span class="lineno"> 2615</span> just click [here](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=W2HF9FESD5LJY&lc=IT&item_name=Michele%20Caini&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted).</div><div class="line"><a name="l02616"></a><span class="lineno"> 2616</span> </div><div class="line"><a name="l02617"></a><span class="lineno"> 2617</span> ## Hire me</div><div class="line"><a name="l02618"></a><span class="lineno"> 2618</span> </div><div class="line"><a name="l02619"></a><span class="lineno"> 2619</span> If you start using `EnTT` and need help, if you want a new feature and want me</div><div class="line"><a name="l02620"></a><span class="lineno"> 2620</span> to give it the highest priority, if you have any other reason to contact me:</div><div class="line"><a name="l02621"></a><span class="lineno"> 2621</span> do not hesitate. I'm available for hiring.<br/></div><div class="line"><a name="l02622"></a><span class="lineno"> 2622</span> Feel free to take a look at my [profile](https://github.com/skypjack) and</div><div class="line"><a name="l02623"></a><span class="lineno"> 2623</span> contact me by mail.</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>
|