Java から Bedrock への変換

ResourcePackManagerは、マージしたJavaリソースパックをBedrockリソースパックに変換し、対応するカスタムコンテンツをGeyserMCクライアントに表示できます。この機能は既定で有効です。

変換が走る条件

変換はBedrockターゲットの存在によってゲートされます。RSPMは、次のいずれかが真であればターゲットが存在するとみなします：

1. このバックエンドにGeyser-Spigotがインストールされている（BedrockプレイヤーはローカルのGeyserに接続します）。
2. このバックエンドにFloodgateがインストールされている（典型的なプロキシ＋バックエンド構成 — Floodgateはローカルで動作し、Geyserは別の場所にあります）。
3. ネットワークモードが有効 — RSPMがVelocity／BungeeCordプロキシの背後にあることを検出しています。バックエンドはBedrockパックを生成し、小さなHTTPサーバー経由でプロキシプラグインから取得できるように公開します。

さらに、bedrockConversionEnabled で変換を有効にする必要があります。無効の場合や対象がない場合、RSPMは以前のBedrock出力の公開を取り消し、変換を省略します。パックが生成されない理由は /rspm status で確認できます。

変換される対象

コンバーターはネームスペース非依存です。1.21.4以降のアイテム定義形式である assets/<namespace>/items/**/*.json ファイルを、minecraft ネームスペースも含めて再帰的にすべて走査します。

フラットと3Dの振り分け

コンバーターは各リーフモデルについて2つのパイプラインのどちらを使うかを決定します。minecraft:item/generated または minecraft:builtin/generated を親に持つモデルはフラット経路にとどまります。それ以外の親チェーンでは、マージされたモデルが空でない elements 配列を持つ場合にのみ3Dパイプラインに進みます。ジオメトリを持たないモデルは2Dスプライトです。

• フラット：モデルの layer0 テクスチャを textures/items/<hash>.png にコピーし、Geyserのアイコンとして登録します。Bedrockはこのレイヤーをインベントリと手持ちの2Dスプライトに使います。Javaの追加レイヤーや任意のモデル分岐まで保持する機能ではありません。
• 3D — コンバーターはテクスチャアトラスを合成し、Javaの直方体をBedrockのジオメトリに変換し、hold／headアニメーションを生成し、64×64のインベントリアイコンをソフトウェアレンダリングし、(モデル × ベースアイテム × アイテム定義 × 述語形状) のマッピングごとにアタッチャブルを1つ書き出します。

ジオメトリのチェックが重要な理由：フラットな手持ち道具（親が minecraft:item/handheld で、layer0 テクスチャのみを持ち elements がないもの）も2Dスプライトです。以前のバージョンはフラットな手持ちアイテムを3Dパイプラインに送っていたため、ジオメトリのステップで失敗し、Bedrockでアイテムが消えるか、バニラのベースアイテムのアイコンにフォールバックしていました。これは特に、フラットな手持ちアイテムを多数同梱するItemsAdderのパックに影響していました。elements はマージ済みの親チェーンから読み取られるため、親からジオメトリを継承する非generatedのモデルは引き続き3Dに振り分けられます。

RSPMは (モデル × ベースアイテム × アイテム定義 × 述語形状) ごとにBedrock識別子を導出します。これにより、剣モデルのベースアイテムや述語ごとの種類を分け、1つのモデルを再利用する2つのアイテム定義にも別々の識別子を割り当てます。生成ファイル名にはファイル内容ではなく元の識別子の短いハッシュを使い、80文字以上のパックパスに対するGeyserの警告を避けます。

対応するアイテムモデル分岐

変換は model、condition、range_dispatch、select に対応します。minecraft: 接頭辞の有無は問いません。composite や special などの他のノードは省略されます。Javaで正しく表示できるパックでも、すべての分岐をBedrockで再現できるとは限りません。

ノード	対応するプロパティと代替動作
condition	broken、damaged、fishing_rod_cast、has_component、custom_model_data。using_item は待機モデルとして on_false だけを残します。その他の非対応条件は両方の分岐を省略します。
range_dispatch	damage、count、bundle_fullness、custom_model_data。use_duration などの非対応プロパティは、存在する場合に fallback だけを残します。
select	charge_type、trim_material、context_dimension、custom_model_data。display_context は gui のケースを残し、それがなければ代替を使います。その他の非対応プロパティは代替だけを残します。

Javaの弓を引く段階や表示状況ごとのモデルは、自動では保持されません。bedrockConverterDebug を有効にして省略されたノードやプロパティを確認し、Bedrockクライアントで実際のアイテムを確認してください。

1.21.4より前のレガシーパック

