add information on context sharing

Author: makspll

crates/bevy_mod_scripting_core/src/lib.rs

@@ -143,6 +143,12 @@ pub trait ConfigureScriptPlugin {
         initializer: ContextPreHandlingInitializer<Self::P>,
     ) -> Self;
     fn add_runtime_initializer(self, initializer: RuntimeInitializer<Self::P>) -> Self;
+
+    /// Switch the context assigning strategy to a global context assigner.
+    ///
+    /// This means that all scripts will share the same context. This is useful for when you want to share data between scripts easilly.
+    /// Be careful however as this also means that scripts can interfere with each other in unexpected ways!.
+    fn enable_context_sharing(self);
 }
 
 impl<P: IntoScriptPluginParams + AsMut<ScriptingPlugin<P>>> ConfigureScriptPlugin for P {
@@ -166,6 +172,10 @@ impl<P: IntoScriptPluginParams + AsMut<ScriptingPlugin<P>>> ConfigureScriptPlugi
         self.as_mut().add_runtime_initializer(initializer);
         self
     }
+
+    fn enable_context_sharing(mut self) {
+        self.as_mut().context_assigner = ContextAssigner::new_global_context_assigner();
+    }
 }
 
 // One of registration of things that need to be done only once per app

docs/src/SUMMARY.md

@@ -8,6 +8,7 @@
 - [Running Scripts](./Summary/running-scripts.md)
 - [Controlling Script Bindings](./Summary/controlling-script-bindings.md)
 - [Modifying Script Contexts](./Summary/customizing-script-contexts.md)
+- [Shared Contexts](./Summary/sharing-contexts-between-scripts.md)
 
 # Scripting Reference
 

docs/src/Summary/sharing-contexts-between-scripts.md

@@ -0,0 +1,24 @@
+# Shared Contexts
+
+By default BMS will create an individual script context, or sandbox, for each script that is run. This means that each script will have its own set of global variables and functions that are isolated from other scripts. However, sometimes this might not be desirable, if you aren't worried about scripts interfering with each other, or if you want to easilly share data between scripts. In these cases, you can use shared contexts.
+
+## Enabling Shared Contexts
+
+You can enable shared contexts by configuring the relevant scripting plugin like so:
+```rust,ignore
+let mut plugin = LuaScriptingPlugin::default().enable_context_sharing();
+
+app.add_plugins(plugin);
+```
+
+## Context Loading Settings
+
+All context loading settings are stored in a separate resource per scripting plugin namely: `ContextLoadingSettings<Plugin>`. 
+
+The settings are as follows:
+- `loader` - the load and unload strategy for contexts. Each scripting plugin will have a load and unload function which is hooked up through here
+- `assigner` - the strategy for assigning/unassigning contexts to scripts. This is used to determine how to assign a context to a script when it is run, and what to do with the context when the script is finished.
+- `context_initializers` - stores all context initializers for the plugin
+- `context_pre_handling_initializers` - stores all context pre-handling initializers for the plugin
+
+More advanced applications might want to customize these settings to suit their needs.