开发者快速入门
基于公共 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.jarbuild/libs/ 中的 JAR 就是分发产物;分发时请保持其内容完整。
6. 安装与调试
- 启动 Cubism Editor 并打开 Turboism 菜单。
- 选择 管理插件… → 从 JAR 安装…,选取构建好的
.jar文件。 - 支持热重载的插件会立即加载并生效;其他插件在重启 Cubism 后生效。
- 本地调试也可直接将 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后续步骤
- 开发你的第一个插件 — 六步引导式教程,将本页扩展为一个完整的插件
- 插件接口 — 核心服务、操作、菜单与事件订阅
- 插件 Manifest 与打包 — 描述符完整规范与字段说明
- SDK API 指南 — SDK 架构、统一对象模型与版本准入
- 插件管理 — 插件市场、版本更新与生命周期治理