Table of contents

About this Guide

This document will provide an introduction to User Interface development for Gorilla Engine SDK-based products.

User Interface development is when you add a custom graphical user interface (“UI” or “GUI”) to your virtual instrument or effect. This means you can select your own on-screen controls (knobs, buttons, sliders, etc.), background images, fonts, colors and layout for the product you wish to build. These on-screen controls bind to any of the available parameters inside your instrument (in the .blob file) allowing end users to interact with your instrument.

Where does this fit into the development process?

The Gorilla Engine SDK development process is not fixed and can vary between projects, but the general stages are as follows:

Stage 1: Designing the sonic component of your instrument or plugin

In this stage, you design the sonic component of your virtual instrument or effect using Gorilla Editor. This includes things like setting up your sample layers, keyboard split points, filters and effects, signal/modulation routing, and much more.

Note that there is no user interface yet and the only way to interact with your plugin (i.e., to play the instrument or run sounds through an effect) is by loading it into Gorilla Editor. The Gorilla Editor User Guide covers this subject in detail.

Stage 2: Defining user-facing controls with Gorilla Script

In Stage 2, you are still working inside Gorilla Editor but you use Gorilla Script to define controls that you would like to expose to your end users. For example, if your instrument includes a filter, you will most likely want to expose its Cutoff and Resonance controls as user-editable controls. You can do this by adding some Gorilla Script code into Gorilla Editor in order to expose those parameters. The Gorilla Script Reference covers this subject in detail.

Pro Tip: Not every parameter needs to be user-accessible and the best instruments often only expose “musically relevant” controls to users. Musically uninteresting/unnecessary parameters are often hidden away (or “hard coded” by developers) to prevent overloading end-users with too many options.

Stage 3: Early testing with auto-generated GUI

In stage 3, you export your instrument or effect from Gorilla Editor as a “.blob” (binary large object file) and load it into Gorilla Tester. This .blob file includes all samples, routings and other parameters AND any Gorilla Script you’ve created in one convenient place.

Note: The amount of parameters that can be exposed in Gorilla Tester is currently limited to 1000. In case you exceed that limit, on the first 1000 will be available.

Since you have not created any graphical assets yet, Gorilla Tester loads the .blob file and automatically generates on-screen knobs to control the parameters you have decided to expose with Gorilla Script (in stage 2).

Gorilla Tester lays out the on-screen in the order they appear in the Gorilla Script document. Note that the auto-generated GUI is not a good-looking interface–it is simply there to let you test your product in a “real world” context alongside other plugins in any host music application of your choosing (Ableton, Live, Logic, etc.) This lets you ensure that all of your controls work as expected and that the mapping, range, and logic of the controls are correct.

Stage 4: Adding a custom user interface [this document]

In stage 4, you continue to test your plugin in Gorilla Tester, but now you replace the auto-generated GUI with your instrument’s own, unique user interface. For example, you can choose what each control should be (a knob, a slider, a switch, a button, etc.), the “look and feel” of the control (vintage, modern, etc.), and where it should be positioned on-screen. You can also set background graphics, fonts, colors, texts and other things as they appear to end users.

This stage often involves making minor tweaks like rearranging the order of controls or moving controls around by a few pixels until they appear “pixel perfect” on screen.

Note that Stage 4 involves several key items like the .yaml file, the .js file, and your various asset files. We’ll cover these in detail in the next section of this document.

Once you are happy with your plugin, we are ready for Stage 5.

Stage 5: Compiling your plugin

This is the last stop of the Gorilla Engine SDK development process. When your plugin looks and sounds great, it’s time to compile it into a finished, working product using Gorilla Compiler. The compiler generates not only a finished working plugin, but a complete installer for Windows or macOS so you basically have a sellable, finished product that is ready to go.

You can find out more in the Gorilla Compiler User Guide.

Key UI elements in detail