旧形式のスキャナーは assets/minecraft/models/item/ 直下のJSONを読み、数値の predicate.custom_model_data を持つオーバーライドからレンジディスパッチ定義を作ります。旧形式のサブフォルダーは再帰走査せず、オーバーライドの他の述語も保持しません。弓を引く状態にも依存するオーバーライドなら、その条件は失われます。旧形式のアイテム数は bedrockConverterDebug が有効な場合だけ表示されます。保守するパックには1.21.4以降のアイテム定義形式を使い、その分岐を上の対応表と照合してください。

ベースアイテム

Geyserは各カスタムアイテムを1つ以上のJavaのベースアイテムに対応付けます。RSPMは次のようにベースアイテムを選びます：

• レガシーのオーバーライドファイルと、ルートの assets/minecraft/items/<item>.json 定義は、そのバニラアイテムに対応付けられます。
• それ以外の定義はファイル名で照合されます。武器や道具の単語は関連するバニラアイテムに対応付けられます：sword は6種類の剣、pickaxe は6種類のツルハシ、wand や staff は minecraft:stick、spear は minecraft:trident などです。防具の名前には、ネームスペースの装備ファイルか、helmet や boots などのスロットを表す単語を使います。それ以外はフォールバックの組み合わせ（紙、棒、名札、コンパス、6種類の剣）を使います。
• freeminecraftmodels ネームスペースの定義は、FreeMinecraftModelsがモデルのボーン表示に使うアイテムである minecraft:leather_horse_armor にも対応付けられます。
• 提供元のプラグインは、assets/<namespace>/rspm_item_bases/<path>.json で実際のベースアイテムを宣言できます。<path> は items/<path>.json に対応します。ファイルの内容は {"base_items": ["minecraft:blaze_rod"]} です。読み取られるのは minecraft: のIDだけで、ファイル名による選択に追加されます。FreeMinecraftModelsは、設定で素材を指定している各カスタムアイテムについてこのファイルを書き出すため、BLAZE_ROD を使うワンドはBedrockでもそのモデルが表示されます。

Java専用アイテム

提供元のプラグインは、assets/<namespace>/rspm_item_java_only/<path>.json にファイルを置くことで、アイテムを変換の対象外にできます。重要なのはファイルの存在だけです。items/<path>.json と items/<path>/ 以下のすべてのアイテム定義が除外され、それらのアイテムにはGeyserのマッピング、アイコン、アタッチャブルが作られません。FreeMinecraftModelsは、Javaのアイテムディスプレイだけが使うパーティクルエフェクト用のスプライトアイテムにこれを使います。Bedrockプレイヤーにはネイティブのパーティクルが表示されます。すべてのアイテムがJava専用のパックでは、レガシー形式の警告は出ません。

手書きのBedrockエンティティバンドル

プラグインはJavaパックの assets/<namespace>/rspm_bedrock_pack/ にネイティブのBedrockエンティティ素材を同梱できます。RSPMはそれを生成パックに取り込みます。許可されるのは entity、models/entity、animations、animation_controllers、render_controllers、materials、particles、textures/entity のみで、マニフェストやアイコンアトラスは置き換えられません。対応する80文字以上のパスを短縮し、同じバンドル内で完全一致するJSONのパス参照を更新します。それ以外は提供されたままコピーします。2つのネームスペースが同じ出力先に異なるバイト列を生成すると、エラーになります。

これが真のカスタムBedrockエンティティを支える仕組みです — Geyser拡張とカスタムエンティティを参照してください。エンティティバンドルのみを含み、アイテムマッピングが1つもないパックでも出荷されます。

装備した防具の変換は、ベースが防具かエリトラであるフラットアイテムの経路で行います。アイテム定義のファイル名から認識可能なスロット接尾辞を除いて <material> を求め、リーフモデルのネームスペースで assets/<namespace>/equipment/<material>.json を探します。humanoid、脚防具の humanoid_leggings、またはエリトラで存在する場合の wings から、最初のテクスチャレイヤーを使います。対応するPNGがマージ済みパックに必要です。生成されるアタッチャブルはBedrockのバニラ防具ジオメトリを使います。装備ファイルだけ、追加のテクスチャレイヤー、または無関係な装備アセットIDでは変換できると判断できません。

