FreeMinecraftModels

FreeMinecraftModels 既是自訂模型的執行系統，也是面向開發者的 API。

外掛提供以下功能：

• 首次設定流程，以及在設定標記為完成前顯示的登入提醒
• 使用 Nightbreak 的設定選單，用於安裝和更新官方模型包
• 在 plugins/FreeMinecraftModels/output/FreeMinecraftModels 產生資源包資料夾
• 在 plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip 產生資源包 ZIP 檔案
• 涵蓋設定、內容更新、生成、偽裝、道具及除錯的指令
• 坐騎點骨骼：名稱以 m_ 開頭的骨骼會在模型上建立座位，讓玩家騎乘自訂實體
• 自訂顯示模型 JSON：在 .bbmodel 旁放置對應的 .json 檔案（Blockbench 顯示物品匯出），以取代遊戲內物品外觀，需要 1.21.4 或更新版本
• 自訂物品與魔法武器：使用含命名空間之附魔的手持模型，以及作者定義的魔杖和法杖
• 動畫混合：idle 與 walk 交叉淡入淡出，death 淡入，攻擊則依 Blockbench 的 Override 與 Blend Weight 疊在移動之上播放，Java 與 Bedrock 玩家皆適用。請參閱動畫混合
• 轉向慣性：生物身上的模型會帶著慣性轉向，慣性大小隨模型尺寸而定。請參閱轉向慣性
• Blockbench 粒子：模型動畫中的粒子關鍵影格會在自訂實體、道具與手持物品上播放，Java 與 Bedrock 玩家皆可看到。請參閱粒子
• 管理員內容瀏覽器（/fmm admin）：依已啟用的包或資料夾顯示已載入模型和成功註冊的自訂物品
• 玩家合成選單（/fmm）：顯示已註冊的道具合成配方，包括 3x3 方格和成品；沒有註冊配方的項目不會顯示
• 玩家偽裝系統：/fmm disguise <model> [player]、/fmm undisguise [player]、/fmm disguiselist，並提供第三方外掛可用的公開 DisguiseAPI
• 家具商店：選用的 Vault 商店 /fmm shop，販售用於放置道具的紙物品。透過各配方的 shopEnabled / shopPrice 設定；停用配方註冊後，有效的商店項目仍可保留
• 玩家 UI API：Lua 腳本可以向玩家顯示 Boss 血條、動作列和標題
• LocationAPI：第三方外掛可註冊地城偵測器和保護提供者，供 FMM 的 Lua 條件 em.location.is_in_dungeon / em.location.is_protected 及受保護區域的道具放置檢查使用
• 遊戲內更新記錄：有未讀的 FreeMinecraftModels 版本說明時，管理員會在登入時收到提醒，並可透過 /freeminecraftmodelschangelog 查看
• 內容修復：/fmm forcereinstallcontent <package|all> 重新下載顯示為最新的內容，用於恢復損壞或遺失的檔案
• 免重啟的外掛更新：/fmm applypluginupdate 或 nightbreak.applyPluginUpdatesWithoutRestart 設定可在伺服器運作時換上已下載的外掛 jar。請參閱配置
• 電影模式：/fmm filmic on|off 或 filmicMode 會將每位玩家已載入區塊中的所有已載入模型傳送給該玩家，即使不在視線內也一樣，供 ReplayMod 錄影使用。請參閱配置

FreeMinecraftModels 宣告 api-version: 1.21.4，因此 Minecraft 1.21.4 是最低支援的伺服器版本。

從這裡開始

• 安裝設定

• 內容包

• 指令

• 配置

• 玩家偽裝

• 家具商店

• 資源包輸出

• 模型製作說明

• 動畫

• API 與開發者指南

• 常見問題

• Lua：入門

• Lua：道具 API

• Lua：範例

• Lua：疑難排解

Lua 腳本

FreeMinecraftModels 透過 MagmaCore 2.0 腳本引擎為道具提供 Lua 支援。腳本位於 plugins/FreeMinecraftModels/scripts/。

有效道具鉤子（8 個）

道具腳本可回應下列鉤子：

鉤子	觸發時機
on_spawn	道具生成到世界中，或隨其區塊再次載入
on_game_tick	道具存在期間的每個遊戲 tick
on_zone_enter	玩家進入腳本建立並監控的區域
on_zone_leave	玩家離開腳本建立並監控的區域
on_destroy	道具被永久移除（區塊卸載或重新載入時不會觸發）
on_left_click	玩家左鍵點擊道具
on_right_click	玩家右鍵點擊道具
on_projectile_hit	投射物擊中道具

道具腳本收到 context.prop 表格，包含 model_id、current_location 等欄位，以及 play_animation(name)、stop_animation() 等方法。

物品效果

裝備物品的 Lua 腳本已停用。手持物品現在使用作者定義的附魔，魔杖和法杖使用魔法武器定義。不要在手持物品定義中加入 scripts:。

目前說明

• 外掛內建的 Nightbreak 官方託管包：Basic Furniture Pack、BetterStructures Prop Pack、EliteMobs Prop Pack、Craftenmine's Weapons Item Pack 和 Craftenmine Tools Item Pack。
• 完整初始化成功後會重新產生資源包，並安排在 40 ticks 後傳送 FmmReloadedEvent，供相依外掛重新連結模型。如果重新載入在準備階段遭拒，則保留目前的執行狀態。
• ResourcePackManager 可以自動分發產生的資源包。請檢查輸出檔案及客戶端實際接受的情況；設定完成標記或已安裝包標記不能證明資源包已送達。