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.

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-plugin

Run 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 stable

Follow 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.json

Its 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 TurboismPlugin or a subinterface, and provide a public no-arg constructor.
  • Use @SubscribeEvent to declare event listener methods, indexed at compile time by turboism-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.
  • turboismApi is 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 build

The output artifact is written to:

build/libs/myplugin-turboism-plugin-0.1.0.jar

The JAR in build/libs/ is your distribution artifact.

6. Install and debug

  1. Start Cubism Editor and open the Turboism menu.
  2. Select Manage Plugins… → Install from JAR…, and select your built .jar file.
  3. Plugins declaring hot-reload support load immediately; others take effect upon restarting Cubism.
  4. 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=plain

Next steps