插件接口

可通过 PluginContext 使用的当前 Preview SDK 接口系列。

当前 Turboism 插件边界以 Java 为基础并由源代码支持。插件实现 TurboismPlugin 或其子接口,并从 Runtime 接收 PluginContext。

有关签名和详细语义,请使用 SDK API 指南 和生成的 HTML 参考文档。

生命周期

public interface TurboismPlugin {
    default void init(PluginContext context) throws Exception {}
    default void enable() throws Exception {}
    default void disable() throws Exception {}
    default void shutdown() throws Exception {}
}

使用 init 进行 context 和配置设置,使用 enable 进行活动注册,使用 disable 停止行为,并使用 shutdown 清理插件私有资源。

Context 服务系列

系列当前入口点典型用途
元数据descriptor()检查当前 JAR 级别描述符
日志logger()输出插件作用域诊断信息
路径paths()访问插件自有的 config/data/cache/state/log 命名空间
本地化localization()读取 manifest 中声明的本地化文本
任务tasks()提交有界且可取消的工作
主机读取hostReads()请求有界的异步主机快照
存储storage()读取并原子写入插件自有数据
用户文件userFiles()使用用户授予的外部文件句柄
Cubismcubism()读取快照并使用统一对象图
查询cubism().model().active().parameters()、selectionQuery()、modelHierarchyQuery()范围受限的类型化查询
事件eventBus()发布和订阅不可变类型化事件
操作actions()注册可复用的插件操作
菜单和 UImenus()、工具栏/上下文菜单注册表、services().require(UiHostCapabilityService.class)提供与工具包无关的 UI 描述符
Canvas 提示services().require(UiHostCapabilityService.class)在绘图区显示原生 Cubism 提示(需要 turboism.ui.canvas.hint 权限)
配置config()注册类型化 schema、读取值并使用 compare-and-set 写入
诊断diagnostics()检查结构化 Runtime 诊断信息
清理disposableScope()注册可关闭的生命周期资源

某项服务在特定的 Runtime/主机组合中可能不可用。请处理明确的不可用结果或异常,而不是绕过 Runtime。

操作和菜单

将行为仅注册一次为一个操作,并将 UI 贡献项绑定到其 ID。

var action = context.actions().register("hello.show", new ActionRegistry.Action() {
    @Override public String id() { return "hello.show"; }
    @Override public String label() { return "Hello"; }
    @Override public Consumer<ActionRegistry.ActionContext> handler() {
        return ignored -> context.logger().info("Hello from Turboism");
    }
});
context.disposableScope().register(action);

菜单、工具栏、面板和上下文菜单贡献项使用 SDK 描述符。它们不暴露主机小部件。

事件

Turboism 提供声明式与编程式两种事件订阅机制:

1. 声明式 @SubscribeEvent(推荐)

在插件入口点类中直接使用 @SubscribeEvent 标记监听方法。编译期由 turboism-event-processor 自动生成订阅者注册表,无需手动挂载与注销:

@SubscribeEvent(priority = EventPriority.NORMAL)
public void onParameterChanged(final ParameterValueEvent.On event) {
    context.logger().info("Parameter changed: " + event.parameter().id());
}

优先级可选:HIGHEST、HIGH、NORMAL、LOW、LOWEST。

2. 编程式动态订阅

record HelloEvent(String message) implements dev.turboism.sdk.event.TurboismEvent {}

var subscription = context.eventBus().subscribe(
    HelloEvent.class,
    event -> context.logger().info(event.message())
);
context.disposableScope().register(subscription);
context.eventBus().publish(new HelloEvent("enabled"));

订阅和发布权限相互独立。事件不得包含原始主机状态。

Cubism 对象 API 与版本适配

CubismModel model = context.cubism().model().active();
Parameter parameter = model.parameters().find(new ParameterId("ParamAngleX"));
float current = parameter.getValue();

SDK 注解限制宿主版本,权限和提供程序仍需分别检查。应处理结构化的版本不可用异常;CubismFacade 没有接收能力 ID 字符串的 isAvailable(capabilityId) 方法。写入还需要对应权限和有效的对象代际。

try {
    parameter.setValue(current + 1.0f);
} catch (CubismEditorApiUnavailableException unavailable) {
    context.logger().info("Unavailable API: " + unavailable.apiId());
}

独立插件设置(SettingsRegistry)

插件可通过 context.services().require(UiHostCapabilityService.class) 向 Cubism 内专用的 Turboism → 插件设置… 双栏窗口贡献设置页面:

var enabled = new java.util.concurrent.atomic.AtomicBoolean(true);
var registry = context.services().require(UiHostCapabilityService.class);
var settings = registry.contributeSettings(new SettingsContribution(
    "myplugin.enabled",
    new SettingsTab("myplugin", "My Plugin"),
    new SettingsControl.Toggle(
        "enabled", "Enable feature",
        SettingsBinding.of(enabled::get, enabled::set)
    )
));
context.disposableScope().register(settings);

可选服务通过 context.services().find(Service.class) 或 require(Service.class) 获取。服务存在不代表已获权限,也不保证所有版本路由操作可用。本例需要 turboism.ui.settings.contribute;绑定仅保存在内存中,持久化设置应使用配置服务。

Hooks

实现 CubismPlugin 或特定 hook 接口,以观察或拦截操作生命周期。

public final class HelloHooks implements CubismPlugin {
    @Override
    public void onParameterValueChanged(
        Parameter parameter,
        float oldValue,
        float newValue
    ) {
        // Bounded observation only.
    }
}

Hooks 遵循 before -> operation -> changed-only on -> after。插件不能注册字节码转换器。

配置、存储和任务

  • 对设置使用类型化 PluginConfigRegistry。
  • 对 DATA、STATE 和 CACHE 使用 PluginStorage。
  • 对用户选择的外部文件使用 UserFileAccessService。
  • 使用 PluginTaskScheduler,而不是不受管理的线程、executor 或定时器。

清理规则

每个可在当前方法之外存活的返回注册项或句柄,都必须显式关闭或登记到 context.disposableScope() 中。