跳至主要內容

FreeMinecraftModels 常見問題

如果你的問題未列在此處，請查看側邊欄看看 wiki 中是否有專頁說明！

入門

我如何安裝和使用 FreeMinecraftModels？​

資訊

安裝：

  1. 下載 FreeMinecraftModels.jar 並將其放入你的 plugins 資料夾
  2. 重啟伺服器以生成外掛資料夾
  3. 執行 /fmm setup 以使用內容管理／首次設定選單
  4. 如果你使用官方內容包，請以 /nightbreaklogin <token> 連結 Nightbreak
  5. 對於官方 Nightbreak 管理的內容，請使用 /fmm setup 或 /fmm downloadall
  6. 對於手動內容，請將 .bbmodel 檔案放入 ~/plugins/FreeMinecraftModels/imports/ 並執行 /fmm reload
  7. 在 ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip 找到生成的資源包

分發資源包：

選擇下列方法之一：

  • 選項 A（建議）：安裝 Resource Pack Manager 以自動分發
  • 選項 B：透過 server.properties 或託管服務手動設定

生成模型：

  • /fmm spawn static <id> - 生成臨時裝飾模型
  • /fmm spawn dynamic <id> - 生成附加到實體的模型
  • /fmm spawn prop <id> - 生成持久化的世界模型

管理：

  • /fmm - 開啟可合成物品選單（需要 freeminecraftmodels.menu）
  • /fmm setup - 開啟內容管理／首次設定選單
  • /fmm recommendedplugins - 瀏覽與 FMM 搭配良好的搭檔外掛
  • /fmm downloadall - 下載最新的外掛更新加上所有可存取的官方內容
  • /fmm downloadallcontent - 下載所有可存取的官方內容（僅內容）
  • /fmm updatecontent - 更新過時的官方內容
  • /fmm downloadpluginupdate - 僅下載最新的外掛 jar 更新
  • /fmm reload - 重新載入外掛並轉換新模型
  • /fmm version - 顯示外掛版本
  • /fmm stats - 顯示實體數量統計

玩家功能：

  • /fmm disguise <modelID> [player] - 將你（或目標玩家）的外觀變為自訂模型
  • /fmm undisguise [player] - 移除玩家的偽裝
  • /fmm disguiselist - 列出當前所有被偽裝的玩家
  • /fmm itemify <model> <material> - 建立可放置的物品，用以生成指定模型
  • /fmm craftify <modelID> - 開啟互動式配方建構器來為道具建立合成配方
  • /fmm shop - 開啟可選的 Vault 支援家具商店（僅在 shop_config.yml 中啟用時可用）
  • /fmm mount <modelID> - 生成偽裝成自訂模型的可騎乘馬（實驗性）

除錯：

  • /fmm hitbox visualize [duration] - 使用粒子視覺化模型的碰撞箱（持續時間以 ticks 為單位，預設 100）
  • /fmm location - 回報已註冊的保護／地城提供者，並在你當前位置測試
  • /fmm debug bedrock [on|off] - 切換用於診斷 Bedrock 顯示管線的詳細 [FMM-BedrockDebug] 日誌串流。並非配置鍵 — 每次重新啟動都會重設為 OFF

管理性：

  • /fmm deleteall [radius] - 移除所有已載入的模型化實體和道具（請謹慎使用 - 無確認提示）。可選的 [radius]（僅限玩家）會將移除範圍限制在指定方塊數以內

權限：

  • freeminecraftmodels.*（預設：OP） - 萬用字元，授予 freeminecraftmodels.admin、freeminecraftmodels.deleteall、freeminecraftmodels.disguise.self 和 freeminecraftmodels.disguise.others。同時也是下列指令所需的字面權限：/fmm reload、/fmm stats、/fmm spawn、/fmm itemify、/fmm craftify、/fmm mount、/fmm hitbox visualize、/fmm debug bedrock、/fmm location、/fmm setup、/fmm recommendedplugins、/fmm downloadall、/fmm downloadallcontent、/fmm updatecontent 和 /fmm downloadpluginupdate
  • freeminecraftmodels.admin（預設：OP） - /fmm admin（管理員內容瀏覽器）和 /fmm giveitem
  • freeminecraftmodels.disguise.self（預設：OP） - 讓玩家僅偽裝／取消偽裝自己
  • freeminecraftmodels.disguise.others（預設：OP） - 允許指定目標的偽裝／取消偽裝，以及 /fmm disguiselist
  • freeminecraftmodels.deleteall（預設：OP） - /fmm deleteall 所需（萬用字元的子權限）
  • freeminecraftmodels.bypassregionprotection（預設：OP） - 即使 preventPropPlacementInProtectedRegions 已啟用，仍可在 WorldGuard 區域或 GriefPrevention 領地內放置／互動道具
  • freeminecraftmodels.menu（預設：true） - 讓所有玩家透過 /fmm 開啟可合成物品瀏覽器
  • freeminecraftmodels.shop（預設：true） - 讓所有玩家開啟 /fmm shop（仍需商店已啟用）

