refactor: extract bevy_mod_scripting_bindings and bevy_mod_scripting_display crates, decouple concerns

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

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/remove_resource/no_resource_data_errors.lua

@@ -1,6 +1,5 @@
-
 local type = world._get_mock_resource_type()
 
-assert_throws(function ()
+assert_throws(function()
     world.remove_resource(type)
-end, "Missing type data ReflectResource for type: Unregistered.TypeId.*")
+end, "Missing type data ReflectResource for type: Unregistered Type.*")

assets/tests/remove_resource/no_resource_data_errors.rhai

@@ -3,4 +3,4 @@ let type = world._get_mock_resource_type.call();
 
 assert_throws(||{
     world.remove_resource.call(type)
-}, "Missing type data ReflectResource for type: Unregistered.TypeId.*");
+}, "Missing type data ReflectResource for type: Unregistered Type.*");

codegen/Cargo.bootstrap.toml

@@ -5,7 +5,7 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
-bevy_mod_scripting_core = { path = "{{BMS_CORE_PATH}}" }
+bevy_mod_scripting_bindings = { path = "{{BMS_BINDINGS_PATH}}" }
 bevy_reflect = { version = "0.16.0", features = [
     "smol_str",
     "glam",

codegen/src/args.rs

@@ -60,9 +60,9 @@ pub struct Args {
     #[arg(global = true, long)]
     pub template_args: Option<String>,
 
-    /// The path to the bevy_mod_scripting_core crate, used to bootstrap necessary traits
+    /// The path to the bevy_mod_scripting_bindings crate, used to bootstrap necessary traits
     #[arg(global = true, long, default_value = ".")]
-    pub bms_core_path: Utf8PathBuf,
+    pub bms_bindings_path: Utf8PathBuf,
 
     /// Crates to exclude from code generation
     #[arg(

codegen/src/bin/main.rs

@@ -16,7 +16,7 @@ use log::{debug, error, info};
 use strum::VariantNames;
 use tera::Context;
 
-const BOOTSTRAP_DEPS: [&str; 2] = ["bevy_reflect", "bevy_mod_scripting_core"];
+const BOOTSTRAP_DEPS: [&str; 2] = ["bevy_reflect", "bevy_mod_scripting_bindings"];
 
 fn main() {
     // parse this here to early exit on wrong args
@@ -176,7 +176,7 @@ fn main() {
 
     debug!("Bootstrap directory: {}", &temp_dir.as_path().display());
 
-    write_bootstrap_files(args.bms_core_path, temp_dir.as_path());
+    write_bootstrap_files(args.bms_bindings_path, temp_dir.as_path());
 
     let bootstrap_rlibs = build_bootstrap(temp_dir.as_path(), &plugin_target_dir.join("bootstrap"));
 
@@ -200,7 +200,7 @@ fn main() {
             )
         };
     } else {
-        panic!("Could not find 'libmlua' artifact among bootstrap crate artifacts, stopping.");
+        panic!("Could not find all bootstrap rlibs, found: {bootstrap_rlibs:?}");
     }
 
     debug!("Running bevy_api_gen main cargo command");
@@ -355,15 +355,16 @@ fn find_bootstrap_dir() -> PathBuf {
 }
 
 /// Generate bootstrapping crate files
-fn write_bootstrap_files(bms_core_path: Utf8PathBuf, path: &Path) {
-    const BMS_CORE_PATH_PLACEHOLDER: &str = "{{BMS_CORE_PATH}}";
+fn write_bootstrap_files(bms_bindings_path: Utf8PathBuf, path: &Path) {
+    const BMS_BINDINGS_PATH_PLACEHOLDER: &str = "{{BMS_BINDINGS_PATH}}";
 
     // write manifest file 'Cargo.toml'
     let mut manifest_content =
         String::from_utf8(include_bytes!("../../Cargo.bootstrap.toml").to_vec())
             .expect("Could not read manifest template as utf8");
 
-    manifest_content = manifest_content.replace(BMS_CORE_PATH_PLACEHOLDER, bms_core_path.as_str());
+    manifest_content =
+        manifest_content.replace(BMS_BINDINGS_PATH_PLACEHOLDER, bms_bindings_path.as_str());
 
     let manifest_path = path.join("Cargo.toml");