refactor: extract bevy_mod_scripting_asset and bevy_mod_scripting_display crates, decouple concerns (#477)

Author: makspll

.github/instructions/documentation.instructions.md

@@ -0,0 +1,95 @@
+---
+applyTo: docs/, **/*.md
+---
+
+# Documentation Instructions
+
+The `/docs` folder contain documentation for the project as well as release notes.
+
+Newer release notes should be added to `/docs/src/ReleaseNotes/`.
+
+When making changes to the documentation, please ensure that you follow these guidelines:
+- Use clear and concise language, focusing on EXAMPLES and practical usage.
+- Use these naming conventions:
+  - Use lowercase letters and hyphens for file names (e.g., `my-documentation-file.md`).
+  - for migration guides use the format `0.0.1-to-0.0.2.md`.
+  - for release notes use the format `0.0.1.md`.
+
+
+# Release Notes Instructions
+
+Release notes should highlight the major highlights of each release, while leaving the breaking changes for migration guides.
+
+When creating release notes, please follow these guidelines:
+- Include links to relevant issues or pull requests when applicable.
+- YOU MUST use the following heading structure:
+  - `# Version - Short Description`
+  - `## Summary`
+  - `### <Theme>` for each major theme or change
+  - `### Other Changes` (if applicable) for smaller changes worth mentioning
+  - `## Migration Guide` (if applicable) providing a link to the detailed migration guide.
+
+
+# Migration Guide Instructions
+
+When creating migration guides, please follow these guidelines:
+- Provide step-by-step instructions for updating projects to the new version.
+- Each breaking change should come under a heading related to the change i.e. `### ScriptAsset removed`
+- Include code snippets to illustrate changes.
+- Use diff format when talking about concrete changes to specific structures or traits.
+- Include links to relevant issues or pull requests when applicable.
+- Generally each pull request has a migration guide section, which must be taken into account and expanded on when writing relevant migration guides.
+
+
+# Examples
+
+## Release Notes Example
+
+```markdown
+# 0.15.0 - Asset Handles and Context Policies
+
+This release focuses on aligning `bevy_mod_scripting` with modern Bevy practices, most notably by switching to `Handle<ScriptAsset>` for script management. This change simplifies the API, removes boilerplate, and makes script handling more idiomatic.
+
+## Summary
+
+### Asset-First Workflow
+Scripts are now treated as first-class Bevy assets. The old `ScriptId` (which was a string) has been replaced by `AssetId<ScriptAsset>`, and you'll primarily interact with scripts via `Handle<ScriptAsset>`.
+
+```rust,ignore
+// New way
+let handle: Handle<ScriptAsset> = asset_server.load("my_script.lua");
+commands.spawn(ScriptComponent(vec![handle]));
+```
+
+Scripts are now only evaluated when they are attached to a `ScriptComponent` or added to `StaticScripts`, which means you have more control over when and how scripts are executed.
+
+### Other Changes
+-   **`Recipients` Enum:** The `Recipients` enum for events has been redesigned to align with the new context policies, offering `AllScripts` and `AllContexts` variants, and removing some variants which don't fit the new model. If you need the old behaviour, you can simply query the ECS first before sending events.
+-   **API Cleanup:** Several types and traits were removed or simplified, including `ScriptAssetSettings`, `AssetPathToScriptIdMapper`, and `ScriptMetadataStore`, as they are no longer needed with the new asset-based approach.
+
+## Migration Guide
+This release contains significant breaking changes. Please refer to the migration guide for detailed instructions on updating your project.
+
+- [Migration Guide: 0.14 to 0.15](https://makspll.github.io/bevy_mod_scripting/Migration/0.14-to-0.15.html)
+
+```
+
+## Migration Guide Example
+
+```markdown
+# Migration Guide: <from> to <to>
+
+## Changes to pre handling callbacks
+
+This change affects the parameters for the `context_pre_handling_initializers`
+```diff
+- context_pre_handling_initializers: vec![|script_id, entity, context| {
++ context_pre_handling_initializers: vec![|context_key, context| {
+```
+and `context_initializers`:
+```diff
+- context_initializers: vec![|script_id, context| {
++ context_initializers: vec![|context_key, context| {
+```
+
+```

.github/instructions/general.instructions.md

@@ -0,0 +1,40 @@
+---
+applyTo: **
+---
+
+# Repository Instructions
+
+## High-Level Structure
+
+### Core Components
+- **bevy_mod_scripting** - Main workspace crate that re-exports key functionality.
+- **bevy_mod_scripting_core** - Core framework with language-agnostic scripting functionality
+- **bevy_mod_scripting_asset** - Handles script assets, loading, and language detection
+- **bevy_mod_scripting_derive** - Procedural macros for generating bindings
+- **bevy_mod_scripting_functions** - Core Bevy function bindings, and plugin managing various binding crates via features.
+
+### Language Implementations
+- **bevy_mod_scripting_lua** - Lua language implementation
+- **bevy_mod_scripting_rhai** - Rhai language implementation
+
+### Binding Crates
+- Multiple **bevy_*_bms_bindings** crates (e.g., transform, asset, pbr, etc.) that provide specific Bevy module bindings
+- These are automatically generated via the `/codegen` tools, per bevy release
+
+### Development Tools
+- **xtask** - Custom task runner for development workflows
+- **codegen** - Code generation tools for generating bindings from Bevy's API
+- **docs** - Documentation built with mdbook
+- **docs/src/ReleaseNotes** - Release notes and migration guides
+
+## Key Features
+
+1. **Script Management** - Loading, hot reloading, and lifecycle management via Bevy's asset system
+2. **Flexible Bindings** - Attach bindings to any Reflect-implementing types
+3. **Dynamic Systems** - Create ECS systems from scripts that run in parallel
+4. **Component Creation** - Register and use components from scripts
+5. **Multiple Language Support** - Currently supports Lua and Rhai
+
+
+## Xtask Commands
+- `cargo xtask check` - Builds the project and runs clippy

assets/lua_to_rhai_test_conversion_prompt.md renamed to .github/instructions/rhai.instructions.md

@@ -1,5 +1,6 @@
-// perfect application of AI
-// helps proompting LLMs to do good for this project
+---
+applyTo: **/.rhai
+---
 
 # Convert lua to rhai script
 Convert the current test to a rhai test. below are examples and instructions on the conversions necessary:

Cargo.toml

@@ -99,6 +99,8 @@ bevy_mod_scripting_rhai = { workspace = true, optional = true }
 bevy_mod_scripting_functions = { workspace = true }
 bevy_mod_scripting_derive = { workspace = true }
 bevy_mod_scripting_asset = { workspace = true }
+bevy_mod_scripting_bindings = { workspace = true }
+bevy_mod_scripting_display = { workspace = true }
 
 [workspace.dependencies]
 # local crates
@@ -112,7 +114,8 @@ ladfile_builder = { path = "crates/ladfile_builder", version = "0.5.1" }
 bevy_mod_scripting_lua = { path = "crates/languages/bevy_mod_scripting_lua", version = "0.15.1", default-features = false }
 bevy_mod_scripting_rhai = { path = "crates/languages/bevy_mod_scripting_rhai", version = "0.15.1", default-features = false }
 bevy_mod_scripting_asset = { path = "crates/bevy_mod_scripting_asset", version = "0.15.1", default-features = false }
-
+bevy_mod_scripting_bindings = { path = "crates/bevy_mod_scripting_bindings", version = "0.15.1", default-features = false }
+bevy_mod_scripting_display = { path = "crates/bevy_mod_scripting_display", version = "0.15.1", default-features = false }
 # bevy
 
 bevy_mod_scripting_core = { path = "crates/bevy_mod_scripting_core", version = "0.15.1" }
@@ -190,7 +193,7 @@ itertools = { version = "0.14", default-features = false }
 fixedbitset = { version = "0.5", default-features = false }
 variadics_please = { version = "1.1.0", default-features = false }
 anyhow = { version = "1.0", default-features = false }
-
+indent_write = { version = "2", default-features = false, features = ["std"] }
 
 # development and testing
 
@@ -245,6 +248,8 @@ members = [
     "crates/bevy_system_reflection",
     "crates/bindings/*",
     "crates/bevy_mod_scripting_asset",
+    "crates/bevy_mod_scripting_bindings",
+    "crates/bevy_mod_scripting_display",
 ]
 resolver = "2"
 exclude = ["codegen", "crates/macro_tests", "xtask"]

assets/tests/add_system/added_systems_run_in_parallel.lua

@@ -26,7 +26,7 @@ digraph {
   node_1 [label="bevy_asset::assets::Assets<bevy_asset::assets::LoadedUntypedAsset>::asset_events"];
   node_2 [label="bevy_asset::assets::Assets<()>::asset_events"];
   node_3 [label="bevy_asset::assets::Assets<bevy_mod_scripting_asset::script_asset::ScriptAsset>::asset_events"];
-  node_4 [label="bevy_mod_scripting_core::bindings::allocator::garbage_collector"];
+  node_4 [label="bevy_mod_scripting_bindings::allocator::garbage_collector"];
   node_5 [label="script_integration_test_harness::dummy_before_post_update_system"];
   node_6 [label="script_integration_test_harness::dummy_post_update_system"];
   node_7 [label="on_test_post_update"];

assets/tests/add_system/added_systems_run_in_parallel.rhai

@@ -25,7 +25,7 @@ digraph {
   node_1 [label="bevy_asset::assets::Assets<bevy_asset::assets::LoadedUntypedAsset>::asset_events"];
   node_2 [label="bevy_asset::assets::Assets<()>::asset_events"];
   node_3 [label="bevy_asset::assets::Assets<bevy_mod_scripting_asset::script_asset::ScriptAsset>::asset_events"];
-  node_4 [label="bevy_mod_scripting_core::bindings::allocator::garbage_collector"];
+  node_4 [label="bevy_mod_scripting_bindings::allocator::garbage_collector"];
   node_5 [label="script_integration_test_harness::dummy_before_post_update_system"];
   node_6 [label="script_integration_test_harness::dummy_post_update_system"];
   node_7 [label="on_test_post_update"];

assets/tests/construct/construct_tuple_struct.lua

@@ -3,6 +3,5 @@ local constructed = construct(type, {
     _1 = 123
 })
 
-print(constructed:display_value())
-
-assert(constructed._1 == 123, "Value was constructed incorrectly, expected constructed.foo to be 123 but got " .. constructed._1)
+assert(constructed._1 == 123,
+    "Value was constructed incorrectly, expected constructed.foo to be 123 but got " .. constructed._1)

assets/tests/display/print_value_by_default.lua

@@ -0,0 +1,71 @@
+local vec = Vec3.new(1, 2, 3)
+
+assert(vec:display() == "Vec3 { x: 1.0, y: 2.0, z: 3.0 }",
+    "Vec3 display incorrect, expected Vec3 { x: 1.0, y: 2.0, z: 3.0 } but got " .. vec:display())
+
+
+-- multiline
+local function strip_alloc_ids(s)
+    s = s:gsub("ReflectAllocationId%b()", "ReflectAllocationId()")
+    return s
+end
+
+local expected_vec3_debug = [[
+ ReflectReference {
+    base: ReflectBaseType {
+        type_id: TypeId(
+            "glam::Vec3",
+        ),
+        base_id: Owned(
+            ReflectAllocationId(*anything*),
+        ),
+    },
+    reflect_path: ParsedPath(
+        [],
+    ),
+}
+]]
+-- normalize allocation ids before comparison so tests don't fail on runtime-generated ids
+do
+    local actual = vec:debug()
+    local expected = expected_vec3_debug
+    actual = strip_alloc_ids(actual)
+    expected = strip_alloc_ids(expected)
+    assert_str_eq(actual, expected)
+end
+
+
+local test_resource = world.get_resource(types.TestResource)
+
+local expected_test_resource_debug = [[
+ReflectReference {
+    base: ReflectBaseType {
+        type_id: TypeId(
+            "test_utils::test_data::TestResource",
+        ),
+        base_id: Resource(
+            ComponentId(
+                "test_utils::test_data::TestResource",
+            ),
+        ),
+    },
+    reflect_path: ParsedPath(
+        [],
+    ),
+}
+]]
+
+-- normalize allocation ids before comparison so tests don't fail on runtime-generated ids
+do
+    local actual = test_resource:debug()
+    local expected = expected_test_resource_debug
+    actual = strip_alloc_ids(actual)
+    expected = strip_alloc_ids(expected)
+    assert_str_eq(actual, expected,
+        "TestResource debug incorrect, expected " .. expected .. " but got " .. actual)
+end
+
+
+assert_str_eq(test_resource:display(), "TestResource { bytes: [0, 1, 2, 3, 4, 5] }",
+    "TestResource display incorrect, expected TestResource { bytes: [0, 1, 2, 3, 4, 5] } but got " ..
+    test_resource:display())

assets/tests/functions/contains_reflect_reference_functions.lua

@@ -19,4 +19,5 @@ for _, function_ref in pairs(functions) do
     table.insert(available_names, function_ref.name)
 end
 
-assert(contains(available_names, "display_ref"), "functions should contain display_ref, but got: " .. table.concat(available_names, ", "))
+assert(contains(available_names, "display"),
+    "functions should contain display, but got: " .. table.concat(available_names, ", "))

assets/tests/functions/contains_reflect_reference_functions.rhai

@@ -11,4 +11,4 @@ for function_ref in functions {
     available_names.push(function_ref.name);
 }
 
-assert("display_ref" in available_names, "functions should contain display_ref, but got: " + available_names);
+assert("display" in available_names, "functions should contain display, but got: " + available_names);