250 lines
21 KiB
HTML
250 lines
21 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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.20"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>EnTT: Main Page</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">EnTT
|
|
 <span id="projectnumber">3.6.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.20 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
/* @license-end */</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="PageDoc"><div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">EnTT Documentation</div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="md_README"></a><img src="https://user-images.githubusercontent.com/1812216/103550016-90752280-4ea8-11eb-8667-12ed2219e137.png" alt="EnTT: Gaming meets modern C++" class="inline"/></p>
|
|
<h1><a class="anchor" id="autotoc_md138"></a>
|
|
Introduction</h1>
|
|
<p>The entity-component-system (also known as <em>ECS</em>) is an architectural pattern used mostly in game development. For further details:</p>
|
|
<ul>
|
|
<li><a href="http://entity-systems.wikidot.com/">Entity Systems Wiki</a></li>
|
|
<li><a href="http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/">Evolve Your Hierarchy</a></li>
|
|
<li><a href="https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system">ECS on Wikipedia</a></li>
|
|
</ul>
|
|
<p>This project started off as a pure entity-component system. Over time the codebase has grown as more and more classes and functionalities were added.<br />
|
|
Here is a brief, yet incomplete list of what it offers today:</p>
|
|
<ul>
|
|
<li>Statically generated integer <b>identifiers</b> for types (assigned either at compile-time or at runtime).</li>
|
|
<li>A <code>constexpr</code> utility for human readable <b>resource names</b>.</li>
|
|
<li>A minimal <b>configuration system</b> built using the monostate pattern.</li>
|
|
<li>An incredibly fast <b>entity-component system</b> based on sparse sets, with its own <em>pay for what you use</em> policy to adjust performance and memory usage according to the users' requirements.</li>
|
|
<li>Views and groups to iterate entities and components and allow different access patterns, from <b>perfect SoA</b> to fully random.</li>
|
|
<li>A lot of <b>facilities</b> built on top of the entity-component system to help the users and avoid reinventing the wheel (dependencies, snapshot, handles, support for <b>reactive systems</b> and so on).</li>
|
|
<li>The smallest and most basic implementation of a <b>service locator</b> ever seen.</li>
|
|
<li>A built-in, non-intrusive and macro-free runtime <b>reflection system</b>.</li>
|
|
<li><b>Static polymorphism</b> made simple and within everyone's reach.</li>
|
|
<li>A <b>cooperative scheduler</b> for processes of any type.</li>
|
|
<li>All that is needed for <b>resource management</b> (cache, loaders, handles).</li>
|
|
<li>Delegates, <b>signal handlers</b> (with built-in support for collectors) and a tiny event dispatcher for immediate and delayed events to integrate in loops.</li>
|
|
<li>A general purpose <b>event emitter</b> as a CRTP idiom based class template.</li>
|
|
<li>And <b>much more</b>! Check out the <a href="https://github.com/skypjack/entt/wiki"><b>wiki</b></a>.</li>
|
|
</ul>
|
|
<p>Consider this list a work in progress as well as the project. The whole API is fully documented in-code for those who are brave enough to read it.</p>
|
|
<p>It is also known that <code>EnTT</code> (version 3) is used in <b>Minecraft</b>.<br />
|
|
Given that the game is available literally everywhere, I can confidently say that the library has been sufficiently tested on every platform that can come to mind.</p>
|
|
<h2><a class="anchor" id="autotoc_md139"></a>
|
|
Code Example</h2>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <entt/entt.hpp></span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">struct </span>position {</div>
|
|
<div class="line"> <span class="keywordtype">float</span> x;</div>
|
|
<div class="line"> <span class="keywordtype">float</span> y;</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">struct </span>velocity {</div>
|
|
<div class="line"> <span class="keywordtype">float</span> dx;</div>
|
|
<div class="line"> <span class="keywordtype">float</span> dy;</div>
|
|
<div class="line">};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordtype">void</span> update(<a class="code" href="classentt_1_1basic__registry.html">entt::registry</a> &registry) {</div>
|
|
<div class="line"> <span class="keyword">auto</span> <a class="code" href="namespaceentt.html#acc5a93cf82f9378248fe6385376cd943">view</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.view<<span class="keyword">const</span> position, velocity>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// use a callback</span></div>
|
|
<div class="line"> <a class="code" href="namespaceentt.html#acc5a93cf82f9378248fe6385376cd943">view</a>.each([](<span class="keyword">const</span> <span class="keyword">auto</span> &pos, <span class="keyword">auto</span> &vel) { <span class="comment">/* ... */</span> });</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// use an extended callback</span></div>
|
|
<div class="line"> <a class="code" href="namespaceentt.html#acc5a93cf82f9378248fe6385376cd943">view</a>.each([](<span class="keyword">const</span> <span class="keyword">auto</span> entity, <span class="keyword">const</span> <span class="keyword">auto</span> &pos, <span class="keyword">auto</span> &vel) { <span class="comment">/* ... */</span> });</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// use a range-for</span></div>
|
|
<div class="line"> <span class="keywordflow">for</span>(<span class="keyword">auto</span> [entity, pos, vel]: <a class="code" href="namespaceentt.html#acc5a93cf82f9378248fe6385376cd943">view</a>.each()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// use forward iterators and get only the components of interest</span></div>
|
|
<div class="line"> <span class="keywordflow">for</span>(<span class="keyword">auto</span> entity: view) {</div>
|
|
<div class="line"> <span class="keyword">auto</span> &vel = <a class="code" href="namespaceentt.html#acc5a93cf82f9378248fe6385376cd943">view</a>.get<velocity>(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>);</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordtype">int</span> main() {</div>
|
|
<div class="line"> <a class="code" href="classentt_1_1basic__registry.html">entt::registry</a> <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="keywordflow">for</span>(<span class="keyword">auto</span> i = 0u; i < 10u; ++i) {</div>
|
|
<div class="line"> <span class="keyword">const</span> <span class="keyword">auto</span> <a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a> = <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.create();</div>
|
|
<div class="line"> <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.emplace<position>(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, i * 1.f, i * 1.f);</div>
|
|
<div class="line"> <span class="keywordflow">if</span>(i % 2 == 0) { <a class="code" href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">registry</a>.emplace<velocity>(<a class="code" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entity</a>, i * .1f, i * .1f); }</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> update(registry);</div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md140"></a>
|
|
Motivation</h2>
|
|
<p>I started developing <code>EnTT</code> for the <em>wrong</em> reason: my goal was to design an entity-component system to beat another well known open source solution both in terms of performance and possibly memory usage.<br />
|
|
In the end, I did it, but it wasn't very satisfying. Actually it wasn't satisfying at all. The fastest and nothing more, fairly little indeed. When I realized it, I tried hard to keep intact the great performance of <code>EnTT</code> and to add all the features I wanted to see in <em>my own library</em> at the same time.</p>
|
|
<p>Nowadays, <code>EnTT</code> is finally what I was looking for: still faster than its <em>competitors</em>, lower memory usage in the average case, a really good API and an amazing set of features. And even more, of course.</p>
|
|
<h2><a class="anchor" id="autotoc_md141"></a>
|
|
Performance</h2>
|
|
<p>The proposed entity-component system is incredibly fast to iterate entities and components, this is a fact. Some compilers make a lot of optimizations because of how <code>EnTT</code> works, some others aren't that good. In general, if we consider real world cases, <code>EnTT</code> is somewhere between a bit and much faster than many of the other solutions around, although I couldn't check them all for obvious reasons.</p>
|
|
<p>If you are interested, you can compile the <code>benchmark</code> test in release mode (to enable compiler optimizations, otherwise it would make little sense) by setting the <code>ENTT_BUILD_BENCHMARK</code> option of <code>CMake</code> to <code>ON</code>, then evaluate yourself whether you're satisfied with the results or not.</p>
|
|
<p>Honestly I got tired of updating the README file whenever there is an improvement.<br />
|
|
There are already a lot of projects out there that use <code>EnTT</code> as a basis for comparison (this should already tell you a lot). Many of these benchmarks are completely wrong, many others are simply incomplete, good at omitting some information and using the wrong function to compare a given feature. Certainly there are also good ones but they age quickly if nobody updates them, especially when the library they are dealing with is actively developed.</p>
|
|
<p>The choice to use <code>EnTT</code> should be based on its carefully designed API, its set of features and the general performance, <b>not</b> because some single benchmark shows it to be the fastest tool available.</p>
|
|
<p>In the future I'll likely try to get even better performance while still adding new features, mainly for fun.<br />
|
|
If you want to contribute and/or have suggestions, feel free to make a PR or open an issue to discuss your idea.</p>
|
|
<h1><a class="anchor" id="autotoc_md142"></a>
|
|
Build Instructions</h1>
|
|
<h2><a class="anchor" id="autotoc_md143"></a>
|
|
Requirements</h2>
|
|
<p>To be able to use <code>EnTT</code>, users must provide a full-featured compiler that supports at least C++17.<br />
|
|
The requirements below are mandatory to compile the tests and to extract the documentation:</p>
|
|
<ul>
|
|
<li><code>CMake</code> version 3.7 or later.</li>
|
|
<li><code>Doxygen</code> version 1.8 or later.</li>
|
|
</ul>
|
|
<p>Alternatively, <a href="https://bazel.build">Bazel</a> is also supported as a build system (credits to <a href="https://github.com/zaucy">zaucy</a> who offered to maintain it).<br />
|
|
In the documentation below I'll still refer to <code>CMake</code>, this being the official build system of the library.</p>
|
|
<p>If you are looking for a C++14 version of <code>EnTT</code>, check out the git tag <code>cpp14</code>.</p>
|
|
<h2><a class="anchor" id="autotoc_md144"></a>
|
|
Library</h2>
|
|
<p><code>EnTT</code> is a header-only library. This means that including the <code><a class="el" href="entt_8hpp_source.html">entt.hpp</a></code> header is enough to include the library as a whole and use it. For those who are interested only in the entity-component system, consider to include the sole <code><a class="el" href="registry_8hpp_source.html">entity/registry.hpp</a></code> header instead.<br />
|
|
It's a matter of adding the following line to the top of a file:</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <entt/entt.hpp></span></div>
|
|
</div><!-- fragment --><p>Use the line below to include only the entity-component system instead:</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <entt/entity/registry.hpp></span></div>
|
|
</div><!-- fragment --><p>Then pass the proper <code>-I</code> argument to the compiler to add the <code>src</code> directory to the include paths.</p>
|
|
<h2><a class="anchor" id="autotoc_md145"></a>
|
|
Documentation</h2>
|
|
<p>The documentation is based on <a href="http://www.doxygen.nl/">doxygen</a>. To build it: </p><pre class="fragment">$ cd build
|
|
$ cmake .. -DENTT_BUILD_DOCS=ON
|
|
$ make
|
|
</pre><p>The API reference will be created in HTML format within the directory <code>build/docs/html</code>. To navigate it with your favorite browser: </p><pre class="fragment">$ cd build
|
|
$ your_favorite_browser docs/html/index.html
|
|
</pre><h2><a class="anchor" id="autotoc_md146"></a>
|
|
Tests</h2>
|
|
<p>To compile and run the tests, <code>EnTT</code> requires <em>googletest</em>.<br />
|
|
<code>cmake</code> will download and compile the library before compiling anything else. In order to build the tests, set the CMake option <code>ENTT_BUILD_TESTING</code> to <code>ON</code>.</p>
|
|
<p>To build the most basic set of tests:</p>
|
|
<ul>
|
|
<li><code>$ cd build</code></li>
|
|
<li><code>$ cmake -DENTT_BUILD_TESTING=ON ..</code></li>
|
|
<li><code>$ make</code></li>
|
|
<li><code>$ make test</code></li>
|
|
</ul>
|
|
<p>Note that benchmarks are not part of this set.</p>
|
|
<h1><a class="anchor" id="autotoc_md147"></a>
|
|
Packaging Tools</h1>
|
|
<p><code>EnTT</code> is available for some of the most known packaging tools. In particular:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/conan-io/conan-center-index"><code>Conan</code></a>, the C/C++ Package Manager for Developers.</li>
|
|
<li><a href="https://github.com/Microsoft/vcpkg"><code>vcpkg</code></a>, Microsoft VC++ Packaging Tool.<br />
|
|
You can download and install <code>EnTT</code> in just a few simple steps:</li>
|
|
</ul>
|
|
<div class="fragment"><div class="line">$ git clone https://github.com/Microsoft/vcpkg.git</div>
|
|
<div class="line">$ cd vcpkg</div>
|
|
<div class="line">$ ./bootstrap-vcpkg.sh</div>
|
|
<div class="line">$ ./vcpkg integrate install</div>
|
|
<div class="line">$ vcpkg install entt</div>
|
|
</div><!-- fragment --><p>The <code>EnTT</code> port in <code>vcpkg</code> is kept up to date by Microsoft team members and community contributors.<br />
|
|
If the version is out of date, please <a href="https://github.com/Microsoft/vcpkg">create an issue or pull request</a> on the <code>vcpkg</code> repository.</p>
|
|
<ul>
|
|
<li><a href="https://github.com/skypjack/homebrew-entt"><code>Homebrew</code></a>, the missing package manager for macOS.<br />
|
|
Available as a homebrew formula. Just type the following to install it:</li>
|
|
</ul>
|
|
<div class="fragment"><div class="line">brew install skypjack/entt/entt</div>
|
|
</div><!-- fragment --><ul>
|
|
<li><a href="https://build2.org"><code>build2</code></a>, build toolchain for developing and packaging C and C++ code.<br />
|
|
In order to use the <a href="https://cppget.org/entt"><code>entt</code></a> package in a <code>build2</code> project, add the following line or a similar one to the <code>manifest</code> file:</li>
|
|
</ul>
|
|
<div class="fragment"><div class="line">depends: entt ^3.0.0</div>
|
|
</div><!-- fragment --><p>Also check that the configuration refers to a valid repository, so that the package can be found by <code>build2</code>:</p>
|
|
<ul>
|
|
<li><a href="https://cppget.org"><code>cppget.org</code></a>, the open-source community central repository, accessible as <code><a href="https://pkg.cppget.org/1/stable">https://pkg.cppget.org/1/stable</a></code>.</li>
|
|
<li><a href="https://github.com/build2-packaging/entt">Package source repository</a>: accessible as either <code><a href="https://github.com/build2-packaging/entt.git">https://github.com/build2-packaging/entt.git</a></code> or <code>ssh://git@github.com/build2-packaging/entt.git</code>. Feel free to <a href="https://github.com/build2-packaging/entt">report issues</a> with this package.</li>
|
|
</ul>
|
|
<p>Both can be used with <code>bpkg add-repo</code> or added in a project <code>repositories.manifest</code>. See the official <a href="https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-repositories">documentation</a> for more details.</p>
|
|
<p>Consider this list a work in progress and help me to make it longer.</p>
|
|
<h1><a class="anchor" id="autotoc_md148"></a>
|
|
License</h1>
|
|
<p>Code and documentation Copyright (c) 2017-2021 Michele Caini.<br />
|
|
Colorful logo Copyright (c) 2018-2021 Richard Caseres.</p>
|
|
<p>Code released under <a href="https://github.com/skypjack/entt/blob/master/LICENSE">the MIT license</a>.<br />
|
|
Documentation released under <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>.<br />
|
|
All logos released under <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>. </p>
|
|
</div></div><!-- PageDoc -->
|
|
</div><!-- contents -->
|
|
<div class="ttc" id="anamespaceentt_html_a292643317d1dbb13e45824f757bd1086"><div class="ttname"><a href="namespaceentt.html#a292643317d1dbb13e45824f757bd1086">entt::registry</a></div><div class="ttdeci">basic_registry< entity > registry</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00076">fwd.hpp:76</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_acc5a93cf82f9378248fe6385376cd943"><div class="ttname"><a href="namespaceentt.html#acc5a93cf82f9378248fe6385376cd943">entt::view</a></div><div class="ttdeci">basic_view< entity, Args... > view</div><div class="ttdoc">Alias declaration for the most common use case.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00128">fwd.hpp:128</a></div></div>
|
|
<div class="ttc" id="aclassentt_1_1basic__registry_html"><div class="ttname"><a href="classentt_1_1basic__registry.html">entt::basic_registry</a></div><div class="ttdoc">Fast and reliable entity-component system.</div><div class="ttdef"><b>Definition:</b> <a href="registry_8hpp_source.html#l00044">registry.hpp:44</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_a0b54e231d069e8a231e14b223388808a"><div class="ttname"><a href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a">entt::entity</a></div><div class="ttdeci">entity</div><div class="ttdoc">Default entity identifier.</div><div class="ttdef"><b>Definition:</b> <a href="entity_2fwd_8hpp_source.html#l00060">fwd.hpp:60</a></div></div>
|
|
<!-- 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.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20
|
|
</small></address>
|
|
</body>
|
|
</html>
|