Skip to content

Commit f7d5aaf

Browse files
committed
feat: improve extension configuration options for end users, and improve docs
1 parent 9033243 commit f7d5aaf

File tree

1 file changed

+41
-4
lines changed

1 file changed

+41
-4
lines changed

docs/src/ScriptSystems/introduction.md

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@
44
Script systems are an experimental feature
55
</div>
66

7-
It's possible within BMS to inject new systems from scripts themselves, although the support is currently limited.
7+
It's possible within BMS to inject new systems from within scripts themselves.
88

9-
Systems introduced by scripts cannot run in parallel to other systems, but can be freely inserted between any other rust system (not script systems at the moment) and into any schedule.
9+
Systems introduced by scripts *can* run in parallel to other systems, and can be freely inserted between any other system, including other script systems.
10+
11+
BMS also provides utilities for visualising schedules using dot graphs, allowing low-effort modding frameworks for game authors.
1012

1113

1214
## Schedules
@@ -27,6 +29,7 @@ To insert a system you will need to use the `system_builder` global function lik
2729

2830
```lua
2931
local system = system_builder("my_system", script_id)
32+
:exclusive()
3033
:after(some_other_system)
3134
:before(another_system)
3235
```
@@ -43,9 +46,43 @@ If your event handler running the script is running in a certain schedule, that
4346

4447
</div>
4548

46-
## Dynamic system
49+
## Parameters
50+
51+
The system builder allows script authors to parameterise systems, using `resource` and `query` functions.
52+
The order in which those functions are called, will define the order in which arguments will be provided to the specified script callback.
53+
54+
For example:
55+
```lua
56+
system_builder("my_system")
57+
:query(
58+
world.query()
59+
:component(ComponentA)
60+
:component(ComponentB)
61+
:with(ComponentC)
62+
:without(ComponentD)
63+
)
64+
:resource(ResourceA)
65+
```
66+
67+
will create a system which calls the specified callback `my_system` with 2 arguments:
68+
- The `ScriptQueryResult` for the first query
69+
- With `components` access to ComponentA and ComponentB
70+
- The `ReflectReference` to `ResourceA`
71+
72+
## Exclusive systems
73+
74+
An exclusive system can be created using the `exclusive` function call on the system builder.
75+
76+
This allows the system to access everything as in a normal event handler.
77+
78+
Non-exclusive systems, will only be able to access the set of components and resources as parameterized when building the system. This is why we can run the system in parallel to other non-overlapping systems.
79+
80+
Exclusive systems on the other hand, cannot run in parallel.
81+
82+
83+
## Callback
4784

48-
The system injected will be similar to an event handler, however it will only trigger the specified script, and without any entity, in the above example you'd see the following lua callback:
85+
The system injected will be similar to an event handler, however it will only trigger the specified script, and without any entity, in the first example you'd see the following lua callback:
4986

5087
```lua
5188
function my_system()

0 commit comments

Comments
 (0)