Variables

General Information

All user-defined variables must be declared in the on init callback.
Variable names may contain only alphanumerical characters (0-9, a-z, A-Z) and underscore (_).
Please do not create variables with the following prefixes, as these are used for internal variables and constants.
- $NI_
- $CONTROL_PAR_
- $EVENT_PAR_
- $ENGINE_PAR_
- $ZONE_PAR_
- $LOOP_PAR_

$ (integer variable)

`declare $<variable-name>`
Declares a user-defined variable to store a single integer value

Examples

on init
    declare $test
    $test := -1
end on

Creating a variable

on init
    declare $test := -1
end on

Creating a variable, similar to above, but with in-line value initialization

% (integer array)

`declare %<variable-name>[<num-of-elements>]`
Declares a user-defined array to store single integer values at specific indices

Remarks

The maximum size of arrays is 1000000 indices.
The number of elements must be defined with a constant value, variables cannot be used for this purpose.
It is possible to initialize an array with one value - refer to the second example below.

Examples

on init
    declare %presets[10 * 8] := ( ...
    {  1 }  8, 8, 8, 0,  0, 0, 0, 0, ...
    {  2 }  8, 8, 8, 8,  0, 0, 0, 0, ...
    {  3 }  8, 8, 8, 8,  8, 8, 8, 8, ...
    {  4 }  0, 0, 5, 3,  2, 0, 0, 0, ...
    {  5 }  0, 0, 4, 4,  3, 2, 0, 0, ...
    {  6 }  0, 0, 8, 7,  4, 0, 0, 0, ...
    {  7 }  0, 0, 4, 5,  4, 4, 2, 2, ...
    {  8 }  0, 0, 5, 4,  0, 3, 0, 0, ...
    {  9 }  0, 0, 4, 6,  7, 5, 3, 0, ...
    { 10 }  0, 0, 5, 6,  4, 4, 3, 2  )
end on

Creating an array for storing preset data

on init
    declare %presets[10 * 8] := (4)
end on

Quick way of initializing the same array with a specific value

~ (real variable)

`declare ~<variable-name>`
Declares a user-defined variable to store a single real value

Remarks

Real numbers must always be defined with a decimal point, even if the number is a whole number. For example 2.0 should be used instead of only 2.

Examples

on init
    declare ~test
    ~test := 0.5
end on

Creating a variable

on init
    declare ~test := 0.5
end on

Creating a variable, similar to the above, but with in-line value initialization

? (real array)

`declare ?<variable-name>[<num-of-elements>]`
Declares a user-defined array to store single real values at specific indices

Remarks

The maximum size of arrays is 1000000 indices.
The number of elements must be defined with a constant integer value, regular variables cannot be used for this purpose.
It is possible to initialize an array with one value - refer to the second example below.
The commands array_equal() and search() do not work with real arrays.

Examples

on init
    declare ?presets[5 * 4] := ( ...
    { 1 }   1.0, 1.0, 1.0, 1.0, ...
    { 2 }   0.5, 0.7, 0.1, 0.5, ...
    { 3 }   1.0, 0.6, 0.6, 0.2, ...
    { 4 }   0.0, 0.0, 0.5, 0.3, ...
    { 5 }   0.0, 1.0, 0.4, 0.1  )
end on

Creating an array for storing preset data

on init
    declare ?presets[10 * 8] := (1.0)
end on

Quick way of initializing the same array with a specific value

@ (string variable)

`declare @<variable-name>`
Declares a user-defined string variable to store text

Remarks

You cannot declare and in-line initialize a string variable as you can with an integer variable.
The maximum length of text that can be stored in a string variable is 320 characters.

Examples

on init
    declare @text
    @text := "Last received note number played or released: "
end on

on note
    message(@text & $EVENT_NOTE)
end on

on release
    message(@text & $EVENT_NOTE)
end on

Use string variables to display long text

! (string array)

`declare !<array-name>[<num-of-elements>]`
Declares a user-defined string array to store text strings at specified indices

Remarks

