跳至主要內容

FreeMinecraftModels 模型製作注意事項

本頁說明 FreeMinecraftModels 在匯入和執行時讀取的模型檔案、配套檔案及名稱規則。

來源格式​

FreeMinecraftModels 目前接受：

  • .bbmodel 檔案，用於可編輯的來源匯入
  • .fmmodel 檔案，用於精簡的運行時就緒模型資料

對於沒有配套檔案的單一 .bbmodel：

  1. 將它直接放在 plugins/FreeMinecraftModels/imports 中，副檔名使用小寫 .bbmodel
  2. 執行 /fmm reload
  3. 檢查轉換後的 .fmmodel 是否出現在作用中的模型資料夾，以及重新載入是否成功

單檔匯入器會將原檔留在 imports，因此後續匯入會再次轉換。它不收集散放的 .json 或 .yml 配套檔案，也不接受散放的 .fmmodel。對於自製模型集，請將模型和配套檔案一起放在作用中的 models 資料夾，或使用結構正確的內容包。imports 中沒有 pack.meta 的任意子資料夾會被略過。重新載入遭拒時可能保留舊目錄，請檢查主控台。

單檔轉換只保留材質的 source、id 和 name，會捨棄動畫尺寸及時間中繼資料，而且要求存在 textures 陣列。若需要這些中繼資料，請使用作用中的模型資料夾或保留原檔的內容包；執行階段的模型讀取器本身允許缺少材質陣列。

資料夾用途​

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled
  • imports 是手動模型匯入和官方包下載在處理前的接收資料夾
  • models 包含已安裝的活動模型內容
  • models_disabled 包含已下載或安裝但目前停用的包內容

舊安裝可能有首字母大寫的 Models 資料夾。FreeMinecraftModels 執行時優先使用現有的小寫 models，否則使用 Models。在不區分大小寫的檔案系統中，兩者指向同一目錄；在區分大小寫的系統中則可以並存。此時共用內容包匯入器優先使用現有的 Models 目的地，而執行階段讀取小寫 models。請在伺服器停止時備份並整併到小寫 models，避免匯入檔案落在作用中的模型樹之外。

模型 ID​

  • 運行時模型 ID 來自檔案名稱，不含 .bbmodel 或 .fmmodel 副檔名
  • 使用穩定、唯一的檔案名稱，因為 ID 是指令和 API 呼叫所解析的對象
  • Blockbench 動畫參考是基於名稱的，因此模型內部的重複或不明確命名比清晰、明確的命名方案更容易造成問題
  • 作用中的模型資料夾內，副檔名比對不區分大小寫，因此接受 .BBModel 和 .FMModel。從 imports 匯入散放檔案時，只辨識小寫 .bbmodel

ID 正規化與衝突​

檔案名稱在成為運行時模型 ID 與資源包檔名之前，會先被正規化：

  1. 轉為小寫
  2. 所有不屬於 a-z、0-9、.、_ 與 - 的字元都會被替換成 _

因此 My Table.bbmodel、my table.bbmodel 與 my_table.bbmodel 全都會正規化成同一個 ID：my_table。

在任何轉換開始之前，FreeMinecraftModels 會掃過整個 models 目錄樹，檢查是否有檔案會正規化成相同的 ID。若擁有該 ID 的所有檔案位元組完全相同（例如兩個內容包附帶同一個模型），FMM 會載入絕對路徑排序在最前面的那個，並略過其他副本而不發出警告。當這些檔案內容不同時：

  • 每一個發生衝突的檔案都會被拒絕 —— 它們全都不會被載入，因此不會出現「最後一個覆蓋前面」這種靜默行為
  • 該模型 ID 在本次載入流程的剩餘過程中都會被封鎖
  • 被拒絕的模型同樣會被排除在 Bedrock 自訂實體套件匯出之外
  • 主控台會出現：
