improve docs, fix issues

Author: makspll

crates/ladfile_builder/src/lib.rs

@@ -21,6 +21,14 @@ use bevy_mod_scripting_core::{
 };
 use bevy_reflect::{NamedField, TypeInfo, TypeRegistry, Typed, UnnamedField};
 use ladfile::*;
+use std::{
+    any::TypeId,
+    borrow::Cow,
+    cmp::{max, min},
+    collections::HashMap,
+    ffi::OsString,
+    path::PathBuf,
+};
 
 /// We can assume that the types here will be either primitives
 /// or reflect types, as the rest will be covered by typed wrappers
@@ -843,6 +851,8 @@ impl<'t> LadFileBuilder<'t> {
 
 #[cfg(test)]
 mod test {
+    use std::collections::HashMap;
+
     use bevy_mod_scripting_core::{
         bindings::{
             function::{

docs/src/Migration/guides.md

@@ -188,4 +188,34 @@ pub struct ScriptCallbackEvent {
     /// Whether the callback should emit a response event
     pub trigger_response: bool,
 }
+```
+
+## Bindings Changes
+
+### ScriptId
+`script_id` is replaced with `script_asset` which now has a type of `Handle<ScriptAsset>`. This means that you can no longer use a string to refer to a script, but rather you must use a handle.
+
+Scripts can still access the asset path of the script using:
+```lua,ignore
+-- prints: "my_script.lua"
+print(script_asset:asset_path())
+```
+
+### ScriptAttachment
+The concept of script attachments has been introduced to describe the idea of a script instance. Previously this was muddied due to the fact script ID's were the primary way to refer to scripts. Now the instance of a script and its mapping to a context is clearer.
+
+This is reflected in a brand new set of bindings:
+
+```lua,ignore
+-- will create backing ScriptAttachment instances, that can be used in other bindings.
+local entity_script = ScriptAttachment.new_entity_script(entity, script_asset)
+local static_script = ScriptAttachment.new_static_script(script_asset)
+```
+
+### System Builder
+the system builder no longer accepts script id's as parameters. Instead it accepts script attachments
+
+```diff,lua
+-system_builder("my_callback", "this_script_id.lua")
++system_builder("my_callback", ScriptAttachment.new_static_script(script_asset))
 ```

docs/src/Migration/0.13-to-0.14.md renamed to docs/src/ReleaseNotes/0.13-to-0.14.md

@@ -0,0 +1,36 @@
+# 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.
+
+### Flexible Context Policies
+You now have much finer control over how script contexts (i.e., the environment a script runs in) are created. The old `enable_context_sharing()` has been replaced with `set_context_policy()` which accepts a `ContextPolicy`:
+
+-   `ContextPolicy::shared()`: All scripts run in one global context
+-   `ContextPolicy::per_script()`: Each script asset gets its own context (the old default.)
+-   `ContextPolicy::per_entity()`: Each entity with scripts gets its own context.
+-   `ContextPolicy::per_entity_and_script()`: A unique context for every script on every entity (the new default).
+
+This means that each script is maximally isolated by default, but you can still opt for shared contexts if needed.
+
+
+### 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)

docs/src/Migration/0.14-to-0.15.md renamed to docs/src/ReleaseNotes/0.14-to-0.15.md

@@ -0,0 +1,5 @@
+# Release Notes
+
+This section contains migration guides and release notes relevant to the `bevy_mod_scripting` crate.
+
+This used to live in the repository, so for older release notes or guides, refer to the [GitHub repository](https://github.com/makspll/bevy_mod_scripting/blob/main/release-notes/)

docs/src/ReleaseNotes/0.15.0.md

@@ -11,8 +11,12 @@
 - [Contexts](./Summary/contexts.md)
 - [Script Systems](./ScriptSystems/introduction.md)
 - [Examples](./Examples/introduction.md)
-- [Migration Guides](./Migration/guides.md)
-    - [0.14-to-0.15](./Migration/0.14-to-0.15.md)
+
+# Release Notes
+
+- [Release Notes](./ReleaseNotes/guides.md)
+    - [0.14-to-0.15](./ReleaseNotes/0.14-to-0.15.md)
+    - [0.15.0](./ReleaseNotes/0.15.0.md)
 
 # Scripting Reference