Subscripts are named modules within a script file that contain groups of commands that can be ran separately from one another. In programming terms, you might know them as methods or functions. A script can contain an unlimited amount of subscripts, as long as each subscript within that script has a unique name.
Formatting
A subscript can be declared in a script using the “script” prefix, followed by the name of the subscript. Any commands following the subscript declaration should be indented within the declaration line. All commands following the subscript declaration will be considered as part of the subscript, until another subscript or event is declared.
A script can start directly with commands instead of declaring a subscript. The scripting system will automatically consider any commands at the start of the script as part of a subscript named “default”, if none is specified.
Example:
print "Default subscript here!" script second_subscript $myVariable = "Hello" print $hello script another_subscript $myVariable = 64 midi note $myVariable 0
Running subscripts
Subscripts can be ran with the runscript command. The runscript command takes both a script name and a subscript name argument, allowing you to target any given subscript, even in other scripts. For convenience, the script argument can also be left as “default”, which will assume the current script that the runscript command is executed from, which allows you to only need to specify the subscript name when running a subscript. The subscript argument of the runscript command is optional, as by default, the default subscript will be targeted.
Example:
runscript default my_subscript
script my_subscript
print "Hello!"
Passing variables
When running a subscript using the runscript command, you are able to pass variables to be included in the subscript being ran. This allows you to pass dynamic information from one subscript to another, without the need for global variables.
Example:
event midi note if ($trigger velocity) > 0 runscript default print_note note:($trigger note) script print_note print $note was just triggered!
Accessibility
Subscripts can also have accessibility levels. This means that you can control which scripts or app controls have access to your subscript.
Valid accessibility levels are:
- public: The subscript can be selected in UI, and ran from other scripts.
- hidden: The subscript is no longer listed in UI, but can still be ran from other scripts.
- private: The subscript is not listed in UI, and can only be ran from the same script it is a part of.
The accessibility level can be specified after the subscript name.
Example:
script my_subscript private print "Only my script can run this!"
Other
Subscripts are selectable in a translation’s script output settings, meaning that if you have a translation configured to run a script, you will also be able to choose which subscript is ran, using the subscript selector in that translation’s advanced settings.