Special Syntax and Miscellaneous Features¶

File Inclusion¶

`import`¶

Includes external KSP files or directories into your script:

import "_IVLS/std-library/std-lib.ksp"
import "_IVLS/std-library/ksp/data-structures/adt.ksp"
import "_IVLS/std-library/nodes/components/"     // all .ksp files in directory

Paths are relative to the project root
Both " and ' quotes supported
Directory imports (trailing /) include all .ksp files

Computed Properties¶

Properties provide getter/setter access, enabling the Type[ref].field syntax:

property property_name
    function get(params) -> result
        result := computed_value
    end function
    function set(params, value)
        // setter logic
    end function
end property

Examples¶

property par
    function get(dims) -> result
        result := Engine.data[dims]
    end function
    function set(dims, value)
        Engine.par_cb(dims, -1, value, FALSE, TRUE)
        Engine.update_ctrl_value(dims)
    end function
end property

property EMCache.adds
    function get(ref, param) -> result
        result := EMCache[ref].i[param * 2]
    end function
    function set(ref, param, value)
        EMCache[ref].i[param * 2] := value
    end function
end property

Coroutine Waits (TCM)¶

The Task Coroutine Manager provides non-blocking waits within taskfunc contexts:

Function	Description
`tcm.wait(microseconds)`	Wait by time
`tcm.wait_ticks(ticks)`	Wait by MIDI ticks

tcm.wait(UI.PARAM_DISP_DELAY_MS * 1000)
tcm.wait_ticks(step_length)

Legacy Waits¶

Standard KSP waits for callback contexts (blocking):

Function	Description
`wait(microseconds)`	Pause callback
`wait_ticks(ticks)`	Pause by MIDI ticks

wait(keymap.key_latency_us[keymap.selected_map, EVENT_NOTE])
wait_ticks(ivls.RELEASE_EXTENSION_TICKS)
wait(DURATION_SIXTEENTH / 8)

UI Property Access (`->`)¶

The arrow operator accesses UI control properties:

control_name -> property := value
variable := control_name -> property

Property	Description
`text`	Display text
`hide`	Visibility (`HIDE_WHOLE_CONTROL`, `HIDE_PART_NOTHING`, `HIDE_PART_BG`)
`x`, `y`	Position
`width`, `height`	Dimensions
`value`	Current value
`parent_panel`	Parent container
`z_layer`	Stacking order
`font_type`	Font
`picture`	Background image
`allow_automation`	DAW automation
`key_alt`, `key_shift`, `key_ctrl`	Modifier key states

null_panel -> hide := HIDE_WHOLE_CONTROL
ram_panel -> hide := HIDE_PART_NOTHING
ui.Display -> text := str
cluster.Trigger -> allow_automation := TRUE
null_widget -> parent_panel := get_ui_id(null_panel)

if (control -> key_alt = ON) or (control -> key_shift = ON)
    // handle modifier keys
end if

`call` Keyword¶

Explicitly invokes a function using the subroutine pattern:

call VMC.remove_ref.internal()
call keymap._init()
call keymap.reboot()

Used with the subroutine pattern for true local scope:

function my_function(args)
    functions.MakeArgs(my_function)
    call _my_function()
end function

function _my_function()
    functions.ReceiveArgs(my_function)
    // implementation
end function

`message()`¶

Debug output to the Kontakt status bar:

message("")                                       // clear
message("Object RAM Load: " & TO_MB(lib_mem) & " MB")
message('Node ' & ivls.node_name(nenv) & ' tried to play invalid Voice!')
message("ConfigFailure (IVLS): Flow length exceeded!")

Built-in Variables¶

MIDI Event Variables¶

Variable	Description	Context
`EVENT_ID`	Event identifier	Note/release
`EVENT_NOTE`	MIDI note (0-127)	Note/release
`EVENT_VELOCITY`	Velocity (0-127)	Note/release
`MIDI_CHANNEL`	Channel (0-15)	Note/release/CC
`CC_NUM`	Controller number	CC
`CC[]`	CC value array	Anywhere
`VCC_PITCH_BEND`	Pitch bend virtual CC	CC
`KEY_DOWN[]`	Key state array	Anywhere
`POLY_AT[]`	Polyphonic aftertouch	Anywhere

Timing Variables¶

Variable	Description
`ENGINE_UPTIME`	Milliseconds since engine start
`DURATION_QUARTER`	Quarter note in microseconds
`DURATION_SIXTEENTH`	Sixteenth note in microseconds
`NI_SONG_POSITION`	Current song position

Voice[vo].note_on_time := ENGINE_UPTIME
bpm := (60000000 + DURATION_QUARTER / 2) / DURATION_QUARTER
wait(DURATION_SIXTEENTH / 8)

Group and Engine Variables¶

Variable	Description
`ALL_GROUPS`	All groups constant
`NUM_GROUPS`	Total group count
`NI_ASYNC_ID`	Async operation ID
`NI_ASYNC_EXIT_STATUS`	Async result (1=success)
`NI_SIGNAL_TYPE`	Signal type in listener

Predefined Conditions¶

define CONDITION.IS_OUTSIDE_EVENT := get_event_par(EVENT_ID, EVENT_PAR_SOURCE) = -1
define CONDITION.IS_PEDAL_DOWN := CC[64] >= 64
define CONDITION.IS_PEDAL_UP := CC[64] < 64
define CONDITION.IS_BOOL(#i#) := in_range(#i#, 0, 2)
define CONDITION.ANY_MODIFIER(#control#) := (#control# -> key_alt = ON) or ...
                                            (#control# -> key_shift = ON) or ...
                                            (#control# -> key_ctrl = ON)

if CONDITION.IS_OUTSIDE_EVENT
    Voice[vo].note := EVENT_NOTE
end if

Standard Constants¶

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

HIDE_WHOLE_CONTROL    // Completely hidden
HIDE_PART_NOTHING     // Fully visible
HIDE_PART_BG          // Hide background only