Deploy preview for PR 562 🛫

pr-preview/pr-562/examples-engine-scene.html

@@ -49,7 +49,7 @@ <h1>
           Scene
         </h1>
         <p>Using the <a href="group__scene-plugin.html" class="m-doc">Scene</a> plugin.</p>
-<p><a name="md_scene_page"></a></p><p>This example shows how the <a href="group__scene-plugin.html" class="m-doc">Scene</a> plugin can be used to spawn a scene from an asset.</p><p>The plugin function is included from the <a href="scene_2plugin_8hpp.html" class="m-doc">engine/<wbr />scene/<wbr />plugin.hpp</a> header. You may need to include other headers, depending on what you want to access.</p><pre class="m-code"><span class="w">    </span><span class="n">cubos</span><span class="p">.</span><span class="n">addPlugin</span><span class="p">(</span><span class="n">scenePlugin</span><span class="p">);</span></pre><p>Let&#x27;s start by taking a look at a scene file.</p><pre class="m-code">{
+<p><a name="md_scene_page"></a></p><p>This example shows how the <a href="group__scene-plugin.html" class="m-doc">Scene</a> plugin can be used to create scene assets and spawn them on the world.</p><p>The plugin function is included from the <a href="scene_2plugin_8hpp.html" class="m-doc">engine/<wbr />scene/<wbr />plugin.hpp</a> header.</p><pre class="m-code"><span class="w">    </span><span class="n">cubos</span><span class="p">.</span><span class="n">addPlugin</span><span class="p">(</span><span class="n">scenePlugin</span><span class="p">);</span></pre><p>Let&#x27;s start by taking a look at a scene file.</p><pre class="m-code">{
   &quot;imports&quot;: {},
   &quot;entities&quot;: {
     &quot;root&quot;: {
@@ -60,7 +60,7 @@ <h1>
       &quot;parent&quot;: &quot;root&quot;
     }
   }
-}</pre><p>A scene file has two parts: the <code>imports</code> and the <code>entities</code>. Each entity is a list of components, with their values set. So in this file we have two entities, one named <code>root</code> and the other named <code>child</code>. <code>root</code> has a single component, <code>num</code>, with a value of 1. <code>child</code> has two components, a <code>parent</code> and a <code>num</code>. In this sample, <code>num</code> is used so we can later identify the entities.</p><aside class="m-note m-danger"><h4>Warning</h4><p>Make sure all the components in a scene file are added to CUBOS., or it will raise an error.</p></aside><p>Let&#x27;s look at a different scene file now, to talk about <code>imports</code>, which is the way we can put subscenes within other scenes.</p><pre class="m-code">{
+}</pre><p>Scene files are JSON files with the extension <code>.cubos</code>. They must have two fields: <code>imports</code> and <code>entities</code>. The <code>entities</code> field is an object where each field identifies and describes the components of an entity. In this scene we have two entities, <code>root</code> and <code>child</code>. <code>root</code> has a single component, <code>num</code>, with a value of 1. <code>child</code> has two components, a <code>parent</code> and a <code>num</code>. In this sample, <code>num</code> is used so we can later identify the entities.</p><aside class="m-note m-info"><h4>Note</h4><p>Make sure these component names match the ones in your application and that they have been registered with <a href="classcubos_1_1engine_1_1Cubos.html" class="m-doc">Cubos</a>.</p></aside><p>Let&#x27;s look at a different scene file now, this time with <code>imports</code>. Imports allows us to instantiate scenes within other scenes.</p><pre class="m-code">{
   &quot;imports&quot;: {
     &quot;sub1&quot;: &quot;cd007ba2-ee0d-44fd-bf36-85c829dbe66f&quot;,
     &quot;sub2&quot;: &quot;cd007ba2-ee0d-44fd-bf36-85c829dbe66f&quot;
@@ -76,26 +76,11 @@ <h1>
       &quot;parent&quot;: &quot;main&quot;
     }
   }
