Skip to main content
  • KSP Reference Manual
  • Variables

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, 32-bit signed integer value.

Remarks

  • Valid numbers that can be stored in an integer variable are in range -2147483648 ... 2147483647.

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.

See Also

on init

make_persistent()

read_persistent_var()

real()

int()

% (integer array)

declare %<variable-name>[<num-of-elements>]

Declares a user-defined array to store multiple 32-bit signed 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.

  • If initializing an array with several values, but number of initializers is less than array size, the last initializer will be used to initialize the rest of the array.

  • Valid numbers that can be stored in an integer array are in range -2147483648 ... 2147483647.

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.

See Also

Array Commands

Group Commands

make_persistent()

~ (real variable)

declare ~<variable-name>

Declares a user-defined variable to store a single, 64-bit (double precision) 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.

  • Decimal digit may be omitted. For example 2. is valid and means the same thing as 2.0

  • Scientific notation is supported. For example, 1.25e5 or 2.76e-3. e can be lowercase or uppercase.

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.

See Also

on init

make_persistent()

read_persistent_var()

real()

int()

? (real array)

declare ?<variable-name>[<num-of-elements>]

Declares a user-defined array to store multiple 64-bit (double precision) 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.

  • If initializing an array with several values, but number of initializers is less than array size, the last initializer will be used to initialize the rest of the array.

  • array_equal() and search() commands 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.

See Also

Array Commands

Group Commands

make_persistent()

@ (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.

See Also

! (string array)

ui_text_edit

make_persistent()

! (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.

See Also

@ (string variable)

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 in uppercase.

  • Valid numbers that can be stored in an integer constant are in range -2147483648 ... 2147483647.

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.

See Also

on init

const ~ (real constant)

declare const ~<name>

Declares a user-defined constant to store a single, 64-bit (double precision) 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 in uppercase.

Examples

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

Just a couple of real constants, man.

See Also

on init

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 on release callback of the corresponding note.

  • Polyphonic variables need much more memory than regular 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.

See Also

read_persistent_var()

make_persistent()

set_snapshot_type()

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,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() 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.

See Also

read_persistent_var()

on persistence_changed

make_instr_persistent()

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 on 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 comment around read_persistent_var and apply the script again to see the difference.

See Also

make_persistent()

on persistence_changed

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 on 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 on 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.