SDK API 指南
当前 Turboism 插件 SDK 的入口点、服务、对象模型、生命周期与能力边界。
Turboism SDK 是插件唯一的公开依赖项。Turboism 发布单一的公共 SDK 层级,源代码仓库中已审查的二进制 API 基线(当前为 v23,即 0.67.4 的现行发布门禁;v2–v22 作为历史审计保留)是兼容性门禁。其可用性取决于四项彼此独立的事实:
- API 存在于 SDK 中;
- 插件声明了所需权限;
- Runtime 具有匹配的能力 Provider;
- 支持当前启用的 Cubism 版本和对象世代。
如需查看生成的类型和方法索引,请打开 SDK HTML API 文档。
SDK API 范围与孵化中 API
插件声明 "turboismApi": "[0.67.0,1.0.0)"。下限是插件所需的最低框架基础版本;Runtime 计算其 API 版本时忽略 beta、nightly 和 SNAPSHOT 后缀。旧式 [0.1.0,0.2.0) 插件会被拒绝。使用后续版本新增的 SDK 成员时,请有意提高下限:针对较新的 SDK 编译,并不会让这些新增内容在较旧的 Runtime 上可用。例如,官方插件 atlas-folder-layout、atlas-bitmask-nesting、atlas-dalsoo-polygon 和 psd-clip-mask-import 要求 0.67.4,external-psd-edit 和 atlas-maxrects-bssf 要求 0.67.2。
@Incubating(dev.turboism.sdk.Incubating)标记可能变更或消失的实验性 API,包括破坏性的签名变更。它不纳入精确兼容性基线;标注在类型上时覆盖其所有成员。对孵化中 API 的依赖应视为绑定于构建时所用的 SDK 版本,并在每次 SDK 更新时复查。在首个稳定 SDK 版本发布之前仍允许破坏性变更,因此未标注的 API 并不能证明首个稳定 SDK 版本已经发布。
插件生命周期
每个入口点都实现 TurboismPlugin 或其子接口,例如 CubismPlugin。
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:保留上下文、注册配置架构,并创建插件私有状态。enable:提供操作、事件、UI、任务和其他活动行为。disable:在 Runtime 关闭插件作用域前停止活动行为。shutdown:释放不归该作用域所有的插件私有资源。
一个 JAR 可以包含多个有序入口点。构造、初始化和启用遵循清单顺序;禁用和关闭则按相反顺序执行。整个 JAR 的启动是原子的。
PluginContext
| 条目 | 用途 |
|---|---|
descriptor() | 当前 JAR 级别的 PluginDescriptor |
logger() | 插件作用域内的日志记录 |
paths() | 配置、数据、缓存、状态和日志命名空间 |
localization() | 区域设置、文本查找和格式化 |
tasks() | 有界的一次性和固定延迟任务 |
hostReads() | 有界的异步主机读取 |
storage() | 插件拥有的 DATA、STATE 和 CACHE 存储 |
userFiles() | 用户授予的文件句柄 |
cubism() | 快照、统一对象访问和事务兼容入口点 |
selectionQuery() | 选区读取和变更订阅 |
modelHierarchyQuery() | 模型树查询 |
cubismRead() | 聚合的读取能力族 |
eventBus() | 类型化事件的发布和订阅 |
actions() 和 menus() | 操作注册和菜单贡献 |
services().require(MainToolbarRegistry.class)、services().require(PaletteToolbarRegistry.class)、services().require(ContextMenuRegistry.class) | 类型化 UI 贡献注册表 |
services().require(UiHostCapabilityService.class) 和 uiScheduler() | 工具包无关的 UI 能力和 UI 线程调度 |
config() | 类型化插件配置 |
diagnostics() | 当前结构化诊断信息 |
disposableScope() | 逆序生命周期清理 |
部分默认服务会抛出 UnsupportedOperationException;另一些则返回显式的不可用实现。插件必须处理不可用的能力族,而不是绕过它们。
可选服务发现
通过类型化目录获取可选服务。服务缺失时,find 可用于降级处理,require 则抛出 PluginServiceUnavailableException。服务已安装也仍需逐操作检查权限、宿主版本、能力和对象代际。
context.services().find(UiHostCapabilityService.class).ifPresent(ui -> {
// Use the installed UI service with the required permissions.
});工具栏、上下文菜单、UI 宿主和设置贡献项均通过该目录获取,不再使用已移除的 PluginContext 便捷访问方法。
注册与清理
大多数注册表返回 Registration,这是一个 AutoCloseable 句柄。
Registration registration = context.actions().register("example.refresh", action);
context.disposableScope().register(registration);该作用域按相反顺序关闭注册项。应将操作、菜单、UI 贡献、订阅、任务句柄和其他可关闭资源放入作用域中,以便 Runtime 能够安全地释放插件 ClassLoader。
Cubism 生命周期钩子通过入口点接口发现,而非通过回调注册总线。
操作、菜单与事件
ActionRegistry.Action 提供 ID、标签和处理程序。ActionContext 可以携带类型化 UI 操作事件,或绑定到世代的上下文菜单选区。
MenuRegistry.MenuContribution 将斜杠分隔的菜单路径与已注册的操作 ID 及顺序绑定。
通用事件总线是类型化的:
record MyEvent(String value) implements dev.turboism.sdk.event.TurboismEvent {}
Registration subscription = context.eventBus().subscribe(
MyEvent.class,
event -> context.logger().info(event.value())
);
context.disposableScope().register(subscription);
context.eventBus().publish(new MyEvent("changed"));
事件应为不可变的、由插件或 SDK 拥有的值。请勿在事件中放入原始主机对象、Swing 小部件、原生句柄或主机 ClassLoader。
快照与查询 API
CubismFacade 仍提供不可变的运行时快照:
CubismRuntimeSnapshot runtime = context.cubism().runtime();
Optional<ProjectSnapshot> project = context.cubism().activeProject();
Optional<DocumentSnapshot> document = context.cubism().activeDocument();
Optional<ModelSnapshot> model = context.cubism().activeModel();
boolean hostPresent = context.cubism().isHostPresent();范围受限的查询服务包括:
- 参数查询使用
context.cubism().model().active().parameters();可选服务通过context.services()获取。 SelectionQueryService:用于当前选区和选区变更订阅;ModelHierarchyQueryService:用于模型树遍历;CubismReadCapabilityService:用于项目、文档、模型、选区、参数、模型对象、网格、变形器、PSD、剪裁蒙版、纹理图集、渲染状态、工作区和主题状态读取族。
快照和查询值是不可变 DTO,而非主机对象引用。
统一的 Cubism 对象图
新的插件代码应优先使用统一对象 API:
CubismModel model = context.cubism().model().active();
Parameter parameter = model.parameters().find(new ParameterId("ParamAngleX"));
float value = parameter.getValue();
parameter.setValue(value + 1.0f);CubismModel 公开参数、参数组、部件、可绘制对象、变形器、Warp 和 Rotation Deformers、Glue、画布、模型更新、默认关键帧锁定和参数绑定操作。
强类型 ID 包括 ProjectId、DocumentId、ModelId、ModelObjectId、ParameterId、ParameterGroupId、PartId、ArtMeshId、DeformerId、GlueId 和 ParameterBindingPointId。
模型及其子对象绑定到世代。在文档切换、重新加载、删除、插件禁用、Provider 替换或其他使其失效的生命周期事件之后,引用会以安全失败方式失效。
操作生命周期钩子
CubismPlugin 组合了 Parameter、Part、Drawable、Deformer 和 Model 钩子族。
public final class ClampPlugin implements CubismPlugin {
@Override
public float beforeSetParameterValue(Parameter parameter, float value) {
return Math.min(value, parameter.getMaximumValue());
}
@Override
public void onParameterValueChanged(
Parameter parameter,
float oldValue,
float newValue
) {
// 仅在权威状态变更后运行。
}
@Override
public void afterSetParameterValue(Parameter parameter, float value) {
// 观察正常完成;请勿执行第二次变更。
}
}before -> 规范操作 -> 权威状态探测 -> on(仅发生变更时)-> after(正常完成时)before同步、有序,并且可以改写参数。on仅在发生可观察到的变更时发出。after观察正常完成。- observe 和 intercept 权限彼此独立。
- 插件无法直接注册字节码转换器。
配置
类型化配置支持架构、编解码器、顺序迁移、异步读取,以及基于修订版本的 compare-and-set 写入。
ConfigKey<Boolean> enabled = new ConfigKey<>(
"example.settings",
"enabled",
true,
ConfigCodecs.booleanValue()
);
ConfigSchema schema = new ConfigSchema(
"example.settings",
"settings.json",
1,
List.of(enabled)
);
context.config().registerSchema(schema, List.of());
context.config().read(enabled);
context.config().write(enabled, true, expectedRevision);Runtime 将插件设置存储在 config/<pluginId>/ 下。插件不得自行构建 turboism.home 下的路径。
插件存储和用户文件
PluginStorage 在三个根目录下提供原子读取、写入、复制、移动、列出和删除操作:
- DATA:用于持久化业务数据;
- STATE:用于可重建的运行时状态;
- CACHE:用于可重建的缓存数据。
StoragePath path = new StoragePath(StorageRoot.STATE, "manual-order.txt");
context.storage().writeUtf8Atomic(path, "a\nb\n");
context.storage().readUtf8(path, 256 * 1024);路径必须是规范化的相对路径。用户选择的外部文件使用 UserFileAccessService 和有作用域的 UserFileHandle 对象;用户文件并非不受限制的文件系统能力。
任务与异步读取
应使用 PluginTaskScheduler,而不是持有不受管理的线程、执行器或计时器。
TaskSubmission submission = context.tasks().submit(
new PluginTaskRequest(
new TaskId("refresh"),
PluginTaskKind.COMPUTE,
PluginTaskPriority.NORMAL,
token -> token.checkCanceled()
)
);任务公开类型化的提交、取消、完成、超时、拒绝、背压和断路器打开结果。
AsyncHostReadService 的意图集经过刻意收窄。仅使用当前 SDK 中存在的意图;不要假定未来会提供 parameter、mesh 或 PSD 意图。
用户界面 API
UI API 使用 SDK DTO,而不是 Swing/AWT 或主机小部件。当前族包括:
- 操作和菜单;
- 主工具栏和调色板工具栏;
- 类型化上下文菜单和上下文选区;
- 覆盖层、对话框、状态通知、canvas 提示和文件选择;
- 工具包无关的
PanelView嵌入式面板; - UI 线程调度;
- canvas-hint 通知(
turboism.ui.canvas.hint权限); - 场景表、外观、控件外观和部分选定的 Editor 贡献。
每个 UI 族都有独立的能力和 Provider 依据。一个可用的族不会启用所有其他族。
权限、能力和操作
- 权限:授权跨越风险边界。
- 能力:表示当前 Provider 和主机版本支持某个功能族。
- 操作:一次具体调用及其诊断身份。
权限不会绕过操作验证,也不会创建缺失的 Provider。
跨插件事件契约
使用 schema 4 的插件描述符可以声明其导出和导入的公共事件类型,每个类型都绑定一个契约版本和事件类型的 ABI 摘要。Runtime 无需 ClassLoader 委托即可解析这些契约,拒绝重复的导出,并拒绝提供程序契约未被接纳的导入。声明事件契约不授予任何主机写入权限;它只是让插件自有的事件类型可供其他插件使用。请参阅插件 Manifest 与打包。
0.67.2 与 0.67.4 的 SDK 新增内容
v22(0.67.2)和 v23(0.67.4)基线只新增 API,未移除任何现有公共类型或可调用的 JVM 描述符:
- 纹理集逐页尺寸:
TextureAtlasPageSize,以及支持各页独立尺寸的TextureAtlasLayoutPlan构造器;TextureAtlasLayoutPlanner.supportsCompleteAtlas()是默认方法,仅支持当前页的规划器应覆盖它并返回false。 - 打包失败:规划器通过公开、可扩展的
TextureAtlasPackingException及其Reason(PAGE_BUDGET_EXHAUSTED、ITEM_DOES_NOT_FIT、INVALID_RESERVED_SIZE)报告输入无法放入。 - 多边形轮廓与多边形页面(0.67.4):
TextureAtlasLayoutItem新增可选的源outline(四参数构造器及访问器;保留三参数构造器),TextureAtlasLayoutPlan新增polygonPages(八参数构造器及访问器),TextureAtlasOutline新增值相等、hashCode和toString。TextureAtlasPolygonLayoutPlanner标注为@Incubating。 - PSD 编辑:
PsdEditFile.openInApplication(String)是默认方法。 SettingsControl.FilePath:SettingsControl是密封接口,因此新变体对穷举式switch而言是源码层面的变更。针对当前 SDK 重新编译时,请补充FilePath分支。TurboismProgressDialog(dev.turboism.sdk.ui.window,0.67.4):在 Cubism Editor 上居中显示的共享非模态进度窗口,提供(title, message)构造器以及show、focus、setMessage、setProgress和close,并实现AutoCloseable。
新增了组件的 record 会改变其反射形态、equals、hashCode 和 toString,保留下来的原规范构造器会丢失参数名元数据。以反射方式检查这些 record 的代码必须相应调整。
非契约的公共类型
少数类会因为共享的内部辅助方法而编译为 public 的 SDK 类,但它们自身的说明明确指出其不属于稳定插件 API 面。当前的例子是 dev.turboism.sdk.cubism.ActiveReadProjections。
请不要调用这些类型,也不要将其签名视为兼容性承诺。它们出现在生成的参考中,是因为它们已存在于已发行的字节码里;具体原因记录在 生成的 API 参考 中。
版本与就绪状态说明
- 20 版本覆盖:当前已审查的 Cubism Editor 版本矩阵覆盖 5.0.00 至 5.3.04 全部 20 个版本。
- 版本约束:
@CubismEditor支持精确value列表或闭区间from/to,并可用exclude排除版本。空注解不增加版本下限;权限、提供程序、能力和对象代际检查仍然生效。请逐版本查看矩阵;覆盖范围不代表所有操作在所有宿主上均可用。 - 0.67 新增的核心能力族:
- 统一模型对象图(
CubismModel、Drawables、Deformers、Parts、Parameters); - 网格建模与会话(
MeshEditService、MeshEditParticipation、MeshMirrorAxisService); - 纹理集排版与统计(
TextureAtlasLayoutService、TextureAtlasEditorSession、TextureAtlasSummary、TextureAtlasLayoutPlanner、TextureAtlasPageSize、TextureAtlasPackingException、TextureAtlasOutline;TextureAtlasPolygonLayoutPlanner标注为@Incubating); - PSD 与剪贴蒙版(
PsdClipMaskDocumentSnapshot、PsdEditFile,包括openInApplication); - 参数批量操作(
ParameterBindingBatchOperations、ParameterBindingTransferPlan); - 3D 模型导入挂钩(
ModelObjectCreateRequest等); - 独立插件设置(
SettingsRegistry、SettingsContribution,SettingsControl变体Choice、Toggle、Text、FilePath和Note); - 进度窗口(
TurboismProgressDialog); - 绘图区原生提示(
CanvasHintNotification、turboism.ui.canvas.hint)。
- 统一模型对象图(
- 确切的版本边界与能力差异已在兼容性文档中完整列出。
- History DTO(
HistoryEntry、HistoryChange、HistoryEditContext、HistoryGroup、HistoryOrigin、HistoryTarget)是有界的不可变语义投影。它们绝不授予主机写入权限。 - Fake 和静态测试仅证明其所命名的层。
- 快照/查询/事务兼容接口当前与统一对象图并存。