Skip to content

Commit 6056b66

Browse files
KelwanKelwan
authored
Update website for new async changes (#97)
1 parent 8aa396c commit 6056b66

15 files changed

+329
-88
lines changed

‎src/app/docs/runtime/runtime.component.html‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,19 @@ <h3 id="core-module">Core</h3>
2626
>
2727
</p>
2828

29+
<h3 id="Async">Async</h3>
30+
<p>
31+
The async module handles everything involving using an external async
32+
execution. This includes flushing events, enqueuing execution options, and
33+
receving async specific errors.
34+
</p>
35+
<p>
36+
Async methods are available in
37+
<a routerLink="/reference/ecsact_runtime/async_8h"
38+
><span class="i24">article</span> ecsact/runtime/async.h</a
39+
>
40+
</p>
41+
2942
<h3 id="dynamic-module">Dynamic</h3>
3043
<p>
3144
The dynamic module is responsible for creating new <em>types</em> and even

‎src/app/docs/unity/defaults/defaults.component.html‎

Lines changed: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,35 +15,83 @@ <h2 id="registry">Registry</h2>
1515
The Registry is an easy way to use core functionality from the Runtime. It
1616
simplifies how they're called and needs less information from the user.
1717
</p>
18+
<p>
19+
NOTE: If Async is enabled in the Ecsact settings the default Registry will
20+
be <code>NULL</code>
21+
</p>
1822
</section>
1923
<section>
2024
<h2 id="runner">Runner</h2>
2125
<p>
22-
The Runner stores and executes actions and runs the Ecsact execution. You
23-
can choose the following options:
26+
The Runner stores and executes its options that are explained more below.
27+
There are two types of runners. Both has synonymous functionality with a
28+
few key differences:
29+
</p>
30+
<h3>Default Runner</h3>
31+
<p>
32+
Runs the Ecsact execution synchronously. You can choose the following
33+
options:
2434
</p>
2535
<ol>
2636
<li><code>Default</code>: Executes per Update tick</li>
2737
<li><code>Fixed Update</code>: Executes per FixedUpate tick</li>
2838
<li><code>None</code>: Implement your own Runner</li>
2939
</ol>
40+
<h3>Async Runner</h3>
41+
<p>
42+
Runs the Ecsact execution asynchronously. If you're interested in
43+
developing multiplayer games this is the way to go. There are some
44+
differences in how it's used.
45+
</p>
46+
<ul>
47+
<li>
48+
the Default Registry is NULL which comes at the cost of direct access to
49+
its inner workings
50+
</li>
51+
<li>
52+
Instead of choosing how the Ecsact execution functions, you instead
53+
connect to an <a routerLink="/docs/runtime" fragment="Async">async</a>
54+
execution. By default, the Ecsact Unity Integration uses the
55+
<code>reference async runtime</code> which takes deltatime as a
56+
parameter in milliseconds on connect.
57+
<code-block-variation>
58+
<pre codeBlockVariationOption><code prism language="csharp">
59+
Ecsact.Defaults.Runtime.async.Connect("good?delta_time=25");
60+
</code></pre>
61+
</code-block-variation>
62+
</li>
63+
</ul>
64+
3065
<h3>ExecutionOptions</h3>
31-
<p>Allows you to add actions to the execution to be performed</p>
66+
<p>
67+
Allows the creation and destruction of entities, adding and removing
68+
components and pushing actions
69+
</p>
3270
<code-block-variation>
3371
<pre codeBlockVariationOption><code ecsactLangSyntax>
3472
main package example;
3573

36-
action BasicAction {{'{'}}{{'}'}}</code></pre>
74+
action BasicAction {{'{'}}{{'}'}}
75+
76+
component Foo;
77+
</code></pre>
3778
</code-block-variation>
3879
<code-block-variation>
3980
<pre codeBlockVariationOption><code prism language="csharp">
4081
// An action declared in Ecsact
41-
example.BasicAction basicAction;
82+
var basicAction = ecsact.basicAction;
4283

4384
// Pushes the action to the executionOptions
4485
Ecsact.Defaults.Runner.executionOptions.PushAction(
4586
basicAction
46-
);</code></pre>
87+
);
88+
89+
// Declare component type of Foo
90+
var fooComponent = example.Foo;
91+
92+
// Add a component to an entity with its ID
93+
Ecsact.Defaults.Runner.executionOptions.AddComponent(entityId, fooComponent);
94+
</code></pre>
4795
</code-block-variation>
4896
<p></p>
4997
</section>

