Contents

Overview

KScript Editor is a text editor specifically written to make it easier to write and work with Kontakt 2[1] scripts. It also features an integrated script compiler, so it's really an IDE. The editor is based on Scintilla - an open source text editor component.

Note: this documentation may not be complete. I will add bits and pieces when I find time to do so.

Extended script syntax

Although it's possible to use just the editing facilities of the editor and copy and paste the code to Kontakt 2, it's also possible to compile your scripts in the editor by pressing F5. By doing so you can check for errors (activate the Extra syntax checks option for even more elaborate error checking) and you can use an extended script language syntax which makes it easier to write and maintain scripts.

The following sections will explain the various extensions to the native KSP syntax that the KScript Editor allows you to use. To translate a script from the extended syntax which is easier to read and work with to the original syntax that Kontakt 2 understands you press the F5 key in KScript Editor. This compiles the script, ie. translates the extended syntax to ordinary KSP syntax. If the compilation was successful the compiled code is automatically placed on the clipboard so you can just go ahead and paste it into Kontakt 2. In the examples below the yellow code samples represents code written with the extended syntax and the gray boxes what the corresponding compiled code looks like.

Variable prefixes are optional

In normal KSP it's mandatory to prefix variables with one of the characters $, %, @ and !. With the extended syntax this is not necessary. The only case where a prefix is necessary is on the declaration line of a string variable or string array variable. Prefixes are not necessary once the variables have been declared (see the last line in the example below). Example:

declare x := a + b + c
declare list[4] 
declare @name  
name := 'sustains'
declare $x := $a + $b + $c
declare %list[4]
declare @name   
@name := 'sustains'

Parenthesis are optional for if, while and select

In an effort to make the source code slightly more readable parenthesis are optional for if statements, while-loops and select statements.

while x <= 10
if x = 1       
select x       
while (x <= 10)  
if (x = 1)       
select (x)       

Note: if the condition starts with a left parenthesis but does not end with a right parenthesis this will at the moment confuse the compiler so for the time being you need to wrap the whole expression in parenthesis in that specific case.

For-loops

KSP only supports while-loops but with the extended syntax you can also use for-loops. Example:

for i := 0 to 9
  list[i] := 1
end for
$i := 0
while ($i <= 9)
  %list[$i] := 1
  inc($i)
end while

It's also possible to loop downwards and/or optionally use a certain step size:

for i := 9 downto 0 step 2
  list[i] := 1
end for
$i := 9
while ($i >= 0)
  %list[$i] := 1
  $i := $i - 2
end while

Else If

The extended syntax provides an "else if" construct since this is lacking in KSP.

if x = 1
  {...}
else if y = 1  
  {...}
else if z = 1  
  {...}
end if
if ($x = 1)
  {...}
else
if ($y = 1)
  {...}
else
if ($z = 1)
  {...}
end if
end if
end if

Variable families

With KSP there is no good way to organize variables so there tends to be a huge list of variable declarations in the init callback which makes it hard to know what is used where. With the extended syntax you can declare variables which belong to the same category in a family and then refer to them as family.variable (the family name followed by a period followed by the variable name). This can make variable names slightly longer but makes it easier to quickly grasp what a variable is used for. In the compiled script the dots are replaced by two underscores.

Note that after the declaration of a variable inside a family you always have to use the fully qualified name to refer to it. For example, in the declaration of keys below one has to use keyswitch.N instead of just N. It is also possible to nest families.

on init
  family keyswitch
    declare current
    declare const N := 10    
    declare keys[keyswitch.N]
  end family
end on

on note
  keyswitch.current := search(keyswitch.keys, 
                              EVENT_NOTE)
end on
on init
  {family keyswitch}
    declare $keyswitch__current
    declare const $keyswitch__N := 10    
    declare %keyswitch__keys[$keyswitch__N]
end on

on note
  $keyswitch__current := search(%keyswitch__keys,
                                $EVENT_NOTE)
end on

User-defined functions

In addition to the natively supported user-defined functions that KSP support and that you invoke using the "call" keyword KScript Editor adds support for two additional types of user-defined functions: inlined functions and task functions (abbreviated taskfunc).

Native functions

Native user-defined functions do not support parameters nor return value and inside them one cannot use certain builtin functions like allow_group. They are invoked using "call" (see the KSP Reference for further information). Kontakt has some restrictions on the order in which you define this type of function, but KScript Editor will automatically reorder the function definitions in the compiled code for you.

function raise_all_notes_one_octave
  change_tune(ALL_EVENTS, 100000*12, 0)
end function

on note
  call raise_all_notes_one_octave
