@gorilla-engine-sdk/create-gorilla-engine-plugin 1.0.0

package/generator-gorilla-engine-plugin/app/templates/.agents/skills/gorilla-engine-dsp/SKILL.md

@@ -0,0 +1,295 @@
+# Gorilla Engine DSP — Instrument Scripting
+
+---
+
+## Workflow
+
+1. Read the target `.txt` script and the relevant arrays in the current `.inst` file. The instrument file controls module order, so resolve addresses from its current topology; a full-file inventory or user-facing pre-flight report is not required. For large instrument files, search from the end unless locating Groups or Mappings.
+2. Load [indexing.md](./references/indexing.md) before deriving `M_GROUP`, `M_FILTER`, `M_MOD_SRC`, `M_MOD`, `M_BUS`, `M_EFFECT`, or other module indices. Derive each index from the documented array position and scope.
+3. Follow the Script Language Reference below, then load [module-control.md](./references/module-control.md) and the reference for each module type used by the change. Use the documented parameter number, range, and encoding; do not infer them from a parameter name.
+4. Edit the external `.txt` script, not the script copy embedded in `.inst`. Reload the script in Gorilla Editor so the change is applied; saving the instrument then copies the loaded script into the instrument file.
+5. Run the narrowest available syntax, test, or build check for the changed script.
+
+---
+
+## Scope
+
+Write `.txt` scripts that expose controls for a topology the user built in Gorilla Editor. A script can control only modules already present in the instrument definition. Always edit the `.txt` file, not the Script section inside `.inst`. For scripting facts, patterns, and module control, see the reference files below.
+
+---
+
+## Script Language Reference
+
+### General Rules
+
+Gorilla Script is not JavaScript. Use the syntax documented here rather than inferring constructs from another language.
+
+- Write one statement per line. Use `...` to continue a statement on the next line; `;` may separate multiple statements on one line when that improves readability.
+- Names are case-sensitive. Variable, constant, property, and function names must start with a letter and contain only letters, numbers, and underscores.
+- Declare every `var`, `const`, and property in `on init`.
+- Numeric values and variables are 32-bit integers. Limited floating-point calculations are available through the conversion functions described below, but floating-point variables and arrays do not exist.
+- The documented control-flow forms are `if ... [else if ...] [else ...] end if`, `select ... case ... end select`, and `while ... end while`. The reference does not define `then` or `for` syntax.
+- Both `=` and `==` test equality. Prefer the canonical examples' `=` form.
+- `return` immediately exits the current callback or user-defined function and may be used inside a conditional.
+- User-defined functions use `function <name> ... end function`, are declared outside callbacks before first use, and are invoked by name without parentheses. The documented syntax has no parameters or return values.
+- Properties expose user-editable or display values. Use documented property declarations such as `prop_array`, `prop_boolean`, `prop_decibels`, `prop_exp`, `prop_linear`, `prop_meter`, `prop_squared`, `prop_stepped`, `prop_text`, and `prop_waveform`; declarations such as `prop_int`, `prop_float`, `prop_string`, and `prop_voice` are not documented. See [properties.md](./references/properties.md).
+- Use `'` for a comment through the end of a line and `{ ... }` for a block comment.
+
+### Callbacks
+
+Every script is organized into callbacks — blocks of code that run in response to events.
+
+```
+on init
+	' Runs once when script loads. Declare all variables and properties here.
+end on
+
+on note
+	' Runs when a MIDI note-on is received. Voices start when callback returns or delay() is called.
+end on
+
+on release
+	' Runs when a MIDI note-off is received.
+end on
+
+on controller
+	' Runs when a MIDI CC value changes. Check EVENT_CC for which controller.
+end on
+
+on poly_at
+	' Runs on polyphonic aftertouch. Check POLY_AT_KEY for the key.
+end on
+
+on program_change
+	' Runs on MIDI program change. Read MIDI_PROGRAM.
+end on
+
+on transport
+	' Runs when host playback starts/stops.
+end on
+
+on <property_name>
+	' Runs when a declared property changes value.
+end on
+
+on new_event
+	' Runs when trigger_new_event() fires.
+end on
+
+on mapping_changed
+	' Runs when a zone, mapping, or sample changes.
+end on
+
+on midi_drag
+	' Runs when user drags MIDI data from instrument. Fill MIDI_DRAG_DATA.
+end on
+
+on chord_changed
+	' Runs when host sends chord info.
+end on
+
+on section_changed
+	' Runs when host sends song section info.
+end on
+
+on io_changed
+	' Runs when a Rack Extension audio output is connected or disconnected.
+end on
+```
+
+### Variables
+
+```
+on init
+	var x                          ' integer variable, default 0
+	var name$ = "hello"            ' string variable
+	var arr[10]                    ' array of 10 integers (index 0-9)
+	var init_arr[4] = (1,2,3,4)   ' array with initial values
+	const MAX = 128                ' constant (read-only)
+	var shared["My Data File"]     ' array backed by a Data File module
+end on
+```
+
+- All `var` and `const` must be in `on init`
+- Values are 32-bit signed integers
+- String variables end with `$` or are initialized with a string
+
+### Functions
+
+```
+function my_function
+	' code here — inlined at call site, zero performance cost
+end function
+
+on note
+	if EVENT_KEY < 60
+		return
+	end if
+	my_function
+end on
+```
+
+- Define outside callbacks, before first use
+- The documented declaration has no parameters or return value
+- `return` exits the current function or callback immediately
+- Always inlined — no call overhead
+
+### Control Flow
+
+```
+' If/Else
+if x > 10
+	' ...
+else if x > 5
+	' ...
+else
+	' ...
+end if
+
+' Select/Case
+select x
+	case 0
+		' ...
+	case 1 to 5
+		' ...
+	case 10
+		' ...
+end select
+
+' While loop
+while x < 100
+	inc(x)
+end while
+```
+
+### Operators
+
+| Operator                 | Description                                                |
+| ------------------------ | ---------------------------------------------------------- |
+| `+`, `-`, `*`, `/`       | Arithmetic (integer division rounds down, div by 0 = 0)    |
+| `mod`                    | Modulus (remainder)                                        |
+| `<<`, `>>`               | Bit shift left/right                                       |
+| `.and.`, `.or.`, `.not.` | Bitwise AND, OR, NOT                                       |
+| `and`, `or`, `not`       | Logical operators (in conditions)                          |
+| `=`, `==`                | Equal (both forms are documented)                          |
+| `!=`, `<>`               | Not equal                                                  |
+| `<`, `>`, `<=`, `>=`     | Comparison                                                 |
+| `&`                      | String concatenation                                       |
+
+### Math Functions
+
+| Function                | Description                              |
+| ----------------------- | ---------------------------------------- |
+| `abs(x)`                | Absolute value                           |
+| `inc(x)`                | Increment by 1 (faster than `x = x + 1`) |
+| `dec(x)`                | Decrement by 1                           |
+| `in_range(x, min, max)` | Returns 1 if min ≤ x ≤ max               |
+| `random(min, max)`      | Random integer in [min, max]             |
+
+### Floating-Point (Single-Line Only)
+
+```
+x = real_to_int(int_to_real(a) * sin(int_to_real(b) / int_to_real(1000)))
+```
+
+Available in float expressions: `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `exp`, `log`, `pow`, `sqrt`, `ceil`, `floor`, `round`.
+
+Use `real_to_int(realValue)` to convert a result back to an integer or `real_to_string(realValue, decimalPlaces)` to convert it to text. No float variables or arrays exist; floats are limited to a single expression.
+
+### String Functions
+
+| Function                        | Description                            |
+| ------------------------------- | -------------------------------------- |
+| `string_find(str, sub, start)`  | Find substring, returns position or -1 |
+| `string_length(str)`            | Character count                        |
+| `string_range(str, start, len)` | Extract substring                      |
+| `character_code(str, pos)`      | ASCII code at position                 |
+| `&`                             | Concatenate strings and numbers        |
+
+### Array Utilities
+
+| Function                                     | Description                          |
+| -------------------------------------------- | ------------------------------------ |
+| `array_copy(src, dest)`                      | Copy array contents                  |
+| `array_equal(a, b)`                          | Returns 1 if same length and content |
+| `array_fill(src[start], dest[start], count)` | Copy/fill range (same array OK)      |
+| `array_find(arr, value)`                     | First index of value, or -1          |
+| `array_find_range(arr[start], value, count)` | Find in range                        |
+| `array_find_max(arr[start], count)`          | Maximum in range                     |
+| `array_find_min(arr[start], count)`          | Minimum in range                     |
+| `array_find_difference(a[start], b[start])`  | First differing index, or -1         |
+| `array_length(arr)`                          | Declared size                        |
+| `array_sort(arr, dir)`                       | 0=ascending, 1=descending; -N sorts the first N ascending |
+| `array_sum(arr, start, count)`               | Sum a range                          |
+| `load_array(arr, nameOrIndex)`               | Load from Data File module           |
+| `save_array(arr, nameOrIndex)`               | Save to Data File module             |
+| `load_midi_file(nameOrIndex)`                | Select MIDI File module; returns its index or -1 |
+
+### Comments
+
+```
+' Single-line comment (everything after single quote)
+{ Block comment
+	spanning multiple lines }
+```
+
+### Line Continuation
+
+```
+var long_array[8] = ( 1, 2, 3, 4, ...
+											5, 6, 7, 8 )
+```
+
+Use `...` at end of line to continue on next line.
+
+### Conditional Compilation
+
+```
+USE_CODE_IF(FEATURE_X)
+	' Only compiled if "FEATURE_X" is in Script Defines
+END_USE_CODE
+
+USE_CODE_IF_NOT(DEBUG)
+	' Only compiled if "DEBUG" is NOT in Script Defines
+END_USE_CODE
+```
+
+### Printing / Debugging
+
+```
+print("value is " & x)       ' Print to status line and debug window
+print_active_events()         ' Debug only; do not use in a released product
+```
+
+### Optimization Tips
+
+- `inc(x)` / `dec(x)` faster than `x = x + 1`
+- `if x` is shorthand for `if x != 0` (faster)
+- Combine expressions: `a = 3 * x + 1` instead of two statements
+- Constant expressions like `10 * MAX_VEL` are precomputed at compile time
+- Functions are always inlined — no overhead
+- Check most likely `case` values first
+
+---
+
+## Reference Files
+
+**Load before writing code — not after something breaks.** If you have not verified a parameter's encoding in this session, look it up **first**.
+
+| Topic              | File                                                                                | When to load                                                                                                                                                                                                    |
+| ------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core modules       | [module-reference-core.md](./references/module-reference-core.md)                   | Instrument, Script, Group, Zone, trigger Conditions                                                                                                                                                             |
+| Modulation modules | [module-reference-modulation.md](./references/module-reference-modulation.md)       | ADSR Env, Custom Env, LFO, Step Seq, Mod Routing parameters                                                                                                                                                     |
+| Voice effects      | [module-reference-voice-effects.md](./references/module-reference-voice-effects.md) | **Load before scripting any oscillator or filter** — per-voice filters, oscillators, and voice-level FX parameters; contains known footguns (e.g. oscillator Tune is absolute frequency, not a semitone offset) |
+| Bus effects        | [module-reference-bus-effects.md](./references/module-reference-bus-effects.md)     | Effect Bus, Effect Mod, and all bus-level effect parameters                                                                                                                                                     |
+| Misc modules       | [module-reference-misc.md](./references/module-reference-misc.md)                   | Voice Group, Alternate Mapping, Wavetable, MIDI File, Data File parameters                                                                                                                                      |
+| Properties         | [properties.md](./references/properties.md)                                         | Declaring UI-bound parameters (prop_linear, prop_exp, prop_boolean, etc.)                                                                                                                                       |
+| Note Events        | [note-events.md](./references/note-events.md)                                       | MIDI note handling, new_note, set_tune, set_vol, fade_in/out, groups, set_controller CC bridge                                                                                                                  |
+| Module Control     | [module-control.md](./references/module-control.md)                                 | `set_module_param`, parameter addressing, ranges, and module-specific encoding                                                                                                                                  |
+| Modulation         | [modulation.md](./references/modulation.md)                                         | Mod sources, mod routing, mod matrix, set_mod_dest, ADSR/LFO/StepSeq                                                                                                                                            |
+| Effects & Filters  | [effects-filters.md](./references/effects-filters.md)                               | Voice effects, bus effects, filter types, oscillators, effect bus routing                                                                                                                                       |
+| Time & Tempo       | [time-tempo.md](./references/time-tempo.md)                                         | delay, delay_ppq, tempo sync, song position, transport                                                                                                                                                          |
+| Script Patterns    | [script-patterns.md](./references/script-patterns.md)                               | Arpeggiators, mono/legato/glide, round robins, crossfades, step sequencers, velocity curves, sliced loops                                                                                                       |
+| Instrument Files   | [instrument-files.md](./references/instrument-files.md)                             | Format, handling, basic audio routing                                                                                                                                                                           |
+| Index Derivation   | [indexing.md](./references/indexing.md)                                             | Deriving any M_XXX index from the .inst file; 0 vs 1 base rules; per-group scope of M_FILTER/M_MOD_SRC/M_MOD                                                                                                    |
+| Quick Start        | [key-rules.md](./references/key-rules.md)                                           | Minimal script and instrument examples                                                                                                                                                                          |

package/generator-gorilla-engine-plugin/app/templates/.agents/skills/gorilla-engine-dsp/references/effects-filters.md

@@ -0,0 +1,186 @@
+# Effects & Filters Reference
+
+## Voice Effects (per-voice, in Groups)
+
+Voice effects are inserted in Groups and process audio individually for each voice. Addressed as `M_FILTER+n` (from 1).
+
+### Filter Types
+
+| Module | Description | Key Params |
+|--------|-------------|------------|
+| LP6 Filter | 1-pole (6 dB/oct) lowpass. Lowest CPU. | Cutoff, Key Tracking |
+| LP12 Filter | 2-pole (12 dB/oct) lowpass | Cutoff, Resonance, Key Tracking |
+| LP24 Filter | 4-pole (24 dB/oct) lowpass | Cutoff, Resonance, Key Tracking |
+| HP6 Filter | 1-pole (6 dB/oct) highpass | Cutoff, Key Tracking |
+| HP12 Filter | 2-pole (12 dB/oct) highpass | Cutoff, Resonance, Key Tracking |
+| BP6 Filter | 2-pole (6 dB/oct) bandpass | Cutoff, Bandwidth, Key Tracking |
+| Ladder Filter | 4-pole vintage analog simulation | Cutoff, Resonance, Key Tracking, Type |
+| State-Variable Filter | 2-pole multi-mode vintage analog | Cutoff, Resonance, Key Tracking, Type (LP/HP/BP/Notch) |
+| Multi-Mode Filter | General purpose up to 4-pole | Cutoff, Resonance, Key Tracking, Type, Slope |
+| MS12 Filter | 2-pole vintage analog | Cutoff, Resonance, Key Tracking, Type |
+| Damping Filter | Acoustic damping simulation | Cutoff, Key Tracking. More natural than filter sweep. |
+| Comb Filter | Delay line with feedback | Cutoff, Feedback, Damping, Key Tracking, Mix |
+
+### Oscillators (Voice Effects)
+
+| Module | Description |
+|--------|-------------|
+| Analog Oscillator | Multi-waveform (Saw, Square, Tri, Sine) + sub oscillator |
+| FM Oscillator | 4-operator FM synth with customizable algorithm |
+| Sample Oscillator | Sample playback with optional granular mode |
+| Sine Oscillator | Pure sine wave |
+| Super Oscillator | Multi-saw (unison) + sub |
+| Wavetable Oscillator | Arbitrary waveform from Wavetable modules |
+
+### Other Voice Effects
+
+| Module | Description |
+|--------|-------------|
+| Gain | Volume control between inserts |
+| Send | Route to output or effect bus |
+| Shaper | Waveshaping with custom curve |
+| Waveshaper | Waveshaping with preset curves |
+| Lo-Fi | Sample rate reduction |
+| Limiter | Safety limiter per voice |
+| EQ Band | Single parametric EQ |
+| Shelf EQ | High/low shelving EQ |
+| Frequency Shifter | Bode frequency shift |
+| Stereo Matrix | Channel routing matrix |
+| Downmix | Multi-channel to stereo |
+| Crossfade | Fade between sample channels |
+| Envelope Follower | Follow audio level as mod source |
+| Timestretch | Timestretching per voice |
+| Compressor | Dynamic range control |
+| Granulate | Granular processing |
+| Phase Modulator | Modulated delay (chorus/flanger/comb) |
+| Tail Loop | Create loop from playback |
+| Teleport | Transfer audio between voices |
+| Mod Shaper | Warp modulation signals |
+| Mod Waveform | Use sample waveform as mod source |
+
+### Controlling Voice Effects from Script
+
+```
+' Bypass = param 1 for ALL voice effects (filters, oscillators, utilities alike).
+' First meaningful control = param 2: Cutoff for filters, Tune for oscillators,
+' first DSP param for utilities (e.g. Level for Gain). Verify with Shift+Copy.
+' Set filter cutoff (param 2) and resonance (param 3) on Group 0, Filter 1
+set_module_param(M_GROUP+0, M_FILTER+1, 0, 2, cutoffValue)
+set_module_param(M_GROUP+0, M_FILTER+1, 0, 3, resoValue)
+
+' Set oscillator parameters
+set_module_param(M_GROUP+0, M_FILTER+1, 0, 3, 2)  ' Waveform = Saw (stepped param)
+
+' Enable/disable a voice effect via its mod routing
+set_module_param(M_GROUP+0, M_FILTER+1, M_MOD+1, 1, 0)  ' disable mod routing
+```
+
+## Bus Effects (post-voice, in Effect Busses)
+
+Bus effects process the mixed output of all voices routed to that bus. Addressed as `M_EFFECT+n` (from 1) within a bus `M_BUS+n`.
+
+### Common Bus Effects
+
+| Module | Description |
+|--------|-------------|
+| Reverb | Algorithmic reverb |
+| Reverb2 | Alternative reverb algorithm |
+| Non-Linear Reverb | Gated/reverse reverb |
+| Convolution | Convolution reverb (IR-based) |
+| Delay | Stereo delay with sync |
+| Multi-Tap Delay | Multi-tap delay |
+| Chorus | Chorus effect |
+| Flanger | Flanger effect |
+| Phaser | Phaser effect |
+| Distortion | Distortion |
+| Overdrive | Overdrive |
+| Saturation | Saturation |
+| Lo-Fi | Bit/sample rate reduction |
+| Compressor | Dynamics compressor |
+| Bus Compressor | Bus/glue compressor |
+| Multi-Band Compressor | Multi-band dynamics |
+| Limiter | Brick-wall limiter |
+| Gate | Noise gate |
+| EQ | Parametric EQ |
+| Isolator EQ | DJ-style isolator |
+| Filter | Master filter |
+| Master Filter | Resonant master filter |
+| Frequency Shifter | Bode shift |
+| Grain Pitch | Granular pitch shift |
+| Guitar Amp | Amp simulation |
+| Rotary | Leslie cabinet simulation |
+| Tremolo/Pan | Tremolo and auto-pan |
+| Vocoder | Vocoder |
+| Pan | Stereo panning |
+| Send | Route to another bus |
+| Sub Bass | Sub bass enhancer |
+| Transient | Transient shaper |
+| Resonators | Resonator bank |
+| Beat Cutter | Beat slicing effects |
+| Crossover | Frequency crossover |
+| Multi-Band Distortion | Per-band distortion |
+| Pitch Shifter | Pitch shifting |
+| Sample Player | Bus-level sample playback |
+| Audio Meter | Level metering |
+| Envelope Follower | Bus-level envelope following |
+
+### Controlling Bus Effects from Script
+
+```
+' Set delay time on Bus 1, Effect 1
+set_module_param(M_BUS+1, M_EFFECT+1, 0, 2, delayTime)
+
+' Set delay sync
+set_module_param(M_BUS+1, M_EFFECT+1, 0, 3, syncOn)
+
+' Bypass an effect (param 1)
+set_module_param(M_BUS+1, M_EFFECT+1, 0, 1, 1)  ' bypass on
+set_module_param(M_BUS+1, M_EFFECT+1, 0, 1, 0)  ' bypass off
+
+' Reverb mix on Bus 1, Effect 2
+set_module_param(M_BUS+1, M_EFFECT+2, 0, 2, mixValue)
+
+' Reorder effects in a bus
+var order[3] = (3, 2, 1)  ' reverse the order of 3 effects
+set_effect_order(M_BUS+1, order)
+```
+
+## Effect Bus Routing
+
+- Groups route audio to buses via the Group **Output** parameter
+- Buses can route to other buses via Bus **Output** parameter
+- Voice-level sends: use Voice Effect: Send
+- Bus-level sends: use Bus Effect: Send
+
+```
+' Route Group 0 output to Bus 2 (param 7 = Output)
+set_module_param(M_GROUP+0, 0, 0, 7, 2)  ' stepped: bus number
+```
+
+## Effect Bus Parameters
+
+| Index | Parameter | Description |
+|-------|-----------|-------------|
+| 1 | Name | Bus name |
+| 2 | Volume | Bus output volume |
+| 3 | Output | Output destination (audio out or another bus) |
+| 4 | Mute | Mute the bus |
+| 5 | Solo | Solo the bus |
+
+## Latency Reporting
+
+Some effects (like Pitch Shift) introduce latency. Report total to host:
+
+```
+on init
+  const LatencyParam = find_module_param(M_BUS+1, M_EFFECT+1, 0, "Latency")
+  var latency
+end on
+
+on controller
+  if EVENT_CC = 123  ' audio restart
+    get_module_param(M_BUS+1, M_EFFECT+1, 0, LatencyParam, latency)
+    declare_latency(latency)
+  end if
+end on
+```

package/generator-gorilla-engine-plugin/app/templates/.agents/skills/gorilla-engine-dsp/references/indexing.md

@@ -0,0 +1,129 @@
+# Index Derivation Cheat Sheet
+
+Every script constant (`M_GROUP`, `M_FILTER`, `M_BUS`, etc.) maps directly to an **array position** in the `.inst` JSON file. Read the file, count positions, apply the formula.
+
+> ⚠ **Critical gotcha — the only 0-based constants:**
+> `M_GROUP` and `M_VGROUP` are the **only** 0-based constants.
+> Every other constant (`M_BUS`, `M_FILTER`, `M_MOD_SRC`, `M_MOD`, `M_EFFECT`, `M_COND`, `M_MAPPING`, `M_SCRIPT`, `M_MIDI`, `M_DATA`, `M_ZONE`) starts at **1**.
+
+---
+
+## Complete Derivation Table
+
+`n` = 0-based position of the item in its JSON array (first item = 0, second = 1, …)
+
+| `.inst` JSON array | Script constant | Base | Formula | Example (first item) |
+|---|---|---|---|---|
+| `"Groups"[n]` | `M_GROUP` | **0** | `M_GROUP+n` | `M_GROUP+0` |
+| `"Voice Groups"[n]` | `M_VGROUP` | **0** | `M_VGROUP+n` | `M_VGROUP+0` (= Instrument Voices) |
+| `"FX Busses"[n]` | `M_BUS` | 1 | `M_BUS+(n+1)` | `M_BUS+1` |
+| `"Mappings"[n]` | `M_MAPPING` | 1 | `M_MAPPING+(n+1)` | `M_MAPPING+1` |
+| `"Scripts"[n]` | `M_SCRIPT` | 1 | `M_SCRIPT+(n+1)` | `M_SCRIPT+1` |
+| `"MIDI Files"[n]` | `M_MIDI` | 1 | `M_MIDI+(n+1)` | `M_MIDI+1` |
+| `"Data Files"[n]` | `M_DATA` | 1 | `M_DATA+(n+1)` | `M_DATA+1` |
+| group `"Conditions"[n]` | `M_COND` | 1 | `M_COND+(n+1)` | `M_COND+1` |
+| group `"ModSources"[n]` | `M_MOD_SRC` | 1 | `M_MOD_SRC+(n+1)` | `M_MOD_SRC+1` |
+| group `"Filters"[n]` | `M_FILTER` | 1 | `M_FILTER+(n+1)` | `M_FILTER+1` |
+| group `"Zones"[n]` | `M_ZONE` | 1 | `M_ZONE+(n+1)` | `M_ZONE+1` |
+| group `"ModRoutings"[n]` | `M_MOD` | 1 | `M_MOD+(n+1)` | `M_MOD+1` |
+| bus `"Effects"[n]` | `M_EFFECT` | 1 | `M_EFFECT+(n+1)` | `M_EFFECT+1` |
+
+---
+
+## Per-Group Scope
+
+`M_FILTER`, `M_MOD_SRC`, `M_MOD`, `M_COND`, and `M_ZONE` are **relative to their group**. The same index in two different groups refers to two completely different modules:
+
+```
+' M_FILTER+1 in Group 0 → first item in Groups[0].Filters[]
+set_module_param(M_GROUP+0, M_FILTER+1, 0, 2, Cutoff)  ' Bypass = param 1, Cutoff = param 2
+
+' M_FILTER+1 in Group 1 → first item in Groups[1].Filters[] — different module type entirely
+set_module_param(M_GROUP+1, M_FILTER+1, 0, 2, Cutoff)  ' Bypass = param 1, Cutoff = param 2
+```
+
+Always derive indices **per group** when reading the `.inst` file.
+
+---
+
+## Worked Example
+
+Given this `.inst` structure:
+
+```json
+{
+  "Groups": [
+    {
+      "Module": "Group", "Name": "Synth",
+      "ModSources":  [ { "Module": "ModSourceADSR" }, { "Module": "ModSourceLFO" } ],
+      "ModRoutings": [ { "Module": "ModRouting" }, { "Module": "ModRouting" } ],
+      "Filters":     [ { "Module": "FilterAnalogOsc" }, { "Module": "FilterLP12" } ]
+    },
+    {
+      "Module": "Group", "Name": "Sub",
+      "ModSources":  [ { "Module": "ModSourceADSR" } ],
+      "ModRoutings": [ { "Module": "ModRouting" } ],
+      "Filters":     [ { "Module": "FilterSineOsc" } ]
+    }
+  ],
+  "Voice Groups": [
+    { "Module": "VoiceGroup" }
+  ],
+  "FX Busses": [
+    { "Module": "EffectBus", "Name": "Reverb Bus", "Effects": [ { "Module": "EffectReverb" }, { "Module": "EffectDelay" } ] },
+    { "Module": "EffectBus", "Name": "Master",     "Effects": [ { "Module": "EffectLimiter" } ] }
+  ],
+  "Mappings": [
+    { "Module": "Mapping", "Name": "RR2" }
+  ],
+  "Scripts": [
+    { "Module": "Script", "Script Path": "script.txt" }
+  ]
+}
+```
+
+Derived indices:
+
+| Item | Derived index |
+|---|---|
+| Group "Synth" | `M_GROUP+0` |
+| Group "Sub" | `M_GROUP+1` |
+| Instrument Voices | `M_VGROUP+0` |
+| FX Bus "Reverb Bus" | `M_BUS+1` |
+| FX Bus "Master" | `M_BUS+2` |
+| Mapping "RR2" | `M_MAPPING+1` |
+| Script | `M_SCRIPT+1` |
+| Group 0 — ADSR (ModSourceADSR) | `M_GROUP+0, M_MOD_SRC+1` |
+| Group 0 — LFO (ModSourceLFO) | `M_GROUP+0, M_MOD_SRC+2` |
+| Group 0 — first ModRouting | `M_GROUP+0, … M_MOD+1` |
+| Group 0 — second ModRouting | `M_GROUP+0, … M_MOD+2` |
+| Group 0 — Analog Oscillator | `M_GROUP+0, M_FILTER+1` |
+| Group 0 — LP12 Filter | `M_GROUP+0, M_FILTER+2` |
+| Group 1 — ADSR | `M_GROUP+1, M_MOD_SRC+1` |
+| Group 1 — Sine Oscillator | `M_GROUP+1, M_FILTER+1` |
+| Bus 1 — Reverb | `M_BUS+1, M_EFFECT+1` |
+| Bus 1 — Delay | `M_BUS+1, M_EFFECT+2` |
+| Bus 2 — Limiter | `M_BUS+2, M_EFFECT+1` |
+
+---
+
+## Quick Formula Summary
+
+```
+' 0-based (only these two):
+M_GROUP+0   → Groups[0]
+M_VGROUP+0  → Voice Groups[0]
+
+' 1-based (everything else):
+M_BUS+1     → FX Busses[0]   (position 0 → index 1)
+M_FILTER+1  → group.Filters[0]
+M_MOD_SRC+1 → group.ModSources[0]
+M_MOD+1     → group.ModRoutings[0]
+M_EFFECT+1  → bus.Effects[0]
+M_MAPPING+1 → Mappings[0]
+M_COND+1    → group.Conditions[0]
+M_ZONE+1    → group.Zones[0]
+M_SCRIPT+1  → Scripts[0]
+M_MIDI+1    → MIDI Files[0]
+M_DATA+1    → Data Files[0]
+```