The maximum size of arrays is 1000000 indices.
Just like with string variables, the contents of a string array cannot be in-line initialized on the same line as the declaration.
The maximum length of a string at any given indice is 320 characters.
Please be aware that large string arrays with long strings can require a lot of memory if they are made persistent (roughly, one character = 1 byte, 320 characters = 320 bytes, 1000000 strings with 320 characters = 305 megabytes)

Examples

on init
    declare $count

    declare !note[12]
    !note[0] := "C"
    !note[1] := "C#"
    !note[2] := "D"
    !note[3] := "D#"
    !note[4] := "E"
    !note[5] := "F"
    !note[6] := "F#"
    !note[7] := "G"
    !note[8] := "G#"
    !note[9] := "A"
    !note[10] := "Bb"
    !note[11] := "B"

    declare !name [128]

    while ($count < 128)
        !name[$count] := !note[$count mod 12] & (($count / 12) - 2)

        inc($count)
    end while
end on

on note
    message("Note played: " & !name[$EVENT_NOTE])
end on

Creating a string array with all MIDI note names

const $ (constant integer)

`declare const $<name>`
Declares a user-defined constant to store a single integer value

Remarks

As the name implies, the value of constant variables can only be read, not changed.
It is quite common (and recommended) to write the names of constants with all capitals.

Examples

on init
    declare const $NUM_PRESETS := 10
    declare const $NUM_PARAMETERS := 5

    declare %preset_data[$NUM_PRESETS * $NUM_PARAMETERS]
end on

Creating constants – useful when creating preset arrays

const ~ (real constant)

`declare const ~<name>`
Declares a user-defined constant to store a single real value

Remarks

As the name implies, the value of constant variables can only be read, not changed.
It is quite common (and recommended) to write the names of constants with all capitals.

Examples

on init
    declare const ~BIG_NUMBER := 100000.0
    declare const ~SMALL_NUMBER := 0.00001
end on

polyphonic $ (polyphonic integer)

`declare polyphonic $<variable-name>`
Declares a user-defined polyphonic variable to store a single integer value per note event

Remarks

A polyphonic variable acts as a unique variable for each executed note event, avoiding conflicts in callbacks that are executed in parallel, for example when using wait().
A polyphonic variable retains its value in the release callback of the corresponding note.
Polyphonic variables need much more memory than normal variables (since the note event queue in KONTAKT supports a maximum of 8192 events, 32 bits * 8192 = 32 kilobytes).
Polyphonic variables can only be used within note and release callbacks.

Examples

on init
    declare polyphonic $a
    { declare $a }
end on

on note
    ignore_event($EVENT_ID)

    $a := 0
    while ($a < 13 and $NOTE_HELD = 1)
        play_note($EVENT_NOTE + $a, $EVENT_VELOCITY, 0, $DURATION_QUARTER / 2)

        inc($a)

        wait($DURATION_QUARTER)
    end while
end on

To hear the effect of the polyphonic variable, play and hold an octave: both notes will ascend chromatically. Then make $a a normal variable and play the octave again: $a will be shared by both executed callbacks, thus both notes will ascend in larger intervals.

on init
    declare $counter
    declare polyphonic $polyphonic_counter
end on

on note
    message($polyphonic_counter & "  " & $counter)
    inc($counter)
    inc($polyphonic_counter)
end on

Since a polyphonic variable is always unique per callback, $polyphonic_counter will always be 0 in the displayed message

make_instr_persistent()

`make_instr_persistent(<variable>)`
Retains the value of a variable within the instrument only

Remarks

make_instr_persistent() is similar to make_persistent(), however the value of a variable is only saved with the instrument, not with snapshots. It can be used to prevent UI elements from being changed when loading snapshots.

Examples

on init
    set_snapshot_type(1)    { init callback not executed upon snapshot loading }

    declare ui_knob $knob_1 (0, 2, 1)
    set_text($knob_1, "Pers")
    make_persistent($knob_1)

    declare ui_knob $knob_2 (0, 2, 1)
    set_text($knob_2, "Inst Pers")
    make_instr_persistent($knob_2)

    declare ui_knob $knob_3 (0, 2, 1)
    set_text($knob_3, "Not Pers")
end on

The second knob will not be changed when loading snapshots

make_persistent()

`make_persistent(<variable>)`
Retainsy the value of a variable with the instrument and snapshot

