Skip to content

Commit 7677bbc

Browse files
zaucyzaucy
committed
feat: add unnreal subsystem documentation
1 parent 72fbc79 commit 7677bbc

File tree

7 files changed

+135
-10
lines changed

7 files changed

+135
-10
lines changed

‎src/app/start/unreal/codegen/unreal-codegen.component.html‎

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,58 @@
11
<article>
22
<h1>Ecsact -> Unreal C++</h1>
3-
<p>A large part of what makes Ecsact work is code generation and with Unreal projects thats no exception. The Ecsact Unreal plugin is not only an Unreal plugin, but an Ecsact Codegen plugin as well!</p>
3+
<p>
4+
A large part of what makes Ecsact work is code generation and with Unreal
5+
projects thats no exception. The Ecsact Unreal plugin is not only an Unreal
6+
plugin, but an Ecsact Codegen plugin as well!
7+
</p>
48
<h2 id="whats-generated">What's Generated?</h2>
59
<p>
6-
The goal of the codegen plugin is to remove a lot of boilerplate code that would otherwise be tedious to write. By default the Ecsact Unreal codegen plugin generates the following:
10+
The goal of the codegen plugin is to remove a lot of boilerplate code that
11+
would otherwise be tedious to write. By default the Ecsact Unreal codegen
12+
plugin generates the following:
713
</p>
814
<ul>
9-
<li><a href="https://dev.epicgames.com/documentation/en-us/unreal-engine/structs-in-unreal-engine" _target="_blank"><span class="i24">open_in_new</span> <code>UStructs</code></a> for every component in your Ecsact file</li>
10-
<li><a href="https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-mass-entity-in-unreal-engine" _target="blank"><span class="i24">open_in_new</span> Unreal Mass Entity</a> Fragments or Tags for every component in your Ecsact file</li>
11-
<li>Ecsact Runner Subsystem with easily overridable component events</li>
15+
<li>
16+
<a
17+
href="https://dev.epicgames.com/documentation/en-us/unreal-engine/structs-in-unreal-engine"
18+
_target="_blank"
19+
><span class="i24">open_in_new</span> <code>UStructs</code></a
20+
>
21+
for every component in your Ecsact file
22+
</li>
23+
<li>
24+
<a
25+
href="https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-mass-entity-in-unreal-engine"
26+
_target="blank"
27+
><span class="i24">open_in_new</span> Unreal Mass Entity</a
28+
>
29+
Fragments or Tags for every component in your Ecsact file
30+
</li>
31+
<li>
32+
<a routerLink="/start/unreal/subsystems" fragment="codegen-subsystems"
33+
>Ecsact Runner Subsystem for component end entity lifecycle evnts</a
34+
>
35+
</li>
1236
<li>Ecsact Runner Subsystem for Ecsact to Entity Mass communication</li>
1337
</ul>
1438

1539
<h2 id="setup-codegen">Setup Codegen</h2>
1640
<p>
17-
We recommend using the <code>EcsactUnrealCodegen</code> command line tool that comes with the <a routerLink="/start">Ecsact SDK</a> since <code>0.9.0</code>. Simply execute <code>EcsactUnrealCodegen</code> for your project and the tool will search for all <code>.ecsact</code> files in your <code>Source</code> directory and use the Ecsact codegen tool with the Ecsat Unreal codegen plugin. The Ecsact Unreal plugin is required to be installed for the tool to find the right codegen plugin. If you run into issues please see the output of <code>EcsactUnrealCodegen</code> for details.</p>
41+
We recommend using the <code>EcsactUnrealCodegen</code> command line tool
42+
that comes with the <a routerLink="/start">Ecsact SDK</a> since
43+
<code>0.9.0</code>. Simply execute <code>EcsactUnrealCodegen</code> for your
44+
project and the tool will search for all <code>.ecsact</code> files in your
45+
<code>Source</code> directory and use the Ecsact codegen tool with the Ecsat
46+
Unreal codegen plugin. The Ecsact Unreal plugin is required to be installed
47+
for the tool to find the right codegen plugin. If you run into issues please
48+
see the output of <code>EcsactUnrealCodegen</code> for details.
49+
</p>
1850
<h3 id="run-codegen-command-line">Command Line or Script</h3>
19-
<p>Replace <code>path/to/project.uproject</code> with the path to your unreal project file and <code>path/to/unreal/install</code> with the full path to your Unreal Engine installation directory</p>
51+
<p>
52+
Replace <code>path/to/project.uproject</code> with the path to your unreal
53+
project file and <code>path/to/unreal/install</code> with the full path to
54+
your Unreal Engine installation directory
55+
</p>
2056
<pre><code prism language="bash">
2157
EcsactUnrealCodegen path/to/project.uproject --engine-dir path/to/unreal/install
2258
</code></pre>

‎src/app/start/unreal/subsystems/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ ng_project(
1212
"//:node_modules/@angular/common",
1313
"//:node_modules/@angular/core",
1414
"//:node_modules/@angular/router",
15+
"//src/components/ecsact-lang-syntax",
1516
"//src/components/code-block-variation",
1617
"//src/components/prism",
1718
],

‎src/app/start/unreal/subsystems/unreal-subsystems.component.html‎

