Like with any other programming languages in KSP there are also variables, arrays and constants.
They can only be declared inside the on init callback and can then be used throughout the whole script. So they are all on global scope by default and can even be used inside custom functions.
VARIABLES
Into variables we can store different values and read or access them anywhere we want throughout the whole script.
There are different variable types like string, integer, real and constant variables.
Furthermore there’s a special polyphonic variable which is not addressed in this article.
Integer Variables
can only store integer numbers and have to be declared like this declare $<variable-name>
The $ makes it an int variable
on init declare $count := 8 {sets the variable named "count" and stores 8} message ($count) {outputs 8} end on
String Variables
can only store strings and have to be declared like this: declare @<variable-name>
The @ makes it a string variable
on init declare @hint @hint:= "Within string variables we can store complete sentences! And yes, she works fine :)" message(@hint) end on
REAL VARIABLES
can only store real numbers (or floating points) and have to be declared like this declare ~<variable-name>
The ~ makes it a real variable
declare ~RealNumber := 4 //this produces an error: declare ~RealNumber := 4.00 // this works declare ~RealNumber := 7694.987653428 // this works
We can not mix integer variables with real variables so if we want to use both within the same calculation we have to convert one or the other
on init declare $integer := 4 declare ~real := 3.9 message(~real + $integer) {this produces an error} message(~real + int_to_real($integer)) {this outputs 7.9} message(real_to_int(~real) + $integer) {this outputs 7} end on
Note: converting real to int just cuts the decimals .. or floors the value.
So real_to_int(3.9) becomes 3
Constant Variables
Constant variables can’t be changed anymore once they have been set. You may wanna use them to avoid accidentally overwriting their values especially when your code gets more complex.
User defined constants can be declared by adding a “const” before the variable name. You also have to define the value right after on:
declare const $<variable-name>:= <value>
This works
on init declare const $MY_CONST := 10 {always stays 10 now} end on
This won’t work
on init declare const $MY_CONST $MY_CONST := 10 end on
This won’t work either
on init declare const $MY_CONST := 10 $MY_CONST := 11 end on
ARRAYS
Compared to a variable an array can hold multiple values at once while each value is stored or assigned to a certain key inside the array.
Think of it like a filing cabinet with little or many drawers. Each drawer (key) holds an individual file (value). We can access and read those files by opening the drawer we need.
Which means:
//To declare an array: declare %array[number_of_total_keys] //To return values of an array: message(%array[$key]) // outputs the value of $key //To Store values into an array: we simply do %array[$key] := $value //To search the key of a given value: search(%array, $value) // outputs the key index where the value was first found
To do so we first declare an array, specify its size (= number of keys). We can then fill the single keys with values (like shown below).
There are also different types of arrays like int, string and real arrays (see below).
int arrays
can only store integers and have to be declared like this declare %<array-name>[number_of_keys]
The % makes it an int array. The value between the brackets [] defines the size of the array. The array size can’t be changed anymore once it is set.
on init declare %parameter[4] {defines an int array named "parameter", with the size of 4 keys } %parameter[0] := 10 {stores 10 into key 0 .. note: the first key starts with 0 not 1} %parameter[1] := 126 %parameter[2] := 10024 %parameter[3] := 8 message(%parameter[2]) {outputs 10024} end on
string arrays
can only store strings and have to be declared like this declare !<array-name>[number_of_keys]
The ! makes it a string array. The value between the brackets [] defines the size of the array. The array size can’t be changed anymore once it is set.
on init declare !notes[4] !notes[0] := "C" !notes[1] := "C#" !notes[2] := "D" !notes[3] := "D#" message(!notes[3]) {outputs D#} end on
real arrays
can only store real numbers and have to be declared like this declare ?<array-name>[number_of_keys]
The ? makes it an array of real numbers. The value between the brackets [] defines the size of the array. The array size can’t be changed anymore once it is set.
Real arrays work the same as real variables:
on init declare ?realArray[8] {declares an array of real numbers with 8 keys} ?realArray[0] := 4 {this produces an error} ?realArray[1] := 4.00 {this works} ?realArray[2] := 854.9882 {this works} message(?realArray[2]) {this outputs 854.9882} end on
To mix int with real arrays we also need to convert one or the other:
on init declare ?realArray[3] ?realArray[0] := 2.5 ?realArray[1] := 7.5 ?realArray[2] := 7.9 declare %intArray[2] %intArray[0] := 2 %intArray[1] := 4 message(?realArray[0] * int_to_real(%intArray[1])) {outputs 10} message(real_to_int(?realArray[1]) * %intArray[0]) {outputs 14} message(real_to_int(?realArray[2]) * %intArray[0]) {outputs 14, so real_to_int just cuts the decimals (or floors the decimal)} end on
Note: converting real to int just cuts the decimals .. or floors the value.
So real_to_int(7.9) becomes 7
BUILT-IN Variables
(also called Control Parameter Variables, Engine Parameter Variables,..)
There are also internal variables which are holding or returning specific values given by the Kontakt engine. Like the actual played note ($EVENT_NOTE) or engine parameters, but also UI parameters and many more.
We use them to control or to address all kinds of Kontakt internal engine parameters like the Instrument’s Volume, or our ui controls and many other parameters. There is a full list of all internal variables and what they do in the KSP Reference Manual.
Without these variables we wouldn’t be able to operate Kontakt with custom scripts. Internal variables cannot be declared or changed. They are always available globally.
Working with these Variables is mainly what Kontakt scripting is about so you will see them a lot with yor scripts. And you will get familiar with many of them. At best study all of them to get to know what Kontakt is capable of and what not. Also this may inspire you.
global & local variables explained
In KSP all variables have to be declared inside the on init callback and are global by default.
Although we can’t use local variables in KSP it is still important to understand the differences. For example to better understand the limitations of KSP compared to other programming languages.
Local variables
are variables defined within a specific block of code or function and can only be accessed within that block.
Global variables
on the other hand, are variables defined outside of any specific block of code or function and can be accessed and modified from anywhere in the program or script.
Serge
Hi _ Fot the @ example, I would have written it like this : she work fine .YummyBeats
yeah true, Kontakt doesn't like filling and declaring strings variables in the same line.That's why it's also recommended to use Sublime since Sublime would just ignore all the peculiarities of Kontakt.