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

Geyser拡張とカスタムBedrockエンティティ

パック変換は、対応するアイテムのテクスチャとモデルを提供します。独自の外見やアニメーションを持つボスなどのカスタムエンティティには、Geyser内で動くコードも必要です。RSPMのGeyser拡張は、対応する生成側プラグインとそのBedrockエンティティ素材を連携させます。

これは別途ダウンロードするものではありません。プラグインとしてインストールするのと同じ ResourcePackManager.jar が、そのまま拡張機能でもあります。

1つのJar、3つの役割​

ResourcePackManager.jar は同時に次の3つです：

  • Bukkit/Paperのバックエンドプラグイン
  • VelocityおよびBungeeCordのプロキシプラグイン
  • Geyser拡張

各ローダーは対応するエントリポイントを使います。以前は別の ResourcePackManager-GeyserBridge.jar を配布していましたが、現在は廃止されています。インストーラーがこのファイルを見つけると、再起動時の置き換え用に共通jarをGeyserの更新キューへ準備します。

インストールの仕組み​

RSPMは可能な場合に拡張を自動でインストールします。動作はGeyserがどこにあるかによって変わります：

構成RSPMの動作
同じサーバー上のGeyser-Spigot初回は実行中のjarを plugins/Geyser-Spigot/extensions/ResourcePackManager.jar にコピーします。既存jarのバイト列が異なる場合、ダウングレード防止を適用したうえで extensions/update/ に置き換え用ファイルを準備します。新規インストールや置き換え準備では再起動を求めるログが出ます。同一の現行jarはコピー不要です。
プロキシ上のGeyser（Geyser-Velocity / Geyser-BungeeCord）プロキシ側の役割が、プロキシの Geyser-*/extensions/ フォルダに対して同じ処理を行います。
Floodgateがローカル、Geyserが外部（Geyserが別プロセスで動作）plugins/ResourcePackManager/geyser-extension/ 以下にコピーを出力します。以前の出力があると update/ サブフォルダーを指す場合があるので、コンソールの正確なパスに従ってください。そのjarを外部Geyserの extensions/ にコピーして再起動します。拡張の出力だけでは、外部へのパック配信や起動時の定義読み込みは設定されません。
GeyserもFloodgateも存在しない何もすることがありません — RSPMは情報行をログに出し、インストールをスキップします。

インストーラーは、インストール済み共通jar、旧ブリッジjar、準備済み更新の中にある、より新しい有効なバージョンを保持します。バージョンに加えてチェックサムも比較するため、同じバージョンでもバイト列が変われば置き換えが必要になる場合があります。

インストールには必ず一度の再起動が必要です。 Geyserは起動時に拡張を読み込むため、コピーまたはステージングされたばかりのjarは、サーバーまたはプロキシが再起動するまで何も行いません。

自動インストールをオフにする​

役割ごとに独立したスイッチがあります：

場所設定既定
バックエンド plugins/ResourcePackManager/config.ymlgeyserExtensionAutoInstalltrue
プロキシ config.ymlgeyser-extension-auto-installtrue

どちらかを false にすると、その役割は拡張のインストールや更新のステージングを行わなくなり、その旨をログに出力します。意味を正確に読み取ってください：

  • 今後のインストールと更新のステージングを防ぎます。
  • インストール済みjarは削除せず、準備済みの更新も取り消しません。ブリッジを無効化するには、該当設定を false にしてGeyserを完全停止します。extensions/ と extensions/update/ の両方から ResourcePackManager.jar と、残っていれば旧 ResourcePackManager-GeyserBridge.jar を削除し、Geyserを起動してください。キューに残ったコピーは起動時に拡張を復元する可能性があります。削除するのはこのRSPMファイルだけです。
  • 設定をオフにしてもパック変換、配信、インストール済み拡張には影響しません。拡張を削除するとカスタムBedrockエンティティ連携が無効になります。アイテム変換とパック配信は独立しています。

バックエンドでオフにすると、ダウンロードしたRSPM更新をローカルGeyser-Spigotの更新キューへ準備する処理も省略します。そのため拡張とプラグインが別の状態になり得ます。ファイルを手動で揃えてください。下の互換性チェックが確認するのは必要なGeyserクラスとバイナリ互換性であり、プラグインと拡張のバージョン一致ではありません。

拡張が実際に行うこと​

  • RSPMのカスタムBedrockエンティティ定義をGeyserに登録します。起動時に、生成されたBedrockパックからエンティティ識別子を読み取ります。各エンティティのプロパティは、そのクライアントエンティティファイルが参照するアニメーションコントローラーとレンダーコントローラーから、コントローラーの識別子で照合して収集されます。そのため、長いファイルパスが短縮されたバンドルでも、プロパティとアニメーションは登録されます。
  • スポーンするエンティティのBedrock定義を差し替え、モデル化されたエンティティがバニラのフォールバックではなく、専用のカスタムBedrockエンティティとしてスポーンするようにします。
  • エンティティが存在する間、ライブのエンティティデータとプロパティのオーバーライドを適用します。
  • GeyserのレシピネットワークIDを早期に初期化します。これによりGeyser 2.11で発生しうるレシピID衝突の問題を回避できます。

素材はBedrock変換のエンティティバンドルから取得します。プラグインが assets/<namespace>/rspm_bedrock_pack/ 以下にネイティブのBedrockエンティティファイルを提供し、RSPMが生成パックへ取り込みます。生成側は対応するJavaエンティティもブリッジ経由で指定する必要があります。素材だけで任意のエンティティがカスタムモデルに変わるわけではありません。