Bedrockパックのマニフェストのヘッダー／モジュールUUIDは、プラグインのバージョン文字列から決定論的に導出されます（シードは rspm_bedrock_header:<pluginVersion> と rspm_bedrock_module:<pluginVersion>）。そのため、同じプラグインバージョンの再構築をまたいでも安定し、プラグインバージョンが変わったときだけ変化します。表示されるヘッダー名は固定の ResourcePackManager Bedrock Pack で、UUIDの一部にはなりません。バージョントリプレットは、ステージングされたBedrockパックのSHA-256コンテンツダイジェストから導出されたキャッシュバスト用トークンに基づき、ビルドごとにバンプされます — 内容が同一なら同じバージョンになり（何も変わらない再構築でGeyserのキャッシュが無駄に更新されません）、内容が実際に変われば、Bedrockの (uuid, version) をキーとするパックキャッシュが無効化されます。ビルド時刻（System.currentTimeMillis()）は、コンテンツダイジェストを計算できないときのフォールバックとしてのみ使われます。

セッション単位のライブ配信（スタンドアロン）

変換が有効で、同じスタンドアロンのバックエンドにGeyser-Spigotがある場合、RSPMは SessionLoadResourcePacksEvent を購読します。参加する各プレイヤーに、最新の公開が許可されたBedrockパックをディスクから提示します。登録済みのマッピングが変わらなければ、テクスチャやジオメトリの編集はサーバーを再起動せず次の参加で届きます。ネットワークモードのバックエンドでは、ローカルにGeyser-Spigotがあっても配信はプロキシに任せます。

Geyserのカスタムアイテムマッピングである custom_mappings/ のJSONは、起動時に固定されます。アイテムの追加や削除、モデル参照や述語の変更には、新しいマッピングと再起動が必要になる場合があります。自動配置が有効なら、RSPMは前回の公開が許可されたマッピングファイルを起動の早い段階で配置します。初回の変換が成功したらGeyserを再起動して新しいマッピングを読み込み、Bedrockクライアントを再接続してください。

すでに接続中のBedrockプレイヤーは、自分が参加した時点で受け取ったパックをそのまま保持します。これはプラグインがセッション途中で上書きできるものではなく、Bedrockプロトコルの制約です。

プロキシモードでの仕組み

プロキシネットワークでは、バックエンド自身は SessionLoadResourcePacks のサブスクライバーを登録しません（購読すべきローカルのGeyserがないため）。代わりに：

1. バックエンドは output/ResourcePackManager_Bedrock.zip を生成し、アイテムマッピングが存在する場合は output/rspm_geyser_mappings.json も生成します。
2. バックエンドは小さなHTTPサーバー（自動導出されるポート、既定は mcPort + 1）を起動し、リクエストごとにファイルを新しく読む /bedrock.zip と /mappings.json ルートを公開し、実際にバインドした正確なポートをプロキシに通知します。
3. プロキシプラグインは5秒ごとにポーリングし、If-None-Match による強いETagを優先しつつ、古いバックエンドとの互換性のために If-Modified-Since も維持します。変更があった場合は各バックエンドの出力をダウンロードし、インボックスが安定するのを待ちます。
4. プロキシプラグインはすべてのバックエンドのBedrockパックを1つのネットワーク全体パックにマージし、プロキシのGeyserを通じてBedrockクライアントに配信します。
5. プロキシがバックエンドのHTTPポートに直接到達できない場合（共有／マネージドホスティングで隣接ポートがファイアウォールで遮断されているケースなど）、バックエンドはファイルを magmaguy.com のリレーエンドポイントにプッシュし、プロキシはそこ経由でファイルを取得します。

セットアップはプロキシネットワークを参照してください。プロキシ側のマージは自動で、有効化のトグルはありません。プロキシの設定にはちょうど2つの項目しかありません：バックエンドのエンドポイント通知が利用できるようになる前に使われるフォールバックのポートオフセット network-http-offset-v2 と、geyserExtensionAutoInstall のプロキシ側に相当する geyser-extension-auto-install です。

出力ファイル

ミックスが成功すると、Bedrock関連のファイルは次の場所に置かれます：

plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip
plugins/ResourcePackManager/output/rspm_geyser_mappings.json  # only when item mappings exist

自動デプロイが有効で、ローカルのGeyserデータフォルダーが検出された場合、マッピングファイルは次の場所にもコピーされます：

<geyser-folder>/custom_mappings/rspm_geyser_mappings.json

Bedrockパックのzipは <geyser-folder>/packs/ にはコピーされず、代わりにセッション単位でライブ配信されます。古いRSPMのリリースがGeyserのパックディレクトリに ResourcePackManager_Bedrock.zip を残していた場合でも、現在のプラグインはGeyserの実行中にそれを削除しません：Geyserはすでにそのパスをスキャン済みで、メモリ上に保持している可能性があるためです。RSPMはその起動についてはライブプロバイダーの登録をスキップし、レガシーファイルの正確なパスを出力します。サーバーを完全に停止し、そのレガシーファイルだけを削除してから、サーバーを再起動してください。/reload では不十分です。

