Script Events

The Problem

Script processors are isolated — they share no globals. But sometimes a processor early in the chain computes something that a later processor needs. Examples:

• A legato detector identifies whether a note is a continuation or a new attack, and wants to flag that for a downstream articulation selector
• A velocity curve processor normalises velocity and wants to pass the original raw velocity to a downstream dynamics script
• A chord analyser tags each note with its harmonic role (root, third, fifth) for a downstream voicing script to act on

Script events are the mechanism for passing this kind of information through the event flow from one RT processor to the next.

Creating a Script Event

sys_create_script_event(offset, payload)

The payload can be any Lua value — number, boolean, string, or table. Use a table when you need to pass more than one piece of information:

-- Upstream script: flag the incoming note as legato
sys_create_script_event(event.offset, {
  isLegato         = true,
  originalVelocity = event.velocity,
  harmonicRole     = "root",
})

The created event enters the queue and travels to every downstream processor just like a note or controller event.

Receiving Script Events Downstream

Script events arrive in onProcessEvents as entries in the events table. Check for sys_event_types.script and read the payload from event.data:

function onProcessEvents(blockLen, events)
  for i, event in ipairs(events) do
    if event.type == sys_event_types.script then
      local payload = event.data
      if payload ~= nil and payload.isLegato then
        -- select a legato articulation
      end
    end
  end
end

event.data holds whatever was passed as payload at create time. Always guard with a nil check in scripts that may receive script events from multiple upstream sources.

Event Shape

Script events have the same common fields as all other events, plus one extra:

Field	All types	script
id	yes
type	yes
offset	yes
data		yes

What Script Events Cannot Do

A script event travels with the event queue — it cannot communicate across unrelated note streams or persist state between blocks in the same script. For that, use script-level Lua variables. If you need to send information to the UI, use cross-script messaging (see Cross-Script Messaging).

Script events also cannot flow backwards (upstream) or sideways to a parallel chain — they follow the processor order, top to bottom.