插件接口
可通过 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() | 使用用户授予的外部文件句柄 |
| Cubism | cubism() | 读取快照并使用统一对象图 |
| 查询 | cubism().model().active().parameters()、selectionQuery()、modelHierarchyQuery() | 范围受限的类型化查询 |
| 事件 | eventBus() | 发布和订阅不可变类型化事件 |
| 操作 | actions() | 注册可复用的插件操作 |
| 菜单和 UI | menus()、工具栏/上下文菜单注册表、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() 中。