Minimal

![Minimal Example](./images/Minimal Example.gif)

Our Minimal example is intended to give you an idea of the smallest valid instrument we could think of. It’s a great starting point for you own instruments. This example can be found in the examples/Legacy folder of the Gorilla Engine SDK.

This example introduces:

Exposing a parameter using Gorilla Editor & Gorilla Script
Creating a GUI model parameter using JavaScript
Generating and skinning a slider using YAML
Skinning the on-screen keyboard.

Exposing an instrument parameter

Any parameter you want to end up on the GUI of your finished product, has to be created using GorillaScript. Here is how this is done in the Minimal example.

on init
'create properties
  prop_decibels Volume(1000000, 12)
end on

on Volume
  'change instrument volume
  set_module_param(M_INST, 0, 0, 4, Volume)
end on

Create these few lines of code, in any script editor of your choice, and drag&drop the text file into Gorilla Editor. This will create a script module, that tells Gorilla Engine to:

Declare a property named Volume with its value displayed in decibels.
Connect the property to the Volume parameter of the instrument module.

Pro Tip: The script command of almost any parameter in Gorilla Editor can be copied. Just click a parameter and press shift+cmd+c (on macOS) or shift+ctrl+c (on Windows), and paste it to you script editor.

![Gorilla Script Volume](./images/Gorilla Script Volume.png)

When the user adjusts the volume (on the GUI, in the host’s automation, or by loading another preset with a different volume setting) the “on Volume” callback in the instrument script is called, which in turn sets the volume parameter of the instrument module.

This process works the same for all Gorilla Engine based products. We covered this workflow in greater detail, using our Basic Synth example.

JavaScript

Note: The following is not intended as a step-by-step guide on how to use JavaScript with Gorilla Engine. See the Gorilla Engine JavaScript API for current reference documentation. The following examples are meant to be a starting point for implementing your own ideas using the Gorilla Engine SDK.

The following JavaScript code is identical to .js file found in the plugin_assets folder of the Minimal example.

const path = require('path')
const blobPath = path.resolve(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}_part1.blob`
)
const blob = GorillaEngine.loadBlob(blobPath)

const instrument = blob.loadInstrument(
  blob.getInstrumentNames()[0]
)
GorillaEngine.setActiveInstrument(instrument)

const yamlPath = path.resolve(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}.yaml`
)
GorillaEngine.UI.loadUIfromYAML(yamlPath)

const volumeLabel = GorillaEngine.UI.getControlById('volumeLabel')
const volumeSlider = GorillaEngine.UI.getControlById('volumeSlider')

instrument.on('volume', () => {
  volumeLabel.text = instrument['volume'].text
})

volumeSlider.on('mouseExit', () => {
  volumeLabel.text = "Volume"
})
volumeSlider.on('mouseEnter', () => {
  volumeLabel.text = instrument['volume'].text
})

volumeLabel.text = "Volume"

Loading a blob file

All Gorilla Engine based products, whether they are SDK examples or finished high-end plugins, are based on blob files. These contain all the work you did in Gorilla Editor and Gorilla Script. If you’re not aware of how to create blob files, take a look at our Gorilla Editor documentation.

// Node.js builtins are available,
// we use the path module to resolve paths
const path = require('path')

