Expanded Custom Trigger guide

streamerbot/2.guide/2.triggers.md

@@ -166,13 +166,18 @@ Simulated Events documentation needed (Coming in Streamer.bot v0.2.2)
 Custom Triggers **require C# Code** to register and execute
 ::
 
-You can define your own triggers using C# Code, which will then show up in the trigger menu UI under `Custom`.
+You can define your own triggers using C# Code. These will then show up in the trigger menu UI under `Custom` once the C# code defining them has been run once.
 
-![custom-trigger](./assets/custom-triggers.png)
+::tip{color=amber}
+Since custom triggers need to be re-defined on every boot of StreamerBot, it is encouraged to define these in your C# module's `public void Init()` method and enable `Precompile on Application start`.
+::
+
+![custom-triggers](./assets/custom-triggers.png)
 
 ::code-group
   ```cs [Register Trigger]
   // Register a new trigger labeled "Game Win" in the "Game Result" category
+  //                           Label         Name                 Category
   CPH.RegisterCustomTrigger("Game Win", "gameResultWin", new[]{"Game Result"});
   ```
   ```cs [Execute Trigger]
@@ -181,4 +186,29 @@ You can define your own triggers using C# Code, which will then show up in the t
   ```
 ::
 
+The category parameter of the `RegisterCustomTrigger` function *always* has to be an array, allowing to nest sub-categories.
+
+This is only for user convenience and does not change the process of triggering a custom trigger by name.
+
+![custom-triggers-nested](./assets/custom-triggers-nested.png)
+
+::code-group
+  ```cs [Register Nested Triggers]
+  // Register three top level triggers in category `Chat Based Poll`
+  CPH.RegisterCustomTrigger("Poll Ended", "poll_ended", new[] {"Chat Based Poll"});
+  CPH.RegisterCustomTrigger("Poll Canceled", "poll_canceled", new[] {"Chat Based Poll"});
+  CPH.RegisterCustomTrigger("Poll Status", "poll_status", new[] {"Chat Based Poll"});
+
+  // Register three nested triggers in category `Winner`, which is in category `Chat Based Poll`
+  CPH.RegisterCustomTrigger("Poll Message Winner", "poll_winner_one", new[] {"Chat Based Poll", "Winner"});
+  CPH.RegisterCustomTrigger("Poll Message Tie 2", "poll_winner_two", new[] {"Chat Based Poll", "Winner"});
+  CPH.RegisterCustomTrigger("Poll Message Tie 3", "poll_winner_three", new[] {"Chat Based Poll", "Winner"});
+  ```
+  ```cs [Execute Nested Triggers]
+  // Call a trigger from any nested level solely by their name
+  CPH.TriggerCodeEvent("poll_ended", true);
+  CPH.TriggerCodeEvent("poll_winner_three", true);
+  ```
+::
+
 :read-more{to="/api/csharp/core/triggers"}