FreeMinecraftModels 配置

此頁面涵蓋當前 config.yml 與 shop_config.yml 中會對設定、渲染、玩家互動以及可選家具商店產生實質影響的設定。

檔案位置

plugins/FreeMinecraftModels/config.yml
plugins/FreeMinecraftModels/shop_config.yml

shop_config.yml 會在首次執行時生成；商店本身在你選擇啟用前都會保持停用。

最低伺服器版本

plugin.yml 宣告 api-version: 1.21.4，因此 Minecraft 1.21.4 是支援的最低伺服器版本。對更舊版本線的支援已移除；舊有的渲染／輸出分支雖仍存在於程式碼中，但在能夠載入此外掛的伺服器上已經不可能被觸及。

config.yml 設定

setupDone

• 預設：false
• 控制首次設定引導是否視為完成
• 此值為 false 時，擁有 freeminecraftmodels.* 的玩家每次登入約10秒後，若仍在線上，就會收到提醒
• 開啟 /fmm setup 會為整個伺服器儲存 true 並停止後續提醒。選擇 /fmm initialize 的完成項目也會儲存此值；它不能證明資源包已安裝或已傳送至用戶端

nightbreak.autoDownloadPluginUpdates

• 預設：false
• 共用的 MagmaCore 設定（位於 config.yml 的 nightbreak: 區段下）
• 為 true 時，FreeMinecraftModels 會在啟動時自動下載可用的外掛 jar 更新以及內容更新檔案
• 下載的外掛和內容更新只會在伺服器重啟後套用
• 自動下載外掛需要有效的 Nightbreak 帳號權杖以及有效的支持者 Patreon 會籍。若兩者不齊備，請將此值保持為 false，改用遊戲內的更新按鈕
• 自動內容更新針對已安裝的內容包，並延後重新載入。這不等於用 /fmm downloadall 安裝所有可存取的內容包。可透過 /fmm setup 或手動切換

useDisplayEntitiesWhenPossible

• 預設：true
• 告訴 FreeMinecraftModels 在伺服器與客戶端路徑支援時優先使用 display entity 渲染
• 設為 false 會讓 Java 用戶端以盔甲座渲染骨骼。保留的 1.19.4 之前的舊分支不代表支援舊伺服器
• 啟用 Bedrock 模型且原生自訂實體橋接可用時，Bedrock 玩家會使用該顯示方式。否則，其骨骼渲染路徑使用盔甲座。此設定不會強制每位玩家使用相同後端

maxModelViewDistance

• 預設：60
• 設定一般觀看距離上限。在模型稀少的世界中，小於10格的近距離例外會略過距離與遮蔽檢查，因此低於10的值在這些世界中不是嚴格上限
• 較低的值可以減少在模型密集區域的封包與客戶端渲染負擔
• 個別實體可以在執行階段透過 ModeledEntity.setViewDistanceOverride(int) 覆寫此值 — 請參閱 API 指南

maxInteractionAndAttackDistance

• 預設：3
• 適用於靜態與動態模型化實體
• 用於執行階段互動與命中偵測檢查

maxInteractionAndAttackDistanceForProps

• 預設：6
• 適用於道具實體
• 此值與靜態／動態實體的互動距離分開

sendCustomModelsToBedrockClientsV2

• 預設：true
• 控制 FreeMinecraftModels 是否嘗試將自訂模型傳送給 Bedrock 客戶端
• 此鍵取代了較舊的 sendCustomModelsToBedrockClients（其預設為 false）。重新命名為 V2 會翻轉預設值，使 Bedrock 玩家預設就能看到模型；如果你之前曾明確設定舊鍵，可以刪除它，新的 V2 鍵會接管
• 如果停用，Bedrock 玩家會回退到底層的原版實體（如果存在），偽裝對他們不會渲染
• 如果啟用，請確保你的 Bedrock/Geyser/Floodgate 資源包路徑確實已為這些客戶端準備好
• Bedrock 診斷日誌並非設定鍵。請用 /fmm debug bedrock on|off 切換，並在收集證據後明確關閉。/fmm reload 不會重設此旗標，重新啟動伺服器才會。請參閱指令

skipUnchangedBoneUpdates

