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

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

@@ -0,0 +1,210 @@
+# Modulation Reference
+
+## Modulation Architecture
+
+Each Group can contain:
+- Up to **16 mod sources** (ADSR envelopes, Custom envelopes, LFOs, Step Sequencers)
+- Up to **64 mod routings** connecting sources to destinations
+- Up to **16 voice effects/filters** that can be modulation destinations
+
+Mod routings in the instrument are set up in Gorilla Editor but can be fully controlled from script.
+
+## Mod Source Types
+
+### ADSR Envelope (ModSourceADSR)
+
+Standard synthesizer envelope. Parameters:
+1. Name
+2. Attack (0–1,000,000 → exponential time)
+3. Attack Curve (-100% to +100%)
+4. Hold
+5. Decay (exponential time)
+6. Decay Curve (-100% to +100%)
+7. Sustain (0–1,000,000 = 0–100%)
+8. Release (exponential time)
+9. Release Curve (-100% to +100%)
+10. Hold End Level
+11. Times x10
+12. Tempo Sync
+
+```
+' Set ADSR Attack for first mod source in Group 0
+set_module_param(M_GROUP+0, M_MOD_SRC+1, 0, 2, attackValue)
+
+' Set Sustain (param 7 — Decay Curve occupies param 6)
+set_module_param(M_GROUP+0, M_MOD_SRC+1, 0, 7, sustainValue)
+```
+
+### LFO (ModSourceLFO)
+
+Low Frequency Oscillator. Parameters:
+1. Name
+2. Wave (Sine, Triangle, Square, Saw, Random, Drift, Saw Up, Saw Exp)
+3. Rate (exponential: Hz)
+4. Sync (tempo sync on/off)
+5. Retrigger
+6. Start Phase
+7. Unipolar (0 = bipolar ±1, 1 = unipolar 0–1)
+
+```
+set_module_param(M_GROUP+0, M_MOD_SRC+2, 0, 3, rateValue)   ' LFO Rate
+set_module_param(M_GROUP+0, M_MOD_SRC+2, 0, 4, syncOn)       ' LFO Sync
+set_module_param(M_GROUP+0, M_MOD_SRC+2, 0, 5, 1)            ' Retrigger on
+```
+
+### Step Sequencer (ModSourceStepSeq)
+
+Step sequence generator. Parameters include steps array, rate, sync, smooth, retrigger.
+
+### Custom Envelope (ModSourceCustom)
+
+Multi-point customizable curve with editable points.
+
+## Mod Routing Parameters
+
+Each mod routing (M_MOD+n) has these parameters:
+
+| Index | Parameter | Description |
+|-------|-----------|-------------|
+| 1 | Active | Enable/disable routing |
+| 2 | Source | Mod source index (see table below) |
+| 3 | CC | MIDI CC number for CC-based sources |
+| 4 | Invert | Invert the modulation signal |
+| 5 | Depth | Modulation amount (0–1,000,000) |
+| 6 | Smooth | Smoothing/glide time (0–1,000,000, exponential) |
+| 7 | Dest | Destination parameter (in display order) |
+| 8 | Curve Active | Enable curve shaping of the source signal. |
+| 9 | Curve | Custom curve points applied to source when Curve Active is on. |
+| 10 | Use MIDI Channel | Per-channel modulation (for MPE) |
+
+### Mod Source Index Values
+
+| Index | Source |
+|-------|--------|
+| 0 | Constant |
+| 1 | Random |
+| 2 | Random (positive only) |
+| 3 | Pitch Bend |
+| 4 | Aftertouch |
+| 5 | MIDI CC (specify CC number in param 3) |
+| 6 | Key Position |
+| 7 | Velocity |
+| 8 | Release Velocity |
+| 9 | Glide |
+| 10 | Release Timer |
+| FIRST_GROUP_MOD_SOURCE+0 | First group mod source (e.g., Amp Env) |
+| FIRST_GROUP_MOD_SOURCE+1 | Second group mod source (e.g., LFO) |
+| FIRST_GROUP_MOD_SOURCE+n | nth group mod source |
+
+## set_mod_dest — Scriptable Mod Matrix
+
+```
+set_mod_dest(group, modRouting, subModule, dest, ampMod)
+```
+
+Dynamically route a mod routing to any destination in the group.
+
+- `group`: `M_GROUP+n`
+- `modRouting`: `M_MOD+n`
+- `subModule`: `M_GROUP` (group itself), `M_MOD_SRC+n`, or `M_FILTER+n`
+- `dest`: Destination parameter index (from 1)
+- `ampMod`: 0 = offset, 1 = scale
+
+```
+' Route Mod Routing 4 to Filter 2 Cutoff (param 2 — Bypass=1, Cutoff=2 for all voice effects)
+set_mod_dest(M_GROUP+0, M_MOD+4, M_FILTER+2, 2, 0)
+
+' Route to Group Volume (param 3)
+set_mod_dest(M_GROUP+0, M_MOD+5, M_GROUP, 3, 1)
+
+' Disable routing (dest 0)
+set_mod_dest(M_GROUP+0, M_MOD+4, 0, 0, 0)
+```
+
+> ⚠ The `dest` indices in `set_mod_dest` follow the same display-order numbering as `set_module_param`. Verify with Shift+Copy if unsure.
+
+## set_mod_sources — Analog-Style Triggering
+
+```
+set_mod_sources(destEventID, sourceEventID, mask, retrig)
+```
+
+Copy or retrigger envelope/LFO states between events.
+
+- `mask`: Bitmask of mod sources (1=first, 2=second, 4=third, 8=fourth...)
+- `retrig`: 0 = continue from current position, 1 = retrigger from start
+
+```
+' Retrigger all mod sources for mono legato
+set_mod_sources(currentEvent, 0, 0xF, 0)
+
+' Copy mod source state from old event to new (for crossfade transitions)
+set_mod_sources(newEvent, oldEvent, 1023, 0)
+
+' Retrigger just the amp envelope (first mod source)
+set_mod_sources(currentEvent, 0, 1, 1)
+```
+
+## Mod Matrix Pattern
+
+Complete example of a scriptable mod matrix:
+
+```
+on init
+  const MOD_MATRIX = M_MOD + 4  ' first routing reserved for mod matrix
+
+  ' Define sources
+  const NUM_SOURCES = 5
+  const SourceNames[NUM_SOURCES] = ("Velocity", "Mod Wheel", "Aftertouch", "LFO", "Envelope")
+  const SourceIndex[NUM_SOURCES] = (7, 5, 4, FIRST_GROUP_MOD_SOURCE+1, FIRST_GROUP_MOD_SOURCE+2)
+  const SourceCC[NUM_SOURCES] = (1, 1, 1, 0, 0)
+
+  ' Define destinations
+  const NUM_DESTS = 4
+  const DestNames[NUM_DESTS] = ("-", "Cutoff", "Resonance", "Volume")
+  const DestModule[NUM_DESTS] = (0, M_FILTER+1, M_FILTER+1, 0)
+  const DestParam[NUM_DESTS] = (0, 2, 3, 3)  ' Bypass=1, Cutoff=2, Resonance=3; Group Volume=3
+  const DestAmpMod[NUM_DESTS] = (0, 0, 0, 1)
+
+  ' Properties
+  prop_stepped Mod_Source
+  prop_squared Mod_Depth(-1000000, 1000000, -100, 100)
+  prop_stepped Mod_Dest
+
+  var i = 0
+  while i < NUM_SOURCES
+    add_step(Mod_Source, SourceNames[i])
+    inc(i)
+  end while
+  i = 0
+  while i < NUM_DESTS
+    add_step(Mod_Dest, DestNames[i])
+    inc(i)
+  end while
+end on
+
+on Mod_Source
+  set_module_param(M_GROUP+0, 0, MOD_MATRIX, 2, SourceIndex[Mod_Source])
+  set_module_param(M_GROUP+0, 0, MOD_MATRIX, 3, SourceCC[Mod_Source])
+end on
+
+on Mod_Depth
+  set_module_param(M_GROUP+0, 0, MOD_MATRIX, 4, Mod_Depth < 0)
+  set_module_param(M_GROUP+0, 0, MOD_MATRIX, 5, abs(Mod_Depth))
+end on
+
+on Mod_Dest
+  set_mod_dest(M_GROUP+0, MOD_MATRIX, DestModule[Mod_Dest], DestParam[Mod_Dest], DestAmpMod[Mod_Dest])
+  set_module_param(M_GROUP+0, 0, MOD_MATRIX, 1, Mod_Dest > 0)  ' Active
+end on
+```
+
+## Effect Modulation (EffectMod)
+
+Bus effects can be modulated using EffectMod modules. These have:
+- Source selection (CC, LFO, envelope follower, step LFO)
+- Destination parameter selection
+- Depth and smoothing
+- Built-in step LFO with custom pattern
+
+Controlled via `set_module_param(M_BUS+n, M_EFFECT+n, ...)` where the effect is an EffectMod.

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

