Posted by & filed under KSP Scripting (NI Kontakt) - Tutorials, KSP: Basics.

This chapter is also described in the KSP manual very detailed. If you are missing something please refer to it.

Statements (if..else, while)

With statements (and the operators below) you define clear conditions. The code inside a statement only gets executed when or as long as your condition is true. The most used statements in KSP are: “if(<your condition is true>)…else…end if” and “while(<your condition is true>)…end while”.  There are some more statements but you will probably only use them with more advanced scripts so they are not addressed here.

if statement

The code inside an if statement only gets executed once, when the condition is true. Furthermore you could also append an else statement (followed by another if statement, and so on) to execute an alternative code when the if condition is false.


on init
     declare $a := 2
     declare $b :=4
     declare $x :=0 {try setting x to 2 and then to 0 again -> press apply}

     declare $x_before := $x

     if($a + $x = $b)
           message("X = 2") {outputs "X = 2" when you set x to 2}
             $x := 2
             message("x was " & $x_before & " but now it has been set to " & $x)
     end if
 end on

while statement

the code inside a while statement gets executed in a loop as long as the while condition is true. You can change variables inside the loop so that the condition gets false sometime. Or to be more precise, you even have to do that otherwise you have an infinite loop which crashes your whole script. To end loops you simply increase a variable by one at the end of each loop run with inc($count). In the loop’s condition you define while ($count < $max), whereby before the loop you set $count to 0 and $max to your preferred loop runs, like declare $count:= 0 and declare $max := 10. So all in all you get the condition: as long as $count is less than 10 => do the loop. Remember: after each loop circle $count is increased by one! So after 10 runs the condition gets false and the loop stops. You can also use the exit command to interrupt a whole callback (so also a loop inside it) no matter if the loop’s condition is still true. This is useful for example when you define an independent if condition inside a while loop which should break it under a certain condition. Unfortunately exit stops the whole callback and can only be used in certain callbacks (not in the init callback) To simulate an exit only for loops you can simply set $count to $max when an independent if condition inside the loop gets true.

While loops comes in handy especially when you want to automate things and to safe numerous code lines.

Example (creates a menu with 10 entries)

on init

 declare ui_menu $menu declare $count declare $max declare $exit := 5 $count := 0 $max := 10 while ($count < $max) add_menu_item ($menu, "Option " & $count+1 , $count+1) {adds one menu entry each loop run} if($count = $exit){exit the code earlier when an independent condition is true} $count = $max end if inc($count) {increases a by 1 each loop run} end while end on

Mathematical Operators

You use Mathematical Operators to define conditions, verify them or do other calculations.

$x := $y {assignment: if y=2 then x =2 as well}

$z := $x + $y {addition: if x=1 and y=3 then z=4 ;) }

$z := $x – $y {subtraction}

$z := $x * $y {multiplication}

x / y {division}

$x mod $y {modulo: see below}

-$x {negative value}

$x > $y {greater than}

$x < $y {less than}

x >= y {greater than or equal}

x <= y {less than or equal}

x = y {equal}

x # y {not equal}

or {see example below}

and {see example below}

not {see example below}

There are more operators which are not addressed here because you only need them for advanced scripts. But you will also find them all in your ksp reference manual.


Remainder of $x divided by $y. The remainder is 0 when x and y are evenly divisible.


on init
    declare $z
    $z :=4 mod 3
    message($z) {outputs 1}
end on



Any code inside the if ... end if statement gets executed when either x = 3 or y = 4.

if ($x = 3 or $y = 4)
end if



when both (or more) conditions are true. Any code inside the if ... end if statement gets executed when x = 3 and y = 4.

if ($x = 3 and $y = 4)
end if



Checks if a (Boolean) value is false. Any code inside the if ... end if statement gets executed when a command (Kontakt function) is returning false.

on note     if (not(in_range($EVENT_NOTE,0,70)))         message("this note is in the defined range")         else message("this note is not in the defined range")     end if end on

combinations (and … or…not)

you can also combine the operators above. With (…) brackets  you can define groups which have a priority over solo operators (like the usual mathematic bracket priority). The following code inside the if statement gets executed when w = 5 or  when x = 3

and y = 4 at the same time.

if ($w=5 or ($x = 3 and $y = 4)) {if one condition inside the brackets is false, the whole if condition is false}
end if

Commands / Functions

functions (or in KSP also called commands) do the real work for you. You use them to get values from the Kontakt Engine, to set values, to find values, to compare values, to randomize values, to control the runtime of your script and much more. Unfortunately there are plenty of commands that they can’t be all listed here. It’s better to learn them step by step anyway. You can also look them all up in your KSP reference manual.


One very important command for the beginning is the message() command, though. You’ve already seen it a lot here. Most of the times you need it to debug your code or find logical errors. The message command simply outputs a text, a variable or a return value in the status bar of Kontakt. Unfortunately the status bar is one single line so you can only see the last message command that has been called which makes debugging nerve-racking!


on init
  message ("I am the status bar")
end on



Leave a Reply

Your email address will not be published. Required fields are marked *