除非另有說明，指令預設僅 OP 可用。如有需要，請將這些權限授予非 OP 玩家。

模型功能與限制

模型大小和旋轉的限制是什麼？​

資訊

大小限制：

  • 每個骨骼的邊界框最大值：192x192x192 模型像素（遊戲中 12x12x12 方塊） — 在單一骨骼內的所有立方體上度量
  • FreeMinecraftModels 使用 4 倍內部縮放，並會位移模型原點以配合 Minecraft 的 -16..+32 資源包範圍
  • 如果某個骨骼超過限制，FMM 會在主控台輸出警告；可以縮小立方體、將它們靠得更近，或將它們拆分為多個骨骼
  • 整個模型可以比這更大 — 僅每個骨骼的限制適用

立方體旋轉限制：

  • 允許的角度：0°、±22.5°、±45° 及 22.5° 的倍數（從 v2.3.0 起）
  • 僅單軸旋轉
  • 範例：[22.5, 0, 0] 可運作，但 [22.5, 0, 45] 僅部分旋轉
  • 其他角度將無法正確顯示

骨骼旋轉：

  • 骨骼支援任何旋轉角度
  • 避免使用 90°、-90°、180°、-180° 的預設靜止位置（可能導致非預期行為）
  • 支援多軸旋轉
  • 每個骨骼會建立一個獨立實體（效能考量）

效能說明：

請盡可能讓骨骼數量保持最少。每個骨骼都會在 Minecraft 中生成一個獨立實體，在大規模時可能影響伺服器效能。

支援哪些動畫？​

資訊

FreeMinecraftModels 支援下列預設狀態動畫（在 AnimationStateType 列舉中宣告）：

標準動畫：

  • spawn
  • idle
  • walk
  • jump
  • attack
  • death
  • custom（由 API 或 Lua 觸發的一次性動畫的通用項目）

運作方式：

  • 在 BlockBench 中使用上述小寫名稱建立動畫，FMM 才會自動將它們繫結到對應的狀態
  • 外掛從 .bbmodel 檔案讀取動畫關鍵影格
  • 動畫會根據實體狀態自動觸發
  • 開發者可以透過 ModeledEntity 上的 playAnimation(animationName, blend, loop)，或從 Lua 使用 context.prop:play_animation(name, blend, loop) 以程式方式觸發動畫

特殊情況：

喚魔者實體會偵測附近的喚魔者尖牙以自動觸發攻擊動畫。

什麼是虛擬骨骼，它們如何運作？​

資訊

虛擬骨骼是使用保留名稱的特殊骨骼，用以為你的模型新增功能：

碰撞箱骨骼：

  • 名稱：hitbox
  • 建立互動區域和碰撞箱
  • 以相符的 x/z 值定義實體邊界

名牌骨骼：

  • 前綴：tag_
  • 在模型上方顯示文字
  • 用於實體命名

頭部旋轉骨骼：

  • 前綴：h_
  • 根據玩家／實體頭部位置旋轉
  • 自動追蹤頭部移動

用法：

在 BlockBench 中以這些特殊名稱之一建立骨骼，外掛就會自動套用對應的功能。

疑難排解常見問題

我看到的不是自訂模型，而是只有馬鎧。​

資訊

如果你在遊戲中看到的不是自訂模型，而是只有馬鎧，問題最有可能是你沒有正確地將 FMM 資源包與你既有的資源包合併。

MagmaGuy 開發了一個名為 Resource Pack Manager（RSPM）的外掛，可以自動為你合併資源包。你可以從 Spigot 這裡下載。

只需將 RSPM 的 .jar 檔案放入你的 plugins 資料夾，RSPM 就會處理一切。它會合併所有資源包、自動託管，並在玩家登入你的伺服器時分發給他們。

為什麼加入 .bbmodel 檔案後看不到我的模型？​

資訊

如果你的模型沒有出現，請檢查下列常見問題：

1. 忘記重新載入

