Microtonic Scripts SDK

This repository contains all the necessary documentation and resources to create GUI scripts for Microtonic. The scripting engine in Microtonic uses a proprietary JavaScript engine based on ECMAScript 3. The engine only works when the Microtonic window is open. There is currently no way to create real-time scripts that process MIDI or audio. Apart from these restrictions, a script can do pretty much anything with the data in Microtonic, and the user interface can look and behave in any way you can imagine.

While script code is running, Microtonic's user interface will freeze. Scripts that run for more than 20 seconds are suspended, and the user gets the option of aborting or continuing. Each Microtonic instance has a memory limit of around 64MB after garbage collection, and scripts that exceed it are terminated. Memory usage can grow faster than raw data size suggests: the smallest allocated JavaScript value, such as a number, uses 16 bytes before any additional array, object, or string storage overhead.

Disclaimer: many proprietary technologies, formats, and languages are involved in creating user interfaces for Sonic Charge plugins. These technologies have evolved organically over time and will continue to do so in the future. There is functional overlap and inconsistencies, and there is no guarantee that a script that works in the current version of Microtonic will work in the next (even though good compatibility is something that we strive for at Sonic Charge).

The documentation in this repository was written for Microtonic version 3.3.4 (build 1048).

Prerequisites

Writing .cushy files, running CushyLint and rendering IVG icons with IVG2PNG need nothing beyond what is bundled in this repository. The CushyLint and IVG2PNG binaries are prebuilt for Windows and macOS and used as-is (on macOS, CushyLint's binaries are built for Apple silicon; see the C++ compiler note below for Intel Macs).

The command-line tools a script author uses run on Windows without Git Bash. Each .sh tool has a .cmd counterpart with the same arguments, output and exit codes, and CushyLint has CushyLint.bat. Run them from a Command Prompt or PowerShell, for example tools\validate-js.cmd.

Node.js is the only tool you may need to install, for these tasks:

• JavaScript validation (tools/validate-js.sh, or tools\validate-js.cmd on Windows): runs ESLint via npx to catch syntax errors, undefined globals and unsupported constructs in .js and .mtscript files before they reach the plugin. Microtonic's engine is ECMAScript 3 with some ECMAScript 5 features, so ESLint parses scripts as ECMAScript 5 and additionally rejects getter/setter literals and with.
• The live scripting bridge (tools/jsconsole-bridge-mcp/): the MCP server that lets an AI assistant run code in a running Microtonic. See Live Scripting Bridge.
• IVGFontConverter: converts TrueType/OpenType fonts to the .ivgfont format used by Cushy and IVG. Requires Node.js to run IVGFontConverter.node.js.
• svg2ivg: converts SVG drafts into IVG with the pinned IVG/tools/svg2ivg.js converter.

The following tools are only needed for SDK maintenance tasks, not for everyday scripting:

• C++ compiler (Xcode Command Line Tools on macOS, MSVC on Windows): only needed when a prebuilt binary cannot run on your machine, in which case CushyLint and the validation scripts build it from source on first use. That happens on Linux, after the bundled sources are updated, and on Intel Macs: CushyLint's PikaCmd and MakaronCmd in CushyLint/build/ are built for Apple silicon only, while IVG2PNG is a universal binary. IVG2PNG renders .ivg files to PNG for visual validation and is sourced from the upstream IVG repository.
• Python 3: required to run tools/bootstrap-docling.sh, which installs Docling into a local virtual environment. Docling is used for the one-off task of converting the Microtonic PDF user guide to Markdown (tools/convert-user-guide.sh).
• Pandoc: required to regenerate the checked-in HTML copies of Markdown reference docs.

Technology Overview

Here is a brief list of the technologies used in Microtonic GUIs:

• Cushy: the layout engine and file format for describing layouts, based on Numbstrict with Makaron support.
• ImpD: a simple imperative computer language disguised as a data format, or the other way around.
• IVG (Imperative Vector Graphics): a compact 2D vector format and renderer written in standard C++, based on ImpD and the NuXPixels rasterizer.
• Makaron: a macro expansion syntax, used to make .cushy files easier to write. Sourced from the Numbstrict repository.
• Numbstrict: an object notation format similar to (but not compatible with) JSON, from the Numbstrict repository.
• NuXJS: our JavaScript engine, fully ECMAScript 3 compliant with features from ECMAScript 5.
• PikaScript: our legacy script language used by older Microtonic scripts and offline tools.

Repository Structure

• agents:

  • Agent instruction packages for AI assistants working with this SDK. See agents/microtonic-script-writer. For a project setup and iteration workflow, see vibe-coding.md.

• CushyLint:

  1. Command-line syntax checker for .cushy files.
  2. Contains cushy.schema, the official reference for the .cushy format.

• docs:

  • Cushy Documentation
  • ImpD Documentation
  • IVG Documentation
  • ivgfont Documentation
  • Makaron Documentation
  • Microtonic JS Reference
  • Microtonic User Guide

• examples: complete example scripts, with screenshots in examples/screenshots.

• IVG: curated vendored snapshot of the IVG source, renderer tools, IVGFiddle output, IVGFontConverter, dependencies, and documentation, pinned to the IVG-2 freeze on IVG main (see IVG/SHIPPING_MICROTONIC_VERSION.md). The IVG/ImpD/ivgfont docs are mirrored into the top-level docs/ by tools/sync-ivg-docs.sh.

• JSConsole.mtscript: an interactive Javascript console for Microtonic.

• legacy: contains documentation for the legacy scripting engine (based on PikaScript).

• Microtonic Resources: a copy of Microtonic's built-in resources (Cushy, IVG, Makaron and schema files, images, patterns and drum patches) for reference. The validators also check it.

• tools:

  • validate-js, validate-examples and validate-static-ivg, each as .sh and .cmd: validators for JavaScript, the examples and static IVG files.
  • IVG2PNG: the prebuilt IVG renderer, and build-ivg2png.sh/.cmd to build it from source.
  • jsconsole-bridge-mcp: the MCP server for the live scripting bridge, registered in .mcp.json.
  • install-jsconsole.js and locate-scripts-folder.ps1/.cmd: install JSConsole and find the Microtonic Scripts folder.
  • Utilities for maintaining the generated documentation.

• tmLanguages: syntax highlighting support for Sonic Charge formats and languages.

Maintaining Documentation

Most reference documentation is edited as Markdown under docs/. Some files also have checked-in .html copies for offline viewing. After editing a Markdown file with a matching HTML file, regenerate the HTML with:

tools/regenerate-doc-html.sh "docs/Microtonic JS Reference.md"

Run tools/regenerate-doc-html.sh with no arguments to regenerate every Markdown file in docs/ that already has a checked-in HTML target. The script uses pandoc -s --no-highlight so regenerated output stays close to the existing plain code-block style.

llms.txt is a generated section index of the docs, agent notes and schemas, with line ranges and sizes, for agents with small context windows. After editing any indexed file, regenerate it with node tools/generate-doc-index.js. tools/validate-examples.sh fails while the index is stale.

Cushy

Cushy is the GUI / layout engine used in all Sonic Charge products. .cushy files define the layout of views and configure how the user can interact with the plugin through GUI variables and GUI actions. The format is based on Numbstrict, the object notation format used in all Sonic Charge products. Numbstrict is similar to JSON with the following differences:

1. C-style comments are supported.
2. You use curly brackets ({ and }) for both structures and arrays.
3. To differentiate empty structures from empty arrays, you may use this syntax: { : }.
4. You may express integer values as hexadecimal numbers in this format: 0xABCD.
5. Real values include infinity (inf) and the NaN value (nan).
6. Free-form text values without quotes are allowed in many cases.
7. You can use \U inside quoted strings to escape a 32-bit Unicode character, e.g., \U0001F9FF.

Here is an "outline" of the Cushy file structure:

bounds: { <left>, <top>, <width>, <height> }
autoexecs: {
    ... actions to run on open, close, or regularly on a timer
}
transitions: {
    ... visual transition effects applied when this Cushy is opened or closed
}
translations: {
    ... special string translations used for this Cushy.
}
views: {
    ... view definitions
}

In Cushy, it's often possible to write mathematical expressions where numerical constants are expected. In these places, $ may be used to insert the default value for the field. E.g., updateRate: $*2 would set updateRate to twice the default. For rectangles such as view bounds you can also use the following variables: t, l, w, h, r, b for top, left, width, height, right and bottom of the default rectangle. E.g. bounds: { l+10,t+10,w-20,h-20 }. The default rectangle for a view bound is the full bounding box of the parent view.

The Numbstrict format can be challenging to write correctly, especially when containing deeply nested hierarchical views and actions. Therefore we created CushyLint, a command-line tool to check the syntax of a .cushy file against the official "schema" specification. Simply run CushyLint (Mac) or CushyLint.bat (Windows) from a command-line prompt with the single argument specifying a single .cushy file path to check or a directory if you want to check multiple files. Directories must end with a slash (/ or \). Relative paths are relative to the current directory.

The files are checked against the official cushy.schema file in the CushyLint directory, plus any other .schema files existing in the directory next to the .cushy file that you are checking. The cushy.schema file is designed to be readable and contains lots of comments, thus also serving as a kind of official reference documentation on .cushy files, available view types, and built-in actions.

Furthermore, you can use macros when writing .cushy files for easier development and maintenance. See Makaron Documentation for documentation on the macro expansion language we use. Macros you write are expanded when .cushy files are loaded inside the plugin, before they are parsed.

For an orientation to the Cushy system (the mental model, coordinates and scaling, what is static versus dynamic, and a map of where each part is documented), see Cushy Documentation. See also cushy.schema and Microtonic JS Reference for more information on how to write Cushy.

IVGFiddle

Included in this distribution is a standalone .html application called IVGFiddle. You can run it simply by opening the IVG/tools/ivgfiddle/output/ivgfiddle.html file in your favorite browser (Google Chrome). It will let you experiment with IVG code and see the graphical output in real-time.

See IVG Documentation for more information on IVG.

IVG2PNG

The IVG directory is a curated vendored snapshot of the upstream IVG repository. A prebuilt IVG2PNG binary for macOS and Windows is included in tools/IVG2PNG/ so no compiler is needed for normal use.

Use IVG2PNG as the preview loop while authoring a single icon or vector asset, not only as a bulk validator. Render the actual .ivg after each meaningful change; do not substitute an SVG approximation or a generic image renderer that may silently omit stroked paths. The single-file recipe covers background colors, scaled glyph previews, and comparison strips.

To render all static .ivg resources in this SDK:

tools/validate-static-ivg.sh        # macOS / Linux
tools\validate-static-ivg.cmd       # Windows

To check your own files instead, pass .ivg files or folders (searched recursively) relative to the current directory, and optionally --out <dir> for the PNGs and logs:

tools/validate-static-ivg.sh [--out <dir>] [<path> ...]

The rendered PNGs are written to microtonic-static-ivg-validation in the temp directory by default ($TMPDIR, else /tmp, on macOS/Linux and %TEMP% on Windows). IVG files that depend on Cushy or GUI variables, use include statements, or are helper files with no top-level bounds are reported as skipped by this static renderer pass.

If the prebuilt binary cannot run on your platform, the scripts automatically rebuild IVG2PNG from source using tools/build-ivg2png.sh (macOS/Linux) or tools\build-ivg2png.cmd (Windows, requires MSVC).

svg2ivg

The curated IVG snapshot also includes the pinned upstream SVG converter:

node IVG/tools/svg2ivg.js input.svg output.ivg

See SVG Support for the supported subset. Treat converted output as a draft: svg2ivg emits a verbose IVG-1 representation, while hand-written SDK icons commonly use a compact IVG-2 form. Tidy the result and verify it with IVG2PNG. For simple shapes, SVG path data can be copied verbatim into IVG's path svg:[...]; the converter earns its keep on transforms, gradients, and groups.

IVGFontConverter

Cushy (and IVG) uses a proprietary file format for fonts: .ivgfont. You can use IVGFontConverter to convert a TrueType or OpenType font to this format. To run, you must install node.js. Then use it like this:

node IVG/tools/IVGFontConverter/IVGFontConverter.node.js <input> [ ?|-|<feature>[,<feature>,...] ] [ <charset>[,<charset>,...] ] > <output>

  ?          List all GSUB features
  -          No extra GSUB feature
  <feature>  Enable GSUB feature by [<script>.[<language>.]]<feature>
  <charset>  Convert Unicode characters [<hex>[-<hex>]] (default is ISO-8859-1)

Example: node IVG/tools/IVGFontConverter/IVGFontConverter.node.js font.otf >font.ivgfont
Example: node IVG/tools/IVGFontConverter/IVGFontConverter.node.js font.otf ss01 >font.ivgfont
         node IVG/tools/IVGFontConverter/IVGFontConverter.node.js font.ttf latn.ROM.locl,latn.ss01 >font.ivgfont
         node IVG/tools/IVGFontConverter/IVGFontConverter.node.js font.ttf - 0020-007f,a0-cf >font.ivgfont

See ivgfont Documentation for details on the generated font format.

JSConsole

A console (JSConsole) is available for developing scripts. It runs inside Microtonic and allows you to enter JavaScript code interactively, see traces, reload all resources and see script performance (as frames per second). Microtonic scripts do not have a step-through debugger or browser-style developer tools, so the normal debugging workflow is to install and open JSConsole.mtscript and use print("message") from script code to write trace output to the console. For blocking checkpoints or user-visible diagnostics, use display("message"), which shows a modal alert and pauses script flow until the user dismisses it.

Install it by copying JSConsole.mtscript to the Microtonic Scripts folder. (You can easily find this folder by choosing Open Scripts Folder from the "puzzle menu" in Microtonic.)

To copy this SDK's bridged JSConsole into a confirmed scripts folder:

node tools/install-jsconsole.js "/path/to/Microtonic Scripts"

With no argument, the helper prints the SDK source path and platform-specific target hints. The helper refuses to run unless the source console contains the bridge commands, which avoids accidentally installing a plain JSConsole copy.

On Windows, before the bridge is installed, you can usually locate the same folder with tools\locate-scripts-folder.cmd -Verify; it mirrors Microtonic's registry lookup. Confirm the result against Open Scripts Folder before writing.

Microtonic caches resources while the GUI window is open, including JavaScript source files loaded by scripts. When editing a GUI script over the bridge, use mt_reload with an until expression that observes the change; reload is asynchronous, so a bare mt_eval("performCushyAction('reload')") returning does not mean the new code is live. In the JSConsole window, use the reload button or type reload to flush cached resources and rebuild the open GUI. A normal reload reruns JavaScript files but keeps the current JavaScript engine and existing globals alive. Shift-clicking the JSConsole reload button, or typing reset, performs a full JavaScript engine reset, which clears memory and starts from a clean scripting environment. Closing the Microtonic GUI window also destroys the entire JavaScript environment, so reopening the GUI starts with no previous script globals, like a full reset.

Live Scripting Bridge

The bridged JSConsole can also take code from outside Microtonic, so an AI assistant can evaluate JavaScript in the running engine, inspect and drive an open GUI script, and reload edited files without GUI automation. Every Microtonic script shares one global space, so code sent over the bridge sees the globals of the script you are working on.

• The MCP server is tools/jsconsole-bridge-mcp/server.js (Node.js). This repository's .mcp.json registers it as microtonic-bridge for MCP clients such as Claude Code.
• It provides three tools: mt_eval runs code and returns the value and print() output, mt_status checks whether the bridge is actually responding, and mt_reload reloads scripts and waits for an until expression to confirm the new code is live.
• To enable it, install the bridged JSConsole.mtscript (see JSConsole), open it in Microtonic and type bridge on. Run mt_status to confirm it reports bridge: LIVE.
• Requests and replies are exchanged through a fixed shared folder (C:/Users/Public/Sonic Charge/Microtonic/ on Windows, /Users/Shared/Sonic Charge/Microtonic/ on macOS, in jsconsole-bridge/). Calls run one at a time.

See tools/jsconsole-bridge-mcp/README.md for setup with other MCP clients, the protocol and troubleshooting.

Development Scripts Folder

For quicker round-trips during development, keep a project-local copy of the entire Microtonic Scripts folder and link Microtonic's scripts folder to it. See Development Scripts Folder for macOS and Windows commands, including re-linking an existing symlink and using macOS' administrator dialog for elevated link steps.

On Windows the live folder is normally under C:\Program Files\Sonic Charge\Microtonic Scripts, which usually requires elevation for every copy. Before the bridge is installed you can locate it with tools\locate-scripts-folder.cmd -Verify. In that case, consider the development-link workflow before the first manual install so later edits are elevation-free.

Syntax Highlighting

TextMate Language Grammars are available for most of the custom languages and formats used by Sonic Charge. You find them in the tmLanguages folder. We have tested them in Sublime Text and Visual Studio Code. Installation instructions:

• Sublime Text

  Use the menu Preferences > Browse Packages... to open Packages and copy the soniccharge folder into this folder.

• Visual Studio Code

  Copy the soniccharge folder into the .vscode/extensions/ directory under your "home folder".

  • Windows: %USERPROFILE%\.vscode\extensions
  • Mac/Linux: $HOME/.vscode/extensions