Declarations

All declarations use the declare keyword. Variables must be declared before use and exist for the script lifetime.

declare <modifiers> <type_prefix> name <dimensions> := <initial_value>

---

Variable Prefixes

Prefix	Type	Example
(none)	Integer	declare counter := 0
$	Integer (KSP native)	$my_var
~	Real (float)	declare ~amplitude := 1.0
@	String	declare @name := "Piano"
%	Integer array (KSP native)	%my_arr[10]
?	Real array (KSP native)	?my_arr[10]
!	String array	declare !names[12]

declare const ON    := 1
declare const OFF   := 0
declare const TRUE  := 1
declare const FALSE := 0

declare const ~PI := 3.14159265358979
declare const ~TAU := 6.28318530717958
declare const INT_MAX := 0x7FFFFFFF
declare const ALLMASK := 11111111111111111111111111111111b

declare rand_seed := 1107155288

---

Modifiers

const -- Compile-time constant

declare const NOTES      := 128
declare const CHANNELS   := 64
declare const ~SQRT_2    := 1.4142135623731

declare const cluster.NULL := -3214327
declare const cluster.CC_TRIGGER := 126

polyphonic -- Per-voice variable

Maintains separate values for each active voice. Only accessible within note/release callback contexts.

family ivls
    declare polyphonic key_parent_vo
    declare polyphonic play_vo
    declare polyphonic play_time
end family

declare polyphonic cluster.task_type

pers -- Snapshot-persistent

Stored in the Kontakt snapshot. Changing snapshots overrides the current session values.

declare pers my_setting := 1
declare pers %preset_data[128]

instpers -- Instrument-persistent

Stored in the current session and saved into the NKI on manual save, but not per snapshot.

declare instpers auto_preview := FALSE
declare instpers auto_load    := TRUE
declare instpers cc[midi.CHANNELS, midi.NOTES]
declare instpers save_enabled[serial.systems.SIZE] := (ON)
declare instpers ui_menu NodeUI

global -- Cross-callback accessible

declare global shared_value
declare global shared_value := 0

---

Arrays

1D Arrays

declare array_name[size]
declare array_name[size] := (initial_values)
declare array_name[] := (values)  // size inferred

declare black_keys[5] := (1, 3, 6, 8, 10)
declare !note_names[12] := ("C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B")
declare node_passes[ivls.node.SIZE] := (FALSE)

2D / 3D Arrays

declare key_down[midi.CHANNELS, midi.NOTES]
declare flows[IVLS.MAX_FLOWS, IVLS.NODES_PER_FLOW] := (-1)
declare flow_args[IVLS.MAX_FLOWS, IVLS.NODES_PER_FLOW, IVLS.ARGS_PER_NODE] := (-1)

Multi-line Initialization

declare Voice.BASE_INIT[] := (...
    -1, ... {input}
    -1, ... {runtime}
  TRUE, ... {auto_release}
    -1, ... {vo_parent}
     0, ... {volume}
     0  ... {pan}
)

---

Families (Namespace Containers)

Families group related declarations under a namespace prefix. At compilation, dots become double underscores.

family family_name
    // declarations prefixed with family_name.
end family

family midi
    declare const NOTES      := 128
    declare const CHANNELS   := 64
    declare const MIDDLE_C   := 60

    const Channel
        Omni  := -1
        Ch_1  := 0
        Ch_16 := 15
    end const

    declare key_down[midi.CHANNELS, midi.NOTES]
    declare !note_names[12] := ("C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B")
end family

// Access: midi.NOTES, midi.Channel.Ch_1, midi.key_down[0, 60]

Reopening Families

Families can be reopened to add members from different files:

family ivls
    const input_type
        VOICE_ON
        VOICE_OFF
    end const
end family

// Later:
family ivls
    const node
        literate_macro(#l#) on IVLS_ALL_NODES
    end const
    declare !node_names[ivls.node.SIZE]
    declare polyphonic key_parent_vo
end family

Nested Families

family nodes
    family Harmony
        family state
            // Accessed as nodes.Harmony.state.*
        end family
    end family
end family

---

Const Blocks (Enumerations)

Auto-numbered constants with an auto-generated SIZE constant.

const enum_name
    VALUE_1        // = 0
    VALUE_2        // = 1
    VALUE_3        // = 2
    // SIZE automatically = 3
end const

Explicit values:

const Channel
    Omni  := -1
    Ch_1  := 0
    Ch_2  := 1
end const

Generated via literate macros:

family ivls
    const node
        literate_macro(#l#) on IVLS_ALL_NODES
    end const
end family
// ivls.node.SIZE = number of nodes
// ivls.node.Stl.Math = sequential index

---

UI Control Declarations

declare ui_button name
declare ui_switch name
declare ui_knob name (min, max, step)
declare ui_slider name (min, max)
declare ui_menu name
declare ui_label name (width, height)
declare ui_panel name
declare ui_table name (width, height)
declare ui_value_edit name (min, max, step)

declare ui_panel ram_panel
declare ui_button null_widget
declare ui_switch cluster.Trigger
declare ui_knob STEPTIME (50, 400, 1)
declare instpers ui_menu NodeUI

---

Summary Table

Type	Syntax	Example
Integer	declare name	declare counter
Integer const	declare const NAME := val	declare const MAX := 128
Real	declare ~name	declare ~amplitude
Real const	declare const ~NAME := val	declare const ~PI := 3.14
String	declare @name	declare @message
String array	declare !name[size]	declare !names[10]
1D array	declare name[size]	declare buffer[100]
2D array	declare name[r, c]	declare grid[10, 10]
Polyphonic	declare polyphonic name	declare polyphonic vel
Instance-persistent	declare instpers name	declare instpers setting
Global	declare global name	declare global shared
UI control	declare ui_type name	declare ui_button Btn