172 lines
14 KiB
HTML
172 lines
14 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" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.9.6"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>EnTT: Frequently Asked Questions</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-awesome.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 id="projectrow">
|
|
<td id="projectalign">
|
|
<div id="projectname">EnTT<span id="projectnumber"> 3.12.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.6 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
/* @license-end */
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
<!-- 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">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div><!-- top -->
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">Frequently Asked Questions </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><h1><a class="anchor" id="autotoc_md115"></a>
|
|
Introduction</h1>
|
|
<p>This is a constantly updated section where I'm trying to put the answers to the most frequently asked questions.<br />
|
|
If you don't find your answer here, there are two cases: nobody has done it yet or this section needs updating. In both cases, you can <a href="https://github.com/skypjack/entt/issues/new">open a new issue</a> or enter either the <a href="https://gitter.im/skypjack/entt">gitter channel</a> or the <a href="https://discord.gg/5BjPWBd">discord server</a> to ask for help.<br />
|
|
Probably someone already has an answer for you and we can then integrate this part of the documentation.</p>
|
|
<h1><a class="anchor" id="autotoc_md116"></a>
|
|
FAQ</h1>
|
|
<h2><a class="anchor" id="autotoc_md117"></a>
|
|
Why is my debug build on Windows so slow?</h2>
|
|
<p><code>EnTT</code> is an experimental project that I also use to keep me up-to-date with the latest revision of the language and the standard library. For this reason, it's likely that some classes you're working with are using standard containers under the hood.<br />
|
|
Unfortunately, it's known that the standard containers aren't particularly performing in debugging (the reasons for this go beyond this document) and are even less so on Windows apparently. Fortunately this can also be mitigated a lot, achieving good results in many cases.</p>
|
|
<p>First of all, there are two things to do in a Windows project:</p>
|
|
<ul>
|
|
<li>Disable the <a href="https://docs.microsoft.com/cpp/build/reference/jmc"><code>/JMC</code></a> option (<em>Just My Code</em> debugging), available starting with Visual Studio 2017 version 15.8.</li>
|
|
<li>Set the <a href="https://docs.microsoft.com/cpp/standard-library/iterator-debug-level"><code>_ITERATOR_DEBUG_LEVEL</code></a> macro to 0. This will disable checked iterators and iterator debugging.</li>
|
|
</ul>
|
|
<p>Moreover, set the <code>ENTT_DISABLE_ASSERT</code> variable or redefine the <code>ENTT_ASSERT</code> macro to disable internal debug checks in <code>EnTT</code>:</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#define ENTT_ASSERT(...) ((void)0)</span></div>
|
|
</div><!-- fragment --><p>These asserts are introduced to help the users but they require to access to the underlying containers and therefore risk ruining the performance in some cases.</p>
|
|
<p>With these changes, debug performance should increase enough in most cases. If you want something more, you can also switch to an optimization level <code>O0</code> or preferably <code>O1</code>.</p>
|
|
<h2><a class="anchor" id="autotoc_md118"></a>
|
|
How can I represent hierarchies with my components?</h2>
|
|
<p>This is one of the first questions that anyone makes when starting to work with the entity-component-system architectural pattern.<br />
|
|
There are several approaches to the problem and the best one depends mainly on the real problem one is facing. In all cases, how to do it doesn't strictly depend on the library in use, but the latter certainly allows or not different techniques depending on how the data are laid out.</p>
|
|
<p>I tried to describe some of the approaches that fit well with the model of <code>EnTT</code>. <a href="https://skypjack.github.io/2019-06-25-ecs-baf-part-4/">This</a> is the first post of a series that tries to <em>explore</em> the problem. More will probably come in future.<br />
|
|
In addition, <code>EnTT</code> also offers the possibility to create stable storage types and therefore have pointer stability for one, all or some components. This is by far the most convenient solution when it comes to creating hierarchies and whatnot. See the documentation for the ECS part of the library and in particular what concerns the <code>component_traits</code> class for further details.</p>
|
|
<h2><a class="anchor" id="autotoc_md119"></a>
|
|
Custom entity identifiers: yay or nay?</h2>
|
|
<p>Custom entity identifiers are definitely a good idea in two cases at least:</p>
|
|
<ul>
|
|
<li>If <code>std::uint32_t</code> isn't large enough for your purposes, since this is the underlying type of <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code>.</li>
|
|
<li>If you want to avoid conflicts when using multiple registries.</li>
|
|
</ul>
|
|
<p>Identifiers can be defined through enum classes and class types that define an <code>entity_type</code> member of type <code>std::uint32_t</code> or <code>std::uint64_t</code>.<br />
|
|
In fact, this is a definition equivalent to that of <code><a class="el" href="namespaceentt.html#a0b54e231d069e8a231e14b223388808a" title="Default entity identifier.">entt::entity</a></code>:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">enum class</span> entity: std::uint32_t {};</div>
|
|
</div><!-- fragment --><p>There is no limit to the number of identifiers that can be defined.</p>
|
|
<h2><a class="anchor" id="autotoc_md120"></a>
|
|
Warning C4307: integral constant overflow</h2>
|
|
<p>According to <a href="https://github.com/skypjack/entt/issues/121">this</a> issue, using a hashed string under VS (toolset v141) could generate a warning.<br />
|
|
First of all, I want to reassure you: it's expected and harmless. However, it can be annoying.</p>
|
|
<p>To suppress it and if you don't want to suppress all the other warnings as well, here is a workaround in the form of a macro:</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#if defined(_MSC_VER)</span></div>
|
|
<div class="line"><span class="preprocessor">#define HS(str) __pragma(warning(suppress:4307)) entt::hashed_string{str}</span></div>
|
|
<div class="line"><span class="preprocessor">#else</span></div>
|
|
<div class="line"><span class="preprocessor">#define HS(str) entt::hashed_string{str}</span></div>
|
|
<div class="line"><span class="preprocessor">#endif</span></div>
|
|
</div><!-- fragment --><p>With an example of use included:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">constexpr</span> <span class="keyword">auto</span> identifier = HS(<span class="stringliteral">"my/resource/identifier"</span>);</div>
|
|
</div><!-- fragment --><p>Thanks to <a href="https://github.com/huwpascoe">huwpascoe</a> for the courtesy.</p>
|
|
<h2><a class="anchor" id="autotoc_md121"></a>
|
|
Warning C4003: the min, the max and the macro</h2>
|
|
<p>On Windows, a header file defines two macros <code>min</code> and <code>max</code> which may result in conflicts with their counterparts in the standard library and therefore in errors during compilation.</p>
|
|
<p>It's a pretty big problem but fortunately it's not a problem of <code>EnTT</code> and there is a fairly simple solution to it.<br />
|
|
It consists in defining the <code>NOMINMAX</code> macro before including any other header so as to get rid of the extra definitions:</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#define NOMINMAX</span></div>
|
|
</div><!-- fragment --><p>Please refer to <a href="https://github.com/skypjack/entt/issues/96">this</a> issue for more details.</p>
|
|
<h2><a class="anchor" id="autotoc_md122"></a>
|
|
The standard and the non-copyable types</h2>
|
|
<p><code>EnTT</code> uses internally the trait <code>std::is_copy_constructible_v</code> to check if a component is actually copyable. However, this trait doesn't really check whether a type is actually copyable. Instead, it just checks that a suitable copy constructor and copy operator exist.<br />
|
|
This can lead to surprising results due to some idiosyncrasies of the standard.</p>
|
|
<p>For example, <code>std::vector</code> defines a copy constructor that is conditionally enabled depending on whether the value type is copyable or not. As a result, <code>std::is_copy_constructible_v</code> returns true for the following specialization:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>type {</div>
|
|
<div class="line"> std::vector<std::unique_ptr<action>> vec;</div>
|
|
<div class="line">};</div>
|
|
</div><!-- fragment --><p>However, the copy constructor is effectively disabled upon specialization. Therefore, trying to assign an instance of this type to an entity may trigger a compilation error.<br />
|
|
As a workaround, users can mark the type explicitly as non-copyable. This also suppresses the implicit generation of the move constructor and operator, which will therefore have to be defaulted accordingly:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">struct </span>type {</div>
|
|
<div class="line"> type(<span class="keyword">const</span> type &) = <span class="keyword">delete</span>;</div>
|
|
<div class="line"> type(type &&) = <span class="keywordflow">default</span>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> type & operator=(<span class="keyword">const</span> type &) = <span class="keyword">delete</span>;</div>
|
|
<div class="line"> type & operator=(type &&) = <span class="keywordflow">default</span>;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> std::vector<std::unique_ptr<action>> vec;</div>
|
|
<div class="line">};</div>
|
|
</div><!-- fragment --><p>Note that aggregate initialization is also disabled as a consequence.<br />
|
|
Fortunately, this type of trick is quite rare. The bad news is that there is no way to deal with it at the library level, this being due to the design of the language. On the other hand, the fact that the language itself also offers a way to mitigate the problem makes it manageable.</p>
|
|
<h2><a class="anchor" id="autotoc_md123"></a>
|
|
Which functions trigger which signals</h2>
|
|
<p>Storage classes offer three <em>signals</em> that are emitted following specific operations. Maybe not everyone knows what these operations are, though.<br />
|
|
If this isn't clear, below you can find a <em>vademecum</em> for this purpose:</p>
|
|
<ul>
|
|
<li><code>on_created</code> is invoked when a component is first added (neither modified nor replaced) to an entity.</li>
|
|
<li><code>on_update</code> is called whenever an existing component is modified or replaced.</li>
|
|
<li><code>on_destroyed</code> is called when a component is explicitly or implicitly removed from an entity.</li>
|
|
</ul>
|
|
<p>Among the most controversial functions can be found <code>emplace_or_replace</code> and <code>destroy</code>. However, following the above rules, it's quite simple to know what will happen.<br />
|
|
In the first case, <code>on_created</code> is invoked if the entity has not the component, otherwise the latter is replaced and therefore <code>on_update</code> is triggered. As for the second case, components are removed from their entities and thus freed when they are recycled. It means that <code>on_destroyed</code> is triggered for every component owned by the entity that is destroyed. </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6
|
|
</small></address>
|
|
</body>
|
|
</html>
|