Posted by & filed under KSP Scripting (NI Kontakt) - Tutorials, KSP: Custom UI (design).

in this tutorial we will create “animated” buttons for Kontakt 5 with the following states:

  • off
  • on
  • pressed off
  • pressed on
  • mouse hover off
  • mouse hover on

Download all files to this tutorial

  • Open Resource Container: Buttons, Wallpaper
  • NKI file: the working script



  1. creating the first button image
  2. aligning button states vertically
  3. the text file
  4. sript – (user interface) declaring the button


Button Animation StatesButton AreaIntroduction

Actually the button animation simply works by the button image itself. The image just needs to hold all button states exactly copied vertically one after another. Thereby every button or button area (right picture) has to be of the exact same height in pixels. Of course the actual button can be of any hight you want. Only the button areas or the copies of your button states have to be of the same height. This gets very important when working with button shadows or glowing buttons etc, whenever you have some transparency around your button. Sounds confusing now but if you keep on reading you will get that.

If your button is done in the Kontakt Script you specify the actual button size only (not the image size) which is in this case width: 180px  and height:32px. Kontakt will automatically display the current button state of the image then. Note these are the dimensions of the button area the button itself is smaller as you can see. We have to keep that in mind when it comes to placing the button inside the UI.

Button Raw1. Create the first button image

Simply create a button with your favorite graphic tool (like gimp, photoshop, illustrator, whatsoever). You are completely free here. Just make sure your button looks good with a png file. Also already think of how you would like to realize the different button states eg. a glow effect for the mouse hover states maybe?!

Once your button is done it is recommended to create a new (gimp, photoshop,..) file with the width of the button area and the height of 6 times the button area height. In this case width = 180px; height = 192px. Now we copy the whole button into that file including all its layers like shadows, glow fx, texture & text layers etc.

button_w_shadowButton Area2. Aligning button states vertically

Now you copy your button vertically. As said every button area has to be of the exact same height in pixels. In this area the button has to “sit” at the same position. Otherwise it would move around when the different states are called through Kontakt. Of course we can also use this to create a 3D push effect like in this example.

If you are working with shadows or glow effects you probably have a transparent or half transparent area around your button. Copying those buttons vertically, can get a little challenging since we won’t be able to see the actual button boundaries (when they are transparent). We can either count the transparent pixels around the button or we can add a rectangle around the button which represents the button area and serves as mask or measurement guidance. Like shown in the second image. In our graphics software (gimp, photoshop) we put everything into a layer group / folder. Then we can simply copy the whole group including the rectangle, button, shadows etc. and put it exactly below the previous layer group.

Now you can edit the individual states (off, on, pressed, mouse over) like adding a glow effect for all “on” states or moving the button within you button area rectangle to simulate a 3D push effect. When done save the file as png and copy it into the resource folder of your instrument

3. The text file

we now create the text file. As with knobs and other graphic elements we also have to copy this text file into the “Resources/pictures” folder. The text file has to have the same file name as the button image. It is required and gives Kontakt extra information about your image like how many animations we use (in this case 6). Use a simple text editor, and copy & paste the following lines:

Has Alpha Channel: yes 
Number of Animations: 6
Horizontal Animation:  no
Vertical Resizable: no
Horizontal Resizable: no
Fixed Top: 0
Fixed Bottom: 0
Fixed Left: 0
Fixed Right:  0

4. Script – (user interface) declaring the button

We don’t have to do any special coding for the animation. We simply declare a button and edit all the usual parameters like the button width, height, position and we assign our image file. If we have set up the text file correctly with 6 animations Kontakt does the rest for us.

set the UI specs.

on init
    {INIT UI}
    declare const $UI_HEIGHT := 164

    set_script_title("Button Animation")

we now declare the button and set its width, height, position and its image. The width and height have to match one button area dimensions (not your actual image dimensions).

So in this case the correct button height we would define in KSP is 32px (whereas the complete image height is 6 x 32px = 192px)
Unfortunately we have to add one pixel then since Kontakt is cutting 1px for some reason. So use 33px instead. Same with the width which is 109px in Kontakt. Actually I don’t know the purpose of this.

    {BUTTON 1}
        {decalre const}
        declare const $BTN1_X := 108+1
        declare const $BTN1_Y := 32+1

        declare ui_button $button1
        move_control_px($button1,(632-$BTN1_X)/2,($UI_HEIGHT-$BTN1_Y)/2-16) {position: center button}
end on

Any Questions? Use the comments below


11 Responses to “Kontakt Scripting (KSP) :: Custom UI – Button Animations (on, off, pressed, mouse over states) – Kontakt 5, User Interface”

  1. Dwight

    The issue I’m having is when I insert my custom button and trigger it with a note, it shows all 6 frames at once. Even though I’ve specified the button size. what am I doing wrong?

    • YummyBeats

      Have you put the correct text file into your pictures folder? The number of animations needs to be exactly 6 for a button (see instructions above)

      Although I beleive this is not the actual problem here: did you keep the exact same distances from one button state to another with your button image? (see the example above) Kontakt devides the total height of your button image by 6 and thats the height of one button state then.

      How do you trigger your button actually inside the note on? Maybe you wanna use a label with an overlayed transparent button instead? So that you have more control over the picture states. See this animation tutorial

  2. James

    Hi, thanks very much for the tutorial!
    On line 3 of the {button 1} part, should that number be 180? My button kept cutting off till I changed that!

    • YummyBeats

      EDIT : Sorry I totally got you wrong first .. the 108 (or 109 to be more precisely) should be fine. The image width is 108px so I actually don’t know why it gets cropped with your setup?!
      Did you use another image file or resize this one?

      I don’t know if this is a bug with Kontakt or if it has any purpose but yes, you may need to add one more pixel to your actual image size.
      In this case it’s 108+1 or 32+1. The +1 was just used to point out this issue more clearly. Of course you can also do $BTN1_X := 109 and don’t need to do this extra addition.

  3. Royd

    Please help. How to make a ui button invisible ? Or how to create an area on gui that will playback oneshot sample on mousecklick?

    • YummyBeats

      To hide a button (or any other ui element) use:
      set_control_par(button_id, $CONTROL_PAR_HIDE, $HIDE_WHOLE_CONTROL)
      Also read this article. It shows how it works in detail, plus you can download the script:

      to playback a sample via button use this:
      on ui_control ($button)
      end on

      • Royd

        I have read “ksp reference manual” . I already tried “set_control_par”, but the button is still visible :( that’s why I decided that I was doing something wrong. I thought that maybe there’s some other method . however, the button works as I need, just still visible . well, I’m going to try again . thanks for the answer.)))

        • YummyBeats

          probably you did not use the ui_id but the button variable?!
          set_control_par(get_ui_id($button_name), $CONTROL_PAR_HIDE, $HIDE_WHOLE_CONTROL)

          • Royd

            I found a bug in my script , but when the button is invisible, its playback function is unavailable too . the button just becomes inactive. but I want to make the interface similar to “ni studio drummer” . something like click on a snare and the snare drum sample is played .

          • YummyBeats

            Actually a function doesn’t get inactive when hiding a ui element. Of course you can’t execute the function anymore with hidden elements. Probably u wanna make an invisible but not hidden button? To do so just use a transparent image as background image for the button. And eg a label for the actual background if needed.

Leave a Reply

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