-}</pre><p>This file imports the asset with id <code>cd007ba2-ee0d-44fd-bf36-85c829dbe66f</code>, which is the scene we looked at in the previous file. It gives this scene the deisgnation of <code>sub1</code>. It then imports the very same scene again, but this time with the name <code>sub2</code> instead. This allows us to have two instances of the same subscene.</p><p>Under <code>entities</code>, we can reference these labels to change some particular values of the subscenes. For example, by referencing <code>sub1.root</code> we are making local changes to the <code>root</code> entity of that instance of the subscene. The result of the changes we make to both <code>sub1.root</code> and <code>sub2.root</code> is that the parent of these entities will be set to be the <code>main</code> entity.</p><p>Now that we have our scene file, let&#x27;s get CUBOS. to load it. The first thing we&#x27;re going to need is a reference to the scene asset. For the purposes of this sample we can simply use an hardcoded reference to the asset.</p><pre class="m-code"><span class="k">static</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">Asset</span><span class="o">&lt;</span><span class="n">Scene</span><span class="o">&gt;</span><span class="w"> </span><span class="n">SceneAsset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">AnyAsset</span><span class="p">(</span><span class="s">&quot;f0d86ba8-5f34-440f-a180-d9d12c8e8b91&quot;</span><span class="p">);</span></pre><p>Then we&#x27;ll need a system that spawns that scene. To do this we simply get the Scene object from the asset, and then spawn its entities. <code>commands.spawn</code> will create in the world a copy of every entitiy defined in the scene. It won&#x27;t remove the entities already there, so if you want to close a scene, you&#x27;ll have to do it yourself.</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">spawnScene</span><span class="p">(</span><span class="n">Commands</span><span class="w"> </span><span class="n">commands</span><span class="p">,</span><span class="w"> </span><span class="n">Read</span><span class="o">&lt;</span><span class="n">Assets</span><span class="o">&gt;</span><span class="w"> </span><span class="n">assets</span><span class="p">)</span>
+}</pre><p>This file imports the asset with id <code>cd007ba2-ee0d-44fd-bf36-85c829dbe66f</code>, which is the scene we looked at in the previous file, under the name <code>sub1</code>. It then imports the very same scene again, but this time with the name <code>sub2</code> instead. This effectively instantiates the entities of the previous scene twice in this new scene, each with their names prefixed with either <code>sub1.</code> or <code>sub2.</code></p><p>Under <code>entities</code>, we can override the entities in the sub-scenes to edit components or add new ones. For example, by referencing <code>sub1.root</code> we are making local changes to the <code>root</code> entity of that instance of the subscene. The result of the changes we make to both <code>sub1.root</code> and <code>sub2.root</code> is that the parent of these entities will be set to be the <code>main</code> entity.</p><p>Now that we have our scene file, let&#x27;s get our application to load it. The first thing we&#x27;re going to need is a reference to the scene asset. For the purposes of this sample we can simply use an hardcoded reference to the asset.</p><pre class="m-code"><span class="k">static</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">Asset</span><span class="o">&lt;</span><span class="n">Scene</span><span class="o">&gt;</span><span class="w"> </span><span class="n">SceneAsset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">AnyAsset</span><span class="p">(</span><span class="s">&quot;f0d86ba8-5f34-440f-a180-d9d12c8e8b91&quot;</span><span class="p">);</span></pre><p>Then we&#x27;ll need a system that spawns that scene. To do this we simply get the Scene object from the asset, and then spawn its entities. <a href="classcubos_1_1core_1_1ecs_1_1Commands.html#a0c75cfde6373904798ba117b9627cd5f" class="m-doc">Commands::<wbr />spawn</a> will create in the world a copy of every entity defined in the scene&#x27;s blueprint. It won&#x27;t remove the entities already there, so if you want to close a scene, you&#x27;ll have to do it yourself.</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">spawnScene</span><span class="p">(</span><span class="n">Commands</span><span class="w"> </span><span class="n">commands</span><span class="p">,</span><span class="w"> </span><span class="n">Read</span><span class="o">&lt;</span><span class="n">Assets</span><span class="o">&gt;</span><span class="w"> </span><span class="n">assets</span><span class="p">)</span>
 <span class="p">{</span>
 <span class="w">    </span><span class="k">auto</span><span class="w"> </span><span class="n">sceneRead</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">assets</span><span class="o">-&gt;</span><span class="n">read</span><span class="p">(</span><span class="n">SceneAsset</span><span class="p">);</span>
 <span class="w">    </span><span class="n">commands</span><span class="p">.</span><span class="n">spawn</span><span class="p">(</span><span class="n">sceneRead</span><span class="o">-&gt;</span><span class="n">blueprint</span><span class="p">);</span>
-<span class="p">}</span></pre><p>And now we&#x27;ll have this system run at startup. It is not required, you can spawn scenes at any point in the execution of the program, but for the purpose of demonstrating the functionality, spawning once at startup is enough.</p><pre class="m-code"><span class="w">    </span><span class="n">cubos</span><span class="p">.</span><span class="n">startupSystem</span><span class="p">(</span><span class="n">spawnScene</span><span class="p">).</span><span class="n">tagged</span><span class="p">(</span><span class="s">&quot;spawn&quot;</span><span class="p">).</span><span class="n">tagged</span><span class="p">(</span><span class="s">&quot;cubos.assets&quot;</span><span class="p">);</span></pre><p>Finally, let&#x27;s print the loaded scene, to check that everything is working correctly.</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">printStuff</span><span class="p">(</span><span class="n">Read</span><span class="o">&lt;</span><span class="n">World</span><span class="o">&gt;</span><span class="w"> </span><span class="n">world</span><span class="p">)</span>
-<span class="p">{</span>
-<span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">cubos</span><span class="o">::</span><span class="n">core</span><span class="o">::</span><span class="n">data</span><span class="o">::</span><span class="n">Context</span><span class="p">;</span>
-<span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">cubos</span><span class="o">::</span><span class="n">core</span><span class="o">::</span><span class="n">data</span><span class="o">::</span><span class="n">DebugSerializer</span><span class="p">;</span>
-<span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">cubos</span><span class="o">::</span><span class="n">core</span><span class="o">::</span><span class="n">data</span><span class="o">::</span><span class="n">SerializationMap</span><span class="p">;</span>
-<span class="w">    </span><span class="k">using</span><span class="w"> </span><span class="n">cubos</span><span class="o">::</span><span class="n">core</span><span class="o">::</span><span class="n">memory</span><span class="o">::</span><span class="n">Stream</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">auto</span><span class="w"> </span><span class="n">entity</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="o">*</span><span class="n">world</span><span class="p">)</span>
-<span class="w">    </span><span class="p">{</span>
-<span class="w">        </span><span class="k">auto</span><span class="w"> </span><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">to_string</span><span class="p">(</span><span class="n">entity</span><span class="p">.</span><span class="n">index</span><span class="p">);</span>
-<span class="w">        </span><span class="k">auto</span><span class="w"> </span><span class="n">ser</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">DebugSerializer</span><span class="p">(</span><span class="n">Stream</span><span class="o">::</span><span class="n">stdOut</span><span class="p">);</span>
-<span class="w">        </span><span class="k">auto</span><span class="w"> </span><span class="n">pkg</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">world</span><span class="o">-&gt;</span><span class="n">pack</span><span class="p">(</span><span class="n">entity</span><span class="p">);</span>
-<span class="w">        </span><span class="n">ser</span><span class="p">.</span><span class="n">write</span><span class="p">(</span><span class="n">pkg</span><span class="p">,</span><span class="w"> </span><span class="n">name</span><span class="p">.</span><span class="n">c_str</span><span class="p">());</span>
-<span class="w">        </span><span class="n">Stream</span><span class="o">::</span><span class="n">stdOut</span><span class="p">.</span><span class="n">put</span><span class="p">(</span><span class="sc">&#39;\n&#39;</span><span class="p">);</span>
-<span class="w">    </span><span class="p">}</span>
-<span class="p">}</span></pre><p>If you run the sample, it should give you a list that has:</p><ul><li>an entity with <code>num</code> set to 0, with no parent. This is the <code>main</code> entity.</li><li>two entities with <code>num</code> set to 1, with same parent, who has <code>num</code> set to 0. These are the <code>root</code> entities of each instance of the subscene.</li><li>two entities with <code>num</code> set to 2, with different parents, but both of them having <code>num</code> set to 1. These are the <code>child</code> entities of each instance of the subscene.</li></ul>
+<span class="p">}</span></pre><p>In this case, we&#x27;ll run this system at startup, since we want to spawn it a single time. Since it&#x27;s a startup system, we&#x27;ll have to tag it with <code>cubos.assets</code> to make sure it runs only after the scene bridge has been registered. On a real game, you could have, for example, a scene for an enemy which you spawn multiple times, instead of just once at startup.</p><pre class="m-code"><span class="w">    </span><span class="n">cubos</span><span class="p">.</span><span class="n">startupSystem</span><span class="p">(</span><span class="n">spawnScene</span><span class="p">).</span><span class="n">tagged</span><span class="p">(</span><span class="s">&quot;spawn&quot;</span><span class="p">).</span><span class="n">tagged</span><span class="p">(</span><span class="s">&quot;cubos.assets&quot;</span><span class="p">);</span></pre><p>This sample will output the list of every entity in the scene, so you can check that everything is working as expected. If you run it, it should give you a list that has:</p><ul><li>an entity with <code>num</code> set to 0, with no parent. This is the <code>main</code> entity.</li><li>two entities with <code>num</code> set to 1, with same parent, who has <code>num</code> set to 0. These are the <code>root</code> entities of each instance of the subscene.</li><li>two entities with <code>num</code> set to 2, with different parents, but both of them having <code>num</code> set to 1. These are the <code>child</code> entities of each instance of the subscene.</li></ul>
       </div>
     </div>
   </div>