When developing a UI for a Gorilla Engine SDK based product, there are a few files/concepts that you need to know:

YAML

YAML is a markup language that describes the appearance of your plugin’s UI. If you have ever developed a website using .HTML, working with .yaml files will hopefully feel familiar to you.

Your instrument’s .yaml file describes both static elements (fonts, colors, background pictures, etc.) and dynamic elements (knobs, sliders, displays and anything a user can click or otherwise interact with.) As an example, let’s say you would like to place a slider on screen. To do this, you will need to specify a number of parameters such as: the slider’s X/Y location, details of the graphical “filmstrip” file containing images of the fader in all possible positions, whether the fader is vertical or horizontal, and so on. All of the information for your on-screen controls is found in your instrument’s .yaml file.

Containers

Just like many other web-development languages, all of the visual elements of your plugin (controls, displays, texts, etc.) can be placed within “containers.” A container is basically a box that houses a set of logically grouped controls. The typical container to use in Gorilla Engine is the label. There is no requirement to use containers with one exception: All your controls - whether nested or not - need to be children of the top level container window. This top level container also has some properties like width and height for you to set the size of your plugin’s UI.

yaml_containers

The first few lines of a .yaml document (i.e., lines 1-4 above) usually set the window size of your plugin. In the example above we:

Create a window (line 1)
Set the window’s width to 515 pixels (line 2)
And set the window’s height to 470 pixels (line 3)
The background_colorparameter (line 4) sets the color of the window in hexidecimal formatting.

Pro Tip: Setting all backgrounds to the same color effectively makes them invisible to end users. Setting no background color makes the control or container transparent.

Lines 5 and 6 determine the minimum and maximum allowable scaling factor (when resizing a plugin window).

These six lines determine the size of your plugin as it appears on-screen. Inside this window, you can start placing controls or create as many sub-containers as you would like. In the example above:

We create a sub-container by placing a label as a child of the window.
Each child item can be of any type (label, text box, slider, etc.) In this case we put another label into the container label.
Lines 9-10 set the X and Y origin of the newly created sub container relative to the original container (the top-left corner is the 0, 0 position and this container originates there)
Lines 11-13, we set the width, height and background color of the first container.

Pro Tip: For simple plugins, the entire screen may be one single container whereas with more advanced plugins, you may wish to have many containers arranged in columns and/or rows each with its own group of controls. For example, you may have one container for your plugins filter parameters whereas a separate container nearby has your oscillator parameters. Having controls placed in separate containers makes it easier to quickly rearrange entire blocks of controls without having to move each control one-by-one. Also, switching visibility on a container affects all controls contained within that container. This can be a handy way to show and hide things appearing on-screen.

Knobs, Sliders and other elements

wet_dry_mix_knob

Let’s say we wanted to add a wet/dry control knob to an instrument (as shown above):

Start with a Knob: property.
Next we set the x: and y: position of the knob in pixels (relative to the container that houses the knob)
Next we set the width: and height: of the knob control (64x64 pixels). This, in turn sets the knob’s window size for the filmstrip.
The value&: instrument.wetdrymix line links this control to the “wetdrymix” parameter in the instrument (in the .blob file)
The filmstrip: line (and the path and count lines below it) specify the filmstrip image location and the number of frames contained within the filmstrip.
Next, we create a label: and position it using the x: and y: (x=22 and y=70), as well as its width: and height: (width=80 and height=24)
Since the label is a text control and we want the text centered, we use text_align: center
The value&: binds the text displayed on screen to the value of the wetdrymix parameter inside the instrument.
The format: lets you define a template string where additional information is shown beyond the value. In this case, the information shown on screen will appear as “current wet dry mix is “ followed by the text value of the parameter.

Comments

comments

Addding a “#” to the beginning of any line in your .yaml file makes that line a “comment.” Comments are ignored by Gorilla Tester and Gorilla Compiler and are there so you can leave hints and reminders to yourself or others looking at your code.

