From 70598ae101abcc29755793d8684df697c19f7b34 Mon Sep 17 00:00:00 2001 From: makspll Date: Fri, 28 Feb 2025 21:03:53 +0000 Subject: [PATCH 1/3] docs: add script systems docs --- docs/src/ScriptSystems/introduction.md | 56 ++++++++++++++++++++++++++ docs/src/Summary/running-scripts.md | 3 +- 2 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 docs/src/ScriptSystems/introduction.md diff --git a/docs/src/ScriptSystems/introduction.md b/docs/src/ScriptSystems/introduction.md new file mode 100644 index 0000000000..57f8a21c68 --- /dev/null +++ b/docs/src/ScriptSystems/introduction.md @@ -0,0 +1,56 @@ +# Script Systems + +
+Script systems are an experimental feature +
+ +It's possible within BMS to inject new systems from scripts themselves, although the support is currently limited. + +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. + + +## Schedules + +Bevy doesn't support reflecting schedules, so BMS rolls it's own schedule registry resource: `AppScheduleRegistry`, which can be used to add any custom schedules you want to interact with. The default Bevy schedules will be pre-populated for you. + +Once you've registered your schedule you will be able to interact with it in scripts like below: + +```lua +local update_schedule = world.get_schedule_by_name("Update") +local systems = update:systems() +local system_with_name = update:get_system_by_name("my_system") +``` + +## Inserting Systems + +To insert a system wou will need to use the `system_builder` global function like below: + +```lua +local system = system_builder("my_system", script_id) + :after(some_Other_system) + :before(another_system) +``` + +This will let you call `world.add_system` like so: + +```lua +world.add_system(update_schedule,system) +``` + +
+ +If your event handler running the script is running in a certain schedule, that schedule will be temporarilly removed by Bevy. Meaning you won't be able to modify it from within the script in-flight. + +
+ +## Dynamic system + +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: + +```lua +function my_system() + print("I am a dynamic system") +end +``` + +get triggered every update. diff --git a/docs/src/Summary/running-scripts.md b/docs/src/Summary/running-scripts.md index a68df6701f..c912ffa197 100644 --- a/docs/src/Summary/running-scripts.md +++ b/docs/src/Summary/running-scripts.md @@ -3,9 +3,10 @@ Once you have scripts discovered and loaded, you'll want to run them. -At the moment BMS supports two methods of making scripts runnable: +At the moment BMS supports three methods of making scripts runnable: - Attaching them to entities via `ScriptComponent`'s - Adding static scripts +- Creating dynamic systems ⚗️ (see [the script systems section](../ScriptSystems/introduction.md)) And then sending script event's which trigger callbacks on the scripts. From bb38b5af333577bcc82efe82a1b2abad56cb57ae Mon Sep 17 00:00:00 2001 From: makspll Date: Fri, 28 Feb 2025 21:09:36 +0000 Subject: [PATCH 2/3] add summary entry --- docs/src/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 438602bbbc..b9426418b9 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -10,6 +10,7 @@ - [Modifying Script Contexts](./Summary/customizing-script-contexts.md) - [Shared Contexts](./Summary/sharing-contexts-between-scripts.md) - [Script ID Mapping](./Summary/script-id-mapping.md) +- [Script Systems](./ScriptSystems/introduction.md) # Scripting Reference From 363a5fb23fdd69f7381083ffcc490925d9cdad7f Mon Sep 17 00:00:00 2001 From: makspll Date: Fri, 28 Feb 2025 21:16:31 +0000 Subject: [PATCH 3/3] typo --- docs/src/ScriptSystems/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/ScriptSystems/introduction.md b/docs/src/ScriptSystems/introduction.md index 57f8a21c68..b5d12b4cf6 100644 --- a/docs/src/ScriptSystems/introduction.md +++ b/docs/src/ScriptSystems/introduction.md @@ -23,7 +23,7 @@ local system_with_name = update:get_system_by_name("my_system") ## Inserting Systems -To insert a system wou will need to use the `system_builder` global function like below: +To insert a system you will need to use the `system_builder` global function like below: ```lua local system = system_builder("my_system", script_id)