Language Reference¶

IVLS-KSP is an extended dialect of Kontakt Script Processor (KSP) that adds modular code organization (nodes, callbacks), a pool-based type system, compile-time code generation (macros, literate macros), voice management (flows, runtimes, VMC), and async task dispatch (clusters).

The ivls-sksp preprocessor transforms IVLS-KSP into standard KSP that Kontakt executes.

What Standard KSP Provides¶

Feature	Description
Callbacks	`on init`, `on note`, `on release`, `on controller`, etc.
Variables	`declare`, arrays, strings, polyphonic variables
Control flow	`if`/`else`, `while`, `for`, `select`/`case`
Functions	`function ... end function` with return values
UI widgets	Knobs, sliders, buttons, menus, labels, panels
Engine access	`play_note()`, `change_vol()`, groups, zones, etc.

What IVLS-KSP Adds¶

Feature	Description
Nodes	Modular code units with structured callbacks
Type system	Pool-based object allocation with properties
Defines	Compile-time constant substitution
Macros	Parameterized code templates
Literate macros	Compile-time iteration and code generation
Families	Namespaced variable grouping (dots become double underscores)
Clusters	Async task dispatch mechanism
Flows	Voice routing through node pipelines

Quick Reference¶

Declarations¶

Syntax	Description
`declare name`	Integer variable
`declare ~name`	Real (float) variable
`declare @name`	String variable
`declare name[size]`	Array
`declare const name`	Constant
`declare polyphonic name`	Per-voice variable
`family name ... end family`	Namespaced group
`define NAME := value`	Compile-time constant

Functions and Macros¶

Syntax	Description
`function name() ... end function`	Inlined function
`function name() -> result`	Function with return value
`taskfunc name() ... end taskfunc`	Coroutine with real call stack
`macro name(#arg#) ... end macro`	Parameterized macro

Control Flow¶

Syntax	Description
`if ... else if ... end if`	Conditional branching
`while ... end while`	Condition loop
`for i := a to b ... end for`	Counted loop
`select ... case ... end select`	Value matching (no fall-through)

Operators¶

Category	Operators
Arithmetic	`+`, `-`, `*`, `/`, `mod`
Comparison	`=`, `#` (not equal), `<`, `>`, `<=`, `>=`
Logical	`and`, `or`, `not`
Bitwise	`.and.`, `.or.`, `.xor.`, `.not.`
Assignment	`:=`
String	`&` (concatenation)

Nodes, Types, and Code Generation¶

Syntax	Description
`node Name: ... end node`	Node declaration
`node Name from Parent:`	Node inheritance
`cb CallbackName:`	Callback block
`type.Create(TypeName)`	Create type pool
`TypeName[ref].field`	Property access
`check_ref(Type, ref)`	Validate reference
`literate_macro(pattern) on LIST`	Compile-time iteration
`__RUN_CB__(Name)`	Inject node callbacks
`__VIRTUAL__(Name)`	Virtual callback hook

Conditional Compilation¶

Syntax	Description
`SET_CONDITION(FLAG)`	Enable compile-time flag
`USE_CODE_IF(FLAG) ... END_USE_CODE`	Conditional inclusion
`USE_CODE_IF_NOT(FLAG) ... END_USE_CODE`	Conditional exclusion

Reference Pages¶

Core Language¶

Declarations - Variables, arrays, constants, families
Functions - Functions and taskfuncs
Macros - Parameterized code templates
Control Flow - Conditionals, loops, select
Operators - Arithmetic, comparison, logical, bitwise
Defines - Compile-time constants and expressions

IVLS Extensions¶

Nodes - Modular code organization
Callbacks - Lifecycle and event callbacks
Types - Pool-based object system
Clusters - Async task dispatch
Code Generation - Literate macros and callback injection
Conditionals - Compile-time conditional compilation

Events and I/O¶

Events - MIDI events and Kontakt callbacks
Special Syntax - Properties, waits, imports, built-in variables