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

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

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

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

/rspm status

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

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

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

  • ResourcePackManagerに自動でURLをプッシュさせたいなら、autoHost を有効にしておく必要があります
  • マージされたパックが存在し、少なくとも1つの配信経路（セルフホストまたはリモート）が成功している必要があります
  • プレイヤーがパックを受け取るのは参加時か、ホスティングが準備できた瞬間に発火する最初のアップロードブロードキャストのときだけです

必要であれば：

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

自前の外部パイプラインでセルフホストしている場合（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 が残っているかを確認します。

クリーンに展開できなかったパックはスキップされ、その際にはコンソールに警告がログ出力されます。

リモート自動ホストから 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 を実行してください。

セルフホストの健全性チェックが失敗し、リモートホストにフォールバックする​

このメッセージは preferSelfHost: true（既定）で、3つのセルフホスト健全性チェックのいずれかが失敗したときの正常な挙動です：

  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と理由はログに記録されます。

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

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

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

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

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

https://magmaguy.com/rsp/

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

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

  1. サーバーの外向きHTTPS接続を修復する
  2. リモートサービスが再び到達可能になるのを待つ
  3. autoHost を無効にして、生成されたzipを自分でホストする
  4. HTTPポートを開けて preferSelfHost: true のままにし、magmaguy.com を一切必要としないセルフホストを使う（このシナリオでは、Layer 3の外部プローブが不要になるように selfHostExternalHost も公開ホスト名に設定してください — RSPMはプローブのIOExceptionでもセルフホストを維持します）

マージされたパックを自分の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

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

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 秒待つ）、スキャナーがマージされたパックにアイテム定義を1つも見つけられなかった、または変換が例外を投げたかです。コンソールで [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プレイヤーで持ち物アイテムが正しくない位置に表示される​

これは変換のバグではなく、調整の問題です。plugins/ResourcePackManager/bedrock_display_offsets.yml を開いて、該当する軸を調整してください。一人称と三人称は独立しているため、一方を調整しても他方には影響しません。Bedrockクライアントは再起動なしでアタッチャブルJSONをライブリロードするので、調整は素早く繰り返せます。各つまみの一覧と役割はBedrock変換を参照してください。

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

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

プロキシ：起動時に「Floodgate key.pem missing」と表示される​

プロキシプラグインがプロキシホスト上で plugins/floodgate/key.pem を見つけられず、アイドル状態になりました。RSPMはネットワークアイデンティティをこのファイルから導出するため、これがないとプロキシはどのバックエンドにもリンクできません。修正：

  1. プロキシにFloodgateをインストールします。BedrockプレイヤーがプロキシにアクセスするためにもFloodgateは必要なので、RSPMの有無にかかわらず必要なものです。
  2. プロキシの plugins/floodgate/key.pem がすべてのバックエンドの同名ファイルとバイト単位で同一であることを確認します。1つの正本 key.pem をすべてのコンポーネント（他のバックエンド＋プロキシ）にコピーして、すべてを再起動します。FloodgateはBedrock認証のためにこれを既に要求しているので、現在Bedrockプレイヤーがネットワーク全体で動作しているなら、これはすでに完了しています。

プロキシ：数回のポーリングサイクル後に「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は空のマッピングテーブルで動作し、そのセッションの残り時間ずっとそのままになります。

修正は、バックエンドが Wrote merged Geyser mappings: N entries をログに出した後でプロキシを再起動することです。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キーは無害な遺物として設定ファイルに残るので、手動でクリーンアップしてください。