跳至主要内容

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 副檔名
  • 使用穩定、唯一的檔案名稱，因為 ID 是指令和 API 呼叫所解析的對象
  • Blockbench 動畫參考是基於名稱的，因此模型內部的重複或不明確命名比清晰、明確的命名方案更容易造成問題

Blockbench 相容性​

  • FreeMinecraftModels 在匯入時偵測 Blockbench 檔案版本
  • 當前匯入器仍包含針對 Blockbench v5 之前版本的相容性分支
  • 如果匯入日誌顯示模型格式與 FreeMinecraftModels 不相容，請先將其視為模型格式問題，而非 wiki 或指令問題

運行時相關的骨骼命名慣例​

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

  • hitbox
    • 保留用於碰撞箱生成
    • 應該清晰地定義模型碰撞箱，而不是用作視覺骨骼
  • tag_...
    • 被視為名稱標籤相關的虛擬骨骼
  • h_...
    • 被視為頭部骨骼
  • b_...
    • 非顯示骨骼（運行時隱藏）。用於不應在遊戲中渲染的結構性或組織性骨骼。
  • m_... 或 mount_...
    • 騎乘點骨骼。帶有此前綴的每個骨骼會在模型上建立一個可騎乘的座位位置。玩家或實體可以在運行時被掛載到這些位置上。多個騎乘骨骼會建立多個座位。由 MountPointManager 內部管理。

這些不僅僅是風格慣例；它們會影響轉換和運行時行為。

IK、空物件和定位器​

當前程式碼確認支援：

  • Blockbench 空物件作為 IK 控制器
  • IK 鏈藍圖和運行時 IK 求解
  • 定位器解析

重要的實用限制：

  • IK 控制器查找是基於名稱的，因此控制器命名需要在模型結構和動畫資料之間保持穩定

1.21.4+ 輸出分割​

對於 Minecraft 1.21.4+，FreeMinecraftModels 會在以下路徑生成物品模型定義檔案：

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

較舊的版本仍使用舊版物品模型路徑。如果你在製作時檢查生成的輸出，請確保你查看的是對應你伺服器版本的正確輸出形式。

展示模型 JSON（1.21.4+）​

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

匯入時，FMM 會將此 JSON 複製到資源包輸出中，並自動將其中的裸紋理參考重寫為指向模型提取的紋理。如果不存在配套 JSON，該物品在遊戲中將顯示為普通紙張。

YML 中的自訂物品配置​

配套的 .yml 設定檔（與模型同名）現在支援可選的物品欄位。如果設定了 material:，模型也可作為自訂可手持物品使用。完整的 YML 格式如下：

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # 可選 — 設定後，模型同時成為自訂物品
name: '&b&lMy Custom Sword'  # 可選 — 顯示名稱
lore:                         # 可選
  - '&7A custom weapon'
enchantments:                 # 可選 — 格式: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

當 material: 存在時，模型會與道具一起顯示在管理員內容瀏覽器中，並可作為功能性物品給予玩家。

Bedrock 和渲染路徑注意事項​

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

實用製作建議​

  • 保持檔案名稱穩定，因為它們會成為運行時 ID
  • 保持控制器和動畫命名明確，因為 Blockbench 動畫查找是基於名稱驅動的
  • 有意識地使用保留的虛擬骨骼名稱（hitbox、tag_、h_、b_、m_、mount_）
  • 在 /fmm reload 之後驗證匯入的輸出，而不僅是在 Blockbench 內部
  • 驗證生成的資源包內容是否對應你的目標 Minecraft 版本線，特別是在 1.21.4+ 上

弓和弩狀態模型​

FMM 支援自訂弓和弩物品的自動拉弓動畫狀態。無需設定 -- 只需使用正確的後綴命名模型檔案，FMM 在資源包生成期間會自動偵測狀態集。

命名慣例​

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

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

範例檔案配置​

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- 設定使用基礎名稱，不是 _idle

對於弩，你需要新增第五個檔案 cool_bow_charged.bbmodel。

偵測機制​

  • 偵測在資源包生成時（啟動時或 /fmm reload）自動進行。
  • 只有 _idle 模型在輸出包中獲得物品定義 JSON。拉弓和裝填狀態作為該定義中的條件條目參考。
  • 只有基礎名稱獲得 YML 設定檔。對於上述範例，設定是 cool_bow.yml，而不是 cool_bow_idle.yml。

展示模型 JSON​

每個狀態模型可以有自己的配套 .json 展示模型（例如 cool_bow_idle.json、cool_bow_draw_full.json）。FMM 會自動將它們接入生成的物品定義中。有關生成的確切 JSON 結構，請參閱資源包輸出。

超出範圍​

本頁不嘗試保證：

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

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