概念

映射层

为什么主机适配需要明确的边界,以及 Turboism 如何将其隔离。

主机应用程序会在不同版本之间更改符号和实现细节。映射层是让主机特定知识保持与插件体验隔离的边界。

为什么需要它

Cubism Editor 内部机制不是公共 API。类名、方法签名、字段布局和求值行为在不同版本之间各不相同,某个构建中存在的符号在另一个构建中可能缺失、被重命名或行为不同。

如果没有明确的边界,每个插件都必须自行用反射、版本检查和主机对象假设来解决这个问题。插件代码会因此与主机一样脆弱,Turboism 也无法在不支持的组合上失败关闭。

Turboism 如何隔离

  • 插件面向已发布的 SDK 类型,永远不会加载 com.live2d.* 类。
  • Runtime 为检测到的主机构建选择确切版本的 adapter 和 Provider。
  • 当前 Stable 发行版 0.67.4 接纳 5.0.00 至 5.3.04 的全部 20 个已审核的确切 Cubism Editor 版本(请参阅兼容性);未列出的版本不会被静默视为兼容。
  • 主机成员选择会被记录并作为已审查证据固定,因此与固定身份不匹配的构建会失败,而不是进行猜测。
  • 公共 Cubism 值在到达插件代码之前,会被复制为 Turboism 自有的不可变类型。
  • 模型对象和引用绑定 generation,并在项目关闭、文档切换、模型重新加载、对象删除、插件禁用、提供程序替换或不受支持的版本切换后失效。

这对插件作者意味着什么

你仍需处理不可用情况,但只需在一个可预期的地方处理:类型化的“不受支持”或“不可用”结果。你不需要自己的反射层,也不应编写它——直接触及主机的插件会绕过映射、权限模型以及让失败可被理解的诊断。

对象 API 和能力模型请参阅 SDK API 指南,按发行版和按能力的版本矩阵请参阅兼容性,当前分支状态请参阅开发状态。