跳至主要內容

Geyser 擴充功能與自訂 Bedrock 實體

資源包轉換提供受支援的物品材質和模型。自訂實體，例如具有獨特外觀與動畫的模型 Boss，也需要 Geyser 內部的程式碼。RSPM Geyser 擴充功能為相容的內容產生外掛及其 Bedrock 實體資源提供這種整合。

你不需要另外下載它。你安裝為外掛的那個 ResourcePackManager.jar 本身就是擴充功能。

一個 Jar，三種身分​

ResourcePackManager.jar 同時是：

  • 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。只匯出擴充功能不會設定外部資源包分發或啟動定義載入。
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 類別與二進位相容性，不會檢查外掛與擴充功能的版本是否相同。

擴充功能實際做了什麼​

  • 在啟動時向 Geyser 註冊 RSPM 的自訂 Bedrock 實體定義，並從產生的 Bedrock 資源包中讀取實體識別碼。每個實體的屬性會從其用戶端實體檔案所參照的動畫控制器與渲染控制器中收集，並依控制器識別碼比對，因此長檔案路徑已被縮短的套組仍能註冊其屬性與動畫。
  • 替換生成中實體的 Bedrock 定義，讓模型化實體以其自訂 Bedrock 實體的形式生成，而非原版後備形式。
  • 在實體存在期間套用即時實體資料與屬性覆寫。
  • 提早準備 Geyser 的配方網路 ID，藉此避免 Geyser 2.11 上一類配方 ID 衝突的問題。

資源來自 Bedrock 轉換中描述的實體套組。外掛在 assets/<namespace>/rspm_bedrock_pack/ 下提供原生 Bedrock 實體檔案，RSPM 將它們匯入產生的資源包。內容產生外掛也必須透過橋接標記對應的 Java 實體；資源套組本身不會將任意實體變成自訂模型。

啟動時，擴充功能從 RSPM 本地產生包的 entity/*.entity.json 項目讀取識別碼。它依序檢查一般代理輸出 plugins/resourcepackmanager/work/merged/Bedrock.zip、plugins/ResourcePackManager/work/merged/Bedrock.zip，再檢查後端輸出 plugins/ResourcePackManager/output/ResourcePackManager_Bedrock.zip，路徑相對於 Geyser 工作目錄。外部 Geyser 行程無法自動讀取另一台機器的輸出。請從日誌確認預先載入了哪個包，不要認為複製擴充功能也會自動提供定義。

Geyser 版本需求​

擴充功能的目標版本為 Geyser 2.11+。

描述檔宣告 Geyser API 等級 2.9.0。這個較低等級不能證明與舊版 Geyser 相容。執行時，擴充功能會檢查必要類別，缺少時停用橋接。

它刻意設計成在類別／連結不相容時 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 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 的伺服器或代理行程。只重新連線不能啟用錯過啟動註冊期間的定義。下次啟動時，產生包必須位於擴充功能讀取的本地路徑，而且兩個定義註冊階段都必須被接收。啟動狀態行會說明是否符合這些條件。

確認是否正常運作​

  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 上，代理外掛也會轉發生命週期與工作階段事件，以涵蓋自動訂閱被錯過的啟動路徑。不必設定。請使用啟動狀態行及註冊或轉發警告，診斷啟用失敗。

後續閱讀​