跳至主要内容

FreeMinecraftModels 模型製作說明

本頁記錄了目前在 FreeMinecraftModels 程式碼庫中可以確認的模型製作細節。內容刻意保持保守：重點放在匯入與執行時契約，而不是涵蓋所有 Blockbench 工作流程偏好。

原始格式​

FreeMinecraftModels 目前接受：

  • 用於可編輯原始匯入的 .bbmodel 檔案
  • 用於精簡後執行時模型資料的 .fmmodel 檔案

標準匯入流程如下：

  1. 將模型放入 plugins/FreeMinecraftModels/imports
  2. 執行 /fmm reload
  3. 讓 FreeMinecraftModels 將模型匯入目前啟用的模型集合，並重新建立產生的資源包輸出

資料夾角色​

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled
  • imports 是手動模型匯入與官方套件下載在處理前進入的入口資料夾
  • models 包含目前已安裝並啟用的模型內容
  • models_disabled 包含已下載或已安裝、但目前被停用的套件內容

模型 ID​

  • 執行時模型 ID 來自檔名本身，不包含 .bbmodel 或 .fmmodel 副檔名
  • 請使用穩定且唯一的檔名，因為命令與 API 呼叫解析的就是這個 ID
  • Blockbench 動畫參照依賴名稱，因此模型內若存在重複或不清楚的命名，比起清楚明確的命名更容易造成問題

Blockbench 相容性​

  • FreeMinecraftModels 會在匯入時偵測 Blockbench 檔案版本
  • 目前的匯入器仍然保留了對 Blockbench v5 之前版本的相容分支
  • 如果匯入日誌指出模型格式與 FreeMinecraftModels 不相容，應先將其視為模型格式問題，而不是 wiki 或命令問題

對執行時有意義的 bone 命名慣例​

目前的轉換器與 skeleton 管線識別以下一些命名慣例：

  • hitbox
    • 保留給 hitbox 產生使用
    • 應用來清楚定義模型 hitbox，而不是當作可視 bone 使用
  • tag_...
    • 會被視為與 nametag 相關的虛擬 bone
  • h_...
    • 會被視為頭部 bone

這些不只是風格慣例；它們會影響轉換與執行時行為。

IK、null object 與 locator​

目前程式碼確認支援：

  • 將 Blockbench null object 作為 IK 控制器
  • IK 鏈 blueprint 與執行時 IK 求解
  • locator 解析

重要的實務限制：

  • IK 控制器查找依賴名稱，因此控制器命名必須在模型結構與動畫資料之間保持穩定

1.21.4+ 輸出分流​

對於 Minecraft 1.21.4+，FreeMinecraftModels 會在以下目錄產生 item model definition 檔案：

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

較舊版本仍然使用舊式 item model 路徑。如果你在製作過程中檢查產生輸出，請確認自己查看的是與伺服器版本對應的輸出形式。

Bedrock 與渲染路徑說明​

  • Bedrock 支援依賴 sendCustomModelsToBedrockClients 以及周圍的 Floodgate/Geyser/resource-pack 路徑
  • 支援版本上的 Java 用戶端在啟用 useDisplayEntitiesWhenPossible 時可以使用 display entity 渲染
  • 不要假設某個模型在 Java 用戶端上顯示正常，就一定適用於你的 Bedrock 路徑

實用製作建議​

  • 保持檔名穩定，因為它們會成為執行時 ID
  • 保持控制器與動畫命名清楚，因為 Blockbench 的動畫查找依賴名稱
  • 有意識地使用保留的 virtual bone 名稱
  • 在 /fmm reload 之後驗證匯入輸出，而不是只在 Blockbench 中檢查
  • 檢查目標 Minecraft 版本線上的產生包內容，特別是 1.21.4+

不在本頁範圍內​

本頁不嘗試保證：

  • 精確的 Blockbench UI 操作步驟
  • 藝術工作流程偏好
  • 舊本地 README 材料中提到的每一個歷史 .bbmodel 細節

這些內容變化速度比上面已驗證的執行時契約更快。