Table of contents
Minimal Example
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 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
Volumewith 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.
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 (we provide a JavaScript reference. The following examples are meant to be a starting point on how to implement 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-explaining. However, if you would like an overview of all available UI controls and their properties, take a look at our Gorilla Engine - JavaScript API Reference.
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
If you are interested in more details on GUI development, take a look at our Intro to UI Development guide.