Pro Tip: Comments can also be very useful when troubleshooting since they let you quickly remove a block of code to see if it is causing a problem. Simply comment out a section of code and if the problem disappears, you know that the problem is likely originating from something in the commented code.

JS (JavaScript)

Your instrument’s .js (JavaScript) file links your instrument or effect (i.e., the .blob file) to the on-screen controls (as defined in the .yaml file). The JavaScript file also determines the logic of your on-screen controls. This means JavaScript handles the basics (pointing to the .blob and .yaml files) but also lets you add all kinds of powerful features if you are an advanced user.

The good news for beginners, however, is that–in many cases–there is no need to touch this file at all. If you are developing your first instrument, you can simply copy the .JS file from the Basic Synth example and use that with your own plugin with no further modification.

To learn more about the JavaScript file, please refer to the Gorilla Tester User Guide.

Plugin Assets

Besides the BLOB, YAML and JS files, your plugin will have a variety of other assets like graphics, fonts and other files needed for it to work properly.

Filmstrips

filmstrip_example

A filmstrip is an image file that contains all possible positions of an on-screen control. It can contain as little as two states (an on/off switch) or a large number of states (128 “steps” of a fader or knob moving across its range).

The filmstrip shown above is a simple on/off switch with two states (“on” at the top; “off” at the bottom). This filmstrip has a width of 72 pixels and a height of 80 pixels. Since it is 80 pixels tall and has two states, we can deduce that the “window” size (the size required to properly display exactly one state of this control) is 72 pixels wide by 40 pixels tall (since 80 / 2 = 40).

Note that some filmstrips may be have 128 possible states and, as a result, be thousands of pixels tall. This is normal. For example a 24 pixel tall crossfader with 128 steps will be 3072 pixels tall (24 * 128 = 3072)

The code surrounding for a 64x64-pixel on-screen knob with 128 possible steps is shown below.

knob: null
x: 30
y: 20
width: 64
height: 64
value&: instrument.wetdrymix
mouse_down_action: ui.mouseDown_wetdrymix
mouse_up_action: ui.mouseUp_wetdrymix
filmstrip: &knob_img
path: images/Rotary Knob Large.png
count: 128

Please refer to the JavaScript API Reference for more information.

Fonts

fonts

Gorilla Engine SDK supports OpenType (.otf) format fonts. We recommend putting them in a sparate “fonts” subfolder for each plugin so that they remain organized.

Fonts can be referenced, sized and aligned using the following:

font:

font_size:

fontKerning:

textColor:

text_align:

For more information, please refer to the JavaScript API Reference.

Other Assets

Note that plugin assets are not limited to filmstrips and fonts. Any type of file your plugin needs to run is an asset and can (should) have its own subfolder. Doing so will keep your assets organized and the Gorilla Compiler can load any number of asset folders.

General Tips on User Interface Design

The design of graphical user interfaces is a broad and fascinating subject. It is beyond the scope of this guide to cover all the best practices in detail. However, we would like to share two tips as general guidance for users of this SDK:

User Interfaces greatly affect the functionalty and “look and feel” of a product. A well designed instrument with sensibly laid out controls and good-looking graphics can really improve an end user’s impression of your product. We include a collection of knobs, buttons, sliders and other elements in the SDK to get you started, however, it may be a good idea to bring in a designer to help build your product’s graphical elements if you yourself are not an expert in this area. Doing so will help you get exactly the right “look and feel” for your product.
User Interfaces should expose the right controls of a product to your end users. An instrument or effect may have dozens or even hundreds of available parameters “under the hood.” Exposing all of these parameters can overwhelm and even irritate users. Curating the available options down to a managable set of controls is critical in shaping an end user’s experience of your product. Use beta testing to validate your assumptions!

There are many fantastic books, websites, videos and more on user interface design and we strongly encourage you to explore those options to learn more.