Advanced scripting - Custom variables

Custom variables provides a way to store information in named variables for later retrieval in events or actions within the same script or scripts in other buttons.

The plugin can store any number of custom variables, and a custom variable can store an integer number from 0-127. The variable content is stored in the background and will work across buttons, pages, and profiles (depending on scope, see below). Custom variables are cleared when the Stream Deck software is restarted and when the plugin is uninstalled/reinstalled or updated.

A custom variable is defined with the syntax "@VariableName" (without the quotes). The @ character is what tells the script engine that the name that follows is a variable name. The name can contain upper and lower case letters, numbers and underscores. The name is not case-sensitive, so @MyVariable and @myvariable is the same variable.

Custom variable scope.

Custom variables can exist in two different scopes, local and global, and the name prefix determines the scope.

  • If the variable name starts with "@local_" or "@l_", the variable's scope is local to that button only. Multiple buttons may have local variables with the same name, and each local variable will be unique for the button where it is defined. This is useful if you make copies of a button and want each copy to be independent and have its own instance of the variable. A value stored in a local variable will not be accessible from other buttons.
  • If the variable name starts with "@event_" or "@e_", the variable is an event reference variable, referencing values in the events in the command. Event variables are by definition local, and are read-only.
  • If the variable name starts with anything other than "@local_", "@l_","@event_" or "@e_" the variable is global. A value stored in a global variable is accessible from all buttons on all pages and in all profiles.
The prefixes @local_, @l_, @event_, and @e_ are prefixes only; @local_myvariable and @l_myvariable are the same local variable, @event_ccvalue and @e_ccvalue are the same event variable.

Setting custom variable values.

You set custom variable values in script actions with a syntax similar to all other actions. This example action stores the value 10 in the variable MyVariable.

{@MyVariable:10}
A variable can store values from 0-127; an attempt to set a value outside this range will force it to the closest boundary. You can use the variable in events and in value references in other actions.

Custom variable events.

You can trigger commands on custom variable values in script events with a syntax similar to all other events. This example triggers the command if the value in the variable MyVariable is 10.

(@MyVariable:10)
When the value of a custom variable is changed (as the result of an action in a command), other commands referencing that variable as an event will be immediately triggered ("immediately" means: before the next action in the current command is processed).

Custom variable events can reference a single value, a range, or a transition:

(@MyVariable:10)
(@MyVariable:0-64)
(@MyVariable:>64>)

Custom variable references.

Custom variable actions can use the #value# reference just like other actions. In addition, custom variables themselves can be referenced in any action. Like the #value# reference, custom variable references must be enclosed by # characters. Example:

[(press){@V1:10}]
[(press){@V2:20}]
[(@V1:0-127)(@V2:0-127){text:#@V1 + @V2#}]
This script will set V1 = 10 the first time the button is pressed and set V2 = 20 the next time it is pressed. The sum will be displayed on the button whenever the value of V1 or V2 is changed.

Custom variable loops.

Commands with custom variables can reference each other in ways that create loops; consider the following scripts:

Example 1:
[(@V1:0){@V1:1}]
[(@V1:1){@V1:0}]
When V1 is set to 0, it will trigger the first command, which will set V1 to 1, which will trigger the second command, which will set V1 to 0, which will trigger the first command.....

Example 2:
[(@V1:0-64){@V1:#@V1 + 1#}]
Any value between 0-64 will trigger the command, adding 1 to the value. If the value is still in the range 0-64, it would trigger the same command again, and again, and again....

The plugin blocks these loops by not allowing commands in a script to be executed more than once. If any command in the "command chain" is triggered a second time, the actions will be ignored, and the loop will break. In the first example, each command will be executed once when the value is changed (from another script). In the second example, the command is only executed once, even if the resulting value is in the range of the event.