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

  • Integer
  • string
  • real

• constant variables

• Arrays

  • integer
  • string
  • real

• Built-In Variables

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

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

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.