开发者快速入门

当前由源代码支持的开发路径是在 Turboism 仓库中添加插件模块。尚未发布独立入门模板和稳定 Maven 坐标。

1. 创建模块

plugins/hello/
├── build.gradle.kts
├── src/main/java/dev/example/plugin/HelloPlugin.java
├── src/main/resources/META-INF/turboism/plugin.json
└── src/test/java/dev/example/plugin/HelloPluginTest.java

将其添加到源仓库的 settings.gradle.kts：

include("plugins:hello")

2. 仅依赖 SDK

plugins {
    `java-library`
}

dependencies {
    compileOnly(project(":sdk"))
    testImplementation(project(":sdk"))
}

compileOnly 是有意为之：Runtime 提供 SDK。插件 JAR 不得复制 dev/turboism/sdk/** class。

不要依赖 Runtime、Bootstrap、com.live2d.*、另一个插件的私有实现包、反射桥接、主机小部件、原生句柄或主机 ClassLoader。

3. 实现入口点

package dev.example.plugin;

import dev.turboism.sdk.plugin.PluginContext;
import dev.turboism.sdk.plugin.TurboismPlugin;

public final class HelloPlugin implements TurboismPlugin {
    private PluginContext context;

    @Override
    public void init(final PluginContext context) {
        this.context = java.util.Objects.requireNonNull(context, "context");
        context.logger().info("HelloPlugin initialized");
    }

    @Override
    public void enable() {
        context.logger().info("HelloPlugin enabled");
    }

    @Override
    public void disable() {
        context.logger().info("HelloPlugin disabled");
    }

    @Override
    public void shutdown() {
        context.logger().info("HelloPlugin shutdown");
        context = null;
    }
}

该 class 必须为 public，实现 TurboismPlugin 或其子接口，并提供一个 public 无参数构造函数。

4. 添加 manifest v2

创建 src/main/resources/META-INF/turboism/plugin.json：

{
  "format": "turboism.plugin.meta",
  "schemaVersion": 2,
  "id": "dev.example.plugin.hello",
  "name": "Hello Plugin",
  "version": "0.1.0",
  "description": "Minimal Turboism plugin lifecycle example.",
  "entrypoints": [
    "dev.example.plugin.HelloPlugin"
  ],
  "turboismApi": "[0.1.0,0.2.0)",
  "authors": [
    { "name": "Example Author" }
  ],
  "license": "MIT",
  "website": "https://example.org/hello-plugin",
  "resources": [],
  "i18n": {
    "baseName": "META-INF/turboism/i18n/messages",
    "locales": []
  },
  "dependencies": [],
  "permissions": [],
  "capabilities": [],
  "environment": {
    "requiresCubism": false,
    "ui": "none"
  }
}

在添加权限、资源、本地化、依赖或多个入口点之前，请阅读插件 Manifest 与打包。

5. 构建与验证

./gradlew :plugins:hello:test :plugins:hello:jar validatePluginMeta \
  --no-daemon --console=plain

构建产物会写入：

build/worktree/<worktreeId>/hello/libs/

libs/ 中的 JAR 就是插件发布产物；分发时请保持其不变。

对于此仅包含生命周期的示例，只有构造函数的测试已足够。

一旦插件注册操作、UI、事件、配置或任务，请使用记录型/伪造的 PluginContext 来验证注册、失败处理、disable/shutdown 行为和 scope 清理。

6. 分发 JAR

直接分享构建出的 JAR。没有 wrapper 归档、没有打包脚本，也没有单独的打包步骤。

7. 安装

使用 Turboism 插件管理并选择 从 JAR 安装…（Install from JAR…）来选取构建出的 JAR。确认将 JAR 标记为本地/未验证来源的对话框。更改会暂存，并在 Cubism 重启后生效。

对于本地开发或备用场景，您也可以手动安装 JAR：完全关闭 Cubism，将构建出的 JAR 复制到 <turboism.home>/plugins/ 根下，确保没有同 plugin ID 的旧 JAR 残留，然后使用同一个 Turboism home 重启。

手动安装会绕过托管保护（UI 确认、preflight、暂存、备份/恢复）；JAR 仍会经过启动验证。完整的手动流程以及更新/卸载规则请参见插件管理。