pr-preview/pr-562/group__scene-plugin.html

@@ -62,7 +62,7 @@ <h3>Contents</h3>
             </li>
           </ul>
         </nav>
-<section id="autotoc_md79"><h3><a href="#autotoc_md79">Bridges</a></h3><ul><li><a href="classcubos_1_1engine_1_1SceneBridge.html" class="m-doc">SceneBridge</a> - registered with the <code>.cubos</code> extension, loads <a href="structcubos_1_1engine_1_1Scene.html" class="m-doc">Scene</a> assets.</li></ul></section><section id="autotoc_md80"><h3><a href="#autotoc_md80">Dependencies</a></h3><ul><li><a href="group__assets-plugin.html" class="m-doc">Assets</a></li></ul></section>
+<aside class="m-note m-default"><h4>See also</h4><p>Take a look at the <a href="examples-engine-scene.html" class="m-doc">Scene</a> example for a demonstration of this plugin.</p></aside><section id="autotoc_md79"><h3><a href="#autotoc_md79">Bridges</a></h3><ul><li><a href="classcubos_1_1engine_1_1SceneBridge.html" class="m-doc">SceneBridge</a> - registered with the <code>.cubos</code> extension, loads <a href="structcubos_1_1engine_1_1Scene.html" class="m-doc">Scene</a> assets.</li></ul></section><section id="autotoc_md80"><h3><a href="#autotoc_md80">Dependencies</a></h3><ul><li><a href="group__assets-plugin.html" class="m-doc">Assets</a></li></ul></section>
         <section id="files">
           <h2><a href="#files">Files</a></h2>
           <dl class="m-doc">