変換可能なマッピングも許可されたエンティティファイルもない場合、RSPMは公開を取り消し、以前のローカル出力とGeyserに配置したマッピングの削除を試みます。ロックされて残ったファイルも配信対象にはなりません。バックエンドの /bedrock.zip は404を返し、提供するBedrockコンテンツがないことを示します。エンティティのみのパックは引き続き公開します。Javaのブロックやバニラのテクスチャを置き換えただけでは変換パックは生成されず、別途作成したBedrockパックが必要です。

bedrockAutoDeployToGeyser を無効にすると、設定との照合時にRSPMが以前配置したマッピングを削除します。bedrockGeyserFolder の変更でも、RSPMが管理していた以前の配置先を整理します。どちらも実行中のGeyserが読み込んだマッピングは変更しません。新しいマッピング一式を反映するにはGeyserを再起動してください。

config.yml 設定

# Toggles Java-to-Bedrock conversion altogether.
bedrockConversionEnabled: true

# Copies the Geyser custom mappings file into the detected Geyser folder's
# custom_mappings/ directory on each mix.
bedrockAutoDeployToGeyser: true

# Manual override for the Geyser data folder. Empty = auto-detect.
# Relative values are tried from the server working directory first, then
# relative to plugins/. Absolute paths work directly.
bedrockGeyserFolder: ""

# Installs and updates the universal ResourcePackManager.jar in Geyser's
# extensions/ folder, which is what makes custom Bedrock ENTITIES render
# instead of armor stands. Separate from pack conversion above — items,
# textures and models convert and serve normally either way.
# Setting this false stops future installation and update staging; it does NOT
# remove an extension jar that is already installed. Delete that by hand while
# Geyser is stopped. See the Geyser extension page.
geyserExtensionAutoInstall: true

# Verbose per-item / per-bone progress logging from the Bedrock pipeline.
# Default false — a clean run emits a single "Bedrock conversion complete: N
# mappings" summary instead of dozens to hundreds of per-item lines. Flip on
# when debugging a specific conversion issue.
bedrockConverterDebug: false

Geyserフォルダーの自動検出は次の順序で確認します：

1. bedrockGeyserFolder が設定されていればそれを使用（まず書かれたとおりに扱うため、相対パスはサーバーの作業ディレクトリから解決されます。そこに存在しない場合は plugins/ からの相対パスとして試されます）。絶対パスもそのまま動作します。
2. plugins/Geyser-Spigot/
3. plugins/Geyser-*/（任意の派生）
4. config/Geyser-*/（Fabric／NeoForge構成向け）

手持ちアイテムのポーズ

各3Dアタッチャブルには、一人称、三人称、頭のアニメーションが作られます。手持ちのポーズは、Javaモデルの display.firstperson_righthand と display.thirdperson_righthand のトランスフォームから作られます。RSPMは各トランスフォームをバニラのBedrockプレイヤーリグに沿って変換するため、手持ちのモデルは、Javaで描画されるのと同じ位置、向き、軸ごとのスケールで配置されます。モデルが定義していないスロットには、Javaの恒等トランスフォームが使われます。頭のアニメーションは display.head から作られます。

調整する項目はありません。手の中でのアイテムの位置を変えるには、Javaモデルの display トランスフォームを変更してください。JavaとBedrockの両方が同じ値に従います。リグは太い腕（Steve）を使うため、細い腕のスキンではBedrockとJavaで半ピクセルずれることがあります。

以前のバージョンでは、plugins/ResourcePackManager/bedrock_display_offsets.yml の手動調整したオフセットを加えていました。このファイルと、その firstPerson* および thirdPerson* の設定は現在読み込まれず、RSPMは更新後にキャッシュされたBedrockパックを再生成します。古いファイルは削除してかまいません。

手持ちアイテムのパーティクル

提供元のプラグインは、assets/<namespace>/rspm_item_particles/<model path>.json のサイドカーを使って、手持ちの3Dアイテムにパーティクルを付けられます。<model path> は手持ちのJavaモデルのパスです（freeminecraftmodels:display/wand なら display/wand）。サイドカーは、エフェクト名をプラグインがエンティティバンドルに同梱するパーティクル識別子に対応付け、ロケーターをJavaモデルのピクセル単位で列挙し、ループするパーティクルのタイムラインを保持します。RSPMはロケーターをアイテムのジオメトリに追加し、タイムラインを追加のアタッチャブルアニメーションとして再生するため、Bedrockクライアントは一人称と三人称の両方で手の位置にパーティクルを描画します。FreeMinecraftModelsは、パーティクルエフェクトを持つアイテムについてこのサイドカーを書き出します。読み取れないサイドカーは警告を出してスキップされます。

