开发开发你的第一个插件

第 1 步:搭建项目

用官方模板创建插件项目,运行设置脚本,了解它生成了什么,并完成一次构建。

这一步你要创建项目,让设置脚本获取 SDK,并构建出一个空但有效的插件 JAR。这里还没有任何 Parameter Peek 专属的内容,但你生成的所有东西都会在之后每一步中复用。

1. 检查工具

你需要 JDK 17 或更新版本。模板自带 Gradle wrapper(Gradle 8.10.2),无需自行安装 Gradle。

java -version

设置脚本在 Linux 和 macOS 上还需要 curl 和 python3,在 Windows 上需要 PowerShell 5.1 或更高版本。

2. 用模板创建项目

打开 turboism/turboism-plugin-template,选择 Use this template 创建自己的仓库,或直接克隆:

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

3. 运行设置脚本

脚本会解析稳定版发布,下载 SDK 与事件注解处理器,校验它们的 SHA-256,并把模板改写为你的插件身份。

./scripts/setup.sh --channel stable \
  --id com.example.parameterpeek \
  --name "Parameter Peek" \
  --package com.example.parameterpeek \
  --class-name ParameterPeekPlugin \
  --author "Your Name" \
  --requires-cubism true \
  --yes
.\scripts\setup.ps1 -Channel stable `
  -Id com.example.parameterpeek `
  -Name "Parameter Peek" `
  -Package com.example.parameterpeek `
  -ClassName ParameterPeekPlugin `
  -Author "Your Name" `
  -RequiresCubism true `
  -Yes

不带参数运行脚本,会以交互方式询问同样的值。请把 com.example 换成你自己掌控的反向域名。

--requires-cubism true 表示该插件需要运行中的 Cubism Editor,因为后续步骤会读取模型数据。从不接触 Cubism 的插件可以保持 false。

脚本会报告解析到的 SDK 版本,以及它记录的 Cubism Editor 版本。对于 Stable 0.67.4,SDK 版本为 0.67.4。重复运行脚本是安全的:只有新下载通过校验后,才会替换旧的 JAR。

慎重选择插件 ID

插件 ID(这里是 com.example.parameterpeek)就是插件的身份。Runtime 用它检测重复,并命名插件自己的目录,例如 config/<pluginId>/ 和 data/<pluginId>/。之后更改 ID,Runtime 会把结果视为另一个插件,已有的用户设置不会随之迁移。ID 采用反向域名语法,至少包含一个点。

4. 浏览生成的项目

parameter-peek/
├── build.gradle.kts
├── gradle.properties                     SDK version recorded by setup
├── settings.gradle.kts
├── libs/
│   ├── turboism-sdk-0.67.4.jar           compile-time SDK (not shipped)
│   └── turboism-event-processor-0.67.4.jar
└── src/main/
    ├── java/com/example/parameterpeek/
    │   └── ParameterPeekPlugin.java      your entrypoint class
    └── resources/META-INF/turboism/
        ├── plugin.json                   the plugin descriptor
        ├── cubism-versions.json          supported Cubism Editor versions
        └── i18n/
            ├── messages.properties       base text catalog
            └── messages_en.properties
文件作用
ParameterPeekPlugin.java入口点。Runtime 构造它并调用其生命周期方法。
plugin.json描述符:身份、入口点、SDK API 范围、声明的权限、本地化。参见插件 Manifest 与打包。
cubism-versions.json你声称支持的确切 Cubism Editor 版本。你会在第 4 步中复查它。
i18n/messages*.properties按键查找的用户可见文本。
libs/*.jar编译器使用的 SDK 与注解处理器。

关键机制:SDK 仅用于编译

打开 build.gradle.kts。SDK 位于 compileOnly,事件处理器位于 annotationProcessor:

dependencies {
    compileOnly(sdkJars)
    annotationProcessor(eventProcessorJars)
    annotationProcessor(sdkJars)
}

这是有意为之。运行时由 Turboism 提供 SDK,因此你的 JAR 不得包含 dev/turboism/sdk/** 类。Runtime 会拒绝复制了 SDK、Runtime 或 Live2D 类的 JAR。注解处理器只在编译期运行:它为你的 @SubscribeEvent 方法建立索引,你会在第 4 步中看到。

你的代码可以依赖公共 SDK,除此之外不要依赖 Turboism 的任何其他部分。不要深入 Runtime、Bootstrap、com.live2d.* 类、其他插件的私有实现或原生句柄。参见设计插件。

5. 构建一次

./gradlew build

首次运行会下载 Gradle 本身,因此需要网络。成功后,插件 JAR 会写入:

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

文件名来自插件 ID 的最后一段加上 build.gradle.kts 中的版本。这个 JAR 是你唯一需要分发的产物:没有包装压缩包,也没有单独的打包步骤。

检查清单

  • java -version 报告 17 或更新版本。
  • libs/ 包含 turboism-sdk-0.67.4.jar 和 turboism-event-processor-0.67.4.jar。
  • ./gradlew build 成功并生成 build/libs/parameterpeek-turboism-plugin-0.1.0.jar。

模板里仍保留着它自带的 hello 示例操作和事件。接下来,你将用自己的代码替换它们。

下一步:第 2 步:打个招呼