プラグインインターフェース

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

FamilyCurrent entrypointTypical use
Metadatadescriptor()現在の JAR-level descriptor を調べる
Logginglogger()plugin-scoped diagnostic を出力する
Pathspaths()plugin-owned config/data/cache/state/log namespace にアクセスする
Localizationlocalization()manifest で宣言された localized text を読む
Taskstasks()上限付き cancellable work を submit する
Host readshostReads()上限付き asynchronous host snapshot を要求する
Storagestorage()plugin-owned data を読み、atomic に書き込む
User filesuserFiles()user-granted external-file handle を使う
Cubismcubism()snapshot を読み、unified object graph を使う
Queriescubism().model().active().parameters(), selectionQuery(), modelHierarchyQuery()狭い型付き query
EventseventBus()immutable な型付き event を publish/subscribe する
Actionsactions()再利用可能な plugin action を登録する
Menus and UImenus(), toolbar/context-menu registries, services().require(UiHostCapabilityService.class)toolkit-neutral UI descriptor を提供する
Canvas hintsservices().require(UiHostCapabilityService.class)描画領域上にネイティブ Cubism hint を表示する(turboism.ui.canvas.hint 権限)
Configurationconfig()型付き schema を登録し、value を読み、compare-and-set write を行う
Diagnosticsdiagnostics()構造化された Runtime diagnostic を調べる
CleanupdisposableScope()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() に登録しなければなりません。