將 .bbmodel 檔案放入 imports 資料夾後，請執行 /fmm reload。這會轉換模型並生成資源包。

2. 資源包未套用

玩家必須啟用 FMM 資源包才能看到模型。

  • 檢查 ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip 是否有生成的包
  • 安裝 Resource Pack Manager 以自動分發
  • 或透過 server.properties 或託管服務手動分發

3. 檔案位置錯誤

手動匯入的 .bbmodel 檔案必須放在：~/plugins/FreeMinecraftModels/imports/

如果你改用官方內容包，請使用 /fmm setup 或 /fmm downloadall，而不是手動放入檔案。

4. 模型有錯誤

在 /fmm reload 期間檢查主控台日誌是否有錯誤訊息。常見問題包括不支援的旋轉、過大的模型或材質問題。

5. 資源包合併問題

如果你看到的是馬鎧而不是模型，表示資源包沒有正確合併。請使用 Resource Pack Manager（RSPM）自動處理合併。

ViaVersion 可能導致資源包無法正確顯示。​

資訊

ViaVersion 可能導致資源包出現問題，特別是在版本低於 1.21.4 的伺服器上執行時。Minecraft 從 1.21.4 起改變了資源包的處理方式。如果你在類似 1.21.3 的版本上執行伺服器，並使用 ViaVersion 讓 1.21.4 客戶端連線，這些客戶端可能會遇到顯示某些資源包內容的問題，例如 FMM（FreeMinecraftModels）的自訂模型。

這是因為 Minecraft 的資源包系統在 1.21.4 更新中發生了改變。

注意： 這是 Minecraft 和 ViaVersion 的限制，並非 FreeMinecraftModels 特有的問題。當在低於 1.21.4 的伺服器版本上執行時，ViaVersion 的協定轉譯可能無法完全支援資源包的變更。

要解決此問題，請考慮將你的伺服器更新到 1.21.4 或更高版本，這樣可以確保與現代資源包功能（包括 FMM 自訂模型）有更好的相容性。

為什麼我的模型導致延遲或效能問題？​

資訊

你的 BlockBench 模型中的每個骨骼都會在 Minecraft 中建立一個獨立實體。骨骼眾多的模型可能影響伺服器效能。

最佳化技巧：

  • 在你的模型中盡量減少骨骼數量
  • 限制生成模型的數量
  • 在不需要動畫時，考慮使用靜態模型而非動態模型
  • 避免在彼此附近生成許多高骨骼數的模型

技術說明：

FreeMinecraftModels 將每個骨骼渲染為一個獨立的 Minecraft 實體。一個有 50 個骨骼的模型會生成 50 個實體。在大規模時，這會影響效能。

最佳實踐：

  • 設計骨骼較少的模型
  • 以實際的生成數量測試效能
  • 在加入新模型時監控伺服器 TPS

進階功能

我需要 Resource Pack Manager（RSPM）嗎？​

資訊

Resource Pack Manager（RSPM）是可選的，但強烈建議使用。

RSPM 的功能：

  • 自動合併來自多個外掛的資源包
  • 託管資源包（無需外部託管）
  • 在玩家登入時自動分發包
  • 免除手動的資源包配置

沒有 RSPM 時：

你必須手動：

  • 將 FMM 資源包與任何既有的伺服器資源包合併
  • 在外部服務或透過 server.properties 託管合併後的包
  • 設定伺服器將包傳送給玩家
  • 每次加入新模型時更新包

為什麼要使用 RSPM：

大多數「看到馬鎧而非模型」的問題都是由不正確的資源包合併造成的。RSPM 會自動處理這個問題。

下載 RSPM：https://www.spigotmc.org/resources/resource-pack-manager.118574/

由 MagmaGuy 開發，與 FreeMinecraftModels 同一位作者。

我可以在自己的外掛中使用 FreeMinecraftModels 嗎？​

資訊

可以，FreeMinecraftModels 為開發者提供了 API。

Maven/Gradle 整合：

儲存庫：https://repo.magmaguy.com/releases

成品：

  • GroupId：com.magmaguy
  • ArtifactId：FreeMinecraftModels
  • Scope：provided（必須安裝在伺服器上，請勿 shade）

主要 API 類別：

  • ModeledEntity（基底類別）
  • StaticEntity
  • DynamicEntity
  • PropEntity

範例用法：

StaticEntity staticEntity = StaticEntity.create(id, location);
if (staticEntity == null) {
    Bukkit.getLogger().warning("Failed to create model");
    return;
}
staticEntity.setRightClickCallback(...);
staticEntity.remove();

