You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/FlecsScriptTutorial.md
+69-39Lines changed: 69 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,3 @@
1
-
This tutorial hasn't been updated for v4 yet! Use the [Script Manual](FlecsScript.md) for now.
2
-
3
1
# Flecs Script Tutorial
4
2
This tutorial shows you how to use Flecs script, which is a declarative language for creating entities without having to write and compile code. Flecs script can be used for different things, such as building scenes, assets, or as a language for configuration files.
5
3
@@ -20,28 +18,28 @@ The page should look similar to this:
20
18
21
19
The panel on the left is the entity treeview, which shows all of the entities in our scene. The center view is the canvas, which shows us the renderable entities of our scene (more on that later). Finally, the pane on the right is the editor, where we can write flecs scripts.
22
20
23
-
At any point in time you can disable panels by clicking on the "x" in the top-right corner. Panels can be brought back by pressing on their button in the menu bar on the left.
21
+
At any point in time you can disable panels by clicking on the button in the top-right corner. Panels can be brought back by pressing on their button in the menu bar on the left.
24
22
25
23
One other important thing is the link button in the top-right of the screen. You can use that button to obtain a link to your content, which is a good way to save progress, or to share what you've created with other people.
26
24
27
25
## The Basics
28
26
Currently the explorer is showing the default scene. Let's clear it by removing all code from the editor. You should now see an empty canvas:
29
27
30
28
31
-
Lets create an entity by typing its name into the editor:
29
+
Lets create an entity by typing its name into the editor followed by an empty scope:
32
30
33
31
```js
34
-
my_entity
32
+
my_entity {}
35
33
```
36
34
37
35
Notice that as we are typing the entity shows up in the treeview:
38
-
[](https://www.flecs.dev/explorer/?wasm=https://www.flecs.dev/explorer/playground.js&script=%0Amy_entity%0A)
36
+
39
37
40
38
Entities are automatically created if they did not exist yet. Try entering the same entity twice:
41
39
42
40
```js
43
-
my_entity
44
-
my_entity
41
+
my_entity {}
42
+
my_entity {}
45
43
```
46
44
47
45
Only one entity shows up in the treeview. The second time `my_entity` was parsed it already existed, so nothing needed to be done.
@@ -50,38 +48,60 @@ Only one entity shows up in the treeview. The second time `my_entity` was parsed
50
48
Now that we have an entity, let's add a few components and tags to it. Change the text in the editor to this, to create an entity with a tag called `SpaceShip`:
51
49
52
50
```js
53
-
my_entity :- SpaceShip
51
+
my_entity { SpaceShip }
54
52
```
55
53
56
-
Note that we didn't have to explicitly declare `SpaceShip` in advance, and that it also shows up as entity in the treeview. We can add multiple things to an entity this way:
54
+
Note that this alone doesn't work as we didn't explicitly declare `SpaceShip` in advance, to fix this we must first declare `SpaceShip` as an empty entity, which is equivalent to a tag:
55
+
```js
56
+
SpaceShip {}
57
57
58
+
my_entity { SpaceShip }
59
+
```
60
+
We can add multiple tags to an entity:
58
61
```js
59
-
my_entity :- SpaceShip
60
-
my_entity :- FasterThanLight
62
+
SpaceShip {}
63
+
FasterThanLight {}
64
+
65
+
my_entity { SpaceShip }
66
+
my_entity { FasterThanLight }
61
67
```
62
68
63
-
To avoid repeating the entity name many times, we can use the `{}` operators to open a scope for the entity. Inside the scope we can list components for the entity by prefixing them with a dash (`-`):
69
+
To avoid repeating the entity name many times, we can use the `{}` operators to open a scope for the entity. Inside the scope we can list components for the entity by placing them on a new line:
70
+
71
+
```js
72
+
SpaceShip {}
73
+
FasterThanLight {}
64
74
75
+
my_entity {
76
+
SpaceShip
77
+
FasterThanLight
78
+
}
79
+
```
80
+
Or separating them with the `;` operator:
65
81
```js
82
+
SpaceShip {}
83
+
FasterThanLight {}
84
+
66
85
my_entity {
67
-
- SpaceShip
68
-
- FasterThanLight
86
+
SpaceShip; FasterThanLight
69
87
}
70
88
```
71
89
72
90
We can inspect the entity and its contents by opening it in the entity inspector. To do this, click on the entity in the treeview. You should now see this:
73
91
74
-
[](https://www.flecs.dev/explorer/?local=true&wasm=https://www.flecs.dev/explorer/playground.js&script=%0Amy_entity%20%7B%0A%20%20-%20SpaceShip%0A%20%20-%20FasterThanLight%0A%7D%0A&entity=my_entity)
92
+
75
93
76
-
Note how the `SpaceShip` and `FasterThanLight` tags show up in the editor. There is also a `Script: main` tag, which exists for Flecs to keep track of which entities got created by our script.
94
+
Note how the `SpaceShip` and `FasterThanLight` tags show up in the editor. There is also a `Script -> main` tag, which exists for Flecs to keep track of which entities got created by our script.
95
+
96
+
We can return to the script editor by clicking on the drop-down above the entity treeview, selecting `scripts` and then clicking on our script, `scene.flecs` in the list.
77
97
78
98
Adding a component is similar to adding tag with a value. Let's add the `Position3` component from the `flecs.components.transform` module which comes preloaded with the playground. Note how it also shows up in the inspector when we add this code:
79
99
80
100
```js
81
101
my_entity {
82
-
-SpaceShip
83
-
-FasterThanLight
84
-
-flecs.components.transform.Position3{1, 2, 3}
102
+
SpaceShip
103
+
FasterThanLight
104
+
flecs.components.transform.Position3:{1, 2, 3}
85
105
}
86
106
```
87
107
@@ -95,35 +115,39 @@ We can now use the component without the module name, which looks much cleaner:
95
115
96
116
```js
97
117
my_entity {
98
-
-SpaceShip
99
-
-FasterThanLight
100
-
-Position3{1, 2, 3}
118
+
SpaceShip
119
+
FasterThanLight
120
+
Position3{1, 2, 3}
101
121
}
102
122
```
103
123
104
124
If all went well, the playground should now look like this:
105
125
106
-
[](https://www.flecs.dev/explorer/?local=true&wasm=https://www.flecs.dev/explorer/playground.js&script=using%20flecs.components.*%0A%0Amy_entity%20%7B%0A%20%20-%20SpaceShip%0A%20%20-%20FasterThanLight%0A%20%20-%20Position3%7B1%2C%202%2C%203%7D%0A%7D%0A&entity=my_entity)
126
+
107
127
108
-
Note how after we added the `Position3` component, the inspector also shows the `Transform`and `WorldCell` components. This happens because the playground imports modules that implement world partitioning and transforms, which we get for free just by using `flecs.components.transform.Position3` component.
128
+
Note how after we added the `Position3` component, the inspector also shows the `Transform`component. This happens because the playground imports modules that implement transforms, which we get for free just by using `flecs.components.transform.Position3` component.
109
129
110
130
In addition to components and tags we can also add relationship pairs to entities. To add a pair, add this line to the scope of the entity, and note how it shows up in the inspector:
111
131
112
132
```js
113
-
-(OwnedBy, Player)
133
+
(OwnedBy, Player)
114
134
```
115
135
116
-
Entities can be created in hierarchies. A child entity is created in the scope of an entity just like the components and tags, but without the preceding `-`. Add this to the scope of the entity:
136
+
Note: you will also need to declare entities for `OwnedBy` and `Player`.
137
+
138
+
Entities can be created in hierarchies. A child entity is created in the scope of an entity just like the components and tags, but followed by a scope. Add this to the scope of the entity:
117
139
118
140
```js
119
141
cockpit {
120
-
pilot :- (Faction, Earth)
142
+
pilot { (Faction, Earth) }
121
143
}
122
144
```
123
145
146
+
Note: you will also need to declare entities for `Faction` and `Earth`.
147
+
124
148
You can see the hierarchy this created in the treeview by expanding `my_entity`:
125
149
126
-
[](https://www.flecs.dev/explorer/?local=true&wasm=https://www.flecs.dev/explorer/playground.js&script=using%20flecs.components.*%0A%0Amy_entity%20%7B%0A%20%20-%20SpaceShip%0A%20%20-%20FasterThanLight%0A%20%20-%20Position3%7B1%2C%202%2C%203%7D%0A%20%20%0A%20%20cockpit%20%7B%0A%20%20%20%20pilot%20%3A-%20(Faction%2C%20Earth)%0A%20%20%7D%0A%7D%0A&entity=my_entity)
150
+
127
151
128
152
Congratulations! You now know how to create entities, hierarchies, and how to add components and tags. None of the entities we created so far are visible in the canvas however, so lets do something about that.
129
153
@@ -146,14 +170,20 @@ Now add these lines into the editor to create our ground `plane`:
146
170
147
171
```js
148
172
plane {
149
-
-Position3{}
173
+
Position3:{}
150
174
Rectangle: {100, 100}
151
-
-Rgb{0.9, 0.9, 0.9}
175
+
Rgb:{0.9, 0.9, 0.9}
152
176
}
153
177
```
154
178
155
179
Something happened! But it doesn't look quite right:
156
180
181
+
182
+
183
+
The playground comes with a ground plane already called `ground_plane`, find it in the entity treeview and disable it by clicking the arrow in the top right of the inspector and then the `Disable` button.
184
+
185
+
With that out of the way, our ground plane still doesn't look quite right:
The rectangle is rotated the wrong way for our plane. To fix this we need to rotate it 90 degrees or `π/2` radians on the x axis. First lets define `π` as a constant value in our script:
We now have all of the basic knowledge to start drawing a fence! Note that if you want to move the camera around, first click on the canvas to give it focus. You can now move the camera around. To release focus from the canvas, click on it again (the green border should disappear).
0 commit comments