FreeMinecraftModels 常見問題
如果你的問題未在此處列出，請查看側邊欄，看看 wiki 中是否有專門的頁面！
入門
如何安裝和使用 FreeMinecraftModels？
資訊
安裝：
- 下載 FreeMinecraftModels.jar 並放入 plugins 資料夾
- 重啟伺服器以生成外掛資料夾
- 如果需要首次設定流程，執行
/fmm initialize - 如果使用官方內容包，透過
/nightbreaklogin <token>連結 Nightbreak - 使用
/fmm setup或/fmm downloadall取得 Nightbreak 管理的官方內容 - 對於手動內容，將
.bbmodel檔案放入~/plugins/FreeMinecraftModels/imports/並執行/fmm reload - 生成的資源包位於
~/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 initialize- 開啟首次設定選單/fmm setup- 開啟內容管理選單/fmm downloadall- 下載所有可存取的官方內容/fmm updatecontent- 更新過期的官方內容/fmm reload- 重新載入外掛並轉換新模型/fmm version- 顯示外掛版本/fmm stats- 顯示實體計數統計
玩家功能：
/fmm disguise <modelID>- 將外觀變為自訂模型/fmm undisguise- 移除玩家偽裝並恢復正常外觀/fmm itemify <model> <material>- 建立可放置物品以生成指定模型/fmm craftify <modelID>- 開啟互動式配方建構器，為道具建立合成配方/fmm mount <modelID>- 生成偽裝為自訂模型的可騎乘馬（實驗性）
除錯：
/fmm hitbox visualize [duration]- 使用粒子視覺化模型碰撞箱（持續時間以 tick 為單位，預設 100）
管理員：
/fmm deleteall- 移除所有目前載入的模型實體（謹慎使用 - 無確認提示）
權限：
freeminecraftmodels.*- 大多數指令需要（disguise、itemify、mount、hitbox visualize、spawn）freeminecraftmodels.deleteall-/fmm deleteall指令需要freeminecraftmodels.admin（預設：OP）- 管理員選單（/fmm admin）和/fmm giveitem需要freeminecraftmodels.menu（預設：true）- 允許所有玩家透過/fmm開啟可合成物品瀏覽器
指令預設僅限 OP 使用，除非另有說明。如需要，請向非 OP 玩家授予這些權限。
模型功能與限制
模型的大小和旋轉限制是什麼？
資訊
大小限制：
- 最大：112x112x112 像素（遊戲內 7x7x7 方塊）
- FreeMinecraftModels 使用 4 倍內部縮放來實現這些尺寸
- 標準 Minecraft 資源包限制為更小的尺寸
立方體旋轉限制：
- 允許的角度：0°、±22.5°、±45° 以及 22.5° 的倍數（自 v2.3.0 起）
- 僅支援單軸旋轉
- 範例：[22.5, 0, 0] 有效，但 [22.5, 0, 45] 僅部分旋轉
- 其他角度將無法正確顯示
骨骼旋轉：
- 骨骼支援任意旋轉角度
- 避免使用 90°、-90°、180°、-180° 的預設靜止位置（可能導致意外行為）
- 支援多軸旋轉
- 每個骨骼建立一個單獨的實體（效能考量）
效能提示：
盡可能保持骨骼數量最少。每個骨骼在 Minecraft 中產生一個單獨的實體，大規模時可能影響伺服器效能。
支援哪些動畫？
資訊
FreeMinecraftModels 支援以下預設狀態動畫：
標準動畫：
- Walk
- Idle
- Death
- Attack
- Spawn
工作原理：
- 在 BlockBench 中建立動畫
- 外掛從 .bbmodel 檔案讀取動畫關鍵影格
- 動畫根據實體狀態自動觸發
- 開發者可以使用
playAnimation(animationName, false, false)以程式方式觸發動畫
特殊情況：
Evoker 實體偵測附近的 Evoker Fangs 以自動觸發攻擊動畫。
什麼是虛擬骨骼？它們如何運作？
資訊
虛擬骨骼是具有保留名稱的特殊骨骼，為你的模型新增功能：
碰撞箱骨骼：
- 名稱：
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 特有的。ViaVersion 的協定轉換在執行低於 1.21.4 的伺服器版本時可能無法完全支援資源包變更。
要解決此問題，請考慮將伺服器更新到 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（基底類別）StaticEntityDynamicEntityPropEntity
使用範例：
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>
工作原理：
- 使玩家對其他玩家不可見
- 在玩家位置覆蓋自訂模型
- 模型跟隨玩家的移動
- 非常適合角色扮演伺服器或特別活動
範例：
/fmm disguise dragon
移除偽裝：
/fmm undisguise
要求：
- 權限：
freeminecraftmodels.* - modelID 必須是 models 資料夾中有效的已轉換模型
注意：
- 玩家碰撞箱保持不變（相同的碰撞箱）
- 其他玩家看到的是自訂模型而不是你的玩家外觀
- 隱身效果在取消偽裝前永久存在
如何建立可放置的模型物品？
資訊
/fmm itemify 指令建立特殊物品，玩家可以使用它們在世界中放置模型。
指令：
/fmm itemify <model> <material>
參數：
model- models 資料夾中任何有效的模型 IDmaterial- 任何 Minecraft 材質（STICK、PAPER、DIAMOND 等）
範例：
/fmm itemify lamp_post STICK
建立內容：
- 一個帶有金色裝飾顯示名稱的自訂物品（例如「✦ Wolf ✦」）
- 描述性說明文字
- 物品直接新增到你的物品欄
- 右鍵點擊以將模型作為道具放置
使用場景：
- 給玩家提供裝飾建築的物品
- 建立傢俱的自訂「生成蛋」
- 在不給予建築權限的情況下分發模型
- 準備創意建築套件
要求：
- 權限：
freeminecraftmodels.* - 玩家必須在遊戲中（非主控台）
如何除錯模型碰撞箱？
資訊
/fmm hitbox visualize 指令使用粒子視覺化模型碰撞箱。
指令：
/fmm hitbox visualize [duration]
參數：
duration（可選）- 顯示碰撞箱的時間，以 tick 為單位（預設：100，最大：1200）- 20 tick = 1 秒
範例：
/fmm hitbox visualize # 顯示 5 秒
/fmm hitbox visualize 200 # 顯示 10 秒
工作原理：
- 搜尋你周圍 10 個方塊內的模型
- 用粒子顯示定向包圍盒（OBB）邊界
- 同時顯示模型及其碰撞邊界
- 用於驗證碰撞箱大小和旋轉
何時使用：
- 測試碰撞箱是否與視覺模型匹配
- 除錯互動問題
- 驗證碰撞箱旋轉
- 排查點擊偵測問題
要求：
- 權限：
freeminecraftmodels.*
注意： FMM 中的碰撞箱會隨模型旋轉，不同於標準 Minecraft AABB。
我可以建立可騎乘的自訂模型嗎？
資訊
是的，使用 /fmm mount 指令建立可騎乘的自訂模型（實驗性功能）。
指令：
/fmm mount <modelID>
功能：
- 在你的位置生成一匹馬
- 將馬偽裝為你的自訂模型
- 自動馴服馬並新增鞍
- 讓你立即騎上馬
範例：
/fmm mount dragon
要求：
- 權限：
freeminecraftmodels.* - 有效的模型 ID
重要提示：
- 此功能標記為實驗性
- 移動速度和行為與標準馬相同
- 馬的碰撞箱保持不變
- 最適合為坐騎設計的模型
使用場景：
- 角色扮演伺服器的自訂坐騎
- VIP 玩家的特殊交通工具
- 冒險地圖的獨特可騎乘生物
什麼是坐騎點骨骼？
資訊
坐騎點讓你使用特殊命名的骨骼直接在模型上定義可騎乘位置。
如何建立坐騎點：
在 Blockbench 中，將任何骨骼命名為 mount_ 前綴（例如 mount_seat、mount_back）。每個 mount_ 骨骼都會成為模型上的一個座位位置，玩家或實體可以在此被騎乘。
工作原理：
- 坐騎位置跟隨骨骼的位置，包括動畫
- 多個
mount_骨骼建立多個座位 - 玩家/實體可以透過 API 或 Lua 腳本被安裝到這些位置
測試：
使用 /fmm mount <modelID> 快速測試模型上的坐騎點。
使用場景：
- 多座位載具（船、馬車）
- 具有特定座位位置的可騎乘生物
- 肩上的寵物或同伴
自訂物品
什麼是自訂物品？
資訊
自訂物品是在其同名 YML 設定檔中設定了 material: 欄位的模型，將它們變成可手持、可裝備的物品，並支援 Lua 腳本。
與道具放置物品的主要區別：
- 自訂物品使用
fmm_item_idPDC（PersistentDataContainer）鍵 - 道具放置物品（來自
/fmm itemify）使用model_idPDC 鍵 - 自訂物品支援 22 個物品特定的 Lua 腳本鉤子（equip、attack、consume 等）
- 自訂物品可以在其 YML 設定中定義附魔、自訂名稱和說明文字
如何建立自訂物品：
- 在 Blockbench 中建立
.bbmodel模型 - 建立同名的 YML 檔案（例如
magic_sword.bbmodel旁的magic_sword.yml） - 在 YML 中設定
material:欄位為任何有效的 Minecraft 材料（例如material: DIAMOND_SWORD） - 可選設定
name:、lore:和enchantments:欄位 - 可選在
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 模型，而不是預設的材料外觀。
如何設定顯示模型：
- 在 Blockbench 中使用 File > Export > Java Block/Item 匯出
.json模型檔案 - 將
.json檔案放在與.bbmodel檔案同名的位置旁（例如magic_sword.bbmodel旁的magic_sword.json） - 執行
/fmm reload
工作原理：
- 在 Minecraft 1.21.4+ 上，物品在手持或在物品欄中查看時會以自訂 3D 模型顯示
- JSON 中的裸材質引用會自動重寫為 FMM 命名空間路徑
- 如果沒有
.json檔案，物品會退回到普通材料外觀 - 較舊的伺服器版本會靜默忽略顯示模型
要求：
- 伺服器執行 Minecraft 1.21.4 或更新版本
- 有效的 Blockbench「Java Block/Item」匯出（
.json）放在模型檔案旁