メインコンテンツまでスキップ

Resource Pack Manager トラブルシューティング

このページでは、ResourcePackManagerのコードベースで現在確認できる挙動のみを扱います。

RSPMで何か問題があるとき、最も有用な最初のステップは次のコマンドです：

/rspm status

これは、バージョン、デプロイモード（standalone vs network-backend）、秘密を含まない短いネットワークキーのフィンガープリントとそのキーの出どころ、JavaおよびBedrockパックの状態、アクティブな配信経路とURL、解決された外部ホストと自動検出された公開IP、関連するすべての設定フラグ、プロキシのデプロイに関するリマインダー（ネットワークプロキシ用jarは同じ ResourcePackManager.jar であること）、Floodgate／Geyser-Spigotの検出状況を表示します。プロキシ上でjarが動作しているときにも同じコマンドが存在し、プロキシ側の対応情報（バックエンド一覧、バックエンドごとの取得結果、マージされたパックの状態）を表示します。

コンソールが静かなのは意図的です​

RSPMは配信経路を新たに初期化するたびに、1行だけを出力します — その結果です：

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip
[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

それ以外 — ステージングされた各パック、マージされた各クラスター、各安定性チェック、各セルフホストプローブとその結果 — は既定で抑制されます。RSPMが自力で回復した状況は、警告として報告されません。 セルフホストのプローブが失敗してRSPMが黙ってリモートホスティングに切り替えたなら、それは障害ではなく成功であり、コンソールはそれについて何も言いません。

つまり、警告がないことは何も起きなかった証拠にはならず、結果の行があることはプレイヤーにパックが届いていることを意味します。ホスティングやマージのバグを報告する前に、実況を有効にしてください：

/rspm verbose on

そして /rspm reload を実行します。このコマンドは plugins/ResourcePackManager/config.yml に verboseLogging: true を書き込み、設定は再起動をまたいで保持されるので、終わったら /rspm verbose off を実行してください。キーを手で編集しても同じことです。Bedrockコンバーターには別途 bedrockConverterDebug というスイッチがあり、こちらは設定ファイル専用です。

正当に目にする可能性がある警告は本物の障害です：特定のプレイヤーへのパック配信が繰り返し失敗する、クライアントが INVALID_URL を報告する、HTTPポートがバインドできなかった、両方の配信経路が失敗した、あるいはプロキシが数サイクルポーリングしてもどのバックエンドもコンテンツを生成していない、といったケースです。

プレイヤーがリソースパックを受け取れない​

まず以下を確認してください：

  • 通常の自動配信を使いたいなら autoHost を有効にしておく必要があります（selfHostForce はテスト用の明示的な上書きです）
  • マージされたパックが存在し、少なくとも1つの配信経路（セルフホストまたはリモート）が成功している必要があります
  • プレイヤーがパックを受け取るのは参加時か、ホスティングが準備できた瞬間に発火する最初のアップロードブロードキャストのときだけです
  • FloodgateのプレイヤーはJava配信から意図的に除外されます。彼らのBedrockパックセッションはGeyserが所有しているためです

必要であれば：

  1. /rspm status を実行して「Hosting」セクションを確認します。Active delivery には、現在セルフホスト、リモート、いずれが使用中かが表示されます。
  2. 「active delivery: not yet ready」と表示される場合 — ミックスまたはアップロードがまだ進行中です。早く参加しすぎたプレイヤーがいる場合、プラグインはコンソールに大きく警告を出し、配信が準備できた瞬間にパックを自動送信します。
  3. 「active delivery: none — hosting disabled or failed」と表示される場合 — autoHost がオフか、セルフホストのプローブとリモートアップロードの両方が失敗しています。下記の「セルフホストの健全性チェックが失敗した」と「自動ホストがリモートサーバーに到達できない」を参照してください。
  4. verboseLogging: true を設定してから /rspm reload を実行し、コンソールでアップロード／セルフホストのプローブ結果を監視し、テスト用プレイヤーで再参加します。（このフラグがない場合、プローブの各ステップは出力されません — 最終的な「Resource pack is live via ...」の結果行だけが出力されます。）

参加時のパック提示は約1秒遅延します。Javaクライアントが FAILED_DOWNLOAD や DISCARDED を報告した場合、RSPMはそのプレイヤーセッションについて最大3回まで自動的に再試行します。プレイヤーによる拒否や INVALID_URL については再試行しません。再試行の枯渇や無効なURLは本物の障害としてログに記録されます。

自前の外部パイプラインでセルフホストしている場合（autoHost: false）、RSPMがあなたのカスタムURLを代わりにプッシュすることはありません。その構成では、サーバー側の独自のパック配信フローが別途必要になります。

ItemsAdderはインストールしているのに、最終パックにそのコンテンツが含まれない​

これは通常、ItemsAdderの設定がResourcePackManagerによる読み取りやホストを妨げている状態であることを意味します。

次を使用してください：

/rspm itemsadder configure

このコマンドは現在、次のことを行います：

  • resource-pack.hosting.no-host.enabled を有効化します
  • protection_1、protection_2、protection_3 を無効化します
  • resource-pack.zip.compress-json-files: false を設定します
  • /iareload、続いて /iazip を実行します
  • 約15秒後にResourcePackManagerをリロードします

「ItemsAdderはすでに自身のパックをホストしている」と表示された場合は、まず手動でItemsAdderのホスティングを無効化し、コマンドを再度実行してください。

マージされたパックが無効、またはアップロードに失敗する​

ResourcePackManagerの自動ホスト統合は、次のサーバー側エラータイプを明示的に処理します：

  • 必須ファイルの欠落
  • ファイルサイズ過大
  • 無効なファイル形式
  • セッションの欠落
  • リモートサーバーに到達できない

これらが発生した場合：

  1. /rspm reload を実行してパックを再構築します。
  2. ソースパックのいずれかが壊れていたり、暗号化されていたり、その他の理由で読み取れなくなっていないかを確認します。
  3. 最終的にマージされたパックのルートに有効な pack.mcmeta と pack.png が残っているかを確認します。

有効化されたパックを展開またはステージングできない場合、現在のミックスは中断され、コンソールが失敗したパックの名前を表示します。そのパックを修復するか、手動で追加したZIPを削除するか、自動統合の設定で isEnabled: false を設定してからリロードしてください。

壊れた1つのパックがもう永遠に全体をブロックすることはありません​

ステージングできないパックは毎回同じように失敗するため、放置すると配信が恒久的に詰まってしまいます — マージは完了せず、同じエラーが際限なく繰り返されます。同じファイルが3回連続で失敗した後、RSPMは残りのパックが出荷できるようにそのパックをマージから外し、その旨を1回だけ大きく通知します：

[ResourcePackManager] Resource pack X.zip failed to stage 3 times in a row and has been excluded
from the merge so the remaining packs can be delivered. The merged pack is now INCOMPLETE ...

これは文字どおりに受け取ってください：プレイヤーが受け取っているパックは、そのプラグインのコンテンツを欠いたものになっています。よくある原因は、壊れているか書き込みが途中で終わったzipです。

この除外は自動的に解除されます。失敗の記録はファイルのサイズと更新時刻をキーにしているため、ファイルを修復または置き換えれば隔離は自動的に解除され、次のマージでパックが復帰します — コマンドも再起動も不要です。/rspm reload もすべての隔離記録をゼロからリセットします。3回に達しなかった失敗カウントは、ミックスが1回成功するたびに破棄されるため、長い稼働時間にわたって散発した無関係な一時的トラブルが積み上がって除外に至ることはありません。

リモート自動ホストから SESSION_NOT_FOUND エラーが返ってきた場合、RSPMはセッションUUIDをクリアし、次のキープアライブティックで再初期化します — 手動介入は不要です。

あるプラグインのアセットが別のプラグインのアセットを上書きしている​

これは次のファイルにある priorityOrder で制御されます：

plugins/ResourcePackManager/config.yml

上位のエントリが下位のエントリに勝ちます。

マージ不可能なファイルでは、ResourcePackManagerは優先度の低いファイルを置き換えます。マージ可能なJSONファイルでは、内容をマージします。現時点でマージ可能なJSONのカテゴリは次のとおりです：

  • sounds.json
  • 言語ファイル
  • minecraft/models/item 配下のバニラのアイテムモデルJSON（非再帰的マージ：パックをまたいで overrides 配列のみが結合され、ファイルの残りの部分は最優先のパックが勝ちます）
  • アトラスファイル
  • フォントファイル
  • items/ 配下の1.21.4以降のアイテムモデル定義（predicateツリーの構造を尊重するフォーマット対応マージ）

pack.mcmeta も特別にマージされます：最も高い pack_format が採用され、supported_formats の範囲は拡張されます（整数、2要素の配列、{min_inclusive, max_inclusive} オブジェクト形式すべてに対応）。オーバーレイエントリは統合され、非標準のトップレベルキーも保持されます。オーバーレイエントリは1.21.9以降との互換のために min_format／max_format フィールドが欠けていれば追加されて正規化されます。さらに、ベースのアトラスソースもオーバーレイのアトラスファイルにマージされ、オーバーレイがベースのエントリを隠さないようになっています。

直近のマージで何が起きたかを確認したい場合は、次を確認してください：

plugins/ResourcePackManager/collision_log.txt

GUIテキストやフォントベースの要素が崩れて見える​

フォントファイルはResourcePackManagerがマージするJSONカテゴリの1つですが、それでも2つの異なるフォントシステムがMinecraft上でうまく共存するとは限りません。

フォント駆動のメニューやHUDがおかしい場合：

  1. 勝たせたいパックが上に来るように priorityOrder を変更します。
  2. /rspm reload を実行します。
  3. 期待した場所で衝突が起きたかを collision_log.txt で確認します。

リソースパックの変更がすぐに反映されない​

ResourcePackManagerには、対応するパックソース向けのウォッチドッグがあります。

変更されたパックが3秒間変化しなくなるまで待ち、すべての監視対象パックが安定した時点で即座に再ミックスが行われます。

別プラグインのパックを能動的に再生成している場合は、ファイル書き込みが止まってから数秒待ってみてください。判断に迷う場合は、上流のプラグインの処理が終わってから /rspm reload を実行してください。

/rspm status がリモートホスティングと表示するが、セルフホストを期待していた​

これは preferSelfHost: true（既定）で、3つのセルフホスト健全性チェックのいずれかが失敗したときの正常な挙動です。RSPMはこれについて警告を出しません — リモートホスティングへのフォールバックは成功した結果なので、失敗したチェックは明示的な「This is OK.」を添えて詳細レベルで記録され、verboseLogging: true にしない限り表示されません。既定で得られる唯一の行は Resource pack is live via automatic hosting — ... です。

3つのレイヤーのどれが失敗したかを見るには、/rspm verbose on（または verboseLogging: true の設定）と /rspm reload を実行してください：

  1. Layer 1（ヒューリスティック） — 解決された外部ホストがRFC1918／ループバック／リンクローカルでした。selfHostExternalHost を実際の公開ホスト名に設定するか、プラグインが api.ipify.org ／ checkip.amazonaws.com に到達できるようにしてください。
  2. Layer 2（localhostセルフプローブ） — http://127.0.0.1:<port>/rspm.zip への HEAD リクエストが、非空のボディと共に200を返しませんでした。ポートバインドの衝突やパックファイルの欠落を検出します。
  3. Layer 3（外部到達性プローブ） — magmaguy.com があなたが通知したURLを取得しようとして到達できませんでした。最も多いのは、ルーターやファイアウォールでHTTPポートが転送されていないケースです。プローブURLと理由コード（PRIVATE_HOST_REJECTED、CONNECT_TIMEOUT、ECONNREFUSED、RATE_LIMITED など）は verboseLogging の下で出力されます。

修正（推奨順）：ファイアウォールとルーターでHTTPポートを開く、selfHostExternalHost をルーティング可能なホスト名に設定する、または preferSelfHost: false に設定してセルフホストを完全にスキップします。

magmaguy.com のプローブ自体に到達できない（RSPMがそれに尋ねるためのアクセスができない）場合、セルフホストは失敗扱いではなく維持されます — フォールバック経路も magmaguy.com を必要とするため、プローブできないという理由でコミットを拒否するのは矛盾している、という理由です。

完全な判定ツリーはセルフホストを参照してください。

自動ホストがリモートサーバーに到達できない​

ResourcePackManagerの組み込みリモートホストは次に通信します：

https://magmaguy.com/rsp/

この接続に失敗すると、プラグインは通信警告をログに出力し、再接続が成功するまでリモートフォールバックを使用できません。

選択肢は次のとおりです：

  1. サーバーの外向きHTTPS接続を修復する
  2. リモートサービスが再び到達可能になるのを待つ
  3. autoHost を無効にして、生成されたzipを自分でホストする
  4. HTTPポートを開け、selfHostExternalHost を公開ホスト名に設定し、preferSelfHost: true のままにする。明示的なホスト名を指定すると公開IPの自動検出はスキップされますが、RSPMはLayer 3のプローブを引き続き試みます。プローブサービス自体に到達できない場合、RSPMはその通信失敗を「あなたのURLが到達不能である証拠」とは扱わず、セルフホストを維持します。

マージされたパックを自分のWebサーバーでセルフホストしたい​

コードがサポートする手順は次のとおりです：

  1. autoHost: false に設定します。
  2. ResourcePackManagerに既存のフォルダーへ追加のコピーを書き込ませたい場合は、resourcePackRerouting を設定します。
  3. ResourcePackManager_RSP.zip を自分でホストします。

resourcePackRerouting は plugins ディレクトリからの相対として解決され、対象フォルダーは事前に存在している必要があります。

その代わりにRSPM組み込みのセルフホストHTTPサーバー（別物 — プラグインと同じJVM）を使いたい場合は、セルフホストを参照してください。

このサーバーについて保存されているリモートデータを確認したい​

次を使用します：

/rspm data_compliance_request

アクティブなリモートホスティングセッションがあれば、ResourcePackManagerは応答を次の場所にダウンロードします：

plugins/ResourcePackManager/data_compliance/data.zip

RSPMは同じ data_compliance フォルダーに ReadMe.md も書き出します。

リモートセッションがない場合（例：セルフホスト中）、コマンドはリクエストできるリモートデータがないことを伝えます。

Bedrockパックが生成されない​

bedrockConversionEnabled は既定で true のため、自動的に動作するはずです。まず /rspm status を実行してください — 「Bedrock Pack」セクションが、パックがディスクにない理由を教えてくれます：

  • 「No Bedrock target detected」 — ローカルのGeyser-Spigotもローカルの Floodgate もなく、ネットワークモードでもありません。変換は意図的にスキップされます。Floodgate（プロキシ構成向け）またはGeyser-Spigot（スタンドアロン構成向け）をインストールし、/rspm reload してください。
  • 「Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing」 — 通常は最初のミックスサイクルがまだ完了していない（起動後 ~30 秒待つ）、変換が変換可能なアイテムマッピングも許可されたエンティティバンドルも見つけられなかった、または変換が例外を投げたかです。コンソールで [BedrockConverter] の警告や Generic scanner: discovered 0 items definition files を探してください。

Geyserの自動検出に失敗する場合：

  1. config.yml の bedrockGeyserFolder をGeyserのデータフォルダーへのパス（例：Geyser-Spigot）に設定します。
  2. 絶対パスはそのまま動作します。相対パスはまずサーバーの作業ディレクトリから、次に plugins ディレクトリからの相対として試されます。

コンバーターは plugins/Geyser-Spigot/、plugins/Geyser-*/ の任意の派生、または Fabric／NeoForge構成向けの config/Geyser-*/ で自動検出を試みます。

アイテム単位／ボーン単位のログ出力が必要な場合は、bedrockConverterDebug: true に設定してリロードしてください。

Bedrock：レガシーパックが存在するためライブプロバイダーがスキップされた​

コンソールが Legacy RSPM Bedrock pack detected を報告した場合、Geyserは起動時に自身のパックディレクトリにある古い ResourcePackManager_Bedrock.zip をすでにスキャンしています。プロセスの実行中にそのファイルを削除すると、Geyserは存在しないパスに対するコーデックをメモリ上に保持したままになるため、RSPMはその起動についてライブパックプロバイダーを意図的にスキップします。

サーバーを完全に停止し、RSPMが出力した正確なレガシーファイルのパスだけを削除してから、サーバーを再起動してください。この移行に /reload を使ってはいけません。現在のパックは plugins/ResourcePackManager/output/ に残り、セッション単位で配信されます。Geyserの packs/ ディレクトリに置くべきものではありません。

Bedrockプレイヤーで持ち物アイテムが正しくない位置に表示される​

これは変換のバグではなく、調整の問題です。plugins/ResourcePackManager/bedrock_display_offsets.yml を開いて該当する軸を調整し、/rspm reload を実行し、Bedrockのテストクライアントを再接続して次の参加で再構築されたパックを受け取らせてください。一人称と三人称は独立しているため、一方を調整しても他方には影響しません。各つまみの一覧と役割はBedrock変換を参照してください。

Bedrockプレイヤーでカスタム防具のテクスチャが表示されない​

カスタム防具は、バニラの防具ジオメトリにJavaのテクスチャを可視レイヤーとして重ねることでBedrock上に描画されます。これが機能するためには、ソースとなるプラグインのパックがアイテム定義と一緒に assets/<namespace>/equipment/<material>.json という装備ファイルを定義している必要があります。変換ログにそのアイテムが出ているのにゲーム内で防具テクスチャが見えない場合は、そのファイルがマージされたパックの中に存在するかを確認してください。

プロキシ：バックエンドがネットワークキーを持っていないと言う​

バックエンドで /rspm status が Network key source: not set — the proxy sends one when a player next connects here を示し、コンソールが「This backend is behind a proxy but has no network key yet」を繰り返します。

plugins/floodgate/key.pem がないことは原因ではありません — そのファイルは今や任意です。キーを所有しているのはプロキシです：プロキシは自身の network-key ファイルを読み込むか、Floodgateの key.pem があれば一度だけそこからシードするか、新しいキーを生成し、そのうえでプレイヤーが接続した時点で各バックエンドへプッシュします。

次の順で確認してください：

  1. プロキシの起動後、そのバックエンドにプレイヤーが接続しましたか？ 付与はプレイヤーの接続に乗って届きます。
  2. プロキシに実際に ResourcePackManager.jar が入っていますか？ バックエンドは plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar に自身のjarのコピーを用意し、そのパスを出力します — それをプロキシの plugins/ にコピーして、プロキシを再起動してください。
  3. モダン転送を使うVelocityでは、バックエンドの転送シークレットはプロキシのものと一致していますか？ モダン転送のバックエンドは、署名なしまたは誤って署名された付与を意図的に拒否します。どちらのケースかはログに書かれています。両側でシークレットを修正すれば、次のプレイヤー接続で自動的に再試行されます。
  4. 両側で /rspm status の Network key fingerprint 行を比べてください。フィンガープリントが一致していればリンクは良好です。キーそのものは決して出力されません。

手順の全体はプロキシネットワークを参照してください。

プロキシ：「Could not save the network key」​

プロキシはキーを解決できましたが、それを network-key ファイルに書き込めませんでした。今回の起動は動作します。しかし次の再起動では別のキーが生成され、既に配布済みのバックエンドはすべて古いキーを保持して新しいキーを拒否します — ネットワーク全体が黙ってリンク解除されます。

再起動する前に、プロキシプラグインのデータフォルダーのファイルシステム権限を修正してください。

プロキシ：数回のポーリングサイクル後に「no merged pack」が表示される​

プロキシで約20秒分の空ポーリングサイクル（既定 5 秒間隔 × 4 サイクル）が続くと、RSPMはポーリングしたすべてのバックエンド、試行したHTTP URL、結果（200／304／404／CONNECT_FAILED など）を列挙する1回限りの診断バナーをログ出力します。バナーは最もよくある修正方法を説明します：

  • すべてのバックエンドで CONNECT_FAILED → プロキシがバックエンドのHTTPポートに到達できません。velocity.toml ／ config.yml のアドレスがプロキシから実際に到達可能なもの（プロキシのネットワークから解決できないDockerの内部名などではない）であること、そしてバックエンドが通知したHTTPポートがプロキシとバックエンド間で開いていることを確認してください。バナーは試行した正確なURLを表示します。バックエンドがポートを通知する前は、プロキシは mcPort + network-http-offset-v2 にフォールバックするため、早い段階での CONNECT_FAILED は、そのフォールバックポートがまだ到達不能であることを意味する場合もあります。
  • すべてのバックエンドで NOT_FOUND_404 → バックエンドは起動していますが、Bedrockパックを生成していません。各バックエンドで /rspm status を実行してください。Bedrock Packの診断ブロックが理由を教えてくれます。

バナーは詰まった期間ごとに1回発火し、少なくとも1つのバックエンドがコンテンツを返すようになると「NetworkSync: recovered」行がログに出力されます。詳細はプロキシネットワークを参照してください。

プロキシ：初回プロキシ起動時にBedrockプレイヤーにモデルが見えない​

Geyserはプロキシ起動時にだけカスタムアイテムテーブルを登録します。Bedrockパックを生成したバックエンドより先にプロキシが起動した場合、Geyserは空のマッピングテーブルで動作し、そのセッションの残り時間ずっとそのままになります。

修正は、プロキシが Merged Bedrock pack published at ... をログに出した後でプロキシを再起動することです。RSPMはプロキシ起動時に前回実行時のマッピングを事前デプロイするため、これが噛むのは新規インストール時のみです — 以降の起動では、Geyserがスキャンする前に何かが用意されています。

バックエンド：「Backend HTTP server failed to bind on port X」​

ネットワークモードでは、バックエンドは小さなHTTPサーバー経由でBedrock出力を公開します。ポートが使用中または利用不可の場合、コンソールに複数行の [ERROR] ブロックが表示されます。修正：

  • config.yml で selfHostPort を別の正の値に設定します。
  • または networkHttpOffset-v2 を変更して、自動導出されるポートを衝突から離します（例：RCONが mcPort + 1？ 2か3に設定します）。プロキシを合わせて更新する必要はありません：バックエンドが正常にバインドすると、実際のHTTPポートをプロキシに自動通知するため、プロキシ自身の network-http-offset-v2 は通知前の推測としてのみ意味を持ちます。

バックエンドのHTTPサーバーがダウンしている間は、このバックエンドのBedrockパックは直接取得ではプロキシに届きません。magmaguy.com のリレーフォールバックは引き続き動作します（バックエンドがファイルをリレーにプッシュし、プロキシはそこ経由で取得します）。

古い v1 設定のクリーンアップ​

RSPM v1からアップグレードするオペレーターは、config.yml に死んだ networkHttpOffset（-v2 なし）キーが残っているかもしれません。RSPM v2は意図的に古いキーを読みません — 次回起動時にv2の既定値（1）が自動的に設定に書き込まれます。死んだv1キーは無害な遺物として設定ファイルに残るので、手動でクリーンアップしてください。