FreeMinecraftModels 家具商店

如需僅允許購買，請在 config.yml 中設定 registerCraftingRecipes: false 並重新啟動。有效且啟用的項目仍留在商店目錄中，但會從 Bukkit 合成和玩家的 /fmm 可合成物品選單中移除。此設定預設為 true。

FreeMinecraftModels 內建一個可選的 Vault 支援商店，讓玩家可以用遊戲內貨幣購買可合成的道具。商店預設為停用 — 只有在明確啟用且有可用的 Vault 經濟提供者時，才會註冊自己。

快速設定

安裝 Vault 與相容 Vault 的經濟提供者（EssentialsX、CMI 等）。
啟動伺服器一次，以生成 plugins/FreeMinecraftModels/shop_config.yml。
在 shop_config.yml 中設定 enabled: true。
重新啟動伺服器或成功完成 /fmm reload；商店在完整初始化時註冊。
在遊戲中執行 /fmm shop 以確認選單已開啟。

缺少任何前提條件時，商店子指令都不會註冊，因此其處理器不會使用可設定的停用訊息。如果商店已啟用但缺少 Vault 或其經濟提供者，FMM 會記錄具體警告。

運作方式

商店從 plugins/FreeMinecraftModels/recipes/ 讀取配方。
商店列出已載入且符合 isEnabled: true 和 shopEnabled: true 的配方。配方會作為單一目錄載入：YAML 語法錯誤、同一 model_id 有兩個啟用的配方檔案，或伺服器拒絕某個配方，都會讓整個目錄載入失敗，而不只是少掉一個項目，因此請在 /fmm reload 後查看主控台。停用合成時，註冊仍會建立並驗證配方
每個項目使用紙製展示物品，在可用時顯示模型外觀，並附有價格、購買提示及模型 ID。購買後取得模型的紙製放置物品；這條路徑不會根據 material: 和附魔建立作者定義的武器
點擊項目會呼叫 PurchaseHandler，它會透過 Vault 檢查玩家的餘額、扣除價格，並將放置物品交給玩家。無法放入物品欄的物品會被丟在玩家腳邊。

權限

權限	預設	說明
`freeminecraftmodels.shop`	`true`	開啟商店所需。預設為 `true`，讓每位玩家都可瀏覽

僅有權限本身並不會啟用商店 — 在 shop_config.yml 中設定 enabled: true 與一個運作中的經濟提供者仍然是必要條件。

`shop_config.yml`

請參閱配置頁面以取得完整的鍵參考。主要的鍵有：

enabled — 主開關（預設 false）
defaultPrice — 缺少 shopPrice 的配方所用預設值；非正數會改用 100.0。修改它不會取代現有配方價格
menuTitle、priceLoreFormat、clickToBuyLoreFormat — 視覺風格
messages.* — 五個可自訂的回饋訊息

所有訊息字串都支援 & 顏色代碼以及配置參考中列出的佔位符。

每個配方的欄位

plugins/FreeMinecraftModels/recipes/<model_id>.yml 中的每個配方都帶有兩個商店專屬欄位：

isEnabled: true
model_id: "wooden_chair"
shape:
  - "L L"
  - "LLL"
  - "L L"
ingredients:
  L: OAK_LOG
shopEnabled: true
shopPrice: 250.0

欄位	預設	行為
`shopEnabled`	`true`	為 `false` 時隱藏購買。合成仍取決於配方啟用狀態及 `registerCraftingRecipes`
`shopPrice`	來自 `shop_config.yml` 的 `defaultPrice`	玩家點擊物品時的 Vault 貨幣成本

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

購買結果

PurchaseHandler 識別七種結果。前五種對應到 shop_config.yml 中可設定的訊息；兩種發放失敗的訊息則是固定的：

結果	觸發條件	訊息鍵
`SUCCESS`	扣款成功且物品放入了物品欄	`messages.purchaseSuccess`
`SUCCESS_WITH_OVERFLOW`	扣款成功，但物品必須丟在玩家腳邊	`messages.purchaseSuccess` + `messages.inventoryFull`
`INSUFFICIENT_FUNDS`	玩家餘額低於價格，或底層的經濟提供者拒絕扣款	`messages.insufficientFunds`
`NOT_FOR_SALE`	配方已停用、設為 `shopEnabled: false`，或其模型未載入	`messages.itemNotForSale`
`SHOP_DISABLED`	商店設定或快取的 Vault 鉤子回報停用	`messages.shopDisabled`
`DELIVERY_FAILED_REFUNDED`	扣款成功但發放失敗，且未發放的金額已退還	固定：`The item could not be delivered. The undelivered amount was refunded.`
`DELIVERY_FAILED_REFUND_PENDING`	扣款成功但發放失敗，且退款失敗或無法讀取已發放的數量	固定：`The purchase could not be settled. The shop has been disabled; contact an administrator to review your payment.`

請使用有限且非負的 shopPrice。購買處理器在呼叫 Vault 前不會驗證這些價格。扣款遭拒的回應會傳回 INSUFFICIENT_FUNDS，但這裡不會捕捉扣款期間的提供者例外。鉤子在初始化時快取提供者，不會持續偵測其移除。

若扣款後發放時拋出例外，FMM 會計算這筆購買有多少已進入物品欄或掉落在地上，並將其餘部分的價格存回。若該退款失敗，或無法讀取已發放的數量，FMM 會停用商店，並記錄 [FMM Shop] Disabled after unresolved purchase，附上玩家 UUID 與需要核對的金額。商店會保持停用，直到你處理完這筆款項並執行 /fmm reload。

疑難排解

/fmm shop 不存在。 商店未註冊。請驗證以下三項：

已安裝 Vault
已註冊經濟提供者（執行 /balance 或 /eco 以確認有提供者回應）
shop_config.yml 中 enabled: true

然後重新啟動伺服器或完成 /fmm reload。匯入器觸發的僅內容重新載入不會重新初始化商店設定或註冊其指令。

我預期看到的物品在選單中遺失。 在 plugins/FreeMinecraftModels/recipes/ 中開啟配方檔。檢查 isEnabled 與 shopEnabled 是否皆為 true。編輯後執行 /fmm reload。

玩家被扣款但沒有取得物品。 檢查玩家腳邊是否有因物品欄滿而掉落的物品，並查看點擊時的主控台。扣款遭拒的回應會傳回 INSUFFICIENT_FUNDS；扣款期間提供者拋出的例外不會轉換成該結果。發放失敗時會記錄 [FMM Shop] Item delivery failed，並附上已發放數量與退款資訊。若主控台顯示 [FMM Shop] Disabled after unresolved purchase，代表退款未成功：請手動處理該筆款項，保留主控台日誌及提供者的交易證據，然後執行 /fmm reload 重新啟用商店。

快速設定​

運作方式​

權限​

shop_config.yml​

每個配方的欄位​

購買結果​

疑難排解​