‎src/app/docs/unity/entities/entities.component.html‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,29 @@
22
<h1>Creating Entities in Unity</h1>
33
<p>There are multiple ways to create entities in Unity with Ecsact</p>
44
<section>
5-
<h2 id="registry">Using the Registry</h2>
5+
<h2 id="registry">Using executionOptions</h2>
66
<p>
7-
The <code>Registry</code> can be used to create entities. It returns the
8-
ID of the entity created
7+
The <code>Runner</code> can be used to create entities through its
8+
options. It has an optional callback with the new entity's ID
99
</p>
1010
<code-block-variation>
1111
<pre
12-
codeBlockVariationOption><code prism language="csharp">int entityId = Ecsact.Defaults.Registry.CreateEntity();</code></pre>
12+
codeBlockVariationOption><code prism language="csharp">Ecsact.Defaults.Runner.executionOptions.CreateEntity((entityId) ={{'>'}} {{'{'}}{{'}'}});</code></pre>
13+
</code-block-variation>
14+
15+
<p>
16+
<code>CreateEntity</code> also returns a builder that allows it to be
17+
created with initial components
18+
</p>
19+
<code-block-variation>
20+
<pre codeBlockVariationOption><code prism language="csharp">
21+
var fooComponent = new example.Foo {{'{'}}.someValue = 5{{'}'}};
22+
var barComponent = new example.Bar {{'{'}}.someOtherValue = 10{{'}'}};
23+
24+
Ecsact.Defaults.Runner.executionOptions
25+
.CreateEntity((entityId) ={{'>'}} {{'{'}}{{'}'}})
26+
.AddComponent(fooComponent)
27+
.AddComponent(barComponent);</code></pre>
1328
</code-block-variation>
1429
</section>
1530
<section>

‎src/app/start/start.component.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@
3535
<a routerLink="tutorials/unity/moving-block" routerLinkActive="active"
3636
><span class="i24 mr-2">school</span>Moving Block</a
3737
>
38+
<a routerLink="tutorials/unity/using-async" routerLinkActive="active">
39+
<span class="i24 mr-2">school</span>Using Async
40+
</a>
3841
</ecsact-sidenav-section>
3942
<ecsact-sidenav-section title="Unreal Engine">
4043
<a routerLink="/start/unreal" routerLinkActive="active"

‎src/app/start/tutorials/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ ng_ts_project(
1111
"//src/app/start/tutorials/systems-in-cpp",
1212
"//src/app/start/tutorials/unity/basic-example",
1313
"//src/app/start/tutorials/unity/moving-block",
14+
"//src/app/start/tutorials/unity/using-async",
1415
"@npm//@angular/core",
1516
"@npm//@angular/router",
1617
],

‎src/app/start/tutorials/tutorials-routing.module.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,13 @@ const routes: Routes = [
3737
m => m.BasicExampleRoutingModule,
3838
),
3939
},
40+
{
41+
path: 'unity/using-async',
42+
loadChildren: () =>
43+
import('./unity/using-async/using-async-routing.module').then(
44+
m => m.UsingAsyncRoutingModule,
45+
),
46+
},
4047
];
4148