重要：

請勿將 FreeMinecraftModels shade 進你的外掛。它必須在伺服器上單獨安裝。

詳細的 API 文件，請參閱官方 README。

我如何將玩家偽裝成自訂模型？​

資訊

/fmm disguise 指令可將玩家的外觀變為任何自訂模型。

指令：

/fmm disguise <modelID> [player]
/fmm undisguise [player]
/fmm disguiselist

運作方式：

  • 使玩家對其他玩家隱形
  • 在玩家的位置上覆蓋自訂模型
  • 模型會跟隨玩家的移動
  • 非常適合角色扮演伺服器或特殊活動

範例：

/fmm disguise dragon              # 偽裝你自己
/fmm disguise dragon Steve         # 偽裝其他玩家
/fmm undisguise Steve              # 取消 Steve 的偽裝
/fmm disguiselist                  # 列出當前所有被偽裝的玩家

需求：

  • 以自己為目標：freeminecraftmodels.disguise.self（預設：OP）
  • 以他人為目標及 /fmm disguiselist：freeminecraftmodels.disguise.others（預設：OP）
  • 只要提供玩家名稱，主控台就可以執行指定目標的形式
  • modelID 必須是你的 models 資料夾中有效的已轉換模型
  • 第三方外掛可以透過公開的 DisguiseAPI 來驅動偽裝

注意事項：

  • 玩家碰撞箱保持不變（相同的碰撞箱）
  • 其他玩家看到的是自訂模型，而不是你的玩家皮膚
  • 在已偽裝時再次偽裝會乾淨地取代先前的偽裝
  • 隱形效果即使在喝牛奶或其他清除效果的互動下也會持續存在，直到玩家取消偽裝

我如何建立可放置的模型物品？​

資訊

/fmm itemify 指令會建立特殊物品，玩家可以用它在世界中放置模型。

指令：

/fmm itemify <model> <material>

參數：

  • model - 你的 models 資料夾中任何有效的模型 ID
  • material - 任何 Minecraft 材質（STICK、PAPER、DIAMOND 等）

範例：

/fmm itemify lamp_post STICK

它會建立什麼：

  • 一個帶有金色裝飾格式化顯示名稱的自訂物品（例如「✦ Wolf ✦」）
  • 說明該物品的描述性物品說明
  • 該物品會直接加入你的物品欄
  • 右鍵點擊以將模型放置為道具

使用情境：

  • 給予玩家物品來裝飾他們的建築
  • 為家具建立自訂的「生怪蛋」
  • 在不給予建築權限的情況下分發模型
  • 為創造建築設定套裝

需求：

  • 權限：freeminecraftmodels.*
  • 玩家必須在遊戲中（非主控台）

我如何除錯模型碰撞箱？​

資訊

/fmm hitbox visualize 指令使用粒子視覺化模型的碰撞箱。

指令：

/fmm hitbox visualize [duration]

參數：

  • duration（可選） - 顯示碰撞箱的持續時間，以 ticks 為單位（預設：100，最大：1200）
  • 20 ticks = 1 秒

範例：

/fmm hitbox visualize          # 顯示 5 秒
/fmm hitbox visualize 200      # 顯示 10 秒

運作方式：

  • 搜尋你周圍 10 格以內的模型
  • 以粒子顯示定向邊界框（OBB）的邊界
  • 同時顯示模型及其碰撞邊界
  • 用於驗證碰撞箱的大小和旋轉

何時使用：

  • 測試碰撞箱是否與視覺模型相符
  • 除錯互動問題
  • 驗證碰撞箱旋轉
  • 排解點擊偵測問題

需求：

  • 權限：freeminecraftmodels.*

注意： 與標準 Minecraft AABB 不同，FMM 中的碰撞箱會隨模型一起旋轉。

我可以建立可騎乘的自訂模型嗎？​

資訊

可以，使用 /fmm mount 指令來建立可騎乘的自訂模型（實驗性功能）。

指令：

/fmm mount <modelID>

它的功能：

  • 在你的位置生成一匹馬
  • 將馬偽裝成你的自訂模型
  • 自動馴服馬並加上馬鞍
  • 讓你立即騎上馬

範例：

/fmm mount dragon

需求：

  • 權限：freeminecraftmodels.*
  • 有效的模型 ID

重要注意事項：

  • 此功能標記為實驗性
  • 移動速度和行為與標準的馬相符
  • 馬的碰撞箱保持不變
  • 最適合搭配為坐騎設計的模型