デバッグログ

2種類のデバッグ出力が利用できます：

• バックエンド：config.yml で bedrockConverterDebug: true にすると、コンバーターからアイテム単位／アタッチャブル単位／マッピング単位のログ行が有効になります。特定のアイテムがBedrockパックに入らなかった理由を知りたいときに便利です。これは verboseLogging とは別物です。verboseLogging はBedrockパイプラインではなくパックのマージとホスティングを対象とします — 変換の問題を追いたいときは bedrockConverterDebug を使ってください。
• プロキシ（VelocityとBungeeCord）：/rspm debug bedrock on でプロキシの GeyserBinder が出力する [RSPM-BedrockDebug] ログストリームを切り替えます。Bedrockプレイヤーがプロキシに参加してもパックが見えない場合の調査に便利です。設定はプロキシ再起動でオフにリセットされるため、誤って付けっぱなしになることはありません。

制限事項と既知の挙動

• 3DのインベントリアイコンはJavaモデルの display.gui トランスフォームからソフトウェアレンダリングされます。仕上がりはおおむね妥当ですが、ピクセル単位で完全とは限りません。アイコンがおかしい場合、もっとも多い原因はモデルが参照しているテクスチャファイルの欠落や名前の食い違いです。
• アイテムアイコンとして使用されるフリップブックテクスチャはフレーム0にトリミングされます。Bedrockの item_texture.json はアニメーションするアイコンに対応しておらず、アニメーションは flipbook_textures.json 経由でブロック／地形テクスチャにのみ使えます。
• アタッチャブルのジオメトリフォーマットバージョンは 1.21.0 に固定されています。インストール環境がそれを解析できない場合はGeyserを更新してください。
• レガシーなバニラのアイテムモデルオーバーライドファイル（assets/minecraft/models/item/ 配下のすべて。shield.json と crossbow.json を含む）は、1つのパックに完全に勝たせるのではなく、パックをまたいでマージされます。overrides 配列のみが結合され（オーバーライドキーで重複排除）、オーバーライド以外のフィールドは引き続き優先度の高いパックが勝ちます。特別扱いされるファイルは1つもありません。
• 参照されているテクスチャやモデルファイルをコンバーターが解決できない場合、そのリーフはスキップされ、残りのパイプラインはそのまま継続します。詳細な解決トレースが必要なら bedrockConverterDebug を有効にしてください。アイテムに有効なカスタムテクスチャが1つも残らなかった場合や、参照されたモデルJSONを解析できなかった場合には、通常の警告が出力されます。
• 解析できないアイテム定義JSONは Bedrock conversion failed: ... で変換を中断します。一方、有効なJSONでもモデルがない場合や非対応ノードの場合は、デバッグログを出して省略されることがあります。省略された定義をすべて致命的な解析エラーと考えず、エラー内容と生成されたマッピング数を確認してください。
• バナーとレッドストーンのベースアイテムはスキップされます。 ベースが16色の染色バナーのいずれか、または minecraft:redstone であるカスタムアイテムには、Geyserのカスタムアイテムマッピングが付与されません。Geyserがそれらのベースから不正なブロックプレーサーを導出してしまうためです。Bedrockではバニラのアイコンが表示されます。この状況が発生した場合、コンソールが該当するアイテムを列挙します。
• 変換は協調的なキャンセルに対応します。RSPMはZIPとマッピングを準備し、公開する一式を置き換えます。置き換え中の失敗やキャンセルでは以前の一式の復元を試み、置き換え前の変換失敗では旧出力の公開を取り消します。公開されたハッシュと世代メタデータにより、受信側は古い世代や混在した世代を拒否できます。ディスクにZIPがあるだけでは、現在の公開が許可されていることやBedrockクライアントで描画されたことの証明にはなりません。
• 変換可能なマッピングも許可されたエンティティファイルもない場合、RSPMは以前の公開を取り消し、出力の削除を試みます。エンティティのみのパックはアイテムマッピングがゼロでも生成します。

パックサイズの最適化

Bedrockパックを公開する前に、RSPMは同じ拡張子を持つバイト単位で同一のテクスチャファイルを重複排除し、JSON内のテクスチャ参照のうち完全一致するものを残されたファイルへ書き換えます。参照が曖昧な場合、より大きな文字列に埋め込まれている場合、あるいは不正／不透明なJSONに含まれる場合は、意図的にエイリアスを残します。これにより、最適化がリソース参照を静かに壊すことはありません。