開発者向けクイックスタート
公開 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.jar6. インストールとデバッグ
- Cubism Editor を起動し、Turboism メニューを開きます。
- プラグイン管理… → JAR からインストール… を選択し、ビルドされた
.jarを選択します。 - ホットリロード対応プラグインは即座に読み込まれて有効になります。その他は Cubism 再起動後に有効になります。
- ローカル開発時は
<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次のステップ
- 最初のプラグインを作る — このページを完全なプラグインへと発展させる、6 ステップのガイド付きチュートリアル
- プラグインインターフェース — サービス、アクション、メニュー、イベント購読
- プラグインマニフェストとパッケージング — 記述子スキーマと各フィールドの詳細
- SDK API ガイド — アーキテクチャ、統合オブジェクトモデル、バージョン承認
- プラグイン管理 — アプリ内マーケット、更新、ライフサイクル