Quick Start

Prerequisites

• Node.js LTS including NPM

  Download and install the .pkg installer for macOS or the .msi installer for Windows. Both installers include NPM, which is needed to run the commands in this guide.

• A Gorilla Engine.com user account and SDK installation, version 26.10 or later

• Windows: There are some Windows specific prerequisites to go over before diving into this guide, please refer to the section covering this topic at the bottom. This guide is qualified and tested for Windows 11. The workflow should also work on Windows 10, but it is not officially supported.

A Note for Users without Software Development Background

Whenever this guide asks you to run a command, we mean executing it in Terminal. Use PowerShell on Windows if there is no Terminal app. Simply copy and paste the command, then press Enter to run it.

Create a Plugin Project

Run the generator to create a plugin:

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

The generated project includes a Gorilla Engine project file (.ugep), a React and TypeScript UI, instrument and asset templates, and build and deployment scripts.

Build and Install

Move into the generated project directory, then build and install the plugin:

cd "your-plugin-folder"
npm run buildAndInstall

The plugin is compiled in the cloud, which may take a few minutes. Run the command again when the .ugep file changes, such as after changing outputs or exposed parameters.

The first build on a machine prompts for your Gorilla Engine.com credentials.

Develop

Developer-focused IDEs

After the build and install above finishes, run this command in your IDE’s integrated terminal or any terminal of your choice:

npm start

This opens the standalone plugin and automatically updates and restarts it when you save changes. Keep npm start running while you work; you can minimize the terminal window, but closing it stops the watcher.

• In a DAW, re-instantiate the plugin after source updates.

If you use an AI chat panel in your IDE, you can ask its agent to make changes to the project. While npm start is running, changes are deployed and the standalone plugin reloads automatically.

AI coding apps

Open the generated project folder in your AI coding app and tell its agent what you want to build or change.

On the first run, the deploy tool asks to make its installed plugin files writable. On macOS, type y and press Enter, then enter your Mac administrator password and press Enter if Terminal asks. No characters appear while you type your password; that is normal and expected. On Windows, choose Yes in the User Account Control dialog.

If your AI app cannot show these prompts or keep the preview running:

1. Open Terminal on macOS or PowerShell on Windows.
2. Set the terminal’s location to the generated project folder. You can right-click the folder in Finder or Windows Explorer and choose Services > New Terminal at Folder or Open in Terminal if available. Otherwise, type cd followed by the folder’s path in quotes, then press Enter.
3. Type npm start and press Enter.
4. Respond to the permission prompt as described above. Keep the terminal open while you work; you can minimize it, but closing it stops the preview.

Debugging in VS Code

Projects created by the scaffolding tool and the SDK’s Gorilla Engine React examples include .vscode/launch.json with JavaScript debugger configurations. You must first build and install the project with npm run buildAndInstall; the debugger uses the installed application, not the project source alone. Then open Run and Debug in VS Code, select Start & Attach, and click the play icon. This starts the installed standalone application and attaches the debugger so you can set breakpoints and inspect your application code. Stop any standalone instance started by npm start before launching another through the debugger.

This is application-layer debugging, not native C++ DSP debugging.

For plugins that require a DAW for testing or debugging, edit .vscode/launch.json: in Start application, replace command (or windows.command on Windows) with a command that launches your chosen DAW executable directly. Keep the <MANUFACTURER>_<PLUGINNAME>_DEBUG_PORT variable in env and the matching port in Attach to started application unchanged. Fully quit the DAW, then select Start & Attach in VS Code’s Run and Debug view and click the play icon. Load the installed plugin in the launched DAW before the attachment attempt times out; the plugin waits for the debugger before running its application code.

The process hosting the plugin must inherit the environment variable from the launched DAW. This depends on the DAW and its hosting settings. Start with one plugin instance to avoid fixed-port conflicts between separate hosting processes.

We recommend REAPER for testing and debugging because it starts quickly and supports running VST/VST3 plugins in the DAW’s own process, in a separate process shared by multiple plugins, or in a dedicated process per plugin instance.

Building Release Installers

We recommend setting experimentalDebuggerSupport and buildStandalone to false in pluginConfig in the .ugep file before building release installers. See Release Build Settings in the Gorilla Compiler documentation.

Additional Prerequisites for Development on Windows

Install InnoSetup 6 to create Windows installers.

Allow local PowerShell scripts to run without signing

1. Open Settings. Press Win + I or click Start > Settings.
2. Go to System.
3. Click Advanced (or directly For developers, depending on your build).
4. Navigate to the Terminal section.
5. Expand the PowerShell item.
6. Turn On the toggle: “Change execution policy to allow local PowerShell scripts to run without signing” (wording may vary slightly).
7. Close Settings.
8. Restart any open PowerShell windows so the new policy takes effect.

Optional Troubleshooting

Disabling Smart App Control and enabling Developer Mode are not required for normal setup. Consider the options below if npm run buildAndInstall fails during installation, or if npm start or npm run deploy cannot change permissions or deploy updated code. Try the relevant option, then retry the failed command.

Disable Smart App Control

Disabling Smart App Control reduces Windows protection. Consider this option if Windows blocks the installer or plugin.

1. Open Windows Security (search “Windows Security” in Start).
2. Go to App & browser control.
3. Click Smart App Control settings.
4. Set Smart App Control to Off.
5. Confirm any warnings.

Enable Developer Mode

Consider this option if permission changes or deployment remain blocked.

1. Open Settings (Win + I).
2. Go to System > Advanced (or For developers, depending on build).
3. Navigate to the For developers / Developer options section.
4. Turn Developer Mode to On.
5. Accept any UAC / confirmation dialogs.