ksp

Last modifiedby & filed under Kontakt Scripting (KSP) - Basics, UIs, Tutorials, Scripts and Tools, Kontakt Scripting (KSP) :: Sublime Text.

this article explains everything about advanced user defined functions in sublime text. The basic syntax, how to use them with mixed arguments, how to declare local variables and how to return values.
It also shows the differences between classic and advanced functions.


1. Content

  1. What is an advanced and what is a classic function?

  2. advanced functions explained

  3. demos

  4. Classic vs Advanced

Note: all the code below doesn’t work if you put it into Kontakt as is. It first needs to be compiled with sublime text!


What is an advanced Function and what is a classic function?

Actually the terms classic and advanced function are just used here to differenciate between the standard KSP functions and functions with more features, which are only available in Subline Text. For example with advanced functions we can use mixed arguments, local variables and also call them inside the on init. See a summary of all the advantages of advanced functions below.

So again please consider in this context that all the code here needs to be compiled with sublime text first (F5 Key) before you can use it with Kontakt.
Learn more about installing sublime text and using it for the first time

advanced user defined functions explained

syntax: declaring an advanced function Without ARGUMENTS

function <function_name>
  message("advanced user defined function")
end function
on init
  //.......
end on

Declaring an advanced function without arguments works exactly like declaring classic functions.
But we can declare the function anywhere we want throughout our code, even before the on init. See the example below

syntax: Calling an advanced function Without ARGUMENTS

call <function_name>
// or just the function name without "call" expression
on init 
  <function_name>
end on

Calling an advanced function without arguments works exactly like calling a classic function.

However we can also call an advanced function before it has been declared or inside the on init callback.
To call them inside the on init we have to omit the “call” expression. See the example below

Example (only works with sublime text):

function advanced_function // a function can be declared anywhere throughut the code even before the on init, however this is not always recommended
  message("I can also be called inside the on init callback")
  if($clear_message = 1) //if the "clear_message" button is hit, this will clear the message again
    message("")
  end if
end function

on init 
  declare ui_button $clear_message
  advanced_function //when calling a function inside the on init, the "call" expression must be omitted
end on

on ui_control($clear_message)
  call advanced_function //if a function without arguments is called regularly, the "call" expression can be used again, but this is not mandatory
  $clear_message := 0  //sets the clear_message button to its off state again
end on

syntax: declaring an advanced function with arguments

function <function_name> ([arg1, arg2, arg3,...])
  message(arg1 & arg2 & arg3) 
end function
  • arguments can be of any type like int, string, real or arrays. They can also be mixed. Also see mixed arguments
  • it is not allowed to use any var-type prefix for the arguments (like $,@,~). The argument type is automaticaly defined by the values or arrays that are passed to the function. Therefore it can be useful to work with clear argument names like intArg1, strArg2, realArg3. Also see the example below
    //declaring a function with arguments like this wont work:
    function my_function($int1,$int2) //defining argument types by adding any $,@,~,%,!,? prefix will cause an error
      message($int1 * $int2)
    end function
    
     //instead declare it like this:
     function my_function(int1,str1,real1)
      message(str & int_to_real(int1) + real1)
    end function

syntax: CALLING an advanced function with arguments

on init
  my_function($param1, $param2, $param3)
end on

on ui_control $button
  my_function($param1, $param2, $param3)
end on
  • to call functions with arguments omitt the “call” expression, otherwise Sublime Text will produce an error when compiling.
  • advanced functions can be called anywhere. For example inside the on init callback or before the function has been declared (see example)

NOTE: when calling the function we can pass any variables or arrays with their prefixes like $param1,@param2, %param3,…. (also see below fucntions with mixed arguments)

Example: function with arguments (only works with sublime text):

on init
  declare ui_slider $slider (0, 10)
  my_function(4,3) //this will just multiply 4 by 3 on init, so the output is 12. Also the arguments get defined as integer arguments here, since integer parameters are passed here the first time
end on

on ui_control($slider)
  my_function($slider,100000) //this will convert the 0 to 10 value scale, sent by the slider, to the default Kontakt value scale from 0 to 1.000.000
end on

function my_function(int1,int2) //clear names are used for the arguments to classify them as integer arguments. Only visually though, keep in mind that they are no integer arguments yet, only when calling the function the first time!
  message(int1 * int2)
end function

Note: to simplify matters, this function only outputs the values directly as a message. For a real use case, we can for example return the converted values to pass them to another function e.g. to call set_engine_par().
Also see the 3rd demo below

“local” variables – declaring varibales inside functions (without decalring them inside the on init)

free premium content

How useful was this article?

something you didn't like? Please tell us before you rate!

Average rating / 5. Vote count:

No votes so far! Be the first to rate this post.

We are sorry that this post was not useful for you!

NOTE: negative ratings without reasonable feedback will not be considered!

Tell us how we can improve this post?

Leave a Reply

use <pre> </pre> to wrap code blocks

use <code> </code> to wrap small code snippets

use basic html to style your comment

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