Remarks

The state of the variable is saved not only with the instrument (or multi or host chunk), but also when a script is saved as a KONTAKT preset (.nkp file).
The state of the variable is read at the end of the init callback. To load a stored value manually within the init callback, insert read_persistent_var(<variable>) before using the stored value.
You can also use the on persistence_changed callback for retrieving the values of persistent variables
When updating script code by replacing old code with new one, the values of persistent variables that have identical names will be retained.
Sometimes, when working on more complex scripts, you might want to flush the values of persistent variables by resetting the script. You can do this by loading the - INIT Script - preset from the Script Editor's Preset menu, then applying your code again.

Examples

on init
    declare ui_knob $Preset (1, 10, 1)
    make_persistent($Preset)
end on

User interface elements, such as knobs, should usually retain their value when reloading the instrument

read_persistent_var()

`read_persistent_var(<variable>)`
Instantly reloads the value of a variable that was saved via the `make_persistent()` command

Remarks

This command can only be used within the init callback.
You can also use the on persistence_changed callback for retrieving the values of persistent variables.

Examples

on init
    declare ui_label $label (1, 1)
    declare ui_button $button
    set_text($button, "$a := 10000")

    declare $a
    make_persistent($a)
    { read_persistent_var($a) }
    set_text($label, $a)
end on

on ui_control ($button)
    $a := 10000
    set_text($label, $a)
end on

After applying this script, click on the button and then save and close the NKI. After reloading it, the label will display 0 because the value of $a is initialized at the very end of the init callback. Now remove the {} around read_persistent_var and apply the script again to see the difference read_persistent_var() imparts.

watch_var()

`watch_var(<variable>)`
Sends an event to the Creator Tools KSP Log for every change of the watched variable’s value

Remarks

This command can only be used within the init callback.
This command has no effect on KONTAKT’s status bar – the events only appear in Creator Tools.
This command does not work with built-in variables ($ENGINE_UPTIME, $NOTE_HELD, $KSP_TIMER, etc.)

Examples

on init
    declare $intVar

    watch_var($intVar)
    make_persistent($intVar)
end on
 
on note
    $intVar := $EVENT_VELOCITY 
end on

Try playing some notes while having Creator Tools running. Make sure you have the KSP Variables or KSP Log panel focused.

watch_array_idx()

`watch_array_idx(<array>, <array_idx>)`
Sends an event to the Creator Tools KSP Log for every change of the watched array index’s value

Remarks

This command can only be used within the init callback.
This command has no effect on KONTAKT’s status bar – the events only appear in Creator Tools.
This command does not work with built-in array variables (%KEY_DOWN, %CC, %EVENT_PAR, etc.)

Examples

on init 
    declare %mykeys[128]

    watch_array_idx(%mykeys, 60)
    watch_array_idx(%mykeys, 61)
    watch_array_idx(%mykeys, 62)
    watch_array_idx(%mykeys, 63)
    watch_array_idx(%mykeys, 64)
    
    declare ui_button $Save
    declare ui_button $Load
end on
 
on note 
    %mykeys[$EVENT_NOTE] := $EVENT_VELOCITY
end on
 
on ui_control($Save)
    save_array(%mykeys, 0)
end on
 
on ui_control($Load)
    load_array(%mykeys, 0)
end on

Try playing some notes or clicking on the save and load buttons while having Creator Tools running. Make sure you have the KSP Variables or KSP Log panel focused.

Variables

General Information

$ (integer variable)

Examples

See Also

% (integer array)

Remarks

Examples

See Also

~ (real variable)

Remarks

Examples

See Also

? (real array)

Remarks

Examples

See Also

@ (string variable)

Remarks

Examples

See Also

! (string array)

Remarks

Examples

See Also

const $ (constant integer)

Remarks

Examples

See Also

const ~ (real constant)

Remarks

Examples

See Also

polyphonic $ (polyphonic integer)

Remarks

Examples

make_instr_persistent()

Remarks

Examples

See Also

make_persistent()

Remarks

Examples

See Also

read_persistent_var()

Remarks

Examples

See Also

watch_var()

Remarks

Examples

watch_array_idx()

Remarks

Examples

Search results