プロキシネットワーク（BungeeCord／Waterfall／Velocity）
ResourcePackManagerはプロキシネットワークで動作します。jarは1つだけ（ResourcePackManager.jar）で、すべてのバックエンドとプロキシに同じjarをインストールします。バックエンド上ではバックエンドの役割（マージ、ホスト、プッシュ、変換）で動作し、VelocityまたはBungeeCord／Waterfallプロキシ上では同じjarがプラットフォームローダーを自動検出してプロキシの役割（ネットワーク側のBedrock配信）で動作します。両者は共有された plugins/floodgate/key.pem ファイルを介して自動的に互いを認識します — 別々のプロキシ用jarも、展開するプロキシ拡張も、貼り付けるキーもありません。
このページ全体で「プロキシプラグイン」とは、プロキシの役割で動作しているその同じ ResourcePackManager.jar を指す略語です。
プロキシプラグインの役割
プロキシプラグインの仕事は、Bedrockパックのマージと配信です。複数のバックエンドがあるネットワークでは、各バックエンドが独自のBedrockパック（マージされたJavaパックの変換版）を生成します。プロキシプラグインは：
- 各バックエンドの小さなHTTPサーバーから
/bedrock.zipと/mappings.jsonを5秒ごとにポーリングします。If-Modified-Sinceを使うため、変更のないファイルの帯域コストはほぼゼロです。各バックエンドは実際にバインドした正確なHTTPポートを通知するため、プロキシは通常そのポートに自動的にヒットします（バックエンドのHTTPポート解決を参照）。 - インボックスの状態が安定するのを待ちます — 連続する2回のポーリングが同じファイルハッシュの集合を観測した時点でマージします。
- すべてのバックエンドのBedrockパックを1つのネットワーク全体パックにマージします。
- マージされたGeyserカスタムマッピングファイルをプロキシの
plugins/Geyser-*/custom_mappings/にコピーします。 - 接続時にGeyserの
SessionLoadResourcePacksEventを通じてマージされたパックをBedrockクライアントに配信します。
プロキシプラグインはBedrockプレイヤーにのみ有用です。 ネットワーク上のJavaパック配信は、依然として通常の setResourcePack ／ addResourcePack API を通じてバックエンドごとに行われます — Javaクライアントには、接続中のバックエンドが送ることを選んだパックが表示されます。ネットワークがJava専用なら、プロキシプラグインは不要です。
セットアップ — 2ステップ
ステップ1：プロキシとすべてのバックエンドにFloodgateをインストールする
Bedrockプレイヤーがプロキシで認証するためにFloodgateが必要です。RSPMはFloodgateの plugins/floodgate/key.pem に乗ってネットワークアイデンティティを導出します — そのファイルはプロキシとすべてのバックエンドでバイト単位で同一でなければなりません。FloodgateはBedrock認証のためにこれを既に要求しているので、現在Bedrockプレイヤーがネットワーク全体で動作しているなら、これはすでに完了しています。
まだFloodgateがない場合は、各コンポーネントにインストールし、続行する前に1つの正本 key.pem を他のすべてのコンポーネントにコピーしてください。
ステップ2：ResourcePackManager.jar をプロキシにコピーする
jarは1つだけです。Bukkit／Paperバックエンドにインストールするのと同じ ResourcePackManager.jar が、そのままプロキシプラグインでもあります — VelocityとBungeeCord／Waterfallの実装が1つのシェードされたjarにまとめられており、実行中のプラットフォームを自動検出します。展開すべきプラットフォーム別のプロキシ用jarはありません。
同じ ResourcePackManager.jar をプロキシの plugins/ フォルダーにコピーしてください：
| プロキシソフトウェア | 使用するjar |
|---|---|
| Velocity | ResourcePackManager.jar |
| BungeeCord | ResourcePackManager.jar |
| Waterfall（Bungeeフォーク） | ResourcePackManager.jar |
これはいつでもバックエンドから /rspm status を実行して確認できます。Proxy deployment セクションに Network proxy jar: ResourcePackManager.jar と Use the same jar on Bukkit/Paper, Velocity, and BungeeCord/Waterfall. が表示されます。
プロキシを再起動します。これだけです。
編集すべき設定もなく、貼り付けるべきキーもありません。プロキシプラグインは起動時にプロキシ上の plugins/floodgate/key.pem を読み、そこからネットワークアイデンティティを導出します。Floodgateはそのファイルがすべてのバックエンドとプロキシで同じであることを既に要求しているため、導出されたキーは各バックエンドのものと自動的に一致します。
プロキシの最初のポーリングは起動の約2秒後に発火し、その後は5秒ごとです。単一サイクルの安定性ゲートと組み合わせると、最初のマージは、プロキシが既にコンテンツを生成している少なくとも1つのバックエンドを見ることができるようになってから約7秒後に公開されます。
動作確認
プロキシコンソール
再起動から ~10 秒以内（バックエンドが起動中であると仮定）に、次のような出力が見えるはずです：
[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)
プロキシでの /rspm status
スナップショットを表示します：バックエンド一覧、バックエンドごと／パスごとの取得結果（200／304／404／CONNECT_FAILED）、連続空ポーリングカウンター、現在のマージ済みパックのパスとサイズ、network-http-offset、プロキシでのFloodgate／Geyserの有無。resourcepackmanager.command.status または resourcepackmanager.* が必要です。コンソールは常に両方を持ちます。プレイヤーに実行させたい場合は、権限プラグイン経由でいずれかを付与してください。出力には秘密情報が現れない（ネットワークキーはマスクされ、認証トークンもありません）ため、寛容に付与しても安全です。
バックエンドでの /rspm status
Deploy mode 行が network-backend になっているはずです。Network key 行にはマスクされたキー（末尾4文字が見える）が表示されます — それをプロキシのマスクされたキーと突き合わせて、両側が一致しているか確認してください。
Bedrockクライアント
Bedrockで接続します。ワールドに到達する前にリソースパックのダウンロードプロンプトが表示されるはずです。カスタムアイテムは、ただのアーマースタンドではなく意図したモデルで描画されます。
設定リファレンス
バックエンド plugins/ResourcePackManager/config.yml
ネットワークモードは自動検出されます — networkMode: true のようなフラグを設定する必要はありません。検出シグナル（いずれか1つで十分）：
- Floodgateが存在し、Geyser-Spigotが存在しない — Bedrock-via-proxyケースの最強シグナルです。
spigot.yml: settings.bungeecord: true— 旧来のBungeeCord／Waterfall IP転送スイッチです。paper-global.yml: proxies.velocity.enabled: true— モダンなVelocity転送です。
ネットワークモード固有で重要な唯一のつまみは networkHttpOffset-v2 で、プロキシが各バックエンドでポーリングするフォールバックHTTPポート（バックエンドが実際にバインドしたポートを通知する前にプロキシが推測するポート）を制御します。既定 1 は事実上すべてのホスティングで動作します。完全なポート解決の話はセルフホストを参照してください。
通常の運用では、各バックエンドが自身の本物のHTTPポートをプロキシに自動通知する（magmaguy.com のエンドポイントレジストリ経由）ため、オフセットは起動時／失敗時のフォールバックとしてのみ参照されます。下記のバックエンドのHTTPポート解決を参照してください。
プロキシ plugins/ResourcePackManager/config.yml
プロキシプラグインは初回起動時に最小限の既定設定を書き出します：
# クライアントにパックの受け入れを強制する（拒否したらキック）。既定: false。
force-resource-pack: false
# そのバックエンドが本物の ResourcePackManager HTTP ポートを通知する前に、
# このプロキシが /bedrock.zip と /mappings.json をヒットするHTTPポートを導出するため、
# 各バックエンドの Minecraft ポートに加算する「フォールバック」オフセット。既定 1。
# 通常の運用ではバックエンドがバインドした正確なポートを通知するため、
# この値は起動時または通知が失敗した場合にのみ使われます — ただし使われる場合は、
# 各バックエンドの networkHttpOffset-v2 と一致させる必要があります。
network-http-offset-v2: 1
network-key エントリは意図的にありません — それは手動貼り付けが誤設定（タイポでサイレントにプロキシ↔バックエンドのリンクが壊れる）の主原因だったため、プレリリース段階で廃止されました。キーは plugins/floodgate/key.pem から自動導出されます。
バックエンドのHTTPポート解決
プロキシは、各バックエンドで /bedrock.zip と /mappings.json をポーリングするためにどのHTTPポートを使えばよいかを知る必要があります。プロキシはそのポートを次の順序で解決します：
- バックエンドが通知したエンドポイント（優先）。 各バックエンドは、実際にバインドした正確なHTTPポートを、ネットワークキーをキーとして magmaguy.com のエンドポイントレジストリにアップロードします。ポーリングのたびに、プロキシはこのリストを更新し、バックエンドが通知したポートを、Minecraftポート（および利用可能な場合はホスト）でサーバーリストのエントリと突き合わせます。これは、バックエンドに明示的な
selfHostPortを設定した管理者も、バックエンドが自動的にmcPort + 1に着地する場合も、同一に扱われることを意味します — プロキシはバックエンドが実際にバインドしたものをそのまま使います。 mcPort + network-http-offset-v2（フォールバック）。 一致する通知が利用できない場合（例：どのバックエンドもまだ通知していない最初のポーリング、またはエンドポイントレジストリが一時的に到達不能）にのみ使われます。これが、フォールバックに依存する場合に2つのオフセットを一致させておくべき理由です。
プロキシは意図的にバックエンドをポートスキャンしません — それはホストにとって不正な振る舞いに見えるためです。直接取得がまったく機能しない場合、リレー経路（下記）が決定的な答えになります。
プロキシでの /rspm status は、バックエンドごとに、どのポートが選ばれたか、そしてそれが通知由来かオフセットフォールバック由来かを表示します。
安定性とマージのケイデンス
プロキシはマージ前に、インボックスの状態が安定するのを待ちます：最初のポーリングがファイルハッシュ集合のベースラインを設定し、同じ集合を観測する次のポーリングがマージをトリガーします（1サイクルの安定性ゲート）。約2秒の初期遅延と5秒のポーリング間隔により、最初のマージはプロキシが少なくとも1つのバックエンドがコンテンツを生成しているのを見ることができるようになってから約7秒後になります。それ以降のマージは、インボックスファイルのSHA-1集合が変わったときだけ再ZIP化されるので、長い静寂期間のコストはほぼゼロです。
バックエンドは bedrock.zip を一時ファイルに書き込んでからアトミックにリネームするため、/bedrock.zip ルートは常に完全なzipを提供します — プロキシは書き込み途中の読み取りを防御する必要がなく、これがゲートが2サイクルではなく1サイクルである理由です。
直接取得 vs リレーフォールバック
既定の経路は直接取得です：プロキシは各バックエンドに対して http://<backend-host>:<mcPort + offset><path> にHTTP GETを行います。
プロキシがバックエンドのHTTPポートに直接到達できない場合（共有／マネージドのMinecraftホスティングでMCポートは公開されているが隣接ポートはファイアウォール越し、というケースが典型）、バックエンドは自分の bedrock.zip と mappings.json を、ネットワークのネームスペース下（Floodgateキーから導出される）にある magmaguy.com のリレーエンドポイントにプッシュします。直接取得がハード失敗したとき、プロキシはリレーを一覧してダウンロードします。
両方の経路が同じマージステップにフィードされるため、オペレーターが選ぶ必要はありません — 直接取得が優先（magmaguy.com への帯域コストゼロ）で、必要なときにリレーが透過的に動作します。
リレーのサーバー側TTLは30分です。バックエンドはエントリを生かしておくため25分ごとにプッシュします。クリーンシャットダウンではTTLを待たずに即座にエントリを落とします。
よくある問題のトラブルシューティング
プロキシ起動時に「Floodgate key.pem missing」と表示される
プロキシプラグインが plugins/floodgate/key.pem を見つけられず、アイドル状態になりました。RSPMはそれなしではどのバックエンドにもリンクできません。
修正：プロキシにFloodgateをインストールし、プロキシの plugins/floodgate/key.pem がすべてのバックエンドの同名ファイルとバイト単位で同一であることを確認してください。Floodgateは既定でインストールごとに異なるキーを自動生成するため — 任意のバックエンドから1つの正本 key.pem を他のすべてのコンポーネントにコピーし、すべてを再起動してください。
~20秒後に「No merged pack content」警告が出る
連続4回の空ポーリングサイクルの後、プロキシはポーリングしたすべてのバックエンド、試行したURL、結果を列挙する1回限りの複数行警告をログ出力します。警告は最もよくある修正方法を説明します：
- すべてのバックエンドで
CONNECT_FAILED— プロキシがバックエンドのHTTPポートにまったく到達できません。velocity.toml／config.ymlのアドレスがプロキシから実際に到達可能なもの（プロキシのネットワークから解決できないDockerの内部名ではない）であること、そしてバックエンドのHTTPポートがプロキシとバックエンド間で開いていることを確認してください。警告は、バックエンドごとに試行した正確なHTTPの host:port と、そのポートがバックエンドの通知由来かmcPort + networkHttpOffset-v2フォールバック由来かを表示します。そのポートを開く手段がない（マネージドホスティング）場合は、上記のリレーフォールバックセクションを参照してください — バックエンドが自動でリレーにアップロードしているはずです。 - すべてのバックエンドで
NOT_FOUND_404— バックエンドは起動していますが、Bedrockパックを生成していません。各バックエンドで/rspm statusを実行してください。Bedrock Packの診断ブロックが理由を教えてくれます（最も多いのは、マージされたパックにアイテム定義がない、または最初のミックスサイクルがまだ完了していない、です）。
警告は詰まった期間ごとに1回発火します。少なくとも1つのバックエンドがコンテンツを返し始めると NetworkSync: recovered 行がログに出力されます。
初回プロキシ起動時にBedrockプレイヤーにカスタムモデルが見えない
Geyserはプロキシ起動時にだけカスタムアイテムテーブルを登録します。Bedrockパックを生成したバックエンドより先にプロキシが起動した場合、Geyserは空のマッピングテーブルで動作し、そのセッションの残り時間ずっとそのままになります。
修正：バックエンドが最初の Merged Bedrock pack published 行をログに出した後、プロキシを一度再起動してください。RSPMはプロキシ起動のたびに前回実行時のマッピングを事前デプロイするので、これが噛むのは新規インストール時のみです — 以降の起動では、Geyserがスキャンする前に何かが用意されています。
起動時に「Duplicate bedrock_identifier」警告が出る
2つのバックエンドが同じベースアイテムに対して同じBedrock識別子を出力しました。後勝ち；そのアイテムを提供するバックエンドが1つだけでよいなら無害です。両方のバックエンドが同じベースアイテムで別々のカスタムアイテムをホストすべきなら、自動生成されるハッシュが異なるように、ソースとなるJavaモデルのいずれかをリネームしてください。
Bedrockプレイヤーが接続したのにパックが見えない
プロキシは、Bedrockセッションが使用可能なRSPMパックなしでロードされたとき、オンラインのすべてのJavaプレイヤーにチャットバナーを発火します：
⚠ [RSPM] Bedrock player Alice connected before the resource pack was ready — they're seeing plain armor stands instead of custom models. Tell them to disconnect and reconnect; the pack will load on their next session. (Cause: ...)
Bedrockプレイヤー自身もモーダルポップアップを受け取り、プロキシコンソールにもバナーが表示されます。さらに深く調査する必要がある場合は、デバッグストリームを有効にしてください（VelocityとBungeeCordの両方で利用可能）：
/rspm debug bedrock on
これは GeyserBinder からの詳細な [RSPM-BedrockDebug] ログ行をオンにします。問題を再現したら、オフにしてください：
/rspm debug bedrock off
設定はプロキシ再起動でオフにリセットされるため、誤って付けっぱなしになることはありません。
ネットワーク上でのRSPMの更新
バックエンドのRSPM jarをアップした後、同じ ResourcePackManager.jar をプロキシの plugins/ フォルダーにも再コピーし、プロキシを再起動してください。すべてのバックエンドとプロキシで同じjarなので、すべてのコンポーネントを同じバージョンに保ってください。
まだサポートされていないこと
- プロキシプラグイン経由でのネットワーク上のJavaパック。 Javaクライアントは、通常のAPIを通じて各バックエンドから直接パックを受け取ります。プロキシ側のJavaパックミキサーはありません。
- バックエンドをまたいだJavaパックマージ。 各バックエンドのJavaパックは独立しています。プレイヤーがバックエンドを切り替えると、新しいバックエンドのパックを受け取ります。
- ネットワークキーのライブ再構成。 キーはFloodgateの
key.pemに紐付いています。変更にはプロキシとすべてのバックエンドの再起動が必要です（これはFloodgateキーをローテーションするときに行うことと同じです）。