Scripting Reference

Lua scripts can be loaded and run in the Instrument Editor tool to assist or automate tasks in the instrument creation process. This section of the documentation contains the scripting basics of the Lua language as well as extension bindings to a Kontakt instrument’s structure.

Instrument Structure

An instrument is shown as a nested tree with properties and values. Containers like groups and zones are represented as vectors (lists with indices). Property values are typed and value-checked so that changes are verified and ignored if the data is invalid.

The structure with property names, types and value-ranges looks like this:

Instrument                                     -- Struct
    name                                       -- String
    script                                     -- Struct
        name                                   -- String
        linked                                 -- Bool
        sourceCode                             -- String
        linkedFileName                         -- String
        bypass                                 -- Bool
    groups                                     -- Vector of Group
        name                                   -- String
        playbackMode                           -- Enum (see below)
        volume                                 -- Real, -inf..12
        pan                                    -- Real, -100..100
        tune                                   -- Real, -36..36
        zones                                  -- Vector of Zone
            file                               -- String
            volume                             -- Real, -inf..12
            pan                                -- Real, -100..100
            tune                               -- Real, -36..36
            rootKey                            -- Int, 0..127
            keyRange                           -- Struct
                low                            -- Int, 0..127
                high                           -- Int, 0..127
            velocityRange                      -- Struct
                low                            -- Int, 0..127
                high                           -- Int, 0..127
            sampleStart                        -- Int, 0..inf
            sampleStartModRange                -- Int, 0..inf
            sampleEnd                          -- Int, 4..inf
            loops                              -- Vector of Loop
                mode                           -- Int, 0..4 (see below)
                start                          -- Int, 0..inf
                length                         -- Int, 4..inf
                xfade                          -- Int, 0..1000000
                count                          -- Int, 0..1000000
                tune                           -- Real, -12..12
            grid                               -- Vector of Gridmode  
                mode                           -- Enum (see below)     
                bpm                            -- Real, 0.10..400

Group playback modes:

instrument.group.playbackMode = PlaybackMode.Sampler
PlaybackMode.DirectFromDisk
PlaybackMode.Wavetable
PlaybackMode.ToneMachine
PlaybackMode.TimeMachine
PlaybackMode.TimeMachine2
PlaybackMode.TimeMachinePro
PlaybackMode.BeatMachine
PlaybackMode.S1200Machine
PlaybackMode.MP60Machine

Loop modes:

0: Oneshot i.e. off
1: Until end
2: Until end alternating
3: Until release
4: Until release alternating

Grid modes:

GridMode.Off
GridMode.Fix
GridMode.Auto

Scripting Basics

Scripting is based on the Lua language. Resources are available online e.g. www.lua.org. The core language has been extended by bindings to the instrument structure. Whenever an instrument is connected and the tree view is displayed, a script can access it via the variable instrument.

Script Path

The global variable scriptPath points to the directory of the executed script. This is useful for file I/O related workflows.

Read properties and print them

A script can print to the console e.g.

print(instrument)

Prints "Instrument" if an instrument is connected, otherwise "nil" i.e. nothing.

print(scriptPath)

Prints the directory of the running script.

All properties can be referenced using dots e.g.

print(instrument.groups[0].name)

Prints the name of the first group - or an error message if no instrument is connected.

print(instrument.groups[0].zones[0].keyRange.high)

Prints the highest key range value of the first zone of the first group.

Iterate over containers

The brackets [ ] refer to the n^th element of the group or zone vector. The number of elements can be read with Lua‘s length operator:

print(#instrument.groups)

This allows iterating through groups or zones:

for n=0,#instrument.groups-1 do
    print(instrument.groups[n].name)
end

Note

Note that vectors are zero-indexed! There are other ways to iterate over containers without using indices. In the Binding Reference chapter, iteration via pairs is described for Vector and Struct and iteration via the traverse function is described under Algorithms.

Changing properties

Changing values works naturally:

instrument.groups[0].name = "Release"

or in a loop:

for n=0,#instrument.groups-1 do
    instrument.groups[n].name = 'grp_'..n
end

Working with containers

Group()

Creates a new object of type Group.

print(scriptPath)