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

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

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

• 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
  { 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

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

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

Macros

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_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

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

Pragma

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

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