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:

JavaScript (JS)

JavaScript is the primary way to build your application and UI logic in Gorilla Engine. Your instrument’s .js file not only links your instrument or effect (i.e. the .blob file) to the on-screen controls, but determines the entire behavior and logic of your plugin’s user interface.

With JavaScript, you have full control over:

Creating and positioning UI controls programmatically
Handling user interactions (mouse clicks, drag operations, etc.)
Implementing custom behavior and animations
Managing state and data flow in your application
Building complex, dynamic interfaces

We strongly recommend looking at the Sequencer example, which is currently the most sophisticated and comprehensive example available in the SDK. It demonstrates best practices for JavaScript-based UI development and showcases the full capabilities of the platform.

To learn more about the JavaScript API and its specifics, please refer to the JavaScript API Reference.

Important Note: While you may see initViewModel used in many existing examples, this function is now deprecated. It was originally designed as a bridge to allow assigning parameters to YAML properties. Although it remains functional for backward compatibility, we recommend using direct JavaScript approaches for new development.

YAML

YAML is a markup language that can be used to define basic structural elements of your plugin’s UI, primarily the window definition. In modern Gorilla Engine development, YAML usage is typically limited to:

Setting the initial plugin window size (width and height)
Setting the initial plugin window scale factor as well as the maximum and minimum scale factor
Defining the window background color
Creating page containers (see the Sequencer example)

While YAML can describe UI controls and layouts (similar to HTML in web development), JavaScript is now the recommended approach for building your plugin’s interface. YAML remains useful for the top-level window configuration, but most UI logic and control creation should be handled in JavaScript. Bear in mind that in the past the majority of UI layout, control positioning, assignment of assets, etc. was handled mainly in YAML so the following sections will contain YAML examples. We intend to replace them in the near future though.

Basic Window Definition

The typical use of YAML in modern Gorilla Engine development looks like this:

window:
  width: 1200
  height: 800
  background_color: '#2a2a2a'
  min_scale: 0.5
  max_scale: 2.0

These lines determine the size and basic appearance of your plugin window. Beyond this, most developers now build their UI entirely in JavaScript.

For legacy information about using YAML for more extensive UI definition, please refer to older examples in the SDK, but note that this approach is no longer the recommended practice.

Note: Property names and their nesting translate 1:1 from YAML to JavaScript so you can apply the following examples also in your JavaScript code.

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.

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 separate “fonts” subfolder for each plugin so that they remain organized.

Fonts are loaded and configured through JavaScript. 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.

Looking Ahead: Gorilla Engine React

We are excited to share that Gorilla Engine React is coming soon! This will be a specialized flavor of React designed specifically for Gorilla Engine, and it will fundamentally change how UIs are built for our platform.

What this means for you:

Current Examples Remain Valid: All existing examples, including the Sequencer, are fully functional and represent the current best practices. Continue using these approaches for your projects.
React Integration Coming in 2026: We are actively working on integrating Gorilla Engine React into the SDK throughout 2026.
New React-Based Sequencer Example: An extensive React-based version of the Sequencer example is currently in development and will serve as a comprehensive reference when Gorilla Engine React launches.
Smooth Transition: We are committed to ensuring a smooth transition path for developers when Gorilla Engine React becomes available.

Stay tuned for more updates as we continue to enhance the Gorilla Engine SDK!

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.