Last modifiedby & filed under KSP Scripting (NI Kontakt) - Tutorials, KSP: UI (design) & Engine.

in this tutorial we will create “animated” buttons for Kontakt 5 or 6 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 (2nd 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 graphical button fx like shadows or glowing button borders etc. So whenever you have some transparent areas around your button. May sound confusing now but if you keep on reading you will get that.

If your button is done you specify the actual button  size i(or button area) n the Kontakt Script Editor. But only of the actual button not the image size holding your six states. 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 whole 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.

1. Create the first button image

Button Raw

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

When your button is done, create a new (gimp, photoshop,..) file with the width of the button area and with a height of 6 times the button area.In this case the new blank file has width = 180px; and height = 192px.

Now we copy the whole button into that new file including all its layers like shadows, glow fx, texture & text layers etc. And duplicate it 6 times.

We now align each button vertically exactly under the previous one (learn more below)

button_w_shadowButton Area2. Aligning button states vertically

Now we copy our button vertically. Again, every button area has to be of the exact same height in pixels. Furthermore the button has to “sit” in that erae at the exact. same position. Otherwise it would move around when the different button states are called. But since you duplicated your parent button you should be good.

On the other hand there are situations were we exactly want the button to move around e.g to simulate a 3D push effect. This is also shown in this example.

NOTE: if you are working with shadows or glow effects you probably have a transparent or half transparent area around your button. Aligning those buttons vertically, can get a little challenging since we won’t be able to see the actual button boundaries (since they are transparent). We can either count the transparent pixels around the button or we can add a rectangle around the button to mark the button area around our button as a guidance. This is also shown in the second image.

In our graphics software we put everything into a layer group / folder so that we can simply copy all the layers belonging to our button at once .. including the important rectangle area guidance. We then just need to duplicate that folder to create a layer group and align the duplicated layer group vertically 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 like shown. When done save the file as png and copy it into the resource folder of your instrument.

Well done you did your first sprite sheet by the way.

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.

        {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

How useful was this article?

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: highly negative votes may be removed without any reasonable given feedback!

Tell us how we can improve this post?

11 Responses to “Kontakt Scripting (KSP) :: Custom UI :: Button Animations (on, off, pressed, mouse over states) – Kontakt 6, 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) play_note(note_number,velocity,sample_offset,duration) 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?! try: 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

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

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

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