[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

解決方法一律是重新命名檔案，讓正規化後的 ID 各不相同。最保險的習慣是從一開始就用小寫加底線來命名模型檔案（stone_table.bbmodel），這會讓檔案名稱與運行時 ID 完全一致，也徹底排除意外衝突的可能。

Blockbench 相容性​

  • FreeMinecraftModels 會從 .bbmodel 讀取 meta.format_version，並依其主版本號分支
  • 缺少 meta 區塊、缺少 format_version，或數值無法解析，全都會退回到版本 4，並記錄一行指名該模型的資訊/警告訊息
  • 缺少 textures 陣列是可接受的，會被視為空的紋理清單而不會讓匯入器崩潰。之後 Bedrock 自訂實體匯出器會略過該模型，因為 Bedrock 匯出至少需要一張紋理
  • 提取出的紋理檔名會被正規化為單一個 .png 副檔名。像 body.jpg、body.PNG 或 body 這樣的來源名稱都會被寫成並參考為 body.png
  • format_version 4.x 及更早版本：骨骼直接從 outliner 樹讀取，該樹內嵌了骨骼名稱
  • format_version 5.x 及更新版本：outliner 結構改變了。outliner 現在是由裸 UUID 字串與 {uuid, isOpen, children} 字典組成的巢狀樹，沒有 name 鍵，而實際的骨骼資料（包含 name）則放在另一個扁平的 groups 陣列中。FMM 會以 UUID 把兩者接起來 —— 每個 outliner 節點都會被換成它在 groups 中對應的條目，然後遞迴合併子節點 —— 因此骨骼名稱、原點與旋轉都能正常解析
  • 手動編輯或以程式產生 .bbmodel 檔案時，值得知道的影響：
    • 缺少 groups 陣列的 v5 檔案會不經合併直接傳遞。已合併的 outliner 仍可能運作；未處理的無名 v5 群組節點則可能在骨架讀取器需要名稱時，導致模型載入失敗
    • outliner 與 groups 之間的 UUID 必須完全一致；找不到對應群組的 outliner 節點會被原樣保留，而不是被丟棄
    • 不要把 v5 的 format_version 與 v4 形式的 outliner 混用，反之亦然 —— 分支是依據宣告的版本選擇的，而非依據實際結構
  • 如果匯入日誌顯示模型格式與 FreeMinecraftModels 不相容，請先將其視為模型格式問題，而非 wiki 或指令問題

影響執行階段的骨骼命名慣例​

當前的轉換器和骨架管線會識別幾個命名慣例：

  • hitbox
    • 保留用於碰撞箱生成
    • 應該清晰地定義模型碰撞箱，而不是用作視覺骨骼
    • 必須是 outliner 中的頂層骨骼才能定義執行階段的碰撞。巢狀 hitbox 會經過一般骨骼解析，但保持隱藏，且不會定義模型的碰撞箱
    • 應恰好包含一個立方體，定義寬（x）、深（z）與高（y）。額外的立方體會記錄 has more than one value defining a hitbox! Only the first cube will be used。空群組會記錄 has a hitbox bone but no hitbox cube!，並留下零尺寸，與沒有 hitbox 不同。立方體的偏移及旋轉不會成為碰撞箱偏移：解析器使用各邊長度的絕對值和零模型偏移
    • 永遠不會有動畫（指向 hitbox 的動畫軌道會被略過）、永遠不會被渲染，也會被排除在 Bedrock 幾何匯出之外。在 Bedrock 上，沒有 hitbox 骨骼的模型會退回為 1.0 x 2.0
  • tag_...
  • h_...
    • 被視為頭部骨骼
  • b_...
    • Java 執行階段的非顯示骨骼。結構用途請使用不含立方體的骨骼：Bedrock 幾何匯出不會篩除 b_ 前綴，因此這些骨骼上的立方體仍可能顯示
  • m_...
    • 騎乘點骨骼。每個帶此前綴的骨骼建立一個玩家座位，由 MountPointManager 管理。多個 m_ 骨骼建立多個座位。管理器選取第一個空座位，並在占用期間使用暫時的 Interaction 實體；其公開騎乘方法接受玩家，不接受任意實體。

前綴區分大小寫，hitbox 名稱的比對則不區分。這些名稱會影響轉換和執行階段行為。

名稱標籤位置​

tag_ 骨骼現在是可選的。FMM 依名稱字母順序選擇第一個 tag_ 骨骼作為名稱標籤錨點。沒有這類骨骼時，會將標籤放在縮放後的碰撞箱上方，因此沒有標籤骨骼的模型也能顯示名稱。

若備用位置不合適，可加入不含立方體的 tag_name 骨骼。多個標籤骨骼不再產生同一名稱標籤的多個副本。

API 支援多行名稱、縮放、行距和可見性。各行由上而下排列，最後一行位於錨點。請參閱API 指南。

立方體陰影與發光​

  • Blockbench 中立方體的 light_emission 值若是 0 到 15 的整數就會保留。其他任何值都會被捨棄，並在主控台輸出以 with invalid light_emission. Expected an integer from 0 to 15; ignoring this value. 結尾的警告。
  • 關閉陰影（shade: false）的立方體，在產生的幾何中也會得到 shade_direction_override: "up"，讓 Minecraft 26.3 用戶端像舊版用戶端一樣以無陰影方式渲染它。FMM 對同名顯示模型 .json 中的立方體也套用相同規則。你自行設定的值會被保留

未分組的立方體​

宣告在 outliner 頂層、沒有所屬群組的立方體，會以裸 UUID 字串而非骨骼條目的形式進來。FreeMinecraftModels 會把它們附加到自動生成的根骨骼（freeminecraftmodels_autogenerated_root）上，讓它們仍然能被渲染。它們無法被動畫定址，因此請把任何你打算做動畫的東西放進真正的群組裡。

IK、空物件和定位器​

當前程式碼確認支援：

  • Blockbench 空物件作為 IK 控制器
  • IK 鏈藍圖和運行時 IK 求解（FABRIK）
  • 定位器解析。定位器也可以作為 Blockbench 粒子效果的錨點；請參閱粒子

只有當空物件的 .bbmodel 項目同時包含 ik_source（來源骨骼）和 ik_target（目標骨骼或定位器）時，才會成為 IK 控制器。匯入器搜尋階層，也包含同層及向下的搜尋路徑。根層級的同層節點會產生僅含來源的鏈。lock_ik_target_rotation 會被讀取及儲存，但目前的求解器並不套用它。

重要的實用限制：

  • 來源／目標的連結是以 UUID 建立的，因此改名也不會失效 —— 但若模型中缺少其中任一個 UUID，主控台會記錄 IK chain in model <model>: Could not find source bone with UUID ... / Could not find target with UUID ...，且該鏈會被略過
  • 如果走訪找不到從來源到目標的路徑，你會看到 Could not find path from source to target，該鏈也會被略過
  • 控制器的動畫查找是基於名稱的，因此控制器命名需要在模型結構和動畫資料之間保持穩定
  • 只有位置關鍵影格驅動 IK，其偏移會加到目標骨骼或定位器的靜止位置，而不是儲存的控制器靜止位置。旋轉與縮放軌道不會驅動 IK

關於 IK 每影格如何被驅動，請參閱動畫。

1.21.4+ 輸出分割​

FreeMinecraftModels 宣告 api-version: 1.21.4，因此 1.21.4 是最低伺服器版本，而你一定會取得的就是現代的物品模型定義配置：

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

舊版（1.21.4 之前）的皮革馬鎧覆寫分支仍存在於程式碼中，但任何能載入當前外掛的伺服器都不會走到那裡。如果你正在閱讀舊筆記或查看舊的輸出資料夾，你看到的差異就來自於此。

展示模型 JSON（1.21.4+）​

管理員可以在 .bbmodel 或 .fmmodel 檔案旁邊放置一個同名的 .json 檔案（例如 table.bbmodel + table.json）。此 JSON 應從 Blockbench 匯出為「Java Block/Item」模型，定義物品在手持或物品欄中顯示時的外觀。

FMM 讀取作用中模型旁的 JSON，將其複製到資源包，並重寫 textures 對應表中不含命名空間的值。數字材質鍵對應模型已擷取材質的索引；未符合的鍵會使用一個可用材質（如果存在）。含命名空間的值保持不變。沒有配套 JSON 時，物品使用基礎材質外觀：擺設放置物品通常為紙，手持物品則使用設定的材質。格式錯誤的配套檔案會記錄 Failed to process display model JSON for ...，且不會註冊該顯示模型。

YML 中的自訂物品設定​

在模型的配套 YAML 中設定 material，即可註冊手持物品：

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A blade with a fire enchantment"
enchantments:
  - "minecraft:fire_aspect,2"

附魔 ID 應為小寫且含命名空間。皮革材質可接受 RGB 染色後綴，例如 LEATHER_CHESTPLATE:ff8800；請參閱配置。使用不支援的材質、無命名空間附魔或非空 scripts: 清單的物品無法使用；主控台會說明原因，原檔則會保留。scripts: 仍僅用於擺設。

其他無效定義，例如非布林值 isEnabled、格式錯誤的附魔項目、重複附魔或無效物品檔名，可能導致候選目錄與重新載入遭拒。物品檔名應為小寫，只含 a-z、0-9、.、_ 和 -，最長 128 個字元。自訂物品掃描讀取 .yml，不讀取 .yaml。透過 /fmm giveitem <item> 或管理員瀏覽器取得已註冊物品；擺設配方及商店購買產生的是紙製放置物品。

物品效果現在由附魔定義管理。魔杖與法杖使用魔法武器設定。兩者都不使用舊的裝備物品 Lua 執行環境。

Bedrock 和渲染路徑注意事項​

  • Bedrock 支援取決於 sendCustomModelsToBedrockClientsV2（預設為 true；取代了較舊的 sendCustomModelsToBedrockClients 鍵）以及周圍的 Floodgate/Geyser/資源包路徑
  • 支援版本上的 Java 客戶端在啟用 useDisplayEntitiesWhenPossible 時可以使用展示實體渲染
  • 不要假設在 Java 客戶端上看起來正確的模型在你的 Bedrock 路徑上也會自動安全

實用製作建議​

  • 保持檔案名稱穩定，因為它們會成為運行時 ID
  • 保持控制器和動畫命名明確，因為 Blockbench 動畫查找是基於名稱驅動的
  • 依用途使用保留的虛擬骨骼名稱（hitbox、tag_、h_、b_、m_）。只有碰撞箱上方的備用名稱標籤位置不合適時，才加入 tag_ 錨點
  • 共用執行階段狀態使用小寫 spawn、idle、walk、attack 和 death；攻擊與死亡仍需要執行階段觸發，其他名稱則需要明確呼叫播放（請見動畫）
  • 打算用於 /fmm disguise 的模型至少也應附帶 idle，並可加上 sneak 與 jump，這兩者只有偽裝控制器會辨識（請見玩家偽裝）
  • 在 /fmm reload 之後驗證匯入的輸出，而不僅是在 Blockbench 內部
  • 驗證生成的資源包內容是否對應你的目標 Minecraft 版本線，特別是在 1.21.4+ 上

弓和弩狀態模型​

FMM 在產生資源包時自動偵測弓和弩的顯示狀態。每個必要狀態都要有已載入的模型檔，以及處理成功的配套顯示 .json；只有檔名並不足夠。請用基礎名稱設定手持物品，並使用對應的 BOW 或 CROSSBOW 材質。

命名慣例​

後綴用途弓弩
_idle手持物品，未拉弓或未裝填必需必需
_draw_start剛開始拉弓必需必需
_draw_half拉到一半必需必需
_draw_full完全拉滿必需必需
_charged已裝填的弩（箭或火箭）--必需

弓需要四個模型（除 _charged 外全部）。弩需要全部五個。

範例檔案配置​

plugins/FreeMinecraftModels/models/my_weapons/
  cool_bow_idle.bbmodel
  cool_bow_idle.json
  cool_bow_draw_start.bbmodel
  cool_bow_draw_start.json
  cool_bow_draw_half.bbmodel
  cool_bow_draw_half.json
  cool_bow_draw_full.bbmodel
  cool_bow_draw_full.json
  cool_bow.yml

對於弩，還需加入 cool_bow_charged.bbmodel 和 cool_bow_charged.json。物品設定為 cool_bow.yml，使用不含 _idle 的基礎名稱。

偵測機制​

  • 偵測在資源包生成時（啟動時或 /fmm reload）自動進行。
  • 完整的顯示狀態集會取得一個以基礎名稱命名的公開物品定義，例如 cool_bow.json。各個 _idle、拉弓和裝填狀態的物品定義會移除，但其幾何仍由基礎定義參照
  • 顯示登錄表公開基礎 ID 並移除狀態 ID。包含 _charged 的完整集合視為弩，不含則視為弓。缺少顯示狀態會阻止分組
  • YML 設定使用基礎名稱，例如 cool_bow.yml。物品目錄會略過含狀態後綴的 YML 檔，擺設設定查找也會移除後綴

展示模型 JSON​

每個必要狀態都必須有自己的配套顯示 .json，例如 cool_bow_idle.json 和 cool_bow_draw_full.json。FMM 透過產生的基礎物品定義連接它們。條件與輸出路徑請參閱資源包輸出。

超出範圍​

本頁不嘗試保證：

  • 確切的 Blockbench UI 步驟
  • 藝術工作流程偏好
  • 較舊的本地 README 資料中描述的每個舊版 .bbmodel 怪癖

這些細節的變化速度比上述已驗證的運行時契約更快。