使用情境：

  • 角色扮演伺服器的自訂坐騎
  • VIP 玩家的特殊交通工具
  • 冒險地圖的獨特可騎乘生物

什麼是騎乘點骨骼？​

資訊

騎乘點讓你可以使用特殊命名的骨骼，直接在你的模型上定義可騎乘的位置。

如何建立騎乘點：

在 Blockbench 中，以前綴 m_ 命名任何骨骼（例如 m_seat、m_back）。每個 m_ 骨骼都會成為模型上玩家或實體可以乘坐的座位位置。

運作方式：

  • 騎乘位置會跟隨骨骼的位置，包括動畫
  • 多個 m_ 骨骼會建立多個座位
  • 玩家／實體可以透過 API 或 Lua 腳本被乘坐到這些位置上

測試：

使用 /fmm mount <modelID> 快速測試模型上的騎乘點。

使用情境：

  • 多座位載具（船、馬車）
  • 具有特定座位位置的可騎乘生物
  • 肩膀乘坐的寵物或夥伴

自訂物品

什麼是自訂物品？​

資訊

自訂物品是在其同伴 YML 配置檔中設定了 material: 欄位的模型，使它們變成可手持、可裝備且支援 Lua 腳本的物品。

與道具放置物品的主要差異：

  • 自訂物品使用 fmm_item_id PDC（PersistentDataContainer）鍵
  • 道具放置物品（來自 /fmm itemify）使用 model_id PDC 鍵
  • 自訂物品支援 22 個物品專屬的 Lua 腳本鉤子（裝備、攻擊、消耗等）
  • 自訂物品可以在其 YML 配置中定義附魔、自訂名稱和物品說明

如何建立自訂物品：

  1. 在 Blockbench 中建立 .bbmodel 模型
  2. 建立一個同名（基底名相同）的同伴 YML 檔案（例如在 magic_sword.bbmodel 旁邊放 magic_sword.yml）
  3. 在 YML 中將 material: 欄位設為任何有效的 Minecraft 材質（例如 material: DIAMOND_SWORD）
  4. 可選地設定 name:、lore: 和 enchantments: 欄位
  5. 可選地在 plugins/FreeMinecraftModels/scripts/ 中建立 Lua 腳本，並透過 scripts: 欄位引用它

範例 YML：

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A legendary weapon"
  - "&cBurns enemies on hit"
enchantments:
  - "FIRE_ASPECT,2"
scripts:
  - flame_blade.lua

如何取得自訂物品：

  • /fmm giveitem <id>（需要 freeminecraftmodels.admin 權限）
  • 透過管理員選單（/fmm admin）

選單

FMM 提供哪些選單？​

資訊

FreeMinecraftModels 提供兩個遊戲內選單，用於瀏覽和管理內容。

玩家選單 — /fmm

  • 權限：freeminecraftmodels.menu（預設：true，所有玩家皆可使用）
  • 僅顯示有定義合成配方的物品
  • 點擊物品以查看帶有空間 3x3 合成方格預覽的詳細視圖
  • 讓玩家可以發現並學習如何合成自訂物品

管理員選單 — /fmm admin

  • 權限：freeminecraftmodels.admin（預設：OP）
  • 完整的內容瀏覽器，顯示：
    • 已安裝的包
    • 未打包的模型資料夾
    • 根層級的模型
    • 自訂物品（設定了 material: 的模型）
  • 讓管理員可以給予物品、預覽模型和管理內容

顯示模型

什麼是顯示模型？​

資訊

顯示模型讓自訂物品可以在玩家的物品欄和手中顯示 3D 模型，而非預設的材質外觀。

如何設定顯示模型：

  1. 在 Blockbench 中，使用 File > Export > Java Block/Item 匯出 .json 模型檔案
  2. 將 .json 檔案放在 .bbmodel 檔案旁邊，並使用相同的基底名（例如在 magic_sword.bbmodel 旁邊放 magic_sword.json）
  3. 執行 /fmm reload

運作方式：

  • 在 Minecraft 1.21.4+ 上，手持或在物品欄中查看時，該物品會以自訂 3D 模型顯示
  • JSON 中的裸材質引用會自動重寫為 FMM 命名空間路徑
  • 如果沒有 .json 檔案，該物品會回退到單純的材質外觀
  • 較舊的伺服器版本會默默忽略顯示模型

需求：

  • 執行 Minecraft 1.21.4 或更新版本的伺服器
  • 放在模型檔案旁邊的有效 Blockbench「Java Block/Item」匯出（.json）