modify docs

Author: makspll

docs/src/SUMMARY.md

@@ -9,6 +9,7 @@
 - [Controlling Script Bindings](./Summary/controlling-script-bindings.md)
 - [Modifying Script Contexts](./Summary/customizing-script-contexts.md)
 - [Contexts](./Summary/contexts.md)
+- [Callbacks](./Summary/callbacks.md)
 - [Script Systems](./ScriptSystems/introduction.md)
 - [Examples](./Examples/introduction.md)
 

docs/src/ScriptingReference/core-callbacks.md

@@ -1,12 +1,14 @@
 # Core Callbacks
 
-On top of callbacks which are registered by your application, BMS provides a set of core callbacks which are always available.
+On top of callbacks which are registered by your application, BMS provides a set of core callbacks which are always available (unless disabled via plugin settings).
 
 The three core callbacks are:
 - `on_script_loaded`
 - `on_script_unloaded`
 - `on_script_reloaded`
 
+For more information on how callbacks generally work see [the callbacks section](../Summary/callbacks.md).
+
 ## `on_script_loaded`
 
 This will be called right after a script has been loaded or reloaded. This is a good place to initialize your script. You should avoid placing a lot of logic into the global body of your script, and instead put it into this callback. Otherwise errors in the initialization will fail the loading of the script.

docs/src/Summary/callbacks.md

@@ -0,0 +1,36 @@
+# Callbacks
+
+Callbacks generally refer to hooks called either manually or via rust event handlers, on scripts which can choose to subscribe to them.
+
+Callbacks come in two variants:
+- Freestanding, top level functions
+- Registered, or "frozen" callbacks
+
+## Freestanding callbacks
+An example of a freestanding callback:
+```lua
+function on_script_loaded()
+    print("doing things")
+end
+```
+
+this callback is refered to by "name", and on the rust side can be invoked either via `RunScriptCallback` command, or by setting up an event handler system which passes on `ScriptCallbackEvent`'s to scripts.
+
+The key thing to note about this type of callback, is that if the script is ever reloaded, and the contents of this callback change, the logic inside it will also be hot-reloaded.
+
+## Registerd Callbacks
+You can also register a callback like so:
+```lua
+register_callback("on_script_loaded", my_registered_callback)
+
+function my_registered_callback()
+    print("doing things")
+end 
+```
+
+Registered callbacks, take priority over freestanding ones, and contrary to freestanding callbacks, they are "frozen". I.e. once a callback is registereed in this manner,
+hot reloads won't affect the logic inside them.
+
+This works well when using shared contexts, where scripts will overwrite top level functions when being loaded. You can use the `on_script_loaded` callback to register all your scripts callbacks while they are loaded as top level functions, and when future loads happen, every callback will be issued correctly.
+
+This functionality is implemented at script plugin level, so some languages might not support this. All core languages do however.

docs/src/Summary/contexts.md

@@ -14,6 +14,12 @@ app.add_plugins(LuaScriptingPlugin::default().set_context_policy(
 ));
 ```
 
+<div class="warning">
+
+Shared contexts require your scripts to be more careful about how they register callbacks due to the nature of top level functions belonging to the "currently loaded" global script. See [the callbacks section](./callbacks.md)
+
+</div>
+
 ### Per Script Context
 A per script context provides each script with their own context. However, scripts may be attached to multiple entities, in which case a single script context is shared by multiple entities.