• 預設：true
• 為 true 時，若追蹤的轉換沒有超出比較容差，便略過骨骼的移動與中繼資料更新。展示實體骨骼追蹤位置、旋轉和縮放；盔甲座骨骼追蹤位置和旋轉
• 靜止骨骼通常略過這些更新，但染色等明確標記為已變更的狀態會強制重新傳送
• 定期完整同步仍會修正用戶端偏差；此選項不會抑制所有類型的模型封包
• 只有為了除錯而想恢復舊的「每 tick 一律重送每個骨骼」行為時，才把它設為 false

useDeltaMetadataPackets

• 預設：true
• 為 true 時，display-entity 模型骨骼的每 tick 中繼資料封包只會傳送有變動的值（骨骼的轉換），而不是每 tick 重新序列化整個 item-display 資料塊（物品模型 + 自訂模型資料）
• 玩家第一次看到某個模型時以及週期性重新同步時，仍會傳送完整狀態
• 設為 false 可為了除錯或比較而恢復舊的「每 tick 完整快照」行為

maxModelsForProximityOverride

• 預設：25
• 近距離可見性覆寫的偽負載平衡器
• 一般情況下，距離玩家小於10格的模型會略過用於選擇觀看者的距離和遮蔽檢查；其他可見性規則仍然適用
• 在密集區域（例如多層樓的 NPC 中樞），該覆寫會把玩家實際上看不見的數十個模型 —— 在其他樓層、在牆後 —— 變成每 tick 都要發送封包的觀看者
• 當某個世界中載入的模型數達到此值時，該世界會停用近距離例外。即使很近，也必須通過設定的距離和可見性檢查。可見性檢查取樣模型中心與碰撞箱角點；沒有碰撞箱則通過檢查。模型稀少的世界保留例外
• 此判定是以世界為單位而非全域，因此擁擠的中樞世界不會拖累安靜的世界
• 把它調得非常高可實質恢復永遠覆寫的行為；設為 0 則一律要求視線
• /fmm packetdebug 是用來測量效果的預期工具 —— 請參閱指令

preventPropPlacementInProtectedRegions

• 預設：true
• 為 true 時，FreeMinecraftModels 會詢問 MagmaCore 已註冊的保護提供者：這位特定玩家是否可以在該道具將佔用的格子中建造，若答案為否則拒絕該次放置
• 擁有 freeminecraftmodels.bypassregionprotection 權限（預設：op）的玩家略過這項 FMM 保護檢查。空間檢查與其他外掛的限制仍然有效
• 內建的玩家權限提供者支援 WorldGuard 與 GriefPrevention，其他外掛也可註冊提供者。提供者拒絕或出錯都會拒絕放置；MagmaCore 也會拒絕受保護位置擁有者涵蓋的地點。沒有拒絕的提供者，也沒有受保護擁有權時，此檢查不增加限制
• 拒絕訊息為 You don't have permission to place a model here!

提供者檢查這位玩家能否建造，因此領地成員身分可能允許放置。受保護位置擁有權是另一項檢查，沒有針對玩家的豁免。這是在查詢已註冊的整合，並非模擬原版方塊放置事件，所以不能重現所有外掛的放置規則。

每次放置都會進行單格檢查；體素化道具還會額外進行一次全體積檢查：

道具類型	檢查的格子
一般（自由形式）道具	與被點擊方塊面相鄰的單一格子 —— 也就是該道具將佔用的格子
voxelize: true 道具	先檢查同一個相鄰格子，接著檢查該道具在格線對齊放置點周圍旋轉後佔用範圍（寬 x 高 x 深）中的每一個格子。只要該體積中任何一格不可用，整次放置就會被拒絕

體積檢查存在的原因是體素化道具可能寬達數格，若只檢查被點擊的格子，玩家就能跨在領地邊界上把大型道具丟進別人的建築裡。它在空間檢查之後執行，因此當佔用範圍實體受阻時，Not enough space to place this model! 仍優先。

檢查範圍使用 Math.round 對碰撞箱各維度取整，最小為一格。封包屏障範圍使用 ceil(size - 0.4)，因此可能不同；放置檢查並不保證涵蓋與用戶端每個碰撞格完全相同的範圍。

備註

查詢提供者之前會先檢查權限。授予 freeminecraftmodels.bypassregionprotection 可讓管理人員免於 FMM 的保護檢查，同時為其他玩家保留此設定。它不會略過空間檢查，也不會撤銷其他外掛取消的事件。

registerCraftingRecipes