// Construct the path to this example's blob file
const blobPath = path.resolve(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}_part1.blob`
)

// Load the blob
const blob = GorillaEngine.loadBlob(blobPath)

Loading static UI from a yml file

This JavaScript snippet, customizes the behaviour our our volume control. It allows us to display the current decibel value of our volume slider as we adjust it, while displaying Volume as text when the value is not changing.

// Construct the path to this example's UI declaration
const yamlPath = path.resolve(
  GorillaEngine.getResourcePath(),
  `${GorillaEngine.getPluginName()}.yaml`
)

// Load the static UI
GorillaEngine.UI.loadUIfromYAML(yamlPath)

Adding dynamic behaviour to the static UI

This JavaScript dynamically changes the text value of the label that is declared in the yml file below.

// Get a references to the controls with the id 'volumeLabel'
// and 'volumeSlider'. We declared them in the yml file
const volumeLabel = GorillaEngine.UI.getControlById('volumeLabel')
const volumeSlider = GorillaEngine.UI.getControlById('volumeSlider')

// Register an event listener with the instrument that updates the
// label's text whenever the instrument property 'volume' changes.
// This volume property refers to the Volume parameter the we defined
// in Gorilla Script: prop_decibels Volume(1000000, 12)
instrument.on('volume', () => {
  volumeLabel.text = instrument['volume'].text
})

// Register an event listener with the slider that resets the label
// text to Volume whenever the mouse leaves the control
volumeSlider.on('mouseExit', () => {
  volumeLabel.text = "Volume"
})

// Register an event listener with the slider that sets the labels
// text to the actual volume whenever the slider is hovered
volumeSlider.on('mouseEnter', () => {
  volumeLabel.text = instrument['volume'].text
})

// Finally we initialiase the labels text
volumeLabel.text = "Volume"

Declaring a static UI

The following YAML code is pretty straight forward and can be applied to most Gorilla Engine based plugins. The controls are arranged in a tree structure of parents and children always starting with the window node as the root parent. It refers to the plugin frame. More controls are added by appending them to the children property of any node. This example adds three children, a slider, a label and a midi_keyboard to the plugin UI by simply appending them to the children property of the root level window.

It can however sometimes be handy to nest controls inside a wrapper component, i.e. in a label, to group them because their position (x and y coordinate) are relative to the parent, causing them to be moved all at once, if you move the parent. Changing the visibility of any control also affects that controls children and their children and so on.

Most of the used properties and syntax should be self-explanatory. For an overview of the available UI controls and their properties, see the Gorilla Engine JavaScript API.

window:
  width: 515
  height: 260
  background_color: 49494e
  children:
    - slider:
      id: 'volumeSlider'
      x: 55
      value&: instrument.volume
      y: 54
      direction: horizontal
      filmstrip:
        path: images/Slider Microtiming Linear.png
        count: 128
    - label:
      id: volumeLabel
      x: 55
      y: 66
      width: 64
      height: 24
      text_align: center
      font: fonts/SpaceGrotesk-Bold.otf
    - midi_keyboard:
      x: 24
      y: 205
      width: 515
      height: 100
      background_color: 00FF0000
      low_key: 36
      high_key: 101
      keys:
        width: 6.2
        corner_radius: 3
        black_height: 32
        white_height: 50
        black_color: 0b0c0d
        black_outline_color: 0b0c0d
        black_pressed_color: 898a8b
        black_outline_pressed_color: 898a8b
        black_hover_color: '343536'
        black_outline_hover_color: '000000'
        white_color: aeb5b7
        white_outline_color: aeb5b7
        white_pressed_color: ffffff
        white_outline_pressed_color: ffffff
        white_hover_color: d4d7d8
        white_outline_hover_color: ffffff

Volume slider

Let’s take a separate look at the part that creates our volume slider.

- slider:
  id: 'volumeSlider' # The id let's us reference this control from the JavaScript
  x: 55
  y: 54
  value&: instrument.volume # The binding causes this slider to control the instrument parameter volume
  direction: horizontal
  filmstrip:
    path: images/Slider Microtiming Linear.png
    count: 128
# Also note how the width and height can be omitted. They're inferred from the filmstrip (a sprite map)

On-screen Keyboard

Last but not least, let’s take a peek at how to skin the on-screen keyboard.

- midi_keyboard:
  x: 24
  y: 205
  width: 515
  height: 100
  background_color: 00FF0000
  low_key: 36
  high_key: 101
  keys:
    width: 6.2
    corner_radius: 3
    black_height: 32
    white_height: 50
    black_color: 0b0c0d
    black_outline_color: 0b0c0d
    black_pressed_color: 898a8b
    black_outline_pressed_color: 898a8b
    black_hover_color: '343536'
    black_outline_hover_color: '000000'
    white_color: aeb5b7
    white_outline_color: aeb5b7
    white_pressed_color: ffffff
    white_outline_pressed_color: ffffff
    white_hover_color: d4d7d8
    white_outline_hover_color: ffffff

For more details on application development, see the JavaScript Interface documentation.