Skip to content

Commit

Permalink
Deploy preview for PR 504 🛫
Browse files Browse the repository at this point in the history
  • Loading branch information
@fallenatlas
fallenatlas committed Sep 17, 2023
1 parent 57c748d commit 08fd40d
Showing 1 changed file with 45 additions and 1 deletion.
46 changes: 45 additions & 1 deletion pr-preview/pr-504/examples-engine-events.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,51 @@ <h1>
Events
</h1>
<p>Using the <a href="classcubos_1_1core_1_1ecs_1_1EventReader.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventReader</a> and <a href="classcubos_1_1core_1_1ecs_1_1EventWriter.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventWriter</a>.</p>
<p><a name="md_events_page"></a></p><p>This example shows how the <a href="classcubos_1_1core_1_1ecs_1_1EventReader.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventReader</a> and the <a href="classcubos_1_1core_1_1ecs_1_1EventWriter.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventWriter</a> can be used and configured, in a simple scene, to emit and read events. These are in the core, meaning, you don&#x27;t need to add them to cubos.</p><p>Firstly, we need to create and register the event we want to emit. Here, our event has one variable, however, you can give it any number of variables of any type you want.</p><pre class="m-code"></pre><p>To receive these events, we can make a simple system, using the <a href="classcubos_1_1core_1_1ecs_1_1EventReader.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventReader</a> and iterating through all the events it has. This will be the layout of all our reader systems (A, C, D).</p><pre class="m-code"></pre><p>Now, to emit these events, we will use the <a href="classcubos_1_1core_1_1ecs_1_1EventWriter.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventWriter</a>. This system will emit 3 events on the first frame and another 3 on the second frame. By setting the value of the ShouldQuit resource to true on the second frame, the engine stops before reaching the third frame.</p><pre class="m-code"></pre><p>Lastly, let&#x27;s set the order we want these system to execute in.</p><pre class="m-code"></pre><p>These are the expected results with this order.</p><pre class="m-code"></pre><p>There are a couple of things to note here. First, the order in which the systems appear to receive the event. C receives the event, followed by D, this happens because even though A comes before C it also come before B, which is where the event is emitted, this means that C and D can read the event emitted by B on that same frame, while A will only read it on the next frame. This also explains why on the second run, A is never displayed, indeed, the engine quit before A got a chance to receive it&#x27;s so desired events. This shows how the results of the execution of systems that use events may vary with the order set for them, so special care should be taken when defining this.</p>
<p><a name="md_events_page"></a></p><p>This example shows how the <a href="classcubos_1_1core_1_1ecs_1_1EventReader.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventReader</a> and the <a href="classcubos_1_1core_1_1ecs_1_1EventWriter.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventWriter</a> can be used and configured, in a simple scene, to emit and read events. These are in the core, meaning, you don&#x27;t need to add them to cubos.</p><p>Firstly, we need to create and register the event we want to emit. Here, our event has one variable, however, you can give it any number of variables of any type you want.</p><pre class="m-code"><span class="k">struct</span><span class="w"> </span><span class="nc">MyEvent</span>
<span class="p">{</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">value</span><span class="p">;</span>
<span class="p">};</span></pre><pre class="m-code"><span class="w"> </span><span class="n">cubos</span><span class="p">.</span><span class="n">addEvent</span><span class="o">&lt;</span><span class="n">MyEvent</span><span class="o">&gt;</span><span class="p">();</span></pre><p>To receive these events, we can make a simple system, using the <a href="classcubos_1_1core_1_1ecs_1_1EventReader.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventReader</a> and iterating through all the events it has. This will be the layout of all our reader systems (A, C, D).</p><pre class="m-code"><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">firstSystem</span><span class="p">(</span><span class="n">ecs</span><span class="o">::</span><span class="n">EventReader</span><span class="o">&lt;</span><span class="n">MyEvent</span><span class="o">&gt;</span><span class="w"> </span><span class="n">reader</span><span class="p">)</span><span class="w"> </span>
<span class="p">{</span>
<span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="k">auto</span><span class="o">&amp;</span><span class="w"> </span><span class="n">event</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">reader</span><span class="p">)</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">CUBOS_INFO</span><span class="p">(</span><span class="s">&quot;A read {}&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">event</span><span class="p">.</span><span class="n">value</span><span class="p">);</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">}</span></pre><p>Now, to emit these events, we will use the <a href="classcubos_1_1core_1_1ecs_1_1EventWriter.html" class="m-doc">cubos::<wbr />core::<wbr />ecs::<wbr />EventWriter</a>. This system will emit 3 events on the first frame and another 3 on the second frame. By setting the value of the ShouldQuit resource to true on the second frame, the engine stops before reaching the third frame.</p><pre class="m-code"><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">secondSystem</span><span class="p">(</span><span class="n">ecs</span><span class="o">::</span><span class="n">EventWriter</span><span class="o">&lt;</span><span class="n">MyEvent</span><span class="o">&gt;</span><span class="w"> </span><span class="n">writer</span><span class="p">,</span><span class="w"> </span><span class="n">ecs</span><span class="o">::</span><span class="n">Write</span><span class="o">&lt;</span><span class="n">State</span><span class="o">&gt;</span><span class="w"> </span><span class="n">state</span><span class="p">,</span><span class="w"> </span><span class="n">ecs</span><span class="o">::</span><span class="n">Write</span><span class="o">&lt;</span><span class="n">cubos</span><span class="o">::</span><span class="n">engine</span><span class="o">::</span><span class="n">ShouldQuit</span><span class="o">&gt;</span><span class="w"> </span><span class="n">quit</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n">state</span><span class="o">-&gt;</span><span class="n">step</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">state</span><span class="o">-&gt;</span><span class="n">step</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="c1">// Write 1 2 3 on first run.</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">writer</span><span class="p">.</span><span class="n">push</span><span class="p">({</span><span class="mi">1</span><span class="p">});</span>
<span class="w"> </span><span class="n">writer</span><span class="p">.</span><span class="n">push</span><span class="p">({</span><span class="mi">2</span><span class="p">});</span>
<span class="w"> </span><span class="n">writer</span><span class="p">.</span><span class="n">push</span><span class="p">({</span><span class="mi">3</span><span class="p">});</span>
<span class="w"> </span><span class="n">CUBOS_INFO</span><span class="p">(</span><span class="s">&quot;B wrote 1 2 3&quot;</span><span class="p">);</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">state</span><span class="o">-&gt;</span><span class="n">step</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">2</span><span class="p">)</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">quit</span><span class="o">-&gt;</span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">true</span><span class="p">;</span><span class="w"> </span><span class="c1">// Stop the loop.</span>
<span class="w"> </span><span class="n">writer</span><span class="p">.</span><span class="n">push</span><span class="p">({</span><span class="mi">4</span><span class="p">});</span>
<span class="w"> </span><span class="n">writer</span><span class="p">.</span><span class="n">push</span><span class="p">({</span><span class="mi">5</span><span class="p">});</span>
<span class="w"> </span><span class="n">writer</span><span class="p">.</span><span class="n">push</span><span class="p">({</span><span class="mi">6</span><span class="p">});</span>
<span class="w"> </span><span class="n">CUBOS_INFO</span><span class="p">(</span><span class="s">&quot;B wrote 4 5 6&quot;</span><span class="p">);</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">}</span></pre><p>Lastly, let&#x27;s set the order we want these system to execute in.</p><pre class="m-code"></pre><p>These are the expected results with this order.</p><pre class="m-code"><span class="w"> </span><span class="c1">// Should print:</span>
<span class="w"> </span><span class="c1">// B wrote 1 2 3</span>
<span class="w"> </span><span class="c1">// C read 1</span>
<span class="w"> </span><span class="c1">// C read 2</span>
<span class="w"> </span><span class="c1">// C read 3</span>
<span class="w"> </span><span class="c1">// D read 1</span>
<span class="w"> </span><span class="c1">// D read 2</span>
<span class="w"> </span><span class="c1">// D read 3</span>
<span class="w"> </span><span class="c1">// A read 1</span>
<span class="w"> </span><span class="c1">// A read 2</span>
<span class="w"> </span><span class="c1">// A read 3</span>
<span class="w"> </span><span class="c1">// B wrote 4 5 6</span>
<span class="w"> </span><span class="c1">// C read 4</span>
<span class="w"> </span><span class="c1">// C read 5</span>
<span class="w"> </span><span class="c1">// C read 6</span>
<span class="w"> </span><span class="c1">// D read 4</span>
<span class="w"> </span><span class="c1">// D read 5</span>
<span class="w"> </span><span class="c1">// D read 6</span></pre><p>There are a couple of things to note here. First, the order in which the systems appear to receive the event. C receives the event, followed by D, this happens because even though A comes before C it also come before B, which is where the event is emitted, this means that C and D can read the event emitted by B on that same frame, while A will only read it on the next frame. This also explains why on the second run, A is never displayed, indeed, the engine quit before A got a chance to receive it&#x27;s so desired events. This shows how the results of the execution of systems that use events may vary with the order set for them, so special care should be taken when defining this.</p>
</div>
</div>
</div>
Expand Down

0 comments on commit 08fd40d

Please sign in to comment.