跳至主要內容

玩家偽裝

FreeMinecraftModels 可以將任何線上玩家偽裝成已載入的模型。偽裝由指令、公開的 DisguiseAPI 以及每位玩家的 PlayerDisguiseEntity（負責處理被偽裝玩家的隱形與模型渲染）所驅動。

指令​

指令權限說明
/fmm disguise <modelID>freeminecraftmodels.disguise.self偽裝發送者。僅限玩家使用
/fmm disguise <modelID> <player>freeminecraftmodels.disguise.others偽裝指定的玩家。可從主控台執行
/fmm undisguisefreeminecraftmodels.disguise.self移除發送者的偽裝。僅限玩家使用
/fmm undisguise <player>freeminecraftmodels.disguise.others移除指定玩家的偽裝。可從主控台執行
/fmm disguiselistfreeminecraftmodels.disguise.others列出每位被偽裝的玩家及其偽裝模型

freeminecraftmodels.* 萬用字元會以 OP 預設值授予 admin、deleteall、disguise.self 與 disguise.others。它同時也會授予另外註冊的 freeminecraftmodels.bypassregionprotection 權限。

行為​

  • 偽裝已被偽裝的玩家會乾淨地取代先前的偽裝 — 不需要先取消偽裝。
  • 被偽裝的玩家對其他玩家是隱形的，所以只看得到模型。被偽裝的玩家仍能正常看到自己。
  • 隱形效果即使在喝牛奶、/effect clear、信標效果清除、死亡與重生，以及通常會剝離該效果的任何其他互動或外掛下也會持續存在（在下一個 tick 由 DisguiseEffectListener 重新套用）。
  • 玩家的碰撞箱不變。怪物鎖定、碰撞與 PvP 都會照常運作。
  • 偽裝不會在伺服器重啟、/fmm reload，或玩家登出後保留 — 它們只在記憶體中追蹤，並由 DisguiseListeners.onQuit 處理常式在 PlayerQuitEvent 時移除偽裝。死亡和世界切換不會取消玩家的偽裝。
  • 在 /fmm reload 時，所有有效的偽裝會作為外掛關閉的一部分被拆除。玩家在重新載入後需要被重新偽裝。

偽裝動畫​

偽裝不會使用一般的模型實體動畫狀態機。每個偽裝都有自己的控制器，每個 tick 讀取被偽裝的玩家，並依名稱挑選一個動畫。

系統會辨識五個保留的動畫名稱，優先順序如下（由高至低）：

優先順序動畫類型觸發條件
1attack一次性玩家揮動手臂
2jump一次性玩家向上離開地面
3sneak循環玩家正在潛行
4walk循環玩家自上一個 tick 起移動超過約 0.01 個方塊
5idle循環其他條件都不適用時

值得知道的行為：

  • 只有模型實際擁有的動畫會被納入考慮。沒有 sneak 動畫的模型會直接落到 walk 或 idle。

  • 一次性動畫會中斷目前的循環，並在固定的 **20 tick（1 秒）**內壓制優先順序較低的動畫。動畫系統沒有提供完成回呼，因此那是假定的上限而非真實長度 —— 如果你希望能乾淨地交還給循環，請把 attack 與 jump 動畫控制在一秒以內。

  • 只有在選中的動畫實際改變時才會重新發出循環，因此穩定行走不會每個 tick 都被重新啟動。

  • 與一般模型實體上（目前無作用的）jump 狀態不同，jump 在偽裝中是真正有接上的。請參閱動畫。

  • 沒有 idle 動畫的偽裝模型，每次偽裝時都會記錄一則警告：

    Disguise model '<model>' has no 'idle' animation — disguised players using this model will freeze on the last animation frame whenever no other action is active.

    請為任何你打算用作偽裝的模型附上一個 idle 動畫。

Bedrock 客戶端​

偽裝依賴 FMM 渲染自訂模型。config.yml 中的預設值 sendCustomModelsToBedrockClientsV2: true 預設啟用 Bedrock 模型傳送；如果你將其設為 false（或沿用了舊的 sendCustomModelsToBedrockClients: false），Bedrock 玩家會看不到模型，也看不到底層的隱形玩家 — 實際上，他們會在被偽裝玩家所站之處什麼都看不到。即使啟用此開關，模型要能渲染仍需要 Bedrock 相容的資源包流程（Floodgate + Geyser + 轉換過的資源包）。

DisguiseAPI​

第三方外掛可以透過 com.magmaguy.freeminecraftmodels.api.DisguiseAPI 以程式化方式驅動偽裝。

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// 偽裝（如果模型 ID 未載入則回傳 false）
boolean ok = DisguiseAPI.disguise(player, "dragon");

// 取消偽裝（如果移除了偽裝則回傳 true）
DisguiseAPI.undisguise(player);

// 查詢
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // 未偽裝時為 null

// 所有被偽裝玩家的不可修改快照
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();

該 API 是公開、重構安全的入口點。外掛應呼叫 DisguiseAPI 而非內部的 DisguiseManager。

常見使用案例​

  • 角色扮演與 RPG 伺服器： 將玩家偽裝成 Boss 模型用於過場動畫或任務腳本。
  • 活動主持： 將主持人偽裝成巨大的自訂模型。
  • 坐騎與載具： 結合 /fmm mount 與 /fmm disguise 創造創意運輸配置。
  • EliteMobs 整合： Boss 腳本可以偽裝觸發事件的玩家，產生暫時性的轉換效果。

疑難排解​

我執行 /fmm disguise dragon 時沒有任何反應。 模型 ID 必須完全符合已載入的模型。請使用 /fmm admin 或該指令的 Tab 補全來驗證模型名稱。指定目標的形式會在解析模型或玩家之前先檢查 freeminecraftmodels.disguise.others，並直接回報缺少該權限。

我的偽裝在 /fmm reload 後消失了。 預期如此。所有偽裝都會在重新載入時被拆除。如果你需要自動重新套用偽裝，請監聽 FmmReloadedEvent。

Bedrock 玩家看不到偽裝。 請參閱上方 Bedrock 客戶端。

被偽裝的玩家仍然對其他人可見。 隱形是以封包層級的效果套用。如果其他外掛每個 tick 都強制移除隱形（某些反作弊外掛會這麼做），它可能會與 FMM 的重新套用衝突。請將 FMM 列入白名單或停用衝突的檢查。