4249
@NgModule({

‎src/app/start/tutorials/unity/basic-example/basic-example.component.html‎

Lines changed: 40 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -55,22 +55,43 @@ <h2 id="create-entity">Creating an Entity</h2>
5555
Great! We have a simple <code>.Ecsact</code> file we can build on. Now we
5656
can make a C# script in Unity, for our use it will be called
5757
<code>BasicExample.cs</code>. This script will allow us to
58-
<a href="/docs/unity/entities">create an entity</a>
58+
<a href="/docs/unity/entities">create an entity</a> with some components
59+
</p>
60+
<p>We'll start by declaring the components we'll be adding to our entity</p>
61+
<code-block-variation>
62+
<pre codeBlockVariationOption><code prism language="csharp">
63+
// Declare an Example component type
64+
var exampleComponent = new example.Example {{'{'}}
65+
example_value = 5,
66+
{{'}'}};
67+
68+
var removeComponent = new example.ToBeRemoved {{'{'}}{{'}'}};
69+
</code></pre>
70+
</code-block-variation>
71+
72+
<p>
73+
Components can be declared from the namespace that is dervied from the
74+
name of your package in the <code>.ecsact</code> file. Now that we have
75+
our components, we can add them to a newly created entity using the
76+
Runner's <code>executionOptions</code>
5977
</p>
6078

6179
<code-block-variation>
6280
<pre codeBlockVariationOption><code prism language="csharp">
63-
// The Registry is a convenient way to access the Core api.
64-
int entityId = Ecsact.Defaults.Registry.CreateEntity();
81+
Ecsact.Defaults.Runner.executionOptions
82+
.CreateEntity()
83+
.AddComponent(exampleComponent)
84+
.AddComponent(removeComponent);
6585
</code></pre>
6686
</code-block-variation>
6787
</section>
6888
<section>
6989
<h2 id="listeners">Runtime Listeners</h2>
7090
<p>
7191
The <a href="docs/unity/defaults">Runtime</a> gives you access to
72-
everything used during Unity's runtime. In this case, we can add listeners
73-
for changes to component state
92+
everything used during Unity's runtime. For example, listeners can be
93+
added for changes to component state or when an entity is created or
94+
destroyed.
7495
</p>
7596

7697
<code-block-variation>
@@ -79,62 +100,30 @@ <h2 id="listeners">Runtime Listeners</h2>
79100
List<{{'System.Action'}}> cleanUpFns = new();
80101

81102
cleanUpFns.AddRange(new[] {{'{'}}
82-
// Callback that's invoked on the removal of a component
83-
Ecsact.Defaults.Runtime.OnRemoveComponent<{{'example.ToBeRemoved'}}>((entity, component) => {{'{'}}
84-
Debug.Log("Example component removed");
103+
// Callback invoked when Example component is added
104+
Ecsact.Defaults.Runtime.OnInitComponent<{{'example.Example'}}>((entity, component) => {{'{'}}
105+
Debug.Log("Example component added");
106+
Debug.Log(component.example_value);
85107
{{'}'}}),
86-
// Callback that's invoked on the removal of a component
108+
// Callback invoked when Example component is updated
87109
Ecsact.Defaults.Runtime.OnUpdateComponent<{{'example.Example'}}>((entity, component) => {{'{'}}
88110
Debug.Log(component.example_value);
111+
{{'}'}}),
112+
// Callback invoked when Example component is removed
113+
Ecsact.Defaults.Runtime.OnRemoveComponent<{{'example.ToBeRemoved'}}>((entity, component) => {{'{'}}
114+
Debug.Log("Example component removed");
115+
{{'}'}}),
116+
// Callback invoked on the creation of an entity
117+
Ecsact.Defaults.Runtime.OnEntityCreated((entityId, placeholderId) => {{'{'}}
118+
Debug.Log("Entity created");
89119
{{'}'}})
90120
{{'}'}});
91121
</code></pre>
92122
</code-block-variation>
93-
94-
<p>
95-
Whenever a component is updated and removed, these callbacks will be
96-
invoked. We'll go over how to update components later, but first we'll
97-
declare the components to add to our newly created entity
98-
</p>
99123
</section>
100124

101125
<section>
102-
<h2 id="components">Declaring and adding components</h2>
103-
<code-block-variation>
104-
<pre codeBlockVariationOption><code prism language="csharp">
105-
// Declare an Example component type
106-
var exampleComponent = new example.Example {{'{'}}
107-
example_value = 5,
108-
{{'}'}};
109-
110-
var removeComponent = new example.ToBeRemoved {{'{'}}{{'}'}};
111-
</code></pre>
112-
</code-block-variation>
113-
114-
<p>
115-
Components can be declared from the namespace that is dervied from the
116-
name of your package in the <code>.ecsact</code> file. Now that we have
117-
our components, we can add it to an entity with its id using the
118-
<code>Registry</code>
119-
</p>
120-
121-
<code-block-variation>
122-
<pre codeBlockVariationOption><code prism language="csharp">
123-
// Add components to your entity
124-
Ecsact.Defaults.Registry.AddComponent(
125-
entityId,
126-
exampleComponent
127-
);
128-
129-
Ecsact.Defaults.Registry.AddComponent(
130-
entityId,
131-
removeComponent
132-
);
133-
</code></pre>
134-
</code-block-variation>
135-
</section>
136-
<section>
137-
<p>Then, when the class is destroyed the listeners will be cleaned up</p>
126+
<p>When the class is destroyed the listeners will be cleaned up</p>
138127
<code-block-variation>
139128
<pre codeBlockVariationOption><code prism language="csharp">
140129
void OnDestroy() {{'{'}}

‎src/app/start/tutorials/unity/moving-block/moving-block.component.html‎

Lines changed: 22 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -110,19 +110,20 @@ <h2 id="gameobject">Adding a GameObject with Unity Sync</h2>
110110
<h2 id="blocks">Generating Blocks</h2>
111111
<p>
112112
What if we took this one step further? We've managed to use Unity Sync
113-
with our Dynamic Entity, but Unity Sync will adapt to changes in entities
113+
with our Dynamic Entity, and now we can can adapt to changes in entities
114114
during runtime. Let's go into our <code>.ecsact</code> file.
115115
</p>
116116
<code-block-variation>
117117
<pre codeBlockVariationOption><code ecsactLangSyntax>
118118
component BlockGenerator;
119119

120+
// This component fulfills our entity to be iterated over by GenerateBlock
120121
component QueueBlock {{'{'}}
121122
i32 pos_x;
122123
i32 pos_y;
123124
{{'}'}}
124125

125-
// An action that will happen on an Input
126+
// An action that will happen on an input
126127
action PerformGenerateBlock {{'{'}}
127128
i32 pos_x;
128129
i32 pos_y;
@@ -168,13 +169,9 @@ <h2 id="blocks">Generating Blocks</h2>
168169
mouseAction.Enable();
169170
mouseAction.performed += OnMouseClick;
170171

171-
// Create an entity that will manage the generation of new entities
172-
entityId = Ecsact.Defaults.Registry.CreateEntity();
173-
174-
Ecsact.Defaults.Registry.AddComponent<{{'example.BlockGenerator'}}>(
175-
entityId,
176-
new example.BlockGenerator {{'{'}}{{'}'}}
177-
);
172+
Ecsact.Defaults.Runner.executionOptions
173+
.CreateEntity()
174+
.AddComponent(new example.BlockGenerator {{'{'}}{{'}'}});
178175
{{'}'}}
179176

180177
public void OnMouseClick
@@ -529,29 +526,22 @@ <h2 id="collision">Basic Collision</h2>
529526
int entityId;
530527

531528
void Start() {{'{'}}
532-
entityId = Ecsact.Defaults.Registry.CreateEntity();
533529

534530
var xScale = System.Convert.ToInt32(gameObject.transform.localScale.x);
535531
var yScale = System.Convert.ToInt32(gameObject.transform.localScale.y);
536532

537533
var xPos = (int)gameObject.transform.position.x;
538534
var yPos = (int)gameObject.transform.position.y;
539535

540-
Ecsact.Defaults.Registry.AddComponent<{{'example.Collider'}}>(
541-
entityId,
542-
new example.Collider {{'{'}}
543-
x_radius = xScale,
544-
y_radius = yScale
545-
{{'}'}}
546-
);
547-
548-
Ecsact.Defaults.Registry.AddComponent<{{'example.Position'}}>(
549-
entityId,
550-
new example.Position {{'{'}}
551-
x = xPos,
552-
y = yPos
553-
{{'}'}}
554-
);
536+
Ecsact.Defaults.Runner.executionOptions
537+
.CreateEntity()
538+
.AddComponent(new example.Collider{{'{'}}
539+
x_radius = xScale,
540+
y_radius = yScale
541+
{{'}'}}).AddComponent(new example.Position{{'{'}}
542+
x = xPos,
543+
y = yPos
544+
{{'}'}});
555545
{{'}'}}
556546
{{'}'}}
557547
</code></pre>
@@ -568,7 +558,12 @@ <h2 id="collision">Basic Collision</h2>
568558
</section>
569559
<h2 id="conclusion">Conclusion</h2>
570560
<p>
571-
Hopefully this has helped you become comfortable with Unity enough with
572-
Ecsact in Unity to try things out for yourself.
561+
Hopefully this has helped you become comfortable with Ecsact in Unity enough
562+
to try things out for yourself.
563+
</p>
564+
<p>
565+
If you're interested in making multiplayer games, check out the last and
566+
much shorter
567+
<a href="start/tutorials/unity/using-async">using-async</a> tutorial.
573568
</p>
574569
</article>

0 commit comments

Comments
 (0)