开发者快速入门

基于公共 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

其 build.gradle.kts 配置(设置脚本已将 JAR 放入 libs/ 时;若没有这些 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) 描述符会被拒绝。
  • 详细的权限、资源、本地化与 schema 规范请阅读插件 Manifest 与打包。

5. 构建与验证

./gradlew build

构建产物写入:

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

build/libs/ 中的 JAR 就是分发产物;分发时请保持其内容完整。

6. 安装与调试

  1. 启动 Cubism Editor 并打开 Turboism 菜单。
  2. 选择 管理插件… → 从 JAR 安装…,选取构建好的 .jar 文件。
  3. 支持热重载的插件会立即加载并生效;其他插件在重启 Cubism 后生效。
  4. 本地调试也可直接将 JAR 复制到 <turboism.home>/plugins/ 目录。

进阶:源码树内模块开发

对于 Turboism 核心贡献者,也可以直接在 Turboism 源码仓库中添加 plugins/<name> 模块:

# 添加到 settings.gradle.kts
include("plugins:my-plugin")

# 构建与验证
./gradlew :plugins:my-plugin:test :plugins:my-plugin:jar validatePluginMeta --console=plain

后续步骤