@@ -0,0 +1,217 @@
+# Module Control Reference
+
+## Module Path Constants
+
+> ⚠ **0 vs 1 base rule** — `M_GROUP` and `M_VGROUP` are the **only** 0-based constants. Every other constant starts at **1**. For the complete derivation table and a worked example, see [indexing.md](./indexing.md).
+
+Every module in the instrument is addressed by a path of constants:
+
+| Constant | Description | Example |
+|----------|-------------|---------|
+| `M_INST` | Instrument module | `M_INST` |
+| `M_GROUP` | Group (add index from 0) | `M_GROUP+0`, `M_GROUP+1` |
+| `M_VGROUP` | Voice Group (add index from 0) | `M_VGROUP+0` = Instrument Voices |
+| `M_BUS` | Effect Bus (add number from 1) | `M_BUS+1` |
+| `M_MAPPING` | Mapping (add number from 1) | `M_MAPPING+1` |
+| `M_MIDI` | MIDI File module (from 1) | `M_MIDI+1` |
+| `M_DATA` | Data File module (from 1) | `M_DATA+1` |
+| `M_SCRIPT` | Script module (from 1) | `M_SCRIPT+1` |
+
+### Sub-Module Constants
+
+| Constant | Description | Example |
+|----------|-------------|---------|
+| `M_COND` | Trigger condition in group (from 1) | `M_COND+1` |
+| `M_MOD_SRC` | Mod source in group (from 1) | `M_MOD_SRC+1` = first envelope/LFO |
+| `M_FILTER` | Voice effect in group — filter, oscillator, or utility (from 1) | `M_FILTER+1` = first voice effect |
+| `M_ZONE` | Zone in group/mapping (from 1) | `M_ZONE+1` |
+| `M_EFFECT` | Bus effect (from 1) | `M_EFFECT+1` |
+| `M_MOD` | Mod routing (from 1) | `M_MOD+1` |
+
+`M_FILTER` is the historical address for every module in a Group's `Filters` array, including oscillators and voice-level utilities. When an editor name exists in both forms, use the JSON `"Module"` type to distinguish them: `Filter*` modules use `M_GROUP+n, M_FILTER+m`; `Effect*` modules use `M_BUS+n, M_EFFECT+m`.
+
+## set_module_param(module, subModule, modRouting, param, value)
+
+Set a parameter in any instrument module.
+
+- `module`: Module path (e.g., `M_GROUP+0`)
+- `subModule`: Sub-module or 0 for the module itself
+- `modRouting`: Mod routing or 0
+- `param`: Parameter index (from 1, in Editor display order)
+- `value`: Continuous sliders = 0 to 1,000,000; stepped = exact value; draggable floats = value × 1000
+
+> ⚠ **String-type parameters (Name, paths, text fields) count toward param indices but are invisible in Shift+Copy output.** They still occupy a slot. The most common trap: `Instrument` has `Blob Path` (string) at param 3 between `Blob Number` (param 2) and `Volume` (param 4). Never count param indices from doc tables alone — always verify with Shift+Copy.
+
+**Shift+Copy is the primary way to get param indices.** In Gorilla Editor, Shift+click Copy on any parameter to copy the exact `set_module_param()` call to clipboard. Do this before writing any `set_module_param()` call for a module you haven't verified before.
+
+### Examples
+
+```
+' Instrument Volume (param 4) — Name=1(str), Blob Number=2, Blob Path=3(str), Volume=4
+set_module_param(M_INST, 0, 0, 4, 500000)
+
+' Group 0 Volume (param 3) — Name=1(str), Active=2, Volume=3
+set_module_param(M_GROUP+0, 0, 0, 3, Volume)
+
+' Group 0, FilterLadder, Cutoff (param 2) — Bypass=1, Cutoff=2
+' NOTE: ALL voice effects have Bypass as param 1. Cutoff/first control is always param 2.
+set_module_param(M_GROUP+0, M_FILTER+2, 0, 2, Cutoff)
+
+' Group 0, FilterLadder, Resonance (param 3)
+set_module_param(M_GROUP+0, M_FILTER+2, 0, 3, Resonance)
+
+' Group 0, Mod Source 1 (ADSR), Attack (param 2) — Name=1(str), Attack=2
+set_module_param(M_GROUP+0, M_MOD_SRC+1, 0, 2, Attack)
+
+' Group 0, Mod Source 1, Sustain (param 7)
+' ADSR order: Attack=2, AttackCurve=3, Hold=4, Decay=5, DecayCurve=6, Sustain=7, Release=8, ReleaseCurve=9
+set_module_param(M_GROUP+0, M_MOD_SRC+1, 0, 7, Sustain)
+
+' Bus 1, Effect 1, parameter 2 (e.g. Delay Time)
+set_module_param(M_BUS+1, M_EFFECT+1, 0, 2, DelayTime)
+
+' Bus 1, Effect 1, Bypass (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
+
+' Mod Routing in Group: Source (param 2), CC (param 3), Depth (param 5), Smooth (param 6)
+set_module_param(M_GROUP+0, 0, M_MOD+1, 2, 7)        ' Source = Velocity
+set_module_param(M_GROUP+0, 0, M_MOD+1, 5, 500000)    ' Depth = 50%
+set_module_param(M_GROUP+0, 0, M_MOD+1, 6, 250000)    ' Smooth = 25%
+
+' Mod Routing inside a sub-module (e.g., mod routing inside a filter)
+set_module_param(M_GROUP+0, M_FILTER+1, M_MOD+1, 5, Depth)
+
+' Group Alternate Mapping (param 16)
+set_module_param(M_GROUP+0, 0, 0, 16, mappingValue)
+```
+
+## Tune Parameter Taxonomy
+
+Different tune-related parameters use different encodings. Using the wrong one is a common source of silent frequency bugs.
+
+| Goal | What to set | Encoding |
+|---|---|---|
+| Pitch-offset a key-tracked group (oscillator or sample) | Group Tune, param 5 | Signed int, 100,000/semitone (+1 octave = 1,200,000) |
+| Fine-tune instrument globally | Instrument Tune, param 5 | Signed int, 100,000/semitone |
+| Fixed-frequency oscillator (Keytrack Off) | Oscillator Tune, param 2 (Sine/Analog), param 3 (Super) — verify via Shift+Copy | Absolute Hz — not semitones |
+| Pitch modulation via mod matrix | ModRouting Dest = "Tune", group-level | 0–1,000,000 depth; full depth = Pitch Bend Range in semitones |
+
+> ⚠ **Oscillator Tune (FilterSineOsc, FilterAnalogOsc, FilterSuperOsc) is an absolute frequency parameter, not a semitone offset.** Setting it to 0 via `set_module_param` will collapse the oscillator to ~2 Hz regardless of Keytrack state. For key-tracked oscillators, use **Group Tune (param 5)** to offset pitch instead — it compounds correctly with key-tracking.
+
+### Bell partial example — per-group pitch offsets with Group Tune
+
+```
+' Tune 5 additive groups to inharmonic bell partials using Group Tune (param 5).
+' Group Tune is a semitone offset from the played key (100,000 per semitone, signed).
+' Oscillators in each group stay key-tracked — only the relative pitch offset changes.
+const GRP_HUM     = 0  ' -12 st (octave below fundamental)
+const GRP_PRIME   = 1  '   0 st (fundamental)
+const GRP_TIERCE  = 2  '  +3 st (minor third above fundamental)
+const GRP_QUINT   = 3  '  +7 st (fifth above fundamental)
+const GRP_NOMINAL = 4  ' +12 st (octave above fundamental)
+
+set_module_param(M_GROUP+GRP_HUM,     0, 0, 5, -1200000)
+set_module_param(M_GROUP+GRP_PRIME,   0, 0, 5, 0)
+set_module_param(M_GROUP+GRP_TIERCE,  0, 0, 5, 300000)
+set_module_param(M_GROUP+GRP_QUINT,   0, 0, 5, 700000)
+set_module_param(M_GROUP+GRP_NOMINAL, 0, 0, 5, 1200000)
+```
+
+## get_module_param(module, subModule, modRouting, param, outVar)
+
+Read a parameter value.
+
+- If `outVar` is a variable: gets numeric value
+- If `outVar` is a string variable: gets display text
+- If `outVar` is an array and param is array-type: reads values into array
+- Returns: number of values read (0 if failed)
+
+```
+var value
+get_module_param(M_BUS+1, M_EFFECT+1, 0, paramIndex, value)
+
+var text$
+get_module_param(M_GROUP+0, 0, 0, 1, text$)  ' get display text
+```
+
+## set_module_params / get_module_params
+
+Set or read ALL parameters of a module at once.
+
+```
+var params[20]
+get_module_params(M_GROUP+0, M_MOD_SRC+1, 0, params)  ' first value = count
+
+params[3] = 500000  ' change attack
+set_module_params(M_GROUP+0, M_MOD_SRC+1, 0, params)
+```
+
+## find_module_param(module, subModule, modRouting, "name")
+
+Find parameter index by name (case sensitive). Returns index or -1. **Cache the result in `on init`.**
+
+```
+on init
+  const CutoffParam = find_module_param(M_GROUP+0, M_FILTER+1, 0, "Cutoff")
+  const LatencyParam = find_module_param(M_BUS+1, M_EFFECT+1, 0, "Latency")
+end on
+```
+
+## get_module_param_name(module, subModule, modRouting, param)
+
+Returns parameter name as string, or empty string if not found.
+
+## set_effect_order(bus, effectIndexes[startPos])
+
+Reorder effects in a bus without changing their indexes.
+
+## Zone and Sample Functions
+
+| Function | Description |
+|----------|-------------|
+| `get_num_zones(group)` | Zone count in group (negative for mapping) |
+| `get_sample_length(zone)` | Sample length in μs |
+| `num_slices_zone(zone)` | Number of slices |
+| `zone_slice_start(zone, index)` | Slice position in μs |
+| `zone_slice_length(zone, index)` | Slice length in μs at current tempo |
+| `get_slice_length(group, zoneIndex)` | Slice Length param in μs |
+| `find_zone(name)` | Find zone by sample path |
+
+Zone ID for `get_sample_length()` etc.: use `prop_waveform` value or `1000000*groupIndex + zoneIndex`.
+
+For mappings, use negative: `-1000000*mappingNumber + zoneIndex`.
+
+```
+var zoneID = -1000000 + 1  ' mapping 1, zone 1
+var length = get_sample_length(zoneID)
+var start = zone_slice_start(zoneID, 0)
+```
+
+## Group Functions
+
+| Function | Description |
+|----------|-------------|
+| `find_group("name")` | Returns group index or -1. Cache in `on init`. |
+| `find_mapping("name")` | Returns mapping index or 0. Cache in `on init`. |
+| `purge_group(group, loaded)` | Unload (0) or load (1) samples. `ALL_GROUPS` supported. |
+| `declare_latency(frames)` | Report audio latency to host for PDC |
+
+## Inter-Script Communication
+
+```
+' Set parameter in another script
+set_module_param(M_SCRIPT+2, 0, 0, paramIndex, value)
+
+' Read parameter from another script
+get_module_param(M_SCRIPT+2, 0, 0, paramIndex, outVar)
+
+' Shared Data File
+var Globals["My Data File"]  ' declare in each script
+
+' Trigger event across scripts
+trigger_new_event()  ' fires on new_event in all scripts
+
+' Set EVENT_PARAMs for later scripts to read
+set_event_param(EVENT_ID, EVENT_PARAM_0, myValue)
+```