Geyser 擴充功能與自訂 Bedrock 實體
轉換資源包能讓 Bedrock 玩家取得正確的物品材質與模型。但要讓他們看到真正的自訂實體——一個會正確渲染並播放動畫的模型化 Boss，而不是顯示成盔甲架——就需要有程式碼在 Geyser 內部執行。這正是 RSPM Geyser 擴充功能的用途。
你不需要另外下載它。你安裝為外掛的那個 ResourcePackManager.jar 本身就是擴充功能。
一個 Jar，三種身分
ResourcePackManager.jar 同時是：
- Bukkit/Paper 後端外掛，
- Velocity 與 BungeeCord/Waterfall 代理外掛，
- 以及 Geyser 擴充功能。
由哪個載入器開啟它，就會選用對應的進入點。舊版曾另外提供一個獨立的 ResourcePackManager-GeyserBridge.jar；該檔案已停用，RSPM 會自動清理殘留檔案。
安裝方式
在 RSPM 能自行處理的情況下，它會替你安裝擴充功能。實際行為取決於 Geyser 所在位置：
| 你的架構 | RSPM 的行為 |
|---|---|
| Geyser-Spigot 位於同一台伺服器 | 將執行中的 jar 複製到 plugins/Geyser-Spigot/extensions/ResourcePackManager.jar。若該處已存在不同版本，則改為透過 Geyser 自身的更新佇列 extensions/update/ 佈署新版本。無論哪種情況，主控台都會出現一行訊息，要求你重啟一次。 |
| Geyser 位於代理端（Geyser-Velocity / Geyser-BungeeCord） | 代理端身分會執行相同動作，複製到代理的 Geyser-*/extensions/ 資料夾。 |
| Floodgate 在本地、Geyser 在外部（Geyser 在獨立行程中執行） | RSPM 無法觸及該行程。它會將副本匯出至 plugins/ResourcePackManager/geyser-extension/，並警告你將該 jar 複製到外部 Geyser 的 extensions/ 資料夾後重啟 Geyser。 |
| Geyser 與 Floodgate 皆不存在 | 無事可做——RSPM 僅記錄一行提示訊息並略過安裝。 |
extensions/ 中已存在的較新版本，永遠不會被較舊版本覆寫。
安裝一律需要重啟一次。 Geyser 只在啟動時載入擴充功能，因此剛複製或佈署的 jar 在伺服器或代理重啟前不會生效。
關閉自動安裝
每個身分都有自己的開關，且彼此獨立：
| 位置 | 設定 | 預設 |
|---|---|---|
後端 plugins/ResourcePackManager/config.yml | geyserExtensionAutoInstall | true |
代理 config.yml | geyser-extension-auto-install | true |
將其中任一項設為 false，該身分就不會再安裝擴充功能或為其預備更新，並會記錄一行訊息說明。請仔細理解其語意：
- 它會阻止未來的安裝與更新預備。
- 它不會移除已經位於
extensions/中的擴充功能 jar。Geyser 正持有該檔案。若要真正停用橋接，請將旗標設為false、停止 Geyser、手動從extensions/刪除 RSPM jar，然後再啟動它。 - 關閉它不會影響資源包轉換或資源包交付。物品、材質與模型仍會照常轉換並提供；只有自訂 Bedrock 實體會失效。
在後端關閉它，也會跳過把已下載的 RSPM 更新預備到本機 Geyser-Spigot 更新佇列的步驟，因此擴充功能與外掛的版本可能逐漸分歧——而這正是下方相容性防護機制存在的目的。
擴充功能實際做了什麼
- 在啟動時向 Geyser 註冊 RSPM 的自訂 Bedrock 實體定義，並從產生的 Bedrock 資源包中讀取實體識別碼。
- 替換生成中實體的 Bedrock 定義，讓模型化實體以其自訂 Bedrock 實體的形式生成，而非原版後備形式。
- 在實體存在期間套用即時實體資料與屬性覆寫。
- 提早準備 Geyser 的配方網路 ID，藉此避免 Geyser 2.11 上一類配方 ID 衝突的問題。
這些定義所參照的 Bedrock 端資源，來自 Bedrock 轉換中描述的實體套件——外掛在 assets/<namespace>/rspm_bedrock_pack/ 底下提供原生 Bedrock 實體檔案，RSPM 再將它們帶入產生的資源包中。
Geyser 版本需求
擴充功能的目標版本為 Geyser 2.11+。
它的描述檔刻意宣告較低的 Geyser API 等級（2.9.0），讓較舊的 Geyser 願意載入它，而不是直接拒絕該 jar。真正的需求是在執行期強制檢查的：擴充功能會探測它需要的類別，並在類別缺失時自行停用，如此便能給出清楚的訊息，而不是拋出操作員難以解讀的載入期拒絕。
它刻意設計成在類別／連結不相容時 fail closed，而不是拖垮 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，或等待與你的 Geyser 版本相符的 RSPM 版本。
較早的 RSPM 版本是透過將 Geyser 某個內部封包轉譯器的內嵌副本換入 Geyser 的註冊表來達成相同效果。該轉譯器替換做法已移除：擴充功能現在改用 Geyser 2.11 的公開實體生命週期／事件來完成註冊與生成定義的替換。核心仍會探測一小組 Geyser 內部項目，用來建構定義實例並接收下游的外掛訊息，這也是相容性防護機制與 RSPM／Geyser 版本精確對應依然重要的原因。
順序問題：為何有時需要重啟
Geyser 會在自身的啟動視窗期間註冊實體定義。若 RSPM 在該視窗關閉之後才產生完 Bedrock 資源包——全新安裝時正是如此，因為開機當下根本還沒有資源包——那些定義就會太遲，無法進入 Geyser 已凍結的註冊表。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 的伺服器或代理行程重啟一次。單靠重新連線無法啟用錯過啟動視窗的定義。之後每次開機順序就會正確，因為 Geyser 開啟註冊視窗時資源包都已存在。
確認是否正常運作
- 檢查目標
extensions/資料夾中確實含有ResourcePackManager.jar。 - 開機時 Geyser 應會列出該擴充功能已載入，且 RSPM 會記錄它註冊了多少個自訂 Bedrock 實體定義。
- 以 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 上，Geyser 的自動擴充功能訂閱機制不像其他平台那樣觸發，因此代理外掛會自行轉發生命週期事件。這由內部處理，無需任何設定。
後續閱讀
- Bedrock / Geyser 轉換 — 會轉換哪些內容以及資源包如何提供
- 代理網路 — Geyser 位於代理端
- 疑難排解