16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 1/9

declare x := a + b + c declare $x := $a + $b + $c

Contents

Overview

Extended script syntax

Variable prefixes are optional

Parenthesis are optional for if, while and select

For-loops

Else if

Variable families

User-defined functions

Native functions

Inlined functions

Task functions

Properties

Macros

Hexademical numbers

Import

Pragma

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:

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 2/9

declare list[4]

declare @name

name := 'sustains'

declare %list[4]

declare @name

@name := 'sustains'

while x <= 10

if x = 1

select x

while (x <= 10)

if (x = 1)

select (x)

for i := 0 to 9

list[i] := 1

end for

$i := 0

while ($i <= 9)

%list[$i] := 1

inc($i)

end while

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

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

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.

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:

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

Else If

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

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

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 3/9

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

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

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

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

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.

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.

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.

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 4/9

{ 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

if ($velocity > 127)

$velocity := 127

end if

{end limit_range($velocity,1,127)}

change_velo($EVENT_ID, $velocity)

end on

function do_something {recommended syntax}

function do_something() {also allowed}

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

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

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

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:

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.

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.

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 5/9

result := a*a

end 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

on init

...

end on

function _twait

...

end function

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):

For functions which are invoked directly or indirectly from the init callback the local/global variables end up at the

point the function was invoked from the first time (any later invokations have no effect as far as variable

declarations are concerned) in the order in which the functions were invoked.

For functions which are only invoked from other callbacks than the init callback declarations of global variables are

placed at the top of the init callback and local variables at the bottom of the init callback in the order in which the

corresponding functions were defined.

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:

Invoking complex functions multiple times does not increase the size of the compiled script much (since the "call"

keyword is used under the hood)

Task functions are re-entrant (if a function is interrupted by wait a second execution of it will not override values

that are needed after the return from the wait call)

Even if the wait function is not used the script developer benefits from being able to use parameters and return

values without the significant increase to the size of the compiled code that inlined functions can result in.

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:

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 6/9

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

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

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

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]

on init

property volume

function get() -> result

result := get_engine_par(...

ENGINE_PAR_VOLUME, 1, -1, -1)

end function

on init

message("Volume: " & get_engine_par($ENGINE_PAR_VOLUME

set_engine_par($ENGINE_PAR_VOLUME,500000,-1,-1,-1)

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:

An invocation of this function is compiled like this:

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:

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 7/9

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

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

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

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($active)

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:

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).

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).

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 8/9

on init

declare ui_button active

end on

on_ui_control_do(active, message(active))

message($active)

end on

x := 0xFF x := 255

import "MyFunctions.txt"

import "MyFunctions.txt" as funcs

on init

funcs.on_init

end on

on note

funcs.humanization_factor := 40

funcs.randomize_note_velocity

end on

on init

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

end on

on init on init

Hexademical numbers

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

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.

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.

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:

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):

16/05/13 Nils Liberg's Kontakt Script Editor

nilsliberg.se/ksp/scripts/tutorial/editor.html 9/9

{#pragma preserve_names x y}

declare x

declare y

declare z

end on

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.