• 預設：true
• 如需僅允許購買，請設為 false 並重新啟動。有效且已啟用的配方項目仍留在商店目錄中，但 Bukkit 合成配方會被移除
• 玩家的 /fmm 可合成物品選單與配方詳情要求配方實際註冊，因此關閉合成的項目不會顯示在這些選單中
• 單個配方的 isEnabled: false 會將它從已載入目錄中移除，包括商店。shopEnabled: false 僅隱藏購買項目

shop_config.yml

可選的 Vault 支援家具商店有自己的設定檔，可以獨立於主外掛行為來啟用或調整。如果 Vault 或經濟提供者缺失，商店將拒絕註冊。

頂層鍵

鍵	預設	說明
enabled	false	/fmm shop 的主開關。只有當此值為 true 且 Vault 與經濟提供者皆存在時，該指令才會註冊
defaultPrice	100.0	缺少 shopPrice 的配方所用預設價格；非正數會改用 100.0。修改此預設值不會改變已儲存的配方價格
menuTitle	&8FMM - Furniture Shop	商店物品欄頂部顯示的標題（支援 & 顏色代碼）
priceLoreFormat	&7Price: &e{price}	附加到每個商店物品上顯示其價格的物品說明行。佔位符：{price}
clickToBuyLoreFormat	&aClick to purchase	附加到每個商店物品上提示購買的物品說明行

訊息鍵（messages.*）

所有訊息字串都支援 & 顏色代碼。

鍵	預設	佔位符
messages.purchaseSuccess	&aPurchased &f{item} &afor &e{price}&a. Balance: &e{balance}&a.	{item}、{price}、{balance}
messages.insufficientFunds	&cYou need &e{price} &cto buy &f{item}&c. Balance: &e{balance}&c.	{item}、{price}、{balance}
messages.shopDisabled	&cThe furniture shop is currently unavailable.	無
messages.itemNotForSale	&cThat item is not currently for sale.	{item}
messages.inventoryFull	&eYour inventory was full; &f{item} &ehas been dropped at your feet.	{item}

每個配方的商店欄位

plugins/FreeMinecraftModels/recipes/<model_id>.yml 中的每個配方檔案都會獲得兩個額外欄位：

欄位	預設	說明
shopEnabled	true	此配方是否在 /fmm shop 中顯示。false 本身不會停用合成；配方啟用狀態與 registerCraftingRecipes 仍然適用
shopPrice	來自 shop_config.yml 的 defaultPrice	此特定物品的 Vault 貨幣成本

配方建構器（/fmm craftify）在儲存時會寫入這兩個欄位，所以調整價格只需要編輯一下文字檔。

權限

在 plugin.yml 中註冊

權限	預設	說明
freeminecraftmodels.*	op	萬用字元，授予 admin、deleteall、self/others 偽裝以及區域保護繞過權限
freeminecraftmodels.admin	op	存取 /fmm admin（管理員內容瀏覽器）和 /fmm giveitem。其他管理／除錯指令（/fmm location、/fmm spawn、/fmm mount、/fmm itemify、/fmm craftify、/fmm reload、/fmm stats、/fmm hitbox visualize、/fmm debug、/fmm packetdebug、/fmm setup, /fmm initialize、/fmm recommendedplugins、/fmm downloadall、/fmm downloadallcontent、/fmm updatecontent、/fmm downloadpluginupdate、/fmm forcereinstallcontent）改為檢查萬用字元 freeminecraftmodels.*
freeminecraftmodels.deleteall	op	萬用字元的子權限；存取 /fmm deleteall
freeminecraftmodels.disguise.self	op	允許對發送者本人使用 /fmm disguise / /fmm undisguise
freeminecraftmodels.disguise.others	op	允許指定目標的偽裝／取消偽裝，以及 /fmm disguiselist
freeminecraftmodels.bypassregionprotection	op	略過 FMM 的放置與互動保護檢查，包括啟用 preventPropPlacementInProtectedRegions 時；不覆寫其他外掛的事件取消或空間要求
freeminecraftmodels.menu	true	存取 /fmm 可合成物品選單
freeminecraftmodels.shop	true	存取 /fmm shop
nightbreak.login	op	由 MagmaCore 註冊，而非由 plugin.yml 註冊。共享的 /nightbreaklogin 與 /nightbreaklogout 指令需要此權限

模型 YML 配置

模型的配套 .yml 與 .bbmodel 使用相同基本名稱並位於同一目錄。道具與手持物品使用不同的設定部分。

道具

isEnabled: true
voxelize: true
solidify: true
scripts:
  - my_prop.lua

