プラグインインターフェース
PluginContext を通じて利用できる、現在の Preview SDK interface family。
現在の Turboism plugin boundary は Java ベースで、source-backed です。plugin は TurboismPlugin または subinterface を実装し、Runtime から PluginContext を受け取ります。
signature と詳細な semantics については、SDK API ガイド と 生成済み HTML reference を使用してください。
lifecycle
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 と configuration の setup、enable は active registration、disable は behavior の停止、shutdown は plugin-private cleanup に使います。
Context service family
| Family | Current entrypoint | Typical use |
|---|---|---|
| Metadata | descriptor() | 現在の JAR-level descriptor を調べる |
| Logging | logger() | plugin-scoped diagnostic を出力する |
| Paths | paths() | plugin-owned config/data/cache/state/log namespace にアクセスする |
| Localization | localization() | manifest で宣言された localized text を読む |
| Tasks | tasks() | 上限付き cancellable work を submit する |
| Host reads | hostReads() | 上限付き asynchronous host snapshot を要求する |
| Storage | storage() | plugin-owned data を読み、atomic に書き込む |
| User files | userFiles() | user-granted external-file handle を使う |
| Cubism | cubism() | snapshot を読み、unified object graph を使う |
| Queries | cubism().model().active().parameters(), selectionQuery(), modelHierarchyQuery() | 狭い型付き query |
| Events | eventBus() | immutable な型付き event を publish/subscribe する |
| Actions | actions() | 再利用可能な plugin action を登録する |
| Menus and UI | menus(), toolbar/context-menu registries, services().require(UiHostCapabilityService.class) | toolkit-neutral UI descriptor を提供する |
| Canvas hints | services().require(UiHostCapabilityService.class) | 描画領域上にネイティブ Cubism hint を表示する(turboism.ui.canvas.hint 権限) |
| Configuration | config() | 型付き schema を登録し、value を読み、compare-and-set write を行う |
| Diagnostics | diagnostics() | 構造化された Runtime diagnostic を調べる |
| Cleanup | disposableScope() | closeable な lifecycle resource を登録する |
特定の Runtime/host combination では service が利用できないことがあります。Runtime を迂回せず、明示的な unavailable result または exception を処理してください。
Action と menu
behavior は action として 1 度登録し、UI contribution をその 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);Menu、toolbar、panel、context-menu contribution は SDK descriptor を使います。host widget は公開しません。
Event
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"));subscribe と publish の permission は別々です。event に raw host state を含めてはいけません。
Cubism オブジェクト API とバージョン適応
CubismModel model = context.cubism().model().active();
Parameter parameter = model.parameters().find(new ParameterId("ParamAngleX"));
float current = parameter.getValue();SDK の注釈はホストバージョンを制約します。権限とプロバイダーは別途確認が必要です。構造化されたバージョン非対応例外を処理してください。CubismFacade に文字列の 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 → プラグイン設定… 2 ペインウィンドウに設定画面を提供できます:
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 が必要です。値はメモリ内だけに保持するため、永続化には設定サービスを使用してください。
Hook
operation lifecycle の observation または interception には、CubismPlugin または特定の hook interface を実装します。
public final class HelloHooks implements CubismPlugin {
@Override
public void onParameterValueChanged(
Parameter parameter,
float oldValue,
float newValue
) {
// Bounded observation only.
}
}Hook は before -> operation -> changed-only on -> after に従います。plugin は bytecode transformer を登録できません。
Configuration、storage、task
- 設定には型付き
PluginConfigRegistryを使います。 - DATA、STATE、CACHE には
PluginStorageを使います。 - user-selected external file には
UserFileAccessServiceを使います。 - 管理されていない thread、executor、timer の代わりに
PluginTaskSchedulerを使います。
Cleanup のルール
現在の method の終了後も存続し得る、返されたすべての registration または handle は、明示的に close するか、context.disposableScope() に登録しなければなりません。