end on

Inlined functions

Inlined functions are declared similarily to native functions. However you can optionally add parameters and a return value. An inlined function is invoked using essentially the same syntax as a native one, but without the "call" keyword. If the function has a return value you can invoke the function in any expression with one limitation: if the body of the function definition consists of more than one line then the function can only be used as the single thing on the right hand side of an assignment, eg. y := myfunc(4, x). A function with return value but no parameters needs to be invoked like this: y := myfunc(). The empty parenthesis are needed in this case to distinguish it from an ordinary variable reference.

Please note that one and the same function definition can be inlined in one place and 'call'ed in another place. By deciding whether to use "call" or not you decide whether or not the function should be inlined or just called.

The sample script below is a simple humanization script which adds a random number between -10 and 10 to incoming velocities. The limit_range function is used to clip the final velocity value to the range 1 to 127.

on init
  declare velocity
end on

on note
  velocity := EVENT_VELOCITY + random(-10, 10)
  limit_range(velocity, 1, 127)
  change_velo(EVENT_ID, velocity)
end on

{ forces value to be between min and max }
function limit_range(value, min, max)      
  if value < min
    value := min
  end if
  if value > max
    value := max
  end if
end function
on init
  declare $velocity
end on

on note
  $velocity := $EVENT_VELOCITY + random(-10, 10)
  {begin limit_range($velocity,1,127)}
    if ($velocity < 1)
      $velocity := 1
    end if
    if ($velocity > 127)
      $velocity := 127
    end if
  {end limit_range($velocity,1,127)}
  change_velo($EVENT_ID, $velocity)
end on

Please compare the uncompiled and compiled code. All invokations of inlined functions are replaced by the body of the function upon compilation. Note how the parameters are inserted into the compiled code: any occurance of value, min and max in the function body is replaced by the parameters velocity, 1 and 127 respectively. From within the body of one function it is possible to call another function, but since the body of every function has to be inlined at some point it is not allowed for a function to directly or indirectly call itself.

For functions which have no parameters it's preferred to leave out the parenthesis alltogether when you declare or call them. It is also possible, but not recommended, to use a pair of empty parenthesis like in languages like Java and C++. Example:

function do_something   {recommended syntax}
function do_something() {also allowed}

If you declare a variable inside a function it is by default considered local to that function. This means that the function has its own copy of the variable so even if a variable with the same name was declared in 'on init' or some other function they won't interfer with each other. Local variables are prefixed with an underscore upon compilation (see $_tmp below). If you want a variable declared inside a function to be accessible from callbacks and other functions you can either declare it like "declare global $x" or make sure the function name starts with "on_init" and all variables inside that function will implicitly be considered global.

on init
  declare x := 1
  declare y := 5
  swap(x, y)
end on

function swap(a, b)
  declare tmp
  tmp := a
  a := b
  b := tmp
end function
on init
  declare $x := 1
  declare $y := 5
  declare $_tmp
  {begin swap($x,$y)}
    $_tmp := $x
    $x := $y
    $y := $_tmp
  {end swap($x,$y)}
end on

Return value

A return value behaves just as if you had passed an extra parameter and assigned a value to it inside the function. The name "result" below carries no special meaning. You can use any name you choose. The function max consists of multiple lines and can only be used on the right hand side of an assignment: z := max(x, y), whereas the square function which is a single-line one can be used anywhere, for example in an arithmetical expression passed as a parameter to a builtin function.

on init
  declare x := 1
  declare y := 5
  declare z
  z := max(x, y)
  message(1 + square(y))
end on

function max(a, b) -> result
  if a > b
    result := a
  else
    result := b
  end if
end function

function square(a) -> result
  result := a*a
end function
on init
  declare $x := 1
  declare $y := 5
  declare $z
  if ($x>$y)
    $z := $x
  else
    $z := $y
  end if
  message(1 + $y*$y)
end on

Declaration order (advanced)
It's useful to know that local variables of a function which ends up not being used in a particular script are stripped from the compiled code. This makes it possible to build function libraries where unused functions don't clutter users' scripts with unnecessary variable declarations. In case several functions declare global variables and they are used in specific places in the callbacks or other functions it's good to be aware of the order in which these variables end up in the 'on init' callback (to make sure variables are declared before they are used for the first time):

Pitfalls
If a function contains an expression like "5*x" and it is invoked with parameter x set to C+5 then the compiled code with be 5*C+5 and not 5*(C+5) as one might expect. As you see the compiler does not automatically insert parenthesis around C+5 so the user needs to either write 5*(x) in the function or pass the expression (C+5) as parameter. Please note that if "use old compiler" is unchecked in the Settings menu you no longer need to worry about this.