Lines changed: 81 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,85 @@
11
<article>
2-
<h1>Ecsact Runner Subsystems</h1>
2+
<h1>Ecsact Subsystems</h1>
3+
<p>
4+
The <a routerLink="/start/unreal/runner">Ecsact Runner</a> has
5+
<em>subsystems</em> that start when the runner starts. Subsystems are
6+
<em>the</em> way to listen for component events and entity lifecycle events.
7+
If you want to know when an Ecsact entity is created/destroyed or an Ecsact
8+
component is added, updated, or removed then Ecsact Runner subsystems is
9+
what you want!
10+
</p>
311
<section>
4-
12+
<h2 id="codegen-subsystems">Built-in Codegen Subsystems</h2>
13+
<p>
14+
There are a few built-in
15+
<a routerLink="/start/unreal/codegen">code generated</a> subsystems that
16+
are a must in any Ecsact unreal project. These subsystems allow you to
17+
listen to specific component events with their correct typings in C++ or
18+
even blueprints.
19+
</p>
20+
<p>
21+
Lets say we have this simple <code>.ecsact</code> file that has a
22+
<code>Health</code> component and <code>Dead</code> tag.
23+
</p>
24+
<pre><code ecsactLangSyntax>
25+
main package example;
26+
component Health {{'{'}} f32 amount; {{'}'}}
27+
component Dead;
28+
</code></pre>
29+
<p>
30+
After your Ecsact Codegen is ran and you've re-built your project you will
31+
have access to a new subsystem that you can extend in either bluprint or
32+
c++. The generated subsystem name will be prefixed with your Ecsact
33+
package name (in this case <code>example</code>.) Following the unreal
34+
naming convention it will have the first letter capitalized.
35+
</p>
36+
<div class="flex flex-row gap-4 text-center my-4">
37+
<div>
38+
<div class="hidden lg:block text-lg font-bold">C++</div>
39+
<a href="/assets/unreal/unreal-subsystem-cpp-create.png">
40+
<img src="/assets/unreal/unreal-subsystem-cpp-create.png" />
41+
</a>
42+
</div>
43+
<div class="hidden lg:block">
44+
<div class="text-lg font-bold">Blueprint</div>
45+
<a href="/assets/unreal/unreal-subsystem-bp-create.png">
46+
<img src="/assets/unreal/unreal-subsystem-bp-create.png" />
47+
</a>
48+
</div>
49+
</div>
50+
<p>
51+
Events are exposed as <code>BlueprintNativeEvent</code> in the subsystem.
52+
Meaning in blueprints you can easily implement these events in the event
53+
graph or in C++ as a virtual member function.
54+
</p>
55+
<div class="flex flex-col gap-4 items-center justify-center my-4">
56+
<div>
57+
<div class="text-lg font-bold text-center">C++</div>
58+
<div>
59+
<code-block-variation class="m-0 rounded-md mt-3">
60+
<pre
61+
codeBlockVariationOption
62+
optionTitle="C++"><code prism language="cpp">
63+
#include "Example__ecsact__ue.h" // generated header
64+
65+
auto UMySubsystem::UpdateHealth_Implementation(
66+
int32 Entity,
67+
FExampleHealth Health
68+
) -&gt; void {{'{'}}
69+
// TODO: play cool heal effect
70+
{{'}'}}
71+
</code></pre>
72+
</code-block-variation>
73+
</div>
74+
</div>
75+
<div>
76+
<div class="text-lg font-bold text-center">Blueprint</div>
77+
<a href="/assets/unreal/unreal-bp-subsystem-01.png">
78+
<img
79+
class="rounded-md mt-3"
80+
src="/assets/unreal/unreal-bp-subsystem-01.png" />
81+
</a>
82+
</div>
83+
</div>
584
</section>
685
</article>

‎src/app/start/unreal/subsystems/unreal-subsystems.component.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
11
import {Component, OnInit, ChangeDetectionStrategy} from '@angular/core';
22
import {RouterLink} from '@angular/router';
33
import {PrismComponent} from '../../../../components/prism/prism.component';
4+
import {EcsactLangSyntaxComponent} from '../../../../components/ecsact-lang-syntax/ecsact-lang-syntax.component';
5+
import {CodeBlockVariationComponent} from '../../../../components/code-block-variation/code-block-variation.component';
6+
import {CodeBlockVariationOptionDirective} from '../../../../components/code-block-variation/code-block-variation-option.directive';
47

58
@Component({
69
templateUrl: './unreal-subsystems.component.html',
710
changeDetection: ChangeDetectionStrategy.OnPush,
811
standalone: true,
9-
imports: [RouterLink, PrismComponent],
12+
imports: [
13+
RouterLink,
14+
PrismComponent,
15+
EcsactLangSyntaxComponent,
16+
CodeBlockVariationComponent,
17+
CodeBlockVariationOptionDirective,
18+
],
1019
})
1120
export class UnrealSubsystemsComponent implements OnInit {
1221
constructor() {}

‎src/assets/unreal/unreal-bp-subsystem-01.png‎

39.3 KB
Loading

‎src/assets/unreal/unreal-subsystem-bp-create.png‎

23.9 KB
Loading

‎src/assets/unreal/unreal-subsystem-cpp-create.png‎

37.6 KB
Loading

0 commit comments

Comments
 (0)