起動時、拡張はRSPMのローカル生成パックの entity/*.entity.json エントリから識別子を読みます。Geyserの作業ディレクトリを基準に、プロキシの標準出力 plugins/resourcepackmanager/work/merged/Bedrock.zip、plugins/ResourcePackManager/work/merged/Bedrock.zip、続いてバックエンドの plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip を確認します。外部Geyserプロセスが別のマシンの出力を自動で読むことはできません。拡張のコピーだけで定義も届くと考えず、ログで事前読み込みしたパックを確認してください。

Geyserのバージョン要件​

拡張はGeyser 2.11以降を対象としています。

記述子はGeyser APIレベル 2.9.0 を宣言します。この低い値だけでは古いGeyserとの互換性を確認できません。実行時に必要なクラスを調べ、不足していればブリッジを無効化します。

クラスやリンケージの非互換が起きてもGeyser本体を巻き添えにして落とすことがないよう、フェイルクローズで設計されています。拡張のシェル自体は長期間安定しているGeyser APIの型しか参照せず、バージョン依存のクラスはコアの起動前にプローブされます。使用中のGeyserビルドにブリッジが必要とするクラスが含まれていない場合、ブリッジは自分自身を無効化し、その旨を通知します：

Disabled the RSPM custom Bedrock entity bridge: this Geyser build does not ship <class>. Geyser itself is unaffected, but custom Bedrock entities will not appear until a ResourcePackManager update matches this Geyser version.

ブリッジの無効化は、独立したアイテムコンバーターやパック配信機能を無効化しません。ただし、それぞれに対応するGeyser APIと正常なパック配信が必要です。カスタムエンティティを復旧するには、互換性のあるRSPMとGeyserを組み合わせてください。

以前のRSPMバージョンでは、Geyserの内部パケットトランスレーターをベンダリングしたコピーをGeyserのレジストリに差し込むことで同じ結果を実現していました。このトランスレーター置き換えは廃止され、拡張は登録とスポーン定義の差し替えにGeyser 2.11の公開エンティティライフサイクル／イベントを使うようになりました。それでもコアは、定義インスタンスの構築と下流のプラグインメッセージ受信に使う一部のGeyser内部をプローブします。互換性ガードと、RSPM／Geyserのバージョンを正確に揃えることが依然として重要なのはこのためです。

順序の問題：再起動が必要になる場合がある理由​

Geyserは起動中の登録期間にエンティティ定義を登録します。その期間が閉じた後にRSPMが初回のBedrockパックを生成すると、実行中のレジストリには間に合いません。RSPMは次回起動で生成パックを事前に読むため、再起動を求めます。

RSPM custom Bedrock entity definitions became available after Geyser closed its startup registration windows ... restart the proxy once to activate the newly generated custom models.

登録終了後に新しいエンティティ識別子や新規・変更されたプロパティ型が届くと警告が出ます。同じ定義とプロパティ型の再出力では再起動は不要です。

初回のパック生成が成功したら、Geyserを動かすサーバーまたはプロキシを再起動してください。再接続だけでは登録期間に間に合わなかった定義を有効化できません。次の起動では、拡張が読むローカルパスに生成パックがあり、2つの定義登録イベントを受け取る必要があります。起動時の状態ログで結果を確認できます。

動作確認の方法​

  1. 対象の extensions/ フォルダに実際に ResourcePackManager.jar が存在するか確認します。
  2. 起動時の RSPM Geyser bridge health 行を確認してください。拡張バージョン、artifactSha256、activationRoute、loadedDefinitions、packUuid、definitionWindows を表示します。カスタムエンティティを含むパックなら、登録済み定義、意図したパックUUID、definitionWindows=observed が必要です。MISSED または RSPM GEYSER BRIDGE UNHEALTHY は登録期間を逃したことを示します。拡張が読み込み済みと表示されるだけでは不十分です。
  3. Bedrockで参加し、モデル化したエンティティの外見とアニメーションを確認してください。アーマースタンドなどのバニラの元エンティティのままなら、ブリッジの起動、クライアントへのパック配信、登録済み定義、生成側の連携を確認します。正常な起動ログだけではクライアントでの描画を証明できません。

トラブルシューティング​

「拡張は読み込まれているのに、エンティティが依然としてアーマースタンドのまま」 パックと拡張は別々の半分です。まずBedrockパック自体がクライアントに届いているかを確認してください（Bedrock変換を参照）。パックのエンティティアセットがなければ、定義が描画すべき対象が存在しません。

「動いていたのに、Geyserを更新したらエンティティが壊れた」 上記の自己無効化メッセージを探してください。Geyserの更新により、ブリッジがプローブするAPIの構成が変わることがあります。

「extensions/ に何もインストールされたことがない」 コンソールで Automatic Geyser extension installation is disabled by geyserExtensionAutoInstall（バックエンド）または ... by geyser-extension-auto-install（プロキシ）を探してください。誰かがスイッチをオフにしています。GeyserとFloodgateの両方がローカルに存在しない場合は、代わりに Geyser-Spigot and Floodgate were not detected locally; skipping automatic Geyser extension installation が表示されます — これは、インストール先が何もないとRSPMが正しく判断した結果です。

「RSPMを更新したのに、拡張が古いバージョンのまま」 拡張が置き換わるのは再起動時のみです。RSPMがGeyserの更新キュー経由でステージングした場合は、差し替えのために一度の再起動が必要です。プラグインjarと拡張jarのバージョンは揃えておいてください — 両者は同じファイルなので、プラグインを再度コピーするだけで十分です。

拡張はアノテーション付きハンドラーに加えて、コードから早期のライフサイクル購読を登録します。Velocityでは、自動購読が間に合わない起動経路を補うため、プロキシプラグインもライフサイクルとセッションのイベントを中継します。設定は不要です。起動時の状態ログと登録・中継の警告を使って、起動失敗を調べてください。

次に読むページ​