プラグインが読み込まれない場合
プラグイン JAR が拒否される、表示されない、期待どおりに動作しない理由を、症状から診断するためのガイド。
目にしている症状から始めてください。各セクションでは、確認する価値のある順に、可能性の高い原因を挙げています。プラグインに固有でないインストーラー、起動、ホストの問題については、トラブルシューティングを参照してください。
まず、証拠を集める
何かを変更する前に、次を行います。
- ログを開く。 Turboism → ログ… を選択し、現在のセッションのログを確認します。プラグイン ID を検索してください。失敗はプラグイン ID が付いた状態で報告されます。
- プラグイン管理を確認する。 Turboism → プラグイン管理… を開きます。プラグインが一覧にある場合は、ダブルクリックして SDK API 範囲と宣言された Cubism バージョンを確認します。
- バージョンを記録する。 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 つのチェックを順に確認します。
- permission。 その呼び出しに対応する permission が
plugin.jsonで宣言されていますか。拒否は、プラグインに対してログに記録されます。 - サービス。
services().find(...)が空で返りましたか。それともunavailable()センチネルが応答しましたか。 - Cubism バージョン。 ログに
CubismEditorApiUnavailableExceptionや利用不可の API ID が表示されていますか。Editor のバージョンがその API を許可していない可能性があります。互換性を参照してください。 - 状態。 モデルドキュメントは実際にアクティブですか。ドキュメントが変更されたために、保持しているオブジェクトが古くなっていませんか。
また、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と比較してください。 - 再現可能な問題は、バージョンとログ行を添えてフィードバックと機能要望から報告してください。共有するものからは、プライベートなパス、認証情報、個人データを取り除いてください。