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

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

@@ -0,0 +1,145 @@
+# Gorilla Editor — Module Reference: Core Modules
+
+Covers: Instrument, Script, Group, Zone, and trigger Conditions.
+
+## Contents
+1. [Instrument](#Instrument)
+2. [Script](#Script)
+3. [Group](#Group)
+4. [Zone](#Zone)
+5. [Alternate Condition](#Alternate-Condition)
+6. [Controller Condition](#Controller-Condition)
+7. [Keyswitch Condition](#Keyswitch-Condition)
+8. [Random Condition](#Random-Condition)
+
+---
+
+## Instrument
+Every instrument has one Instrument module.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Instrument name. |
+| Blob Number | The blob number to use when exporting the instrument to use in a Gorilla Engine based product can be set here. Set to '-' to include a custom blob name in the Blob Path. |
+| Blob Path | Folder to save the .blob file (path should be relative to the instrument location). |
+| Volume | Volume for the whole instrument (leave at 0.0 dB to minimize CPU load). Often this parameter will be controlled by the instrument script to implement the master volume. |
+| Tune | Tuning for the whole instrument - note this is tuning of all samples, not transposition of the MIDI input. |
+| Output | Selects the main audio output - normally leave this set to 1. |
+| Voices | Displays the current number of voices the instrument is playing. |
+| Sustain Pedal | Sets the sustain pedal mode. Possible values are: <br />`Off`: No response to sustain pedal, so it can be handled in the instrument script.<br />`On`: Normal response to sustain pedal.<br />`Latch`: Sustain notes until the next note is played.<br />`Damper`: Sustained voices are not released while the sustain pedal is held, or the key that triggered the voice has been played again and is still held. |
+| Glide | Only has an effect in Group modules where the Glide mod source is used. Possible values are: <br />`Off`: No glide.<br />`On`: Always glide.<br />`Auto`: Only glide if a key is already held. |
+| Default Keyswitch | Sets which keyswitch key (if any) will be active when the instrument is loaded. |
+| Pitch Bend Range | Adjust maximum depth of all modulation routings from Pitch Bend to Group Tune. |
+| Active Events | Displays the number of script events currently active - useful for script debugging. Hanging events are most likely note events that were never released. |
+| Script Defines | List of words separated by spaces or commas, used with script USE_CODE_IF(). |
+| Overview Size | Number of overview points to generate for samples (applied when exporting). |
+| Simultaneous Max | If set, limits the number of MIDI note and pedal messages in one audio buffer to reduce the maximum CPU load. Excess messages are delayed until the next audio buffer. |
+| Group Solo | Displays if any groups are currently soloed. |
+| Bus Solo | Displays if any effect busses are currently soloed. |
+| Groups | [Group](#Group) |
+| Mappings | [Mapping](#Mapping) |
+| Voice Groups | [VoiceGroup](#VoiceGroup) |
+| FX Busses | [EffectBus](#EffectBus) |
+| Wavetables | [Wavetable](#Wavetable) |
+| MIDI Files | [MidiFile](#MidiFile) |
+| Data Files | [DataFile](#DataFile) |
+| Scripts | [Script](#Script) |
+
+## Script
+Contains the instrument script and displays any parameters declared in the script for editing.
+| Parameter | Description |
+| --------- | ----------- |
+| Bypass | Bypass processing of note and controller events by this script. |
+| Script Path | Location of script text file on disk. |
+| Script | Text of currently active script. |
+| Status | Last message printed by the script. |
+
+## Group
+The Instrument can have any number of Group modules. A Group module organizes multiple sample zones and allows for setting trigger conditions and other settings that apply to all samples in the Group. Each Group can contain up to 16 mod sources, 64 mod routings and 8 filters.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this Group. |
+| Active | When switched off, the Group will not respond to incoming notes. |
+| Volume | Volume for all voices in the Group. |
+| Pan | Pan (balance if stereo) for all voices in the Group. |
+| Tune | Coarse and fine tuning for all voices in the Group. |
+| Tracking | Pitch tracking of samples across the keyboard (0% = none, 100% = normal). |
+| Output | Select the audio output or Effect Bus to output all Group voices to. |
+| Voice Group | Select a Voice Group to control the Group polyphony. |
+| Voices | Displays the current number of voices the Group is playing. |
+| Quality | Sample playback interpolation mode. Each mode has a different trade-off between CPU load and sound quality. Possible values are: <br />`Eco`: Lowest quality and CPU load. Fine for background sounds, or sounds with little high frequency content.<br />`Mid`: Middle quality and CPU load. Use instead of Lagrange to increase quality if transposing up a long way.<br />`High`: Higher quality and CPU load. Use instead of Sinc 8 to save CPU if transposing up a long way.<br />`Lagrange`: Standard 4-point Lagrange interpolation. Good quality for most sounds. Low CPU load.<br />`Hermite`: 4-point Hermite interpolation. Similar to Lagrange but sounds smoother at the expense of some aliasing.<br />`Sinc 8`: 8-point Sinc interpolation. High quality, but high CPU load especially when transposing up.<br />`Vintage`: Emulates a variable rate DAC without an anti-imaging filter (so you might want to add your own lowpass filter tracking the pitch). Low CPU load. |
+| Release Trigger | Group should play when a note-off is received rather than a note-on. |
+| Release Timer | Used as a mod source for attenuation of release-triggered voices depending on how long the note was held. |
+| Sample Start | Adjust the sample start point of all zones in the Group (subject to the zone Start Mod Range setting). |
+| Loop Follows Start |  Possible values are: <br />`Off`: The sample loop set in the Zone is played, unaffected.<br />`On`: The sample loop is shifted to the playback start position, which can then be modulated.<br />`Quantized`: The loop position is rounded to the nearest multiple of the loop length, so startpoint modulation steps through different sections of the sample for wavetable-style playback. For best results set the sample loop to the last wavetable in the sample and Start Mod Range to maximum.<br />`Quant+Phase`: Same as Quantized, but the sample starts playing at a random position within the loop, to avoid unwanted alignment between unison voices. |
+| Mapping Shift | This allows the sample mapping to be shifted up or down the keyboard. Usually used in combination with the Tune parameter to transpose the group, compared to just tuning the group which may play samples outside their normal key range. |
+| Alternate Mapping | Select an alternative set of sample zones to play, instead of this group's zones. |
+| De-glitch Start | Reduce clicks when the sample startpoint is not at a zero crossing. |
+| Mute | Mute the output of this group (unless Solo is on). Does not stop voices in the group from playing. |
+| Solo | Solo this group and mute any non-soloed groups. Set to Ignore if soloing other groups should not mute this one. |
+| Conditions | [Condition*](#Condition*) |
+| ModSources | [ModSource*](#ModSource*) |
+| ModRoutings | [ModRouting](#ModRouting) |
+| Filters | [Filter*](#Filter*) |
+| Zones | [Zone](#Zone) |
+
+## Zone
+Each Group can contain any number of Zone modules. Each Zone loads and plays one audio file. A Zone with no audio file can still be used to trigger voices that use oscillators to generate their sound.
+| Parameter | Description |
+| --------- | ----------- |
+| Sample | Relative path and filename of sample this zone plays. |
+| Status | Displays if the sample was Loaded, Not Loaded, or Not Found. |
+| Volume | Volume offset. |
+| Pan | Pan position offset. |
+| Tune | Tuning offset. |
+| Root Key | Key that will play the sample at its original pitch. |
+| Low Key | Lowest key that will trigger this zone. |
+| High Key | Highest key that will trigger this zone. |
+| Low Vel | Lowest velocity that will trigger this zone. |
+| High Vel | Highest velocity that will trigger this zone. |
+| Low Key Fade | Fade out at bottom of key range. |
+| High Key Fade | Fade out at top of key range. |
+| Low Vel Fade | Fade out at bottom of velocity range. |
+| High Vel Fade | Fade out at top of velocity range. |
+| Fade Curve | Curve of fades (0 = linear, 100 = equal power). |
+| Start | Start point of sample, in frames. |
+| Start Mod Range | Startpoint modulation range in frames. |
+| End | End point of sample, in frames. |
+| Length | Display available length in frames. |
+| Reverse | Play the sample in reverse (from End until Start or Loop Start). |
+| Loop | Enable looping. |
+| Loop Start | Loop start point, in frames. |
+| Loop End | Loop end point, in frames (this frame is not included in the loop). |
+| Slice Length | Imported from Recycle files or set manually - can be read by instrument script. |
+| Zone Param 1 | Per-zone value to use as a modulation source. |
+| Zone Param 2 | Per-zone value to use as a modulation source. |
+| Orig Tempo | Imported from Apple Loop, Acid or REX files or set manually - read by Timestretch module. |
+
+## Alternate Condition
+Lets you define Round Robins, where each note plays a different group in turn. Note that much more detailed conditions can be set up in the instrument script.
+| Parameter | Description |
+| --------- | ----------- |
+| Position | Position of this Group in the cycle of Groups with Alternate trigger conditions (0 = never play). |
+| Next Condition | Logic for combining the result of this trigger condition with the next (if any). 'And' conditions are evaluated before 'Or', so for example: A AND B OR C AND NOT D is evaluated as (A AND B) OR (C AND NOT D). |
+
+## Controller Condition
+Only play the group if a MIDI controller is in the specified range, e.g. only when the Sustain Pedal is down. Note that much more detailed conditions can be set up in the instrument script.
+| Parameter | Description |
+| --------- | ----------- |
+| CC | MIDI controller number. |
+| From | Lowest controller value that enables this Group. |
+| To | Highest controller value that enables this Group. |
+| Next Condition | Logic for combining the result of this trigger condition with the next (if any). 'And' conditions are evaluated before 'Or', so for example: A AND B OR C AND NOT D is evaluated as (A AND B) OR (C AND NOT D). |
+
+## Keyswitch Condition
+Activate different groups depending on which keyswitch MIDI key was last pressed, e.g. for selecting articulations in Orchestral instruments. Note that much more detailed conditions can be set up in the instrument script.
+| Parameter | Description |
+| --------- | ----------- |
+| From | Lowest keyswitch key that enables this Group. |
+| To | Highest keyswitch key that enables this Group. |
+| Next Condition | Logic for combining the result of this trigger condition with the next (if any). 'And' conditions are evaluated before 'Or', so for example: A AND B OR C AND NOT D is evaluated as (A AND B) OR (C AND NOT D). |
+
+## Random Condition
+Use when you want to alternate between two or more Groups in a random order. Note that much more detailed conditions can be set up in the instrument script.
+| Parameter | Description |
+| --------- | ----------- |
+| Next Condition | Logic for combining the result of this trigger condition with the next (if any). 'And' conditions are evaluated before 'Or', so for example: A AND B OR C AND NOT D is evaluated as (A AND B) OR (C AND NOT D). |

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

@@ -0,0 +1,59 @@
+# Gorilla Editor — Module Reference: Miscellaneous Modules
+
+Covers: Alternate Mapping, Voice Group, Wavetable, MIDI File, and Data File.
+
+## Contents
+1. [Alternate Mapping](#Alternate-Mapping)
+2. [Voice Group](#Voice-Group)
+3. [Wavetable](#Wavetable)
+4. [MIDI File](#MIDI-File)
+5. [Data File](#Data-File)
+
+---
+
+## Alternate Mapping
+Collection of Zones that can be played by any Group, as an alternative to the Group's own Zones.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this Mapping. |
+| Active | When switched off, this mapping's samples will be purged (not preloaded in memory) unless they are used in other Groups or Mappings. |
+| Zones | [Zone](#Zone) |
+
+## Voice Group
+Polyphony management settings. The available voices in a Voice Group are shared between all Groups assigned to that Voice Group. There is always at least one Voice Group called Instrument Voices which sets the overall maximum polyphony of the instrument. If a Group is not assigned to a Voice Group its polyphony is still managed by the Instrument Voices settings.
+| Parameter | Description |
+| --------- | ----------- |
+| Max Voices | Maximum number of voices for all Groups assigned to this voice Group. |
+| Per-Key Voices | Maximum number of voices on the same note (leave set to '-' if not needed). |
+| Voices | Displays the current number of voices played in this Voice Group. |
+| Voice Stealing | Priority mode for stealing voices when Max Voices is exceeded. |
+| Prefer Released | Prefer to steal voices that were already released. |
+| Exclusive Group | When a voice is triggered, all voices in other Groups with the same Exclusive Group setting in their voice Group will be cut off. |
+| Fade Time | Fade-out length for voices that get stolen. |
+
+## Wavetable
+Set of waveforms that can be played by the Wavetable oscillator. The size and number of waveforms in the wavetable can be varied, and they be overwritten by dropping a WAV file. When using the 'windowed' option the spectrum is measured at equally spaced points along the WAV file, otherwise the WAV file is assumed to contain a series of single cycle waveforms to import. The import uses the current size and number of waveforms - it can help to try adjusting these to get the best import, or adjusting the wavetable size (number of harmonics) after import.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this module. |
+| Waves | Waveform/spectrum editor. |
+
+## MIDI File
+MIDI sequence, created by dragging a .mid file into the instrument. Can be accessed by the instrument script.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this module. |
+| File Path | Displayed the location of the MIDI file on your computer |
+| Reload | Re-loads the MIDI file into the module (for example, if the file has been edited) |
+| Tracks | Displays the number of tracks in the sequence. |
+
+## Data File
+Array of data, created by dragging a .csv or .nka file into the instrument. Can be accessed by the instrument script. The file should only contain integer values separated by commas and line breaks.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this module. |
+| Save Changes | Determines if and how modified data is saved. OFF means data is not saved. SESSION means modified data is saved with the session. PATCH means modified data is saved with the patch. |
+| Range | Sets the available range for step values. Options include +/- 128 steps, +/- 20,000 steps, or +/- 1,000,000 steps. |
+| Steps | Sets the maximum number of steps in the data file. |
+| Data | Data is visually displayed and can be edited by click-dragging. |
+| Step Value | The currently selected step (highlighted) with precision by click-dragging its numerical value or by double-clicking the value and entering it directly. |

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

@@ -0,0 +1,85 @@
+# Gorilla Editor — Module Reference: Modulation Modules
+
+Covers: ADSR Env, Custom Env, LFO, Step Seq, and Mod Routing.
+
+> **Cross-references:** `ModRouting` is defined in this file and referenced throughout voice effects and bus effects files.
+
+## Contents
+1. [ADSR Env](#ADSR-Env)
+2. [Custom Env](#Custom-Env)
+3. [LFO](#LFO)
+4. [Step Seq](#Step-Seq)
+5. [Mod Routing](#Mod-Routing)
+
+---
+
+## ADSR Env
+Standard synthesizer envelope, to use as a mod source.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this mod source. |
+| ModRoutings | See [Mod Routing](#Mod-Routing) |
+| Attack | Attack time. |
+| Attack Curve | -100% (slow to reach final value) to +100% (fast to reach final value). |
+| Hold | Hold time at maximum level. |
+| Decay | Decay time. |
+| Decay Curve | -100% (slow to reach final value) to +100% (fast to reach final value). Typically 75 - 90% for exponential curves. |
+| Sustain | Sustain Level. |
+| Release | Release time. |
+| Release Curve | Typically +90% for exponential fade out, or 0% for linear. |
+| Hold End Level | Level at the end of the Hold stage. |
+| Times x10 | Multiplies all time parameters by 10. |
+| Tempo Sync | Sync envelope times to host tempo. |
+
+## Custom Env
+Customizable multi-point curve, to use as a mod source.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this mod source. |
+| ModRoutings | See [Mod Routing](#Mod-Routing) |
+| Sync | Measure envelope stage lengths in seconds or quarternote beats. |
+| Curve | Edit the envelope points. |
+| Randomize Levels | Randomize the level of each envelope point on each trigger. |
+
+> **Scripting tip — Controllable segment timing:** A `Custom Env`'s internal `ModRoutings` can use `Dest: "Time 1"`, `"Time 2"`, etc. to modulate individual segment durations from an external mod source (e.g. `MIDI CC`). Set the routing up in Gorilla Editor, then use `set_controller(cc, value)` in the script to control the timing at runtime. This is the standard way to make custom envelope speed scriptable. See the *Glide via ModSourceCustom + set_controller* pattern in [script-patterns.md](./script-patterns.md).
+
+## LFO
+Low Frequency Oscillator, to use as a mod source.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this mod source. |
+| ModRoutings | See [Mod Routing](#Mod-Routing) |
+| Wave | Sine, Triangle, Square, Saw, Random (random steps), Drift (smooth random), Saw Up, Saw Exp (exponential decay). |
+| Rate | Duration of 1 cycle of the LFO waveform. |
+| Sync | Set Rate units to Hz (cycles per second) or beats (quarternotes per cycle). |
+| Retrigger | When Off, all voices will be modulated together in sync. When On, the LFO for each voice starts from the beginning when the note is triggered. |
+| Start Phase | This shifts the starting point in the LFO waveform. It is most useful when Retrigger is off and Sync is set to beats: then it adjusts the alignment of the LFO waveform relative to beats on the song timeline. |
+| Unipolar | When On, the LFO output varies between 0.0 and 1.0, rather than -1.0 and 1.0. |
+
+## Step Seq
+Step sequence generator, to use as a mod source.
+| Parameter | Description |
+| --------- | ----------- |
+| Name | Name to display for this mod source. |
+| ModRoutings | See [Mod Routing](#Mod-Routing) |
+| Rate | Length of each step in beats. |
+| Steps | Number of steps to repeat (1 to 32). |
+| Sequence | Level for each step. |
+| Retrigger | When Off, all voices will be modulated together in sync. When On, the sequence for each voice starts from the beginning when the note is triggered. |
+
+## Mod Routing
+Modulation routing, to modulate a parameter of the module containing the routing by one of the available mod source signals. Each Group can contain up to 64 mod routings.
+| Parameter | Description |
+| --------- | ----------- |
+| Active | Switch the modulation routing on and off (an inactive routing still uses a little CPU, so delete any that are no longer needed). |
+| Source | Modulation Source. External (MIDI) and Group (e.g. envelope and LFO) sources are available here. Possible values are: <br />`Constant`: Constant maximum value<br />`Random`: Random bipolar value between -1 and +1<br />`Random +`: Random unipolar value between 0 and 1.<br />`Pitch Bend`: Incoming MIDI pitch bend.<br />`Aftertouch`: Incoming MIDI channel pressure.<br />`MIDI CC`: The current value of the specified MIDI controller.<br />`Use MIDI Channel`: Use the pitch bend, aftertouch or CC value from the note's MIDI channel. When off, uses the last value received on any channel.<br />`Key`: Keyboard position relative to C3. Value increases by 1.0 per octave. For convenience, Key includes all other pitch modulation such as Pitch Bend when used to modulate a voice effect.<br />`Velocity`: Incoming MIDI velocity.<br />`Release Timer`: Set on note release based on Group Release Timer setting. value is 1 if note is released immediately, 0.5 if released after half the Timer time, and so on).<br />`Glide`: Distance relative to previous key, if Instrument Glide setting is active.<br />`Event Param 0`: Value set by script or an envelope follower.<br />`Event Param 1`: Value set by script or an envelope follower.<br />`Event Param 2`: Value set by script or an envelope follower.<br />`Event Param 3`: Value set by script or an envelope follower.<br />`Release Vel`: Release velocity (bipolar, zero until note released).<br />`Vel In Zone`: Velocity relative to zone velocity range (from -1 to 0).<br />`Zone Param 1`: Value read from the Zone being played.<br />`Zone Param 2`: Value read from the Zone being played. |
+| CC | Selects the MIDI controller to monitor when Source is set to MIDI CC. |
+| Invert | Reduce the destination parameter instead of increasing it. |
+| Depth | Amount of modulation. (100% pitch modulation = 1 octave). |
+| Smooth | Smoothing of parameter changes - useful for MIDI controllers. At the maximum setting the initial value is held forever. |
+| Dest | Destination parameter to be modulated (depends on the module the routing is inserted in). |
+| Curve Active | Determines if a custom curve is applied to the source value. |
+| Curve | Edit the curve points. |
+| Use MIDI Channel | For MIDI source, use the last value on the channel that triggered this voice, rather than the last value on any channel. |
+| Freeze In Release | Hold the source value so it doesn't change after the key is released. |
+| Custom Dest | Additional destination parameter for advanced routing. |