Merge pull request #82 from Chylum/docs/why-cilbox

Add Clarification That Cilbox Is Especially for UGC/DLC and Security

Author: dooly123

content/docs/world/scripting.mdx

@@ -8,6 +8,13 @@ For reasons, custom code must either be generated by rebuilding the client (i.e.
 
 ## How to Add Scripts Via Unity Client Build
 
+<Callout type="info">
+
+If you are building a game or application with the framework, and supporting user-generated content (such as scenes, avatars, or props) is not a priority, you may prefer to build your MonoBehaviour scripts natively rather than leveraging Cilbox.
+
+This is because Cilbox is a CIL interpreter, which will incur a significant speed penalty and may support a subset of available language features.
+</Callout>
+
 - Create a canvas object with a button inside it.
 
 - Add a script to the button object. As a simple example, we'll create a script that updates a TMP text object called TestButton.
@@ -158,7 +165,13 @@ You should disable or remove the canvas object from the scene. This is because k
 
 ## How to Add Network Syncing Scripts Via Cilbox
 
-The Cilbox CIL can be used to create scripts that work in runtime. Currently, Cilbox is still quite experimental. The following example shows how to create a script to make a cube rotate using Cilbox.
+Cilbox is a scripting system to act as glue to help provide some minimal game logic, enabling portability of basic behaviours in user-generated content such as props, avatars, and scenes. It can be used to create scripts that work at runtime. 
+
+Currently, Cilbox is still very experimental. The following example shows how to create a script to make a cube rotate using Cilbox.
+
+<Callout type="info">
+Note: Cilbox is especially useful if you are making an application or game that loads user-generated content, and want to support scripting on that user content. It allows shipping scripts as something like DLC alongside your other content, while also providing a more secure sandbox for code to be executed within, preventing scripts with harmful or undesirable behaviours from executing.
+</Callout>
 
 - Create a cube object and an ObjectRotator component to attach to it. Make sure to add [Cilboxable] above your class.
 
@@ -208,7 +221,7 @@ Note: If your editor can't detect the Cilbox namespace, you can either create yo
 
 ![Window showing cube rotating Cilbox demo in app](/img/scripting/23.png)
 
-Here is an additional example using shaders which you can try.
+Below are some additional example scripts you can try out.
 
 ``` cs title="NM_Wind "
 using UnityEngine;
@@ -235,4 +248,51 @@ public class NM_Wind : MonoBehaviour
         Shader.SetGlobalFloat("WIND_SETTINGS_GustWorldScale", 0.0016666667f);
     }
 }
-```
+```
+
+```cs title="Gun"
+using UnityEngine;
+using Basis.Scripts.BasisSdk.Interactions;
+using Basis.Scripts.Device_Management.Devices;
+
+[Cilboxable]
+public class Gun : MonoBehaviour
+{
+    private BasisPickupInteractable pickup;
+
+    void Start()
+    {
+        this.pickup = GetComponent<BasisPickupInteractable>();
+        this.pickup.OnInteractStartEvent.AddListener(OnPickup);
+        this.pickup.OnInteractEndEvent.AddListener(OnDrop);
+        this.pickup.OnPickupUse.AddListener(OnUse);
+    }
+
+    private void OnPickup(BasisInput input)
+    {
+        Debug.Log("HoloGun: Picked up!");
+    }
+
+    private void OnDrop(BasisInput input)
+    {
+        Debug.Log("HoloGun: Dropped!");
+    }
+
+    void OnUse(BasisPickUpUseMode mode)
+    {
+        switch (mode)
+        {
+            case BasisPickUpUseMode.OnPickUpUseDown:
+                Debug.Log("HoloGun: Pew Pew!");
+                break;
+            case BasisPickUpUseMode.OnPickUpUseUp:
+                Debug.Log("HoloGun: Pew Pew! (released)");
+                break;
+        }
+    }
+}
+```
+
+<Callout type="info">
+Instead of BasisNetworkBehaviour, BasisNetworkShim can be inherited from to create networked scripts.
+</Callout>