Task functions

The task function feature is based on a system by Robert Villwock (a.k.a. Big Bob) called Task Control Module (abbreviated TCM) which has been integrated into KScript Editor. This extended syntax under the surface relies on functions being invoked using the "call" keyword. However, parameters you pass to a task function and local variables declared inside them (taskfunc) are specific to the current callback. Please see the official TCM Guide (pdf).

If your script invokes wait(...) inside a function then you run the risk of having the same function be entered in the context of another callback instance (i.e. the first callback is paused and another is executed and happens to enter the same function). This can cause problems with the latter invokation incorrectly overriding variable values set and relied upon in the first callback (after the wait call some variables would unexpectedly have assumed different values). Please note that local variables declared inside inlined functions "under the hood" are global variables with a name unique to the function in which it is declared.

The Task Control Module solves this problem by allocating a full sized array with 32768 entries and divides this into a number of chunks where each chunk can be assigned to a callback instance. This memory area is then used as a stack where parameters to task functions, function return values and local variables are stored. Since each executed callback gets its own memory storage this solves the problem with values getting overwritten when a function is re-entered. Moreover, TCM makes it possible to pass parameters to and return a result from functions without having to rely on inlined functions. Although inlined functions are suitable in many cases it's a problem that many invokations of them can greatly increase the length of the compiled code (if a 100-line function is invoked 10 times it will result in 1000 lines of compiled code).

So in short TCM has these advantages:

In order to use TCM you add tcm.init(stack_depth) to your init callback, where stack_depth is the size of the per-callback stacks. You also replace wait(...) by tcm.wait(...). The syntax for invoking a task function does not use "call", but please note that the "call" keyword will be added by the compiler. Here is an example of a task function:

on init
  { each callback is able to store up to 
    100 values at a time (space used for 
    parameters and local variables) }
  tcm.init(100)   
  declare x
end on

taskfunc get_random_value(min, max) -> result
  declare r
  r := random(min, max)
  tcm.wait(500000)  
  { will use right r value even if 
    the function was re-entered }
  result := r  
end taskfunc

on note
  { if another note is played 
    get_random_value may be re-entered }
  x := get_random_value(10, 40)
  message('x = ' & x)
end on
on init
  ...
end on

function _twait
  ...
end function

function get_random_value
  %p[$sp-5] := $fp
  $fp := $sp-5
  $sp := $fp
  %p[$fp+1] := random(%p[$fp+2],%p[$fp+3])
  %p[$sp-1] := 500000
  call _twait
  %p[$fp+4] := %p[$fp+1]
  $sp := $fp
  $fp := %p[$fp]
  $sp := $sp+5
end function

on note
  %p[$sp-3] := 10
  %p[$sp-2] := 40
  call get_random_value
  $x := %p[$sp-1]
  message("x = " & $x)
end on

Please note how the reference to the local variable r is changed into the stack reference %p[$fp+1]. This highlights that a local variable of a task function is stored in a place unique to each callback. A local variable of an inlined function on the other hand just gets a unique variable name but uses a global storage (hence the re-entrancy problems in that case).

By default parameters are just passed into a function and any changes to their values don't make it out. If you want a parameter to be passed both in and out you can prefix it by the keyword var. If you want it to be passed only out (as a kind of result variable where the input doesn't matter) you can prefix it by the keyword out. This syntax was copied from the Pascal programming language which KSP generally seems to be inspired by. An example:

taskfunc swap_get_max(var a, var b, out max)
  declare tmp
  tmp := a
  a := b
  b := tmp
  if a > b
    max := a
  else
    max := b
  end if
end taskfunc

An invocation of this function is compiled like this:

swap_get_max(x, y, z)
  %p[$sp-3] := $x
  %p[$sp-2] := $y
  call swap_get_max
  $x := %p[$sp-3]
  $y := %p[$sp-2]
  $z := %p[$sp-1]

Please note how $x and $y are both passed in and out of the stack system (%p) whereas $z is only passed out. Normally you would use a return value declared using the -> result syntax instead of the out keyword like this. However, out could be useful in case you want to return multiple values.

Properties

A property is a kind of pseudo variable. When you use the property name inside an expression the property reference is replaced by an invokation of the get function of the property (which is inlined). When you use the property name on the left hand side of an assignment, the set function is automatically invoked and the right hand side expression is passed as a parameter. Here is an example:

on init
  property volume
    function get() -> result
      result := get_engine_par(...
           ENGINE_PAR_VOLUME, 1, -1, -1)
    end function
    function set(value)
      set_engine_par(ENGINE_PAR_VOLUME, ...
                   value, -1, -1, -1)
    end function
  end property
      
  { invokes get function: }
  message('Volume: ' & volume)  
  
  { invokes set function: }
  volume := 500000              
end on
on init
  message("Volume: " & get_engine_par($ENGINE_PAR_VOLUME,-1,-1,-1))
  set_engine_par($ENGINE_PAR_VOLUME,500000,-1,-1,-1)
end on

You can also make properties that behave like array variables - even with more than one index. For example you can make a property that behaves as a two-dimensional array in the following way:

declare data[100]  { 10 rows, 10 columns }

property matrix
  function get(x, y) -> result
    result := data[x * 10 + y]
  end function
  function set(x, y, value)
    data[x * 10 + y] := value
  end function
end property

matrix[4, 5] := 10

If there are multiple indices they are separated by a comma as in the example above. The indices are automatically paired up with the get/set parameters from left to right. The last parameter of the set function is always the value to be set. Please note that it would be possible to pass matrix[0] (the first column) as an actual parameter to a function and then within the function add a second reference to the row.

In some cases it can enhance readability to be able to specify the indices at separate places in a name. For example, if the property in the example above instead had been named col.row, then instead of writing matrix[4, 5] one could write col[4].row[5]. The indices are moved to the end by the compiler so it would be equivalent to col.row[4, 5], only more legible in some circumstances.

Macros

The extended syntax allows you to use macros. These are in many ways similar to functions. However, whereas functions interpret the code inside the function body, eg. to support declaration of local variables, macros are used to just perform a very simple text substitution. Macros are inlined as the first compilation step. The differences between functions and macros are:

  • A macro may not invoke other macros.
  • Macro parameters can be used more freely, eg. in declare statements and as part of variable names (not inside strings however).
macro declare_button(#var#, #text#)
  declare ui_button #var#_button
  set_text(#var#_button, #text#)
end macro

on init
  declare_button(active, "Active")
end on
on init
  declare ui_button $active_button
  set_text($active_button, "Active")
end on

  • A macro definition may contain top-level constructs like callbacks and function definitions, in which case the macro may and must be invoked at the top-level (outside of callbacks/functions).

macro on_ui_control_do(#control#, #command#)
  on ui_control(#control#)
    #command#
  end on
end macro

on init
  declare ui_button active
end on

on_ui_control_do(active, message(active))
on init
  declare ui_button $active
end on

on ui_control($active)
  message($active)
end on

Hexademical numbers

The extended syntax allows you to use hexadecimal numbers if you prefix them by "0x".

x := 0xFF
x := 255

Import

It can be useful to be able to split up a script into separate files. The extended syntax allows you to bring in the functions and callbacks from such a script module using the import keyword. The following sample script imports all functions from the file "MyFunctions.txt" which is assumed to be placed in the same folder as the script importing it. This is equivalent to replacing the import line with the contents of the given file.

import "MyFunctions.txt"

It's also possible to import a module into its own namespace like this example shows. All variables then need to be prefixed with the given name followed by a dot (compare families). Importing modules this way ensures that there will be no variable name clashes with variables in the current script.

import "MyFunctions.txt" as funcs

on init
  funcs.on_init
end on

on note
  funcs.humanization_factor := 40
  funcs.randomize_note_velocity
end on

Pragma

It is possible to control how the compiler operates by using a pragma directive. On the surface it looks like a comment, but it is recognized by the compiler. At the moment there is only one use (but it may be extended in the future) - to instruct the compiler to save the compiled code in a file upon successful compilation. This is useful since it makes it easier to update the script source in Kontakt 4 which has a feature that lets you link the source code to a certain text file. Here is an example of how to have the compiler output the compiled code to a file:

on init
  {#pragma save_compiled_source D:\Program Files\Native Instruments\Kontakt 4\test.txt}
end on

For this pragma directive to have any effect the path needs to be absolute, contain both "Native Instruments" and "Kontakt 4", and end with ".txt". These conditions are safety precautions since any earlier text file with the name given will be overwritten upon compilation.

You can also make it so that some variable names are exempted from the variable name compaction/obfuscation (for example if you want to use them with the save_array() function and want the file names to be intelligible):

on init
  {#pragma preserve_names x y}
  declare x
  declare y  
  declare z  
end on
on init
  declare $x
  declare $y
  declare $js1at
end on
















[1] KONTAKT is a registered trademark of NATIVE INSTRUMENTS Software Synthesis GmbH. I am in no way affiliated with Native Instruments.