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

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:

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

nilsliberg.se/ksp/scripts/tutorial/editor.html 1/9
16/05/13 Nils Liberg's Kontakt Script Editor
declare list[4] declare %list[4]
declare @name declare @name
name := 'sustains' @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 while (x <= 10)

if x = 1 if (x = 1)
select x 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 $i := 0
list[i] := 1 while ($i <= 9)
end for %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 $i := 9

list[i] := 1 while ($i >= 0)
end for %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 if ($x = 1)
{...} {...}
else if y = 1 else
{...} if ($y = 1)
else if z = 1 {...}
{...} else
end if 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

nilsliberg.se/ksp/scripts/tutorial/editor.html 2/9
16/05/13 Nils Liberg's Kontakt Script Editor
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 on init
family keyswitch {family keyswitch}
declare current declare $keyswitch__current
declare const N := 10 declare const $keyswitch__N := 10
declare keys[keyswitch.N] declare %keyswitch__keys[$keyswitch__N]
end family end on
end on
on note
on note $keyswitch__current := search(%keyswitch__keys,
keyswitch.current := search(keyswitch.keys, $EVENT_NOTE)
EVENT_NOTE) end on
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 on init
declare velocity declare $velocity
end on end on

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

nilsliberg.se/ksp/scripts/tutorial/editor.html 3/9
16/05/13 Nils Liberg's Kontakt Script Editor
{ forces value to be between min and max } if ($velocity > 127)
function limit_range(value, min, max) $velocity := 127
if value < min end if
value := min {end limit_range($velocity,1,127)}
end if change_velo($EVENT_ID, $velocity)
if value > max end on
value := max
end if
end function

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 on init
declare x := 1 declare $x := 1
declare y := 5 declare $y := 5
swap(x, y) declare $_tmp
end on {begin swap($x,$y)}
$_tmp := $x
function swap(a, b) $x := $y
declare tmp $y := $_tmp
tmp := a {end swap($x,$y)}
a := b end on
b := tmp
end function

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 on init
declare x := 1 declare $x := 1
declare y := 5 declare $y := 5
declare z declare $z
z := max(x, y) if ($x>$y)
message(1 + square(y)) $z := $x
end on else
$z := $y
function max(a, b) -> result end if
if a > b message(1 + $y*$y)
result := a end on
else
result := b
end if
end function

function square(a) -> result

nilsliberg.se/ksp/scripts/tutorial/editor.html 4/9
16/05/13 Nils Liberg's Kontakt Script Editor
result := a*a
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:

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

nilsliberg.se/ksp/scripts/tutorial/editor.html 5/9
16/05/13 Nils Liberg's Kontakt Script Editor
taskfunc get_random_value(min, max) -> result function get_random_value
declare r %p[$sp-5] := $fp
r := random(min, max) $fp := $sp-5
tcm.wait(500000) $sp := $fp
{ will use right r value even if %p[$fp+1] := random(%p[$fp+2],%p[$fp+3])
the function was re-entered } %p[$sp-1] := 500000
result := r call _twait
end taskfunc %p[$fp+4] := %p[$fp+1]
$sp := $fp
on note $fp := %p[$fp]
{ if another note is played $sp := $sp+5
get_random_value may be re-entered } end function
x := get_random_value(10, 40)
message('x = ' & x) on note
end on %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 on init
property volume message("Volume: " & get_engine_par($ENGINE_PAR_VOLUME
function get() -> result set_engine_par($ENGINE_PAR_VOLUME,500000,-1,-1,-1)
result := get_engine_par(... end on
ENGINE_PAR_VOLUME, 1, -1, -1)
end function

nilsliberg.se/ksp/scripts/tutorial/editor.html 6/9
16/05/13 Nils Liberg's Kontakt Script Editor
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

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#) on init

declare ui_button #var#_button declare ui_button $active_button
set_text(#var#_button, #text#) set_text($active_button, "Active")
end macro end on

on init
declare_button(active, "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 init

on ui_control(#control#) declare ui_button $active
#command# end on
end on
end macro on ui_control($active)

nilsliberg.se/ksp/scripts/tutorial/editor.html 7/9
16/05/13 Nils Liberg's Kontakt Script Editor
message($active)
on init end on
declare ui_button active
end on

on_ui_control_do(active, message(active))

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 on init

nilsliberg.se/ksp/scripts/tutorial/editor.html 8/9
16/05/13 Nils Liberg's Kontakt Script Editor
{#pragma preserve_names x y} declare $x
declare x declare $y
declare y declare $js1at
declare z end on
end on

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

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