change handle to weak so unloading strong handle is enough to delete script, and update docs

Author: makspll

crates/bevy_mod_scripting_core/src/systems.rs

@@ -70,7 +70,7 @@ pub fn sync_script_data<C: Context, R: Runtime>(
             commands.queue(CreateOrUpdateScript::<C, R>::new(
                 script_id,
                 asset.content.clone(),
-                Some(script_assets.reserve_handle()),
+                Some(script_assets.reserve_handle().clone_weak()),
             ));
         } else {
             commands.queue(DeleteScript::<C, R>::new(script_id));

docs/src/SUMMARY.md

@@ -5,4 +5,5 @@
 # Quick Start
 
 - [Managing Scripts](./managing-scripts.md)
+- [Running Scripts](./running-scripts.md)
 - [Controlling Script Bindings](./controlling-script-bindings.md)

docs/src/managing-scripts.md

@@ -17,15 +17,11 @@ fn load_script(server: Res<AssetServer>, mut handle: Local<Handle<ScriptAsset>>)
 }
 ```
 
-In practice you will likely store this handle in a resource or component, when your load all the scripts necessary for your application. 
+In practice you will likely store this handle in a resource or component, when your load all the scripts necessary for your application.
 
+## Unloading 
+Scripts are automatically unloaded when the asset is dropped. This means that if you have a handle to a script and it goes out of scope, the script will be unloaded.
 
-## Deleting scripts
-In order to delete a previously loaded script, you will need to issue a `DeleteScript` command like so:
-
-```rust,ignore
-DeleteScript::new("my_script.lua".into())
-```
 
 This will delete references to the script and remove any internal handles to the asset. You will also need to clean up any handles to the asset you hold in your application in order for the asset to be unloaded.
 
@@ -41,5 +37,12 @@ In order to manually re-load or load a script you can issue the `CreateOrUpdateS
 CreateOrUpdateScript::new("my_script.lua".into(), "print(\"hello world from new script body\")".into(), asset_handle)
 ```
 
-## Loading timeframe
+## Manually Deleting scripts
+In order to delete a previously loaded script, you will need to issue a `DeleteScript` command like so:
+
+```rust,ignore
+DeleteScript::new("my_script.lua".into())
+```
+
+## Loading/Unloading timeframe
 Scripts are processed via commands, so any asset events will be processed at the next command execution point running after BMS internal asset systems.

docs/src/running-scripts.md

@@ -0,0 +1,47 @@
+# Attaching Scripts
+
+Once you have scripts discovered and loaded, you'll want to run them. At the moment BMS supports one method of triggering scripts, and that is by attaching them to entities via `ScriptComponent`'s and then sending script event's which trigger callbacks on the scripts.
+
+In order to attach a script and make it runnable simply add a `ScriptComponent` to an entity
+```rust,ignore
+    commands.entity(my_entity).insert(ScriptComponent::new(vec!["my_script.lua", "my_other_script.lua"]));
+```
+
+# Running Scripts
+
+Scripts can run logic either when loaded or when triggered by an event. For example the script:
+
+```lua
+print("hello from load time")
+function on_event()
+    print("hello from event time")
+end
+```
+
+Will print "hello from load time" when the script is loaded, and "hello from event time" when the script receives an event targeting the `on_event` callback with a receiver list including this script or entity.
+
+In order to trigger `on_event` you need to first define a label, then send an event containing the label:
+```rust,ignore
+// define the label
+struct OnEventCallback;
+impl IntoCallbackLabel for OnEventCallback {
+    fn into_callback_label() -> CallbackLabel {
+        "on_event".into()
+    }
+}
+
+// trigger the event
+fn send_event(mut writer: EventWriter<ScriptCallbackEvent<()>>) {
+    writer.send(ScriptCallbackEvent::new_for_all(
+        OnEventCallback::into_callback_label(),
+        (),
+    ));
+}
+```
+
+Note the `()` corresponds to the payload for the event, i.e. in this case we are not sending any arguments.
+
+TODO: this should be replaced with `ScriptValue` before release  
+```
+assert!(false, "TODO: replace with ScriptValue");
+```