Developer Quick Start
Build a minimal Java 17 Turboism plugin against the public SDK.
Turboism provides an official standalone project template and scaffolding tools. You can create a new standalone repository from the template and run an automated setup script to fetch the matching SDK and annotation processor.
This example targets Stable 0.67.4. The setup script resolves the stable channel by default and downloads turboism-sdk-<version>.jar and turboism-event-processor-<version>.jar from that release. Check gradle.properties (turboismSdkVersion) and the downloaded filenames to confirm the SDK version you compile against. Use --channel beta or --version <version> only when you deliberately target another release.
1. Use the standalone template (Recommended)
Create a new repository on GitHub via Use this template from turboism/turboism-plugin-template, or clone it directly:
git clone https://github.com/turboism/turboism-plugin-template.git my-plugin
cd my-pluginRun the scaffolding setup script (which downloads the matching SDK and event annotation processor from the official release feed, verifying SHA-256):
# Linux / macOS
./scripts/setup.sh --channel stable
# Windows (PowerShell)
.\scripts\setup.ps1 -Channel stableFollow the interactive prompts to enter your plugin ID (e.g. com.example.myplugin), display name, package name, and author. The script refactors Java packages and classes and sets up dependencies under libs/.
2. Project structure and build configuration
The standalone template directory layout:
my-plugin/
├── gradlew
├── gradlew.bat
├── build.gradle.kts
├── libs/
│ ├── turboism-sdk-*.jar
│ └── turboism-event-processor-*.jar
├── src/main/java/com/example/myplugin/MyPlugin.java
├── src/main/resources/META-INF/turboism/plugin.json
└── src/main/resources/META-INF/turboism/cubism-versions.jsonIts build.gradle.kts configuration when the setup script has placed the JARs in libs/ (without them, the template resolves dev.turboism:sdk and dev.turboism:event-processor from mavenLocal() using turboismSdkVersion):
plugins {
`java-library`
}
java {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
val sdkJars = fileTree("libs") { include("turboism-sdk-*.jar") }
val eventProcessorJars = fileTree("libs") { include("turboism-event-processor-*.jar") }
dependencies {
compileOnly(sdkJars)
if (!eventProcessorJars.isEmpty) {
annotationProcessor(eventProcessorJars)
annotationProcessor(sdkJars)
}
}compileOnly is intentional: the Runtime provides the SDK at execution time. Plugin JARs must not bundle or shade dev/turboism/sdk/** classes.
Do not depend on Runtime, Bootstrap, com.live2d.* internal classes, another plugin's private implementation, reflection bridges, or native handles.
3. Implement entrypoint and event listening
package com.example.myplugin;
import dev.turboism.sdk.event.SubscribeEvent;
import dev.turboism.sdk.cubism.event.ParameterValueEvent;
import dev.turboism.sdk.plugin.PluginContext;
import dev.turboism.sdk.plugin.TurboismPlugin;
public final class MyPlugin implements TurboismPlugin {
private PluginContext context;
@Override
public void init(final PluginContext context) {
this.context = java.util.Objects.requireNonNull(context, "context");
context.logger().info("MyPlugin initialized");
}
@Override
public void enable() {
context.logger().info("MyPlugin enabled");
}
@SubscribeEvent
public void onParameterChanged(final ParameterValueEvent.On event) {
context.logger().info("Parameter changed: " + event.parameter().id());
}
@Override
public void disable() {
context.logger().info("MyPlugin disabled");
}
@Override
public void shutdown() {
context.logger().info("MyPlugin shutdown");
context = null;
}
}- The class must be public, implement
TurboismPluginor a subinterface, and provide a public no-arg constructor. - Use
@SubscribeEventto declare event listener methods, indexed at compile time byturboism-event-processor.
@CubismEditor describes API version constraints; it does not grant permissions or prove that a capability is available. Declare the plugin’s supported versions in the separate META-INF/turboism/cubism-versions.json file (see Manifest).
4. Add plugin descriptor
Edit src/main/resources/META-INF/turboism/plugin.json:
{
"format": "turboism.plugin.meta",
"schemaVersion": 3,
"id": "com.example.myplugin",
"name": "My Plugin",
"version": "0.1.0",
"description": "Minimal Turboism plugin lifecycle example.",
"category": "workflow",
"tags": ["example"],
"entrypoints": [
"com.example.myplugin.MyPlugin"
],
"turboismApi": "[0.67.0,1.0.0)",
"authors": [
{ "name": "Example Author" }
],
"license": "MIT",
"website": "https://example.org/my-plugin",
"resources": [],
"i18n": {
"baseName": "META-INF/turboism/i18n/messages",
"locales": []
},
"dependencies": [],
"permissions": [
{ "id": "turboism.event.subscribe", "scope": "application", "reason": "Subscribe to parameter observations." },
{ "id": "turboism.cubism.model.observe", "scope": "application", "reason": "Observe parameter value changes." }
],
"capabilities": [],
"lifecycle": {
"hotReload": true
},
"environment": {
"requiresCubism": true,
"ui": "none"
}
}"lifecycle": { "hotReload": true }declares that the plugin supports hot reloading, allowing enable, disable, and update actions to take effect immediately without restarting Cubism.turboismApiis the plugin SDK API range.[0.67.0,1.0.0)accepts every framework API from 0.67.0 up to, but excluding, 1.0.0; raise the lower bound if you use SDK members added in a later release. Legacy[0.1.0,0.2.0)descriptors are rejected.- For permissions, resources, i18n, and schema details, see Plugin Manifest and Packaging.
5. Build and verify
./gradlew buildThe output artifact is written to:
build/libs/myplugin-turboism-plugin-0.1.0.jarThe JAR in build/libs/ is your distribution artifact.
6. Install and debug
- Start Cubism Editor and open the Turboism menu.
- Select Manage Plugins… → Install from JAR…, and select your built
.jarfile. - Plugins declaring hot-reload support load immediately; others take effect upon restarting Cubism.
- For local debugging, you can also copy the JAR directly into
<turboism.home>/plugins/.
Advanced: In-tree module development
Core contributors working inside the Turboism repository can add a plugins/<name> module directly:
# Add to settings.gradle.kts
include("plugins:my-plugin")
# Build and verify
./gradlew :plugins:my-plugin:test :plugins:my-plugin:jar validatePluginMeta --console=plainNext steps
- Build Your First Plugin — A guided six-step tutorial that expands this page into a complete plugin
- Plugin Interfaces — Services, actions, menus, and events
- Plugin Manifest and Packaging — Descriptor schema and fields
- SDK API Guide — Architecture, unified object model, and version admission
- Plugin Management — In-App Market, updates, and lifecycle governance