ステップ 4: モデルを読み取る
アクティブなモデルのパラメータを読み取り、型付きイベントでパラメータの変更を数え、利用できないデータを処理し、サポートする Cubism バージョンを宣言します。
Parameter Peek はまだ挨拶するだけです。このステップでは、Editor から 2 つのことを学びます。開いているモデルにパラメータがいくつあるか、そしてプラグインが有効化されてからパラメータ値が何回変更されたかです。
1. 新しい permission を追加する
モデルデータの読み取りとその変更の観測は、さらに 2 つのリスク境界を越えます。イベントの受信には 3 つ目が必要です。これらを plugin.json の permissions に追加します。
{ "id": "turboism.cubism.model.read", "scope": "application", "reason": "Counts the parameters of the active model." },
{ "id": "turboism.cubism.model.observe", "scope": "application", "reason": "Counts parameter value changes." },
{ "id": "turboism.event.subscribe", "scope": "application", "reason": "Receives parameter change events." }model.read はモデルオブジェクトの読み取りを、model.observe はモデルの変更を表すイベントの受信を、event.subscribe はイベントを購読すること自体を許可します。パラメータイベントには、後ろの 2 つの両方が必要です。
2. アクティブなモデルを読み取る
report() を置き換え、カウンターのフィールドを追加します。変更箇所はコメントで示しています。
import dev.turboism.sdk.cubism.CubismEditorApiUnavailableException;
import dev.turboism.sdk.cubism.event.ParameterValueEvent;
import dev.turboism.sdk.event.SubscribeEvent;
import java.util.concurrent.atomic.AtomicInteger;
public final class ParameterPeekPlugin implements TurboismPlugin {
private final AtomicInteger observedEdits = new AtomicInteger(); // new
private PluginContext context;
private PluginLogger logger;
// init(), disable(), shutdown() unchanged
@Override
public void enable() throws Exception {
observedEdits.set(0); // new
// ... action and menu registration unchanged
}
@SubscribeEvent // new
public void onParameterChanged(final ParameterValueEvent.On event) {
observedEdits.incrementAndGet();
}
private void report() {
final String summary;
try {
if (!context.cubism().hasActiveModel()) {
summary = context.localization().text("parameterpeek.summary.no-model");
} else {
final int count = context.cubism().model().active().parameters().all().size();
summary = context.localization().format("parameterpeek.summary", count, observedEdits.get());
}
} catch (CubismEditorApiUnavailableException unavailable) {
logger.info("Parameter reading is unavailable on this Cubism version: " + unavailable.apiId());
return;
}
logger.info(summary);
context.services().find(UiHostCapabilityService.class).ifPresent(ui ->
ui.notifyStatus(new StatusNotification("parameterpeek.report", "INFO", summary)));
}
}両方のカタログファイルに、2 つの新しいメッセージを追加します。
parameterpeek.summary=The active model has {0} parameters; {1} value changes observed since enable.
parameterpeek.summary.no-model=Open a model document first.{0} と {1} は java.text.MessageFormat のプレースホルダーで、localization().format(key, args...) によって埋められます。MessageFormat であるため、メッセージ内のリテラルのアポストロフィは 2 回書く('')必要があり、数値はアクティブなロケールに合わせて書式化されます。
重要な仕組み: モデルを見る 2 つの方法
SDK は Cubism を 2 通りの見方で提供します。
context.cubism().activeModel()のようなスナップショットは、不変の値オブジェクトです。読み取りが軽く、保持しても安全ですが、ある時点の状態を表します。context.cubism().model().active()から到達するオブジェクトモデルは、ライブのParameters、Parts、Drawablesなどを提供します。これらのオブジェクトは世代に束縛されています。ドキュメントの切り替え、再読み込み、削除、Provider の置換の後に、保持していた参照は誤ったものを黙って指すのではなく、fail closed になります。
このため、Parameter をフィールドに保存して後で再利用してはいけません。必要になるたびに context.cubism() から解決し直してください。より広い読み取りパターンについては、SDK API ガイドを参照してください。
重要な仕組み: fail closed にして、そのことを伝える
Cubism のデータが常にあるとは限りません。report() がそれをどう処理しているかを見てください。
hasActiveModel()は、ドキュメントがモデルではないという一般的なケースに、例外なしで答えます。CubismEditorApiUnavailableExceptionは、より稀なケース、つまりアクティブな Cubism バージョンがその呼び出しを許可していない場合を扱います。ユーザーに届かせずに、機能の境界でこれを捕捉して縮退(ここではログ出力)させます。
何をするか決めるために Cubism のバージョン番号を文字列比較してはいけません。SDK に判断させてください。同じ考え方があらゆるサービスに当てはまります。permission は問い合わせを許可するだけで、答えを約束するものではありません。permission と可用性を参照してください。
3. イベントに反応する
ParameterValueEvent は 3 つの状態を持つ sealed ファミリーです。
| 型 | 発火するタイミング | 値を変更できるか |
|---|---|---|
Before | ホストの書き込みの前に同期的に。 | はい。ただし別の intercept permission が必要です。 |
On | 値が実際に変化した書き込みの後に。 | いいえ。観測のみです。 |
After | 値が変化しなかったものを含め、成功したすべての書き込みの後に。 | いいえ。観測のみです。 |
Parameter Peek は変更を数えるため、On が適切な型です。観測に Before は必要ありません。
@SubscribeEvent は宣言的なスタイルです。ステップ 1 でセットアップした turboism-event-processor アノテーションプロセッサが、コンパイル時にアノテーションを読み取り、購読者のインデックス(JAR で見た __TurboismSubscriberCatalog クラス)を生成するため、手動での登録や破棄は不要です。リスナーは、public クラスの public なインスタンスメソッドで、void を返し、具体的なイベントパラメータをちょうど 1 つ宣言している必要があります。それ以外はプロセッサがコンパイルエラーとして報告します。
代わりに手動で購読することもでき、プロセッサのない SDK でも動作します。返されたハンドルは disposable scope に保持してください。
Registration subscription = context.eventBus().subscribe(
ParameterValueEvent.On.class,
event -> observedEdits.incrementAndGet());
context.disposableScope().register(subscription);同じイベントには、どちらか一方のスタイルだけを使ってください。両方を使うと、変更が 2 回数えられます。
重要な仕組み: イベントは自分のスレッドでは実行されない
通常のイベント観測は非同期に配信され、ライフサイクルメソッドは遷移ごとに異なる可能性のあるワーカースレッドで実行され、メニューアクションはさらに別の場所で実行されます。プラグインを並行処理されるものとして扱ってください。カウンターが int ではなく AtomicInteger なのはそのためです。リスナーは短く、ブロックしないようにしてください。スレッドとタスクで、ルールとバックグラウンド処理や UI 処理のスケジュール方法を説明しています。
4. サポートする Cubism バージョンを宣言する
src/main/resources/META-INF/turboism/cubism-versions.json を開きます。セットアップスクリプトが、リリースでレビュー済みの Cubism Editor バージョンからこれを埋めています。
{
"format": "turboism.plugin-cubism-versions/v1",
"plugin": "com.example.parameterpeek",
"supportedVersions": ["5.0.00", "5.0.01", "..." , "5.3.04"],
"fullFeatureVersions": ["5.0.00", "5.0.01", "..." , "5.3.04"]
}supportedVersionsは、プラグインが利用できる Editor の正確なバージョンを列挙します。fullFeatureVersionsは、すべての機能が動作するサブセットです。supportedVersionsのサブセットである必要があります。
このファイルはあなたが行う主張であり、SDK が代わりに確認してくれるものではありません。両方のリストを、実際にテストしたバージョンに絞ってください。不確かな場合は、宣言を少なめにしてください。プラグイン管理は、宣言がない、または無効な場合を 未宣言 と表示し、ユーザーはプラグインの詳細であなたのリストを確認します。
@CubismEditor などの SDK アノテーションは、ある SDK API がどのバージョンで動作するかを示します。プラグインがそのバージョンで動作することの証明にはなりません。互換性は、SDK の宣言、自分自身のテスト、実行時チェックの組み合わせで決まります。レビュー済みのバージョンセットと Editor のマイナーラインごとのケイパビリティの境界については、互換性を参照してください。
5. 試す
ビルドし、再インストール(ステップ 3を参照)し、Cubism を再起動してから、次を行います。
- モデルを開かずに Parameter Peek: Report を実行します。
Open a model document first.と表示されるはずです。 - モデルを開いて、もう一度実行します。パラメータ数と
0 value changesが表示されるはずです。 - パラメータのスライダーを何度か動かしてから、もう一度コマンドを実行します。変更回数が増えます。
チェックポイント
- レポートがテストモデルの正しいパラメータ数を表示する。
- パラメータを編集すると変更カウンターが増え、モデルがない場合は分かりやすいメッセージが表示される。
cubism-versions.jsonにテスト済みのバージョンだけが列挙されている。
次へ: ステップ 5: 設定を追加する