第 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-peek3. 运行设置脚本
脚本会解析稳定版发布,下载 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 步:打个招呼