開発主要な仕組み

プラグインが読み込まれない場合

プラグイン JAR が拒否される、表示されない、期待どおりに動作しない理由を、症状から診断するためのガイド。

目にしている症状から始めてください。各セクションでは、確認する価値のある順に、可能性の高い原因を挙げています。プラグインに固有でないインストーラー、起動、ホストの問題については、トラブルシューティングを参照してください。

まず、証拠を集める

何かを変更する前に、次を行います。

  1. ログを開く。 Turboism → ログ… を選択し、現在のセッションのログを確認します。プラグイン ID を検索してください。失敗はプラグイン ID が付いた状態で報告されます。
  2. プラグイン管理を確認する。 Turboism → プラグイン管理… を開きます。プラグインが一覧にある場合は、ダブルクリックして SDK API 範囲と宣言された Cubism バージョンを確認します。
  3. バージョンを記録する。 Turboism のバージョン、Cubism Editor のバージョン、正確な手順を記録します。バージョンに依存する失敗はよくあります。

Turboism の実行中は、プラグイン、config、pending 状態のファイルを編集しないでください。また、JAR を拒否した検証を無効にしてはいけません。

インストール時に JAR が拒否される

JAR からインストール… は、最初にファイルを検査します。次の理由で JAR を拒否することがあります。

  • シンボリックリンクや通常ファイルでないソース、または raw サイズ、エントリサイズ、合計展開サイズ、エントリ数、圧縮比の制限を超えるアーカイブ。
  • 不正または重複したエントリ、特殊ファイル、あるいは META-INF/turboism/plugin.json の欠落または重複。
  • 記述子の ID、バージョン、API 範囲の不一致。
  • コピーされた SDK、Runtime、テスト、Live2D のクラス: ビルドでは、SDK を shade せず、compileOnly を使う必要があります。
  • ネイティブバイナリ、インストーラーのペイロード、ネストした JAR。
  • エントリポイントの欠落、または宣言されていない通常のリソース。
  • plugin.json で宣言された i18n カタログが JAR にない。

./gradlew clean build でソースからリビルドし、Gradle が生成した JAR をインストールしてください。アーカイブを手作業で編集してはいけません。

インストールされるが表示されない

次の点を確認してください。

  • Cubism を完全に再起動した後に操作が適用されたこと。両方の起動で同じ Turboism home を使用していること。
  • JAR を手動でコピーした場合、サブフォルダーではなく <turboism.home>/plugins/ のルートに直接あること。
  • 同じプラグイン ID の古い JAR が残っていないこと(重複は DUPLICATE_PLUGIN_ID で失敗します)。
  • プラグイン ID がプラグイン管理… で無効になっていないこと。
  • environment.requiresCubism が、起動した環境と一致していること。
  • エントリポイントのクラスが存在し、public で、TurboismPlugin を実装し、public な引数なしコンストラクタを持つこと。
  • 記述子がサポートされている schemaVersion を使い、それに対して有効であること。不明なフィールドは無視されず拒否されるため、フィールド名のタイプミスで読み込みが失敗します。

非互換と表示される

プラグイン管理とプラグインマーケットは、プラグインの turboismApi 範囲が実行中の Turboism API を含まない場合、そのプラグインを非互換として表示します。旧来の [0.1.0,0.2.0) 範囲は TURBOISM_API_INCOMPATIBLE で失敗します。[0.67.0,1.0.0) を使い、より新しい SDK メンバーに依存する場合は、より高い下限を使ってください。

読み込まれるが、開始に失敗する

構築、init、enable のいずれかが例外をスローすると、Runtime は JAR 全体をロールバックし、例外がプラグイン ID とともにログに現れます。典型的な原因は次のとおりです。

  • 利用できないサービスへの、ガードのない呼び出し(permission と可用性を参照)。
  • ローカライズのキーまたはカタログの欠落。
  • 無効な configuration スキーマ(たとえば不正なキー名、または重複した config ID やパス)。
  • 後で実行されるメソッドでしか設定しないフィールドによる NullPointerException。

修正はほとんどの場合、より広い permission ではなく、ガード(isAvailable()、services().find(...))や記述子の修正です。

開始するが、機能が何もしない

permission と可用性の 4 つのチェックを順に確認します。

  1. permission。 その呼び出しに対応する permission が plugin.json で宣言されていますか。拒否は、プラグインに対してログに記録されます。
  2. サービス。 services().find(...) が空で返りましたか。それとも unavailable() センチネルが応答しましたか。
  3. Cubism バージョン。 ログに CubismEditorApiUnavailableException や利用不可の API ID が表示されていますか。Editor のバージョンがその API を許可していない可能性があります。互換性を参照してください。
  4. 状態。 モデルドキュメントは実際にアクティブですか。ドキュメントが変更されたために、保持しているオブジェクトが古くなっていませんか。

また、enable() で登録したこと、ハンドルを disposable scope に登録したこと、プラグインがインストールされているだけでなく有効であることも確認してください。

プラグイン内から Runtime が報告した問題を表面化したい場合は、context.diagnostics() を通じて構造化された診断情報を利用できます。

メニュー項目またはアクションがない

  • メニューパスはスラッシュ区切りの文字列です。カタログから取得している場合は、ベースカタログである messages.properties にキーが存在することを確認してください。
  • turboism.action.register と turboism.ui.menu.contribute の両方が必要です。一方はアクション用、もう一方はメニュー項目用です。
  • メニュー contribution はアクションの ID を参照します。どちらかにタイプミスがあると、裏に何もないメニュー項目、またはメニューのないアクションになります。

設定が表示されない、または保持されない

  • スキーマを登録するには turboism.config.plugin.write が、読み取るには turboism.config.plugin.read が必要です。
  • スキーマは、何かがそれを読み取る前の init で登録し、config().isAvailable() でガードしてください。
  • エディターのフィールドの key は、スキーマで宣言されたキーと一致し、小文字の [a-z0-9._-] を使う必要があります。
  • 書き込みにはリビジョンが使われます。古いリビジョンは、例外ではなく結果の中の値として拒否されるため、結果を確認してください。

それでも解決しない場合

  • 問題が現れる最小のバージョン、できればステップ 2 の hello プラグインまで、プラグインを縮小してください。
  • 記述子をプラグインマニフェストとパッケージングおよびファーストパーティプラグインの plugin.json と比較してください。
  • 再現可能な問題は、バージョンとログ行を添えてフィードバックと機能要望から報告してください。共有するものからは、プライベートなパス、認証情報、個人データを取り除いてください。