premium article

Posted by & filed under KSP Scripting (NI Kontakt) - Tutorials, KSP: Sublime 3.

in this tutorial we will work with sublime 3 and macros. A macro works almost like a function. You have to call it like a function and you can use arguments and pass variables to alter or individualize several parameters inside. But instead of returning any values or executing any code, a macro is “printing” the whole code inside it whenever and wherever it gets called. So we can use macros to even create functions, callbacks or any other code. At best whenever we got similar code patterns so that we don’t have to write the same lines of code again and again.
In the second part of this article we build a small synth with one FX using several kind of macros to create 4 fully functional knob units.

Download all files to this tutorial

  • working synth with a nice retro lead (sampled)
  • Open Resource Container: all image files
  • NKI & KSP file: the working script


1. Content

  1. introduction

  2. macro basics (how macros work)

  3. advanced macro handling [premium]

1. Introduction

first we learn how macros basically work and in the second part (premium) we use them to create a fully functional line of knobs to control a FX. Each knob will be framed by 2 labels (above and below) holding the knobs name and the knob’s values. Another macro will be used for the “on ui_control” callback.

2. macro basics

First open and “prepare” Sublime 3 if you haven’t done yet. Read more here

since we can place the macro code anywhere we want, we will write the macro first and then the on init callback.

Sometimes we may need global variables from outside the macro. As we can only declare them inside the on init callback we should declare all new variables immediately as soon as we are using them so that we don’t lose track of them.

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

declare macros like a function

this example outputs “$c is now 10”

macro my_macro (#a#,#b#) // #a# and #b#b are arguments we use to pass values into the macro, the # is an obligation 
     //any code in here will be printed where the macro gets called
     $c := #a# + #b# //$c is a global variable which has to be declared inside the on init callback before we call the macro.
     message("$c is now " & $c)
end macro

on init
     declare $c //make sure you declare $c before calling the macro
     my_macro(3,7) //this calls the macro passing 3 and 7
end on

So it is pretty simple we can use macros to declare other functions or callbacks like “on ui_control” and use it to create all kinds of code elements we can imagine

this macro creates a slider with a custom image and also positions it

macro declare_knob (#name#,#posx#,#posy#,#width#,#height#,#image#)
    declare ui_slider $knob_#name#(0,1000000)
    $knob_#name# -> width := #width#
    $knob_#name# -> height:= #height#
    $knob_#name# -> pos_x:= #posx#
    $knob_#name# -> pos_y:= #posy#
    $knob_#name# -> text := ""
    $knob_#name# -> default_value := 1000000 / 2
    $knob_#name# -> mouse_behaviour := -400
    $knob_#name# -> picture := "#image#"
end macro
on init

     //declare_knob (#name#,#posx#,#posy#,#width#,#height#,#image#)
end on

as each knob (or slider) has the exact same code pattern we can bundle them into one macro. All individual parameters like position and size can be passed. We can then call the macro in the on init callback as many times as we want and create many many knobs in no time with only one line of code for each knob.

3. The advanced usage of macros

now that we understand macros we can proceed to a more complex example and declare multiple ui elements and  on ui_control callbacks.
We will create a group of several knobs to control the LoFi FX. One group holds several knob units containing a top label, the knob itself and a sub label for the knob’s value (see image). Whereas the bottom label will display the current knob’s value when turning the knob. On release it falls back to the original label.

premium content


Leave a Reply

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