feat: ✨ Parallelizable Script Systems with Res and Query parameters & Schedule debugging utilities (#361)

# Summary
Major step towards #244 

- Adds a `bevy_system_reflection` crate to organize all the things that
would be nice to upstream to bevy eventually and aren't really core
logic
- Moves `ReflectSchedule` etc into that crate
- Adds a few more things to the reflected sets, schedules and systems
- Adds `DynamicSystemParam` enum which we use to store config for script
systems
- Adds `ScriptSystem` which can be converted into a system using the
`IntoSystem` trait via `ScriptSystemBuilder`
- The custom script system allows us to use default_system_sets
predictably for script systems, which previously all lived under the
same `SystemTypeSet` which didn't let us do ordering between them
- Adds utilities for script writers for printing dot graphs of system
schedules
- Splits `WorldGuard::new`  into `new_exclusive` and `new_non_exclusive`

# Example
this allows you to parameterize systems like:
```lua
    world.add_system(
        post_update_schedule,
        system_builder("my_parameterised_system", script_id)
            :resource(ResourceTypeA)
            :query(world.query():component(ComponentA):component(ComponentB))
            :resource(ResourceTypeB)
    )
```

and then have the callback run with those parameters passed in:
```lua
function my_parameterised_system(resourceA,query,resourceB)
    print("my_parameterised_system")
    runs[#runs + 1] = "my_non_exclusive_system"

    assert(resourceA ~= nil, "Expected to get resource but got nil")
    assert(query ~= nil, "Expected to get query but got nil")
    assert(resourceB ~= nil, "Expected to get resource but got nil")

    assert(#resourceA.bytes == 6, "Expected 6 bytes, got: " .. #resourceA.bytes)
    assert(resourceB.string == "Initial Value", "Expected 'Initial Value', got: " .. resourceB.string)
    assert(#query == 2, "Expected 3 results, got: " .. #query)
    for i,result in pairs(query) do
        components = result:components()
        assert(#components == 2, "Expected 2 components, got " .. #components)
        local componentA = components[1]
        local componentB = components[2]
        assert(componentA._1 == "Default", "Expected 'Default', got: " .. componentA._1)
        assert(componentB._1 == "Default", "Expected 'Default', got: " .. componentA._1)
    end
end
```

The system will setup a specially sandboxed world guard for the system
which only allows access to those set components and resources, this
combined with the archetype component access setup in the new system
type, allows us to parallelize against any other bevy system where there
are no overlaps in access!.

One can also create exclusive systems via `:exclusive` allowing a normal
uninhibiting world guard

Tests
    - [x] ordering between script systems
    - [x] exclusive & non exclusive systems 
    - [x] check these run in parallel as expected
    - [x] test scripts can only access resources and queries as expected

Author: makspll

Cargo.toml

@@ -93,6 +93,7 @@ members = [
     "crates/ladfile",
     "crates/lad_backends/mdbook_lad_preprocessor",
     "crates/ladfile_builder",
+    "crates/bevy_system_reflection",
 ]
 resolver = "2"
 exclude = ["crates/bevy_api_gen", "crates/macro_tests"]

assets/lua_to_rhai_test_conversion_prompt.md

@@ -0,0 +1,240 @@
+// perfect application of AI
+// helps proompting LLMs to do good for this project
+
+# Convert lua to rhai script
+Convert the current test to a rhai test. below are examples and instructions on the conversions necessary:
+
+## Dynamic function calls
+Functions which are not native to rhai MUST be explicitly called using the below syntax:
+
+```rhai
+type.function.call(arguments...)
+```
+
+native rhai functions MUST NOT be converted using the syntax above.
+
+Below is a list of some of the native functions their argument names and some constants available in rhai:
+
+```csv
+function,arguments
+is_odd,
+is_even,
+min,"a, b"
+max,"a, b"
+to_float,
+to_decimal,
+abs,value
+sign,value
+is_zero,
+sin,angle
+cos,angle
+tan,angle
+sinh,angle
+cosh,angle
+tanh,angle
+hypot,"x, y"
+asin,value
+acos,value
+atan,value
+atan,"x, y"
+asinh,value
+acosh,value
+atanh,value
+sqrt,value
+exp,value
+ln,value
+log,value
+floor,
+ceiling,
+round,
+round,decimal_points
+int,
+fraction,
+round_up,decimal_points
+round_down,decimal_points
+round_half_up,decimal_points
+round_half_down,decimal_points
+to_int,
+to_decimal,
+to_float,
+to_degrees,
+to_radians,
+is_nan,
+is_finite,
+is_infinite,
+parse_int,"string, [radix]"
+parse_float,string
+parse_decimal,string
+to_binary,value
+to_octal,value
+to_hex,value
+PI,
+E,
+```
+
+## Operators
+Operators are different in lua and rhai, below is a list of operators supported:
+
+```
+Operators	Assignment operators	Supported types
+(see standard types)
++,	+=	
+
+    INT
+    FLOAT (if not no_float)
+    Decimal (requires decimal)
+    char
+    string
+
+-, *, /, %, **,	-=, *=, /=, %=, **=	
+
+    INT
+    FLOAT (if not no_float)
+    Decimal (requires decimal)
+
+<<, >>	<<=, >>=	
+
+    INT
+
+&, |, ^	&=, |=, ^=	
+
+    INT (bit-wise)
+    bool (non-short-circuiting)
+
+&&, ||		
+
+    bool (short-circuits)
+
+==, !=		
+
+    INT
+    FLOAT (if not no_float)
+    Decimal (requires decimal)
+    bool
+    char
+    string
+    BLOB
+    numeric range
+    ()
+
+>, >=, <, <=		
+
+    INT
+    FLOAT (if not no_float)
+    Decimal (requires decimal)
+    char
+    string
+    ()
+```
+
+## Function syntax
+Functions in rhai look like this:
+
+```rhai
+fn function_name(arg1, arg2) {
+    return value;
+}
+```
+
+## Semicolons
+Every statement must end in a semicolon
+
+
+Below is a new section on Rhai strings that you can add to the prompt:
+
+## Rhai Strings
+
+Rhai supports different string types such as raw strings (enclosed by matching `#` and double-quotes), multi-line literal strings (enclosed by backticks to preserve exact formatting), and strings with interpolation (using `${…}` inside multi-line literals). These variants allow you to easily include complex content like newlines, quotes, and even embedded expressions while keeping the original formatting. Here are three examples:
+
+````rhai
+// Raw string example:
+let raw_str = #"Hello, raw string! \n No escape sequences here."#;
+````
+
+````rhai
+// Multi-line literal string example:
+let multi_line = `
+This is a multi-line literal string,
+which preserves whitespaces, newlines, and "quotes" exactly.
+`;
+````
+
+````rhai
+// String interpolation example:
+let value = 42;
+let interpolated = `The answer is ${value}, which is computed dynamically.`;
+````
+
+## Null Checks
+null checks can be performed by checking `type_of(value) == "()"`
+
+## Examples
+Below is an example lua test and its equivalent rhai script:
+
+### Lua
+```lua
+local entity_a = world.spawn()
+local entity_b = world.spawn()
+local entity_c = world.spawn()
+local entity_d = world._get_entity_with_test_component("CompWithFromWorldAndComponentData")
+
+local component_with = world.get_type_by_name("CompWithFromWorldAndComponentData")
+local component_without = world.get_type_by_name("CompWithDefaultAndComponentData")
+
+world.add_default_component(entity_a, component_with)
+world.add_default_component(entity_b, component_with)
+world.add_default_component(entity_c, component_with)
+
+world.add_default_component(entity_b, component_without)
+
+local found_entities = {}
+for i,result in pairs(world.query():component(component_with):without(component_without):build()) do
+    table.insert(found_entities, result:entity())
+end
+
+assert(#found_entities == 3, "Expected 3 entities, got " .. #found_entities)
+
+expected_entities = {
+    entity_c,
+    entity_d,
+    entity_a,
+}
+
+for i, entity in ipairs(found_entities) do
+    assert(entity:index() == expected_entities[i]:index(), "Expected entity " .. expected_entities[i]:index() .. " but got " .. entity:index())
+end
+```
+
+### Rhai
+```rhai
+let entity_a = world.spawn_.call();
+let entity_b = world.spawn_.call();
+let entity_c = world.spawn_.call();
+let entity_d = world._get_entity_with_test_component.call("CompWithFromWorldAndComponentData");
+
+let component_with = world.get_type_by_name.call("CompWithFromWorldAndComponentData");
+let component_without = world.get_type_by_name.call("CompWithDefaultAndComponentData");
+
+world.add_default_component.call(entity_a, component_with);
+world.add_default_component.call(entity_b, component_with);
+world.add_default_component.call(entity_c, component_with);
+
+world.add_default_component.call(entity_b, component_without);
+
+let found_entities = [];
+for (result, i) in world.query.call().component.call(component_with).without.call(component_without).build.call() {
+    found_entities.push(result.entity.call());
+}
+
+assert(found_entities.len == 3, "Expected 3 entities, got " + found_entities.len);
+
+let expected_entities = [
+    entity_d,
+    entity_a,
+    entity_c,
+];
+
+for (entity, i) in found_entities {
+    assert(entity.index.call() == expected_entities[i].index.call(), "Expected entity " + expected_entities[i].index.call() + " but got " + entity.index.call());
+}
+```

assets/tests/add_system/added_systems_run_in_parallel.lua

@@ -0,0 +1,43 @@
+
+function on_test()
+    local post_update_schedule = world.get_schedule_by_name("PostUpdate")
+    
+    local test_system = post_update_schedule:get_system_by_name("on_test_post_update")
+    
+    local system_a = world.add_system(
+        post_update_schedule,
+        system_builder("custom_system_a", script_id)
+            :after(test_system)
+    )
+        
+    local system_b = world.add_system(
+        post_update_schedule,
+        system_builder("custom_system_b", script_id)
+            :after(test_system)
+    )    
+
+    -- generate a schedule graph and verify it's what we expect
+    local dot_graph = post_update_schedule:render_dot()
+
+    local expected_dot_graph = [[
+digraph {
+  node_0 [label="bevy_mod_scripting_core::bindings::allocator::garbage_collector"];
+  node_1 [label="on_test_post_update"];
+  node_2 [label="script_integration_test_harness::dummy_before_post_update_system"];
+  node_3 [label="script_integration_test_harness::dummy_post_update_system"];
+  node_4 [label="custom_system_a"];
+  node_5 [label="custom_system_b"];
+  node_6 [label="SystemSet GarbageCollection"];
+  node_7 [label="SystemSet ScriptSystem(custom_system_a)"];
+  node_8 [label="SystemSet ScriptSystem(custom_system_b)"];
+  node_0 -> node_6 [color=red, label="child of", arrowhead=diamond];
+  node_4 -> node_7 [color=red, label="child of", arrowhead=diamond];
+  node_5 -> node_8 [color=red, label="child of", arrowhead=diamond];
+  node_1 -> node_4 [color=blue, label="runs before", arrowhead=normal];
+  node_1 -> node_5 [color=blue, label="runs before", arrowhead=normal];
+  node_2 -> node_3 [color=blue, label="runs before", arrowhead=normal];
+}
+    ]]
+
+    assert_str_eq(dot_graph, expected_dot_graph, "Expected the schedule graph to match the expected graph")
+end

assets/tests/add_system/added_systems_run_in_parallel.rhai

@@ -0,0 +1,41 @@
+fn on_test() {
+    let post_update_schedule = world.get_schedule_by_name.call("PostUpdate");
+    
+    let test_system = post_update_schedule.get_system_by_name.call("on_test_post_update");
+    
+    let system_a = world.add_system.call(
+        post_update_schedule,
+        system_builder.call("custom_system_a", script_id)
+            .after.call(test_system)
+    );
+        
+    let system_b = world.add_system.call(
+        post_update_schedule,
+        system_builder.call("custom_system_b", script_id)
+            .after.call(test_system)
+    );
+        
+    // generate a schedule graph and verify it's what we expect
+    let dot_graph = post_update_schedule.render_dot.call();
+    
+    let expected_dot_graph = `
+digraph {
+  node_0 [label="bevy_mod_scripting_core::bindings::allocator::garbage_collector"];
+  node_1 [label="on_test_post_update"];
+  node_2 [label="script_integration_test_harness::dummy_before_post_update_system"];
+  node_3 [label="script_integration_test_harness::dummy_post_update_system"];
+  node_4 [label="custom_system_a"];
+  node_5 [label="custom_system_b"];
+  node_6 [label="SystemSet GarbageCollection"];
+  node_7 [label="SystemSet ScriptSystem(custom_system_a)"];
+  node_8 [label="SystemSet ScriptSystem(custom_system_b)"];
+  node_0 -> node_6 [color=red, label="child of", arrowhead=diamond];
+  node_4 -> node_7 [color=red, label="child of", arrowhead=diamond];
+  node_5 -> node_8 [color=red, label="child of", arrowhead=diamond];
+  node_1 -> node_4 [color=blue, label="runs before", arrowhead=normal];
+  node_1 -> node_5 [color=blue, label="runs before", arrowhead=normal];
+  node_2 -> node_3 [color=blue, label="runs before", arrowhead=normal];
+}`; 
+    
+    assert_str_eq.call(dot_graph, expected_dot_graph, "Expected the schedule graph to match the expected graph");
+}

assets/tests/add_system/adds_system_in_correct_order.lua

@@ -20,6 +20,13 @@ function on_test()
         system_builder("custom_system_before", script_id)
             :before(test_system)
     )    
+
+    local script_system_between = world.add_system(
+        post_update_schedule,
+        system_builder("custom_system_between", script_id)
+            :after(test_system)
+            :before(system_after)
+    )
 end
 
 
@@ -39,10 +46,16 @@ function custom_system_after()
     runs[#runs + 1] = "custom_system_after"
 end
 
+function custom_system_between()
+    print("custom_system_between")
+    runs[#runs + 1] = "custom_system_between"
+end
+
 -- runs in the `Last` bevy schedule
 function on_test_last()
-    assert(#runs == 3, "Expected 3 runs, got: " .. #runs)
+    assert(#runs == 4, "Expected 4 runs, got: " .. #runs)
     assert(runs[1] == "custom_system_before", "Expected custom_system_before to run first, got: " .. runs[1])
     assert(runs[2] == "on_test_post_update", "Expected on_test_post_update to run second, got: " .. runs[2])
-    assert(runs[3] == "custom_system_after", "Expected custom_system_after to run third, got: " .. runs[3])
+    assert(runs[3] == "custom_system_between", "Expected custom_system_between to run third, got: " .. runs[3])
+    assert(runs[4] == "custom_system_after", "Expected custom_system_after to run second, got: " .. runs[4])
 end