add clarifying language around the use of global variables

streamerbot/2.guide/03.variables.md

@@ -4,9 +4,9 @@ description: Usage of arguments and variables in your Streamer.bot actions
 ---
 
 ## Introduction
-When a trigger executes an action, it will automatically generate a set of variables specific to that event source and make them available to that action via the **argument stack**. You can use subsequent sub-actions to populate additional arguments, or even manipulate existing arguments on the stack.
+When a trigger executes an action, it will automatically generate a set of variables specific to that event source and type, and make them available to that action via the **argument stack**. You can use subsequent sub-actions to populate additional arguments, or even to manipulate existing arguments on the stack.
 
-Arguments only persist until the called action finishes execution and can not be referenced by any other action. To share variables across multiple actions, or to persist them across restarts, you can store them as [Global Variables](#global).
+Arguments only exist within the scope of the current action. Once the action finishes execution, they can not be referenced by any other action. To share variables across multiple actions, or to persist them across restarts, you can store them as [Global Variables](#global-variables).
 
 ::read-more{to=/api/triggers}
 Explore all available triggers and their variables in the [Triggers API References](/api/triggers)
@@ -24,12 +24,12 @@ These variables can be utilized in most [sub-action](/guide/actions#sub-actions)
 
 ![Using variables within a text field](assets/variable-example.png){caption-alt}
 
-To use a variable from the current argument stack, wrap the variable name with `%` symbols:
+To replace a variable name with its value from the current argument stack, wrap the variable name with `%` symbols:
 
 `%userName%`{lang=cs}
 
 ::tip
-Variables are added onto the argument stack during sequential execution of each sub-action. If you are testing and a variable seems to be missing, ensure that you are testing at the correct point of execution!
+Variables are added to the argument stack by each sub-action, which execute sequentially. If you are testing and a variable seems to be missing, ensure that the sub-action which sets it runs *before* you're attempting to access it!
 ::
 
 ::read-more{to=#inspecting-arguments}
@@ -39,25 +39,35 @@ Read more about how to **inspect arguments** after an action has executed
 ### Global Variables
 Global variables allow you to share data between multiple actions, or even persist it across multiple restarts of Streamer.bot.
 
-To quickly access a global variable, wrap the variable name with `~` symbols:
+::tip{to=/api/sub-actions/core/globals/global-set}
+To set the value of of a global variable in your action, call the `Set Global Variable` sub-action<br/>
+:icon{name=i-mdi-alert} This **does not** also make the global variable's value available in your action
+::
+
+::warning{to=/api/sub-actions/core/globals/global-get}
+To access the value of a global variable in your action, you **must *first*** assign it to a local variable with the `Get Global Variable` sub-action
+::
 
-`~myGlobalVariable~`{lang=cs}
+To directly access the value of a ***persisted* global variable**, wrap the variable name with `~` symbols:
+
+`~myPersistedGlobalVariable~`{lang=cs}
 
 ::tip
-This syntax currently only works for **persisted** global variables, and **not** user variables.
+This syntax currently *only* works for **persisted** global variables, and **not** user global variables.
 ::
 
-::read-more{to=#inspecting-arguments}
-Read more about how to use the variable viewer to **view all of your global variables in one place!**
+
+::read-more{to=#global-variable-viewer}
+Read more about how to use the global variable viewer to **view all of your global variables in one place!**
 ::
 
 :read-more{to=/api/sub-actions/core/globals}
 
 #### User Global Variables
-User variables function as global variables, but store values **per user**.
+User global variables function as global variables, but store values **per user**.
 
 ::tip
-User variables can be useful for creating per-user counters, leaderboards, or anything you can think of!
+User global variables can be useful for creating per-user counters, leaderboards, or anything you can think of!
 ::
 
 ### Generic
@@ -189,34 +199,34 @@ $parse(line%i%)$
 // ==> returns value of %line1% (the second line of the file)
 ```
 ::tip
-`%arguments%` and `~persistedVariables~` will be parsed in `parse`'s parameter, but not other `$inline()$` functions. If you wish to use a function, then set another argument to the output of the function, and use that argument in the `parse` instead.
+`%arguments%` and `~persistedGlobalVariables~` will be parsed in `parse`'s parameter, but not other `$inline()$` functions or formatting. If you wish to use another function, set another argument to the output of the function, and use that argument in `parse` instead.
 ::
 
-## Variable Viewer
-The Variable Viewer in Streamer.bot provides a convenient location to **view, modify, and create** all types of global variables, including per-platform user variables.
+## Global Variable Viewer
+The global variable viewer in Streamer.bot provides a convenient location to **view, modify, and create** all types of global variables, including per-platform user global variables.
 
-You can open the variable viewer at any time by clicking `Variables` on the Streamer.bot toolbar:
-![Variable Viewer Button](assets/variable-viewer-button.png)
+You can open the global variable viewer at any time by clicking `Global Variables` on the Streamer.bot toolbar:
+![Global Variable Viewer Button](assets/variable-viewer-button.png)
 
 You will be greeted with a popup window:
 ![View Global Variables](assets/variable-viewer-globals.png)
 
 ::tip
-Variables are **updated in real-time**, making this view extremely useful while you create and test your actions!
+Global variables are **updated in real-time**, making this view extremely useful while you create and test your actions!
 ::
 
 ### Options
-#### Add/Edit Variables
+#### Add/Edit Global Variables
 Selecting `Add` or `Edit` from the [context menu](#variables-context-menu) will greet you with the following options:
-![Variable Viewer Edit Dialog](assets/variable-viewer-edit-dialog.png)
+![Global Variable Viewer Edit Dialog](assets/variable-viewer-edit-dialog.png)
 
 ::field-group
   ::field{name="Variable Name" type="Text" required}
-  Enter the name for your new variable
+  Enter the name for your new global variable
   ::
 
   ::field{name="Value" type="Text" required}
-  Enter a new value for this variable
+  Enter a new value for this global variable
   ::
 
   ::field{name="Auto Type" type="Toggle"}
@@ -230,28 +240,28 @@ Selecting `Add` or `Edit` from the [context menu](#variables-context-menu) will
   ::
 ::
 
-#### Variables Context Menu
+#### Global Variables Context Menu
 The <kbd>Right-Click</kbd> context menu provides the following options:
 
 ::field-group
   ::field{name="Add Variable"}
-  Create a new variable of the current category type (e.g. persisted, non-persisted)
+  Create a new global variable of the current category type (e.g. persisted, non-persisted)
   ::
 
   ::field{name="Edit Variable"}
-  Edit the selected variable, see configuration options above
+  Edit the selected global variable, see configuration options above
   ::
 
   ::field{name="Delete Variable"}
-  Remove the selected variable
+  Remove the selected global variable
   ::
 
   ::field{name="Copy Variable Name"}
-  Copy the selected variable name to your clipboard
+  Copy the selected global variable name to your clipboard
   ::
 
   ::field{name="Delete all Variables"}
-  Remove **all** variables from the current category type (e.g. persisted, non-persisted)
+  Remove **all** global variables from the current category type (e.g. persisted, non-persisted)
   ::
 ::
 
@@ -260,17 +270,17 @@ The <kbd>Right-Click</kbd> context menu provides the following options:
 Navigate to `Action Queues > Action History` in Streamer.bot
 ::
 
-From the `Action History` view, you can <kbd>Right-Click</kbd> an action execution to inspect all variables on the argument stack:
+From the `Action History` view, you can <kbd>Right-Click</kbd> an action execution to inspect all variables from that action's argument stack:
 
 ![Action History Context Menu](assets/action-history-context-menu.png)
 
 ::field-group
   ::field{name="Inspect Variables When Queued"}
-  View all variables on the argument stack **before** the action has started
+  View all variables on the argument stack from **before** any of the sub-actions had run
   ::
 
   ::field{name="Inspect Variables After Run"}
-  View all variables on the argument stack **after** the action has completed
+  View all variables on the argument stack from **after** the action had completed
   ::
 ::
 
@@ -280,5 +290,5 @@ When you select one of these options, you will be greeted with a dialog containi
 ![Action History Variables](assets/action-history-variables.png)
 
 ::tip
-You can use this dialog any time you want to know what variables are populated by a trigger
+You can use this dialog any time you want to know what variables are populated by a trigger or the sub-actions during a specific run of an action
 ::

streamerbot/3.api/1.sub-actions/core/globals/global-get.md

@@ -2,17 +2,18 @@
 title: Get Global Variable
 description: Fetch the value of a global variable and populate a local argument
 parameters:
-  - name: GlobalVariableSource
-  - name: GlobalVariablePersisted
+  - name: Source
+  - name: Persisted
   - name: Variable Name
     type: Text
     required: true
     description: |
-      Enter the name of the variable you would like to fetch
+      Enter the name of the global variable you would like to fetch
 
       ::warning
-      `Variable Name` must be entered in `camelCase` (the first letter must be lowercase)
+      This is the **name** of the global variable, which means it should not be wrapped in `%` symbols unless you specifically want to use the **value** of a local variable in the **name** of your global variable
       ::
+
   - name: Destination Variable
     type: Text
     required: true
@@ -22,6 +23,11 @@ parameters:
       ::tip
       It is recommended to use a **different name** than the global variable name
       ::
+
+      ::warning
+      This is the **name** of the destination variable, which means it should not be wrapped in `%` symbols unless you specifically want to use the **value** of a local variable in the **name** of your destination variable
+      ::
+
   - name: Default Value
     type: Text
     description: |
@@ -36,8 +42,8 @@ csharpMethods:
 ---
 
 ::tip
-You can quickly access persisted globals without this sub-action by wrapping the name with `~`<br>
-:icon{name=i-mdi-chevron-right} `~myGlobalVariable~`{lang=cs}
+You can directly access the value of **persisted** non-user globals without this sub-action by wrapping the name with `~`<br>
+:icon{name=i-mdi-chevron-right} `~myPersistedGlobalVariable~`{lang=cs}
 ::
 
 :read-more{to=/guide/variables}

streamerbot/3.api/1.sub-actions/core/globals/global-set.md

@@ -1,42 +1,42 @@
 ---
 title: Set Global Variable
-description: Create or update a global variable
+description: Create or update the value of a global variable
 parameters:
-  - name: GlobalVariableSource
-  - name: GlobalVariablePersisted
+  - name: Destination
+  - name: Persisted
   - name: Variable Name
     type: Text
     required: true
     description: |
-      Enter the name of the variable you would like to create or modify
+      Enter the name of the global variable you would like to create or update
 
       ::warning
-      `Variable Name` must be entered in `camelCase` (the first letter must be lowercase)
+      `Variable Name` is the **name** of the global variable, which means it should not be wrapped in `%` symbols unless you specifically want to use the **value** of a local variable as the **name** of your global variable
       ::
-  - name: Source
-    type: Select
-    default: Argument
-    required: true
-    description: |
-      Select the source for the value to assign to the global variable
 
-      - `Argument` - Use the value of an argument
-      - `Value` - Assign any arbitrary value
-      - `Increment` - Add to an existing `int`{lang=cs} variable
-      - `Decrement` - Subtract from an existing `int`{lang=cs} variable
   - name: Value
     type: Text
     required: true
     description: |
-      Enter the value to assign to the global variable, depends on the selected `Source` type, detailed above
+      Enter the value to assign to the global variable, depending on the selected type in the dropdown
 
-      - `Argument` - Enter the name of an existing argument to assign its value to the global variable
+      All options support parsing of %arguments%
       - `Value` - Enter any value
-      - `Increment` - Enter any `int`{lang=cs}
-      - `Decrement` - Enter any `int`{lang=cs}
+      - `Increment` - Enter any `int`{lang=cs} to be added to the existing value
+      - `Decrement` - Enter any `int`{lang=cs} to be subtracted from the existing value
+
+      ::tip
+      If left empty, `Increment` and `Decrement` default to 1. If the global variable did not already exist, it will add or subtract from 0
+      ::
+
 variables: []
 csharpMethods:
   - SetGlobalVar
 ---
 
+::warning{to=/api/sub-actions/core/globals/global-get}
+This **does not** also make the global variable's value available in your action<br/>
+To access the value of a global variable in your action, you **must *first*** assign it to a local variable with the `Get Global Variable` sub-action
+::
+
 :read-more{to=/guide/variables}

streamerbot/3.api/1.sub-actions/core/logic/if-else.md

@@ -8,7 +8,8 @@ parameters:
     description: |
       The value to be tested. Performs full parsing of `%arguments%`{lang=cs}, `~persistedGlobals~`{lang=cs} and `$inlineFunctions()$`{lang=cs}
       ::warning
-      Unlike earlier version of Streamer.bot, arguments must be enclosed in `%...%` in order for their values to be tested. If using `Does Not Exist`, then just use the argument name, without the `%`.
+      Unlike earlier version of Streamer.bot, arguments **must** be enclosed in `%...%` in order for their values to be tested<br/>
+      If using `Does Not Exist`, you **must** use *only* the argument name without the `%`.
       ::
   - name: Operator
     type: Select

streamerbot/3.api/_parameters/core/GlobalVariableDestination.md

@@ -0,0 +1,13 @@
+---
+name: Destination
+type: Select
+default: Global
+required: true
+---
+
+Select the destination type for the global variable
+
+- `Global` - Set a general global variable (non user variable)
+- `User (redeemer)` - Set a user global for the current user who **activated** the action
+- `User (target)` - Set a user global for the `targetUser`
+    - Used in conjunction with the [Get User Info for Target](/api/sub-actions/twitch/user/get-user-info-for-target) sub-action