欄位	說明
isEnabled	是否啟用定義；預設為 true
scripts	來自 plugins/FreeMinecraftModels/scripts/ 的獨立道具 Lua 腳本
voxelize	按方塊網格及90度增量對齊放置和旋轉，並檢查旋轉後整個佔用範圍的可用空間
solidify	配合體素化傳送僅存在於封包中的屏障方塊，提供用戶端碰撞；它們不是世界方塊，會隨道具一同移除

手持物品

isEnabled: true
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in ice"
enchantments:
  - "minecraft:sharpness,3"
  - "minecraft:unbreaking,2"

material 選擇 Bukkit 物品材質，註冊手持物品而不是道具。name 和 lore 支援顏色代碼。附魔使用帶命名空間的小寫 ID 及正整數等級。透過 /fmm giveitem <id> 或管理員選單取得已註冊物品。道具配方和商店建立的是紙製放置物品，並非這裡由作者定義的手持物品。

更新相容性

裝備物品的 Lua 腳本已停用。手持物品定義若包含非空的 scripts:、SHARPNESS,3 等無命名空間的舊附魔，或伺服器上不可用的材質，會被略過並輸出診斷。FMM 不會更改作者檔案。請移除舊物品腳本繫結，透過附魔定義撰寫效果；道具腳本仍受支援。

魔杖和法杖請新增魔法武器定義。不要把武器行為放進道具腳本或已停用的物品鉤子。

運作說明

• /fmm reload 先匯入並驗證作者定義的物品和附魔，同時維持目前目錄運作。驗證失敗會拒絕重新載入；成功後則完整重新初始化，包括 config.yml、shop_config.yml、配方、模型及資源包輸出。同時發起的初始化或重新載入要求會被拒絕
• 完整初始化成功後會安排在40 tick 後發出 FmmReloadedEvent，供相依外掛重新繫結模型附件。匯入器觸發的較小範圍內容重新載入也會在成功時發出事件，但不重新載入主設定、商店設定或配方登錄表。如果該內容路徑清空運作中的登錄表後失敗，FMM 會被停用；驗證遭拒不等於重新載入完成
• 卸載世界時，FMM 移除道具的執行階段模型，保留持久化的底層盔甲座。重新載入這些實體時，會去除重複並還原道具。這不同於永久拾取或銷毀道具
• FreeMinecraftModels 只負責生成資源包，並不會自行託管。
• ResourcePackManager 仍然是 Java 客戶端的建議傳遞路徑，也是混合配置下最安全且有文件記錄的路徑。
• 產生的資源包是位元組穩定的，因此從未變動的模型集合重新產生會得到完全相同的 zip 與 SHA1。這正是 ResourcePackManager 能夠略過多餘重新上傳的原因。請參閱資源包輸出。
• WorldGuard、WorldEdit、GriefPrevention、Vault、floodgate 和 Geyser-Spigot 在 plugin.yml 中宣告為 softdepend。WorldGuard 與 GriefPrevention 提供內建保護查詢；WorldEdit 不是獨立的保護提供者。Vault 加經濟提供者可啟用商店。對應的 Bedrock 顯示方式需要用戶端辨識、渲染橋接和資源包傳遞都可用

何時要變更這些值

請將此設定用於執行階段行為調整，而非內容包管理。

• 使用 /fmm setup、/fmm downloadall 與 /fmm updatecontent 進行官方包的生命週期工作
• 使用 imports 資料夾進行手動 .bbmodel 或其他本機內容匯入工作
• 在需要調整渲染模式、可視距離、互動距離、Bedrock 行為、區域保護強制執行或自動更新下載時使用 config.yml
• 在模型密集的世界中，使用 skipUnchangedBoneUpdates、useDeltaMetadataPackets 與 maxModelsForProximityOverride 進行封包／頻寬調校。這三者的預設值都是已最佳化的行為；false 或極高的設定是為了除錯與 A/B 比較而存在，並非建議的正式環境數值
• 使用 shop_config.yml（以及每個配方的 shopEnabled/shopPrice 欄位）來調整家具商店，無需碰程式碼

已知注意事項

• Bedrock 行為同時取決於 sendCustomModelsToBedrockClientsV2 以及你更廣泛的 Floodgate/Geyser/資源包設定，所以除非你已測試過你的確切堆疊，否則請保守地說明。
• 如果商店已啟用但缺少 Vault 或經濟提供者，商店仍不可用，並會在啟動時記錄具體警告。/fmm version 只會報告外掛版本；/fmm shop 缺失時請檢查這些警告。