FreeMinecraftModels 配置

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

檔案位置

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

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

config.yml 設定

setupDone

• 預設：false
• 控制首次設定引導是否視為完成
• 在此值仍為 false 時，擁有廣泛 FreeMinecraftModels 權限的玩家會收到執行 /fmm initialize 的提醒
• 設定流程會替你切換此值；正常引導期間你不需要手動編輯

useDisplayEntitiesWhenPossible

• 預設：true
• 告訴 FreeMinecraftModels 在伺服器與客戶端路徑支援時優先使用 display entity 渲染
• 當 display entity 不可用時（早於 1.19.4 或 Bedrock），外掛仍會回退到 armor stand 顯示
• Bedrock 客戶端屬於特殊情況，所以不要假設這會強制每位玩家走相同的渲染路徑

maxModelViewDistance

• 預設：60
• 限制模型化實體被傳送給觀看者的距離
• 較低的值可以減少在模型密集區域的封包與客戶端渲染負擔
• 個別實體可以在執行階段透過 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 在執行階段切換，因此絕不會意外地在正式環境保持啟用。請參閱指令

shop_config.yml

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

頂層鍵

鍵	預設	說明
enabled	false	/fmm shop 的主開關。只有當此值為 true 且 Vault 與經濟提供者皆存在時，該指令才會註冊
defaultPrice	100.0	在下次載入時寫入未設定自己 shopPrice 的配方檔的價格
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 中可見。shopEnabled: false 的配方仍可合成但永遠不會被列出販售
shopPrice	來自 shop_config.yml 的 defaultPrice	此特定物品的 Vault 貨幣成本

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

權限

在 plugin.yml 中註冊

權限	預設	說明
freeminecraftmodels.*	op	萬用字元，授予 admin + 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 bedrock、/fmm setup、/fmm initialize、/fmm downloadall、/fmm updatecontent）改為檢查萬用字元 freeminecraftmodels.*
freeminecraftmodels.disguise.self	op	允許對發送者本人使用 /fmm disguise / /fmm undisguise
freeminecraftmodels.disguise.others	op	允許指定目標的偽裝／取消偽裝，以及 /fmm disguiselist
freeminecraftmodels.menu	true	存取 /fmm 可合成物品選單
freeminecraftmodels.shop	true	存取 /fmm shop

由指令強制執行（未在 plugin.yml 中註冊）

權限	預設	說明
freeminecraftmodels.deleteall	op	存取 /fmm deleteall（由指令處理器在執行階段檢查）

模型 YML 配置

每個 .bbmodel 檔案都可以有一個同伴 .yml 檔案（同名、同目錄），用於控制特定模型的設定。統一的 YML 格式支援下列欄位：

isEnabled: true
voxelize: true
solidify: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in ice"
  - "&7Deals frost damage"
enchantments:
  - SHARPNESS,3
  - UNBREAKING,2

欄位	類型	說明
isEnabled	boolean	模型是否會被載入（預設：true）
scripts	字串列表	要附加的 Lua 腳本檔名（位於 plugins/FreeMinecraftModels/scripts/）
voxelize	boolean	為 true 時，道具會對齊到 90 度旋轉增量，並在放置時對齊方塊網格。佔地面積由模型的碰撞箱尺寸計算（四捨五入到整方塊）。放置會檢查佔地面積中所有方塊是否為非固體
solidify	boolean	為 true（需要 voxelize: true）時，會在道具佔地面積的每個方塊上放置僅封包的屏障方塊，為其提供客戶端碰撞。這些屏障是不可見的，僅存在於封包中 — 並不會放置到世界中。屏障會在道具被拾起或銷毀時自動移除
material	string	Bukkit 材質名稱（例如 DIAMOND_SWORD、PAPER）。設定後，模型會成為玩家可手持與裝備的自訂物品
name	string	自訂物品的顯示名稱（支援 & 顏色代碼）
lore	字串列表	自訂物品的物品說明行（支援 & 顏色代碼）
enchantments	字串列表	附魔，格式為 ENCHANTMENT_NAME,LEVEL（例如 SHARPNESS,3）

當 material 被設定時，模型會被註冊為自訂物品。玩家可以透過 /fmm giveitem 取得，如果有配置配方則可合成，並可使用全部 22 個 Lua 物品鉤子。

運作說明

• /fmm reload 會重新匯入內容並重新生成輸出資源包，所以影響渲染行為的配置變更最容易在重新載入後驗證。每次重新載入都會派發 FmmReloadedEvent，讓相依的外掛可以重新繫結其模型附件。
• FreeMinecraftModels 只負責生成資源包，並不會自行託管。
• ResourcePackManager 仍然是 Java 客戶端的建議傳遞路徑，也是混合配置下最安全且有文件記錄的路徑。
• WorldGuard、WorldEdit、GriefPrevention 和 Vault 在 plugin.yml 中宣告為 softdepend — 任一項都不是啟動外掛所必需的，但在存在時會解鎖特定功能（保護感知的 Lua 判斷以及家具商店）。

何時要變更這些值

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

• 使用 /fmm initialize、/fmm setup、/fmm downloadall 與 /fmm updatecontent 進行官方包的生命週期工作
• 使用 imports 資料夾進行手動 .bbmodel 或其他本機內容匯入工作
• 在需要調整渲染模式、可視距離、互動距離或 Bedrock 行為時使用 config.yml
• 使用 shop_config.yml（以及每個配方的 shopEnabled/shopPrice 欄位）來調整家具商店，無需碰程式碼

已知注意事項

• Bedrock 行為同時取決於 sendCustomModelsToBedrockClientsV2 以及你更廣泛的 Floodgate/Geyser/資源包設定，所以除非你已測試過你的確切堆疊，否則請保守地說明。
• 如果 Vault 或經濟提供者缺失，商店會默默地自我停用。如果 /fmm shop 意外缺失，請使用 /fmm version 並檢查啟動時的主控台。