DevelopmentBuild Your First Plugin

Build Your First Plugin

A six-step hands-on tutorial from an empty folder to an installed Turboism plugin with a menu command, live Cubism data, a saved setting, and tests.

This series walks you through building one small but complete Turboism plugin, Parameter Peek. By the end you will have written, built, installed, and tested a real plugin, and you will know which mechanisms made it work.

What you will build

Parameter Peek adds a Parameter Peek: Report command to the Cubism Editor. When you run it, the plugin:

  • counts the parameters of the model you have open;
  • reports how many parameter value changes it has seen since it was enabled;
  • writes the result to the Turboism log, and shows it in the status bar when a setting you can change in Plugin Settings allows it.

The plugin is deliberately small. It only reads the model, so it is safe to experiment with, yet it touches every part of a typical plugin: lifecycle, actions and menus, permissions, localization, Cubism data, events, saved settings, and tests.

Before you start

  • Java. You should be comfortable with classes, interfaces, lambdas, and records. You do not need to know Cubism internals or the Turboism runtime.
  • JDK 17 or newer on your PATH (run java -version to check). Plugins are compiled to Java 17 bytecode.
  • Turboism installed with a supported Cubism Editor, to run the plugin in step 3 and after. See Installation and Compatibility. You can complete steps 1 and 2, and the unit tests in step 6, without Cubism.
  • A disposable test model to open in the Editor. Parameter Peek only reads, but test plugins on data you can afford to lose.

This tutorial is written for Stable 0.67.4. The project template downloads the matching SDK for you, and a plugin built this way declares the SDK API range [0.67.0,1.0.0).

The six steps

StepYou doMechanism you meet
1. Set up the projectCreate a project from the official template and build it.The SDK is compileOnly; the plugin ID; project layout.
2. Say helloAdd a menu command that logs and shows a message.Lifecycle, actions and menus, declared permissions, localization.
3. Build and installInstall the JAR in Cubism and run the command.Managed install and restart, strict JAR validation, logs.
4. Read the modelCount parameters and observe changes.Cubism snapshots, events, fail-closed availability, Cubism version support.
5. Add a settingSave a preference and expose it in Plugin Settings.Typed configuration, plugin-owned storage, graceful degradation.
6. Test and shipWrite unit tests, polish the metadata, and share the JAR.Testing without a host, versioning, distribution.

Every step ends in a working plugin and a short checkpoint, so you can stop and resume at any step boundary.

How the tutorial is organized

The steps stay on the shortest path to a working plugin. When a mechanism deserves more than a paragraph, the step gives you what you need to keep going and links to a standalone page in Key Mechanisms:

The big picture

Your plugin JAR
├── META-INF/turboism/plugin.json   who you are and what you ask for
├── your Java classes               what you do
└── resources                       localized text, Cubism version list
        │
        │  Runtime validates the JAR and admits only what you declared
        ▼
PluginContext                       the only door to the host
├── actions(), menus()              commands and menu entries
├── eventBus()                      typed events
├── cubism()                        snapshots and the Cubism object model
├── config(), storage()             settings and plugin-owned data
└── logger(), localization() ...    plugin-private helpers

Everything your plugin does goes through PluginContext. Runtime checks each call against the permissions you declared, the services the host provides, and the active Cubism version. If you remember one idea from this series, make it that one.

Reference and alternatives