開発者向けクイックスタート

公開 SDK を使用して最小限の Java 17 Turboism プラグインを構築します。

Turboism は公式のスタンドアロンプロジェクトテンプレートとスキャフォールディングツールを提供しています。テンプレートから独立リポジトリを作成し、自動セットアップスクリプトを実行して対応する SDK とアノテーションプロセッサを取得できます。

この例は Stable 0.67.4 を対象としています。セットアップスクリプトは既定で stable チャネルを解決し、そのリリースから turboism-sdk-<version>.jar と turboism-event-processor-<version>.jar を取得します。gradle.properties(turboismSdkVersion)とダウンロードしたファイル名で、コンパイルに使う SDK バージョンを確認してください。--channel beta や --version <version> は、意図的に別のリリースを対象にする場合にのみ使用します。

1. 公式テンプレートの使用(推奨)

GitHub の Use this template から turboism/turboism-plugin-template リポジトリをもとに作成するか、直接クローンします:

git clone https://github.com/turboism/turboism-plugin-template.git my-plugin
cd my-plugin

セットアップスクリプトを実行します(公式リリースフィードから対応バージョンの SDK とイベントアノテーションプロセッサをダウンロードし、SHA-256 を検証します):

# Linux / macOS
./scripts/setup.sh --channel stable

# Windows (PowerShell)
.\scripts\setup.ps1 -Channel stable

ターミナルの対話式プロンプトに従ってプラグイン ID(例: com.example.myplugin)、表示名、パッケージ名、作者情報を入力します。スクリプトが Java パッケージとクラス名を再構成し、libs/ に依存関係を設定します。

2. プロジェクト構造とビルド構成

スタンドアロンテンプレートのディレクトリ構造:

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

セットアップスクリプトが JAR を libs/ に配置した場合の build.gradle.kts の構成(JAR がない場合、テンプレートは turboismSdkVersion を使って mavenLocal() から dev.turboism:sdk と dev.turboism:event-processor を解決します):

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 は意図的なものです: Runtime が実行時に SDK を提供します。プラグイン JAR に dev/turboism/sdk/** クラスを含めないでください。

Runtime、Bootstrap、com.live2d.* 内部クラス、他のプラグインのプライベート実装、リフレクションブリッジ、ネイティブハンドルには依存しないでください。

3. エントリポイントとイベント受信の実装

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;
    }
}
  • クラスは public であり、TurboismPlugin またはそのサブインターフェースを実装し、public 引数なしコンストラクタを提供する必要があります。
  • @SubscribeEvent アノテーションを使ってイベント購読メソッドを宣言でき、コンパイル時に turboism-event-processor がインデックスを生成します。

@CubismEditor は API のバージョン制約を表します。権限や機能の可用性は保証しません。プラグインの対応バージョンは別ファイル META-INF/turboism/cubism-versions.json に記載します(マニフェスト参照)。

4. プラグイン記述子の追加

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 } はプラグインがホットリロードに対応していることを示し、Cubism を再起動せずに有効化、無効化、更新が即座に反映されます。
  • turboismApi はプラグイン SDK API 範囲です。[0.67.0,1.0.0) は 0.67.0 以上 1.0.0 未満のすべてのフレームワーク API を受け入れます。後のリリースで追加された SDK メンバーを使う場合は下限を引き上げてください。旧来の [0.1.0,0.2.0) 記述子は拒否されます。
  • 権限、リソース、国際化の詳細については プラグインマニフェストとパッケージング を参照してください。

5. ビルドと検証

./gradlew build

成果物は以下に書き込まれます:

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

6. インストールとデバッグ

  1. Cubism Editor を起動し、Turboism メニューを開きます。
  2. プラグイン管理… → JAR からインストール… を選択し、ビルドされた .jar を選択します。
  3. ホットリロード対応プラグインは即座に読み込まれて有効になります。その他は Cubism 再起動後に有効になります。
  4. ローカル開発時は <turboism.home>/plugins/ ディレクトリに直接 JAR をコピーすることもできます。

上級者向け: ソースツリー内モジュール開発

Turboism コアコントリビューターはリポジトリ内で直接 plugins/<name> モジュールを追加できます:

# settings.gradle.kts に追加
include("plugins:my-plugin")

# ビルドと検証
./gradlew :plugins:my-plugin:test :plugins:my-plugin:jar validatePluginMeta --console=plain

次のステップ