FreeMinecraftModels 資源包輸出

FreeMinecraftModels 將產生的資源包寫入 output。

預設輸出路徑

外掛在啟動時與 /fmm reload 時會重建此資料夾：

plugins/FreeMinecraftModels/output/FreeMinecraftModels

然後將該資料夾壓縮為：

plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip

當 ResourcePackManager 與 FreeMinecraftModels 整合時，預期使用的就是這個 zip 路徑。

產生過程會刪除 output 中除了上次發布的 FreeMinecraftModels.zip 以外的所有內容，然後重新建立。請將模型原始檔及其他檔案存放在此目錄之外。如果 FMM 無法清空該資料夾，產生過程會以 Failed to prepare output folder 失敗，FMM 也不會完成初始化。

產生的內容

產生過程會複製外掛附帶的資源包中繼資料、圖示和圖集，再加入已載入的模型與材質：

pack.mcmeta
pack.png
assets/minecraft/atlases/blocks.json
assets/freeminecraftmodels/... 模型與紋理輸出

附帶資源缺漏，或 FMM 無法建立某個資料夾，都會讓產生過程失敗。單一模型的檔案寫入失敗會被記錄，產生過程則繼續進行，因此除了輸出之外也請查看主控台。建立 ZIP 前，FMM 會為自己的實體材質（包括粒子材質）加入明確的圖集項目，並取代自己以實體目錄為基礎的圖集來源。其他圖集來源保持不變。讀取或寫入圖集失敗會讓產生過程失敗。

FreeMinecraftModels 會在下列路徑下產生物品模型定義檔：

assets/freeminecraftmodels/items

程式碼中仍保留供 1.21.4 之前版本使用的舊版皮革馬鎧覆寫路徑，但外掛宣告 api-version: 1.21.4，因此能載入此外掛的伺服器都不會使用該分支。

顯示模型輸出（1.21.4+）

當模型旁有有效的同名 .json 顯示模型檔案時（請參閱模型製作說明），FMM 會處理其 textures 對應表並寫入：

assets/freeminecraftmodels/models/display/{modelId}.json

它也會在下列路徑生成對應的物品定義：

assets/freeminecraftmodels/items/display/{modelId}.json

含命名空間的材質值保持不變。其他值依數字材質索引解析，無法解析時使用一個可用的已擷取材質。格式錯誤的顯示 JSON 會產生警告，且不會註冊。執行階段的登錄表讓 FMM 能將處理後的顯示模型用於物品在手中和物品欄內的外觀。

粒子精靈圖

對於模型使用的每個粒子效果，FMM 會寫入該效果的材質，並為每張精靈圖寫入一個平面物品模型：

assets/freeminecraftmodels/textures/entity/fmm_particles/{modelId}/{effect}.png
assets/freeminecraftmodels/models/particle/{modelId}/{effect}/{index}.json
assets/freeminecraftmodels/items/particle/{modelId}/{effect}/{index}.json

只有 Java 玩家會看到這些精靈圖。Bedrock 玩家則透過下方 Bedrock 套件中的原生粒子看到該效果。

ResourcePackManager 附屬檔案

FMM 會寫入一些小型 JSON 檔案，供 ResourcePackManager 在將資源包轉換為 Bedrock 格式時讀取。它們對 Java 用戶端沒有影響。

檔案	寫入時機	用途
`assets/freeminecraftmodels/rspm_item_bases/display/{modelId}.json`	模型有顯示模型，且其同名 `.yml` 設定了伺服器認得的 `material`。皮革染色後綴（例如 `LEATHER_CHESTPLATE:ff8800`）會略過此檔案	指出自訂物品所基於的原版物品（例如 `minecraft:blaze_rod`），讓 Bedrock 在正確的基底物品上顯示模型，而不是從檔名猜測
`assets/freeminecraftmodels/rspm_item_particles/display/{modelId}.json`	模型有顯示模型，以及含有粒子關鍵影格的動畫	列出 ResourcePackManager 加入該物品 Bedrock attachable 的效果、定位器與循環粒子時間軸
`assets/freeminecraftmodels/rspm_item_java_only/particle/{modelId}/{effect}.json`	模型使用了粒子效果	告知 ResourcePackManager 不要將該效果的精靈圖物品轉換為 Bedrock 自訂物品

當 particleEffectsEnabled 為 false 時，FMM 會略過 rspm_item_particles 檔案與 Bedrock 粒子檔案。Java 粒子精靈圖及其 rspm_item_java_only 檔案仍會寫入。

Bedrock 自訂實體套件

除了 Java 資源包資產，FreeMinecraftModels 也會嘗試為每個含材質的已載入模型匯出 Bedrock 自訂實體套件到：

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/rspm_bedrock_pack

每個模型會提供材質、幾何、render controller、動畫、animation controller 和實體定義，全部位於 freeminecraftmodels: 命名空間（freeminecraftmodels:<model_id>）。具有粒子效果的模型還會提供 particles/<model_id>_<effect>.json（識別碼 fmm:<model_id>_<effect>），以及在 FMM 找到效果材質時提供 textures/entity/fmm_particles/<model_id>/<effect>.png。請參閱粒子。

製作模型時請注意：

沒有材質的模型會被略過，主控台會顯示 Skipping Bedrock custom entity export for <id>: model has no textures.
Java 匯入器仍接受沒有材質的定義；略過只適用於該模型的 Bedrock 自訂實體套件項目。
Bedrock 幾何排除騎乘點骨骼（m_）、自動產生的名稱骨骼（fmm_nametag_bone_*）和 hitbox。作者建立的 tag_ 錨點仍保留在幾何中，通常不含方塊。
沒有動畫的模型仍會匯出單一 idle 動畫槽。
除非模型有超過 672 個動畫，否則模型的幾何體會掛在產生的 freeminecraftmodels_lean 骨骼上。該骨骼向 Bedrock 玩家呈現移動朝向與身體置中。含有 MoLang 關鍵影格的動畫通道會依作者寫的原樣寫入，因此由 Bedrock 客戶端求值。
Bedrock 實體執行階段的碰撞箱寬度和高度來自模型的 hitbox 骨骼；沒有該骨骼時使用 1.0 x 2.0。

空 hitbox 群組的尺寸為零，不會使用上述備用值。b_ 前綴會隱藏 Java 渲染，但不會從 Bedrock 幾何中排除對應骨骼。Bedrock 動畫匯出不會烘焙 FMM 在執行階段計算的 IK 解；請參閱動畫。匯出錯誤會寫入記錄，並可能留下不完整的套件檔案。

Bedrock 執行階段後端需要啟用名為 floodgate、Geyser-Spigot 或 Geyser 的外掛，此項檢查不區分大小寫。個別玩家偵測另行檢查 Floodgate 或 Geyser-Spigot；僅符合後端啟用條件，並不能證明玩家偵測或資源包傳送正常。在純 Java 伺服器上，FMM 仍會匯出套件檔案，但不會建立或執行該後端。

弓與弩條件性物品輸出

當 FMM 偵測到一套完整的、已載入且已註冊顯示 JSON 的弓或弩狀態模型時（請參閱模型製作說明），會以模型的基礎 ID 產生一個物品定義。該定義在用戶端切換狀態。設定的物品必須使用對應的 BOW 或 CROSSBOW 材質。

弓的輸出

對於弓，生成的物品定義在 using_item 上使用 minecraft:condition，並在 use_duration 上使用 minecraft:range_dispatch（scale 0.05）：

條件	使用的模型
不在使用該物品	`_idle`
使用中、回退（剛開始）	`_draw_start`
使用中、閾值 `0.65`	`_draw_half`
使用中、閾值 `0.9`	`_draw_full`

弩的輸出

對於弩，生成的物品定義在 charge_type 上使用 minecraft:select。當已充能（箭矢或火箭）時，它會顯示 _charged 模型。未充能的回退使用 crossbow/pull 上的 minecraft:range_dispatch：

條件	使用的模型
不在使用、未充能	`_idle`
使用中、回退（剛開始）	`_draw_start`
使用中、閾值 `0.58`	`_draw_half`
使用中、閾值 `1.0`	`_draw_full`
已充能（箭矢或火箭）	`_charged`

輸出位置

生成的條件性物品定義會寫在其他物品定義旁，位於：

assets/freeminecraftmodels/items/display/{baseModelId}.json

基礎 ID 成為公開的顯示物品。各狀態的獨立物品定義會從輸出及執行階段登錄表移除，但其顯示幾何會保留，因為條件式定義仍參照它們。

Minecraft 26.1+ 相容性修正

資源包產生器在所有支援的版本套用以下修正，包括 Minecraft 26.1 及更新版本：

UV 鉗制： 先將表面的 UV 限制在材質的 UV 範圍（0–textureWidth / 0–textureHeight），再縮放到 Minecraft 的 16x16 UV 空間。此範圍優先使用材質的 UV 中繼資料，否則使用影像尺寸或模型的備用解析度。限制負值或過大的座標可能使受影響的表面失去材質細節。
略過空骨骼和僅含錨點的骨骼： 沒有方塊的骨骼不會寫入幾何 JSON，因此若為它產生物品模型定義，就會留下失效參照。1.21.x 會忽略此問題，但 26.1+ 會逐一記錄 Missing block model: freeminecraftmodels:...。產生器現在會同時略過這類骨骼的幾何檔和物品定義。這也涵蓋僅用於碰撞的 hitbox 骨骼、tag_name 位置錨點、FMM 自動產生的 fmm_nametag_bone_*，以及純包裝或錨點骨骼。

這些修正會自動套用，無需設定。

備註

tag_ 名稱標籤錨點不需要方塊。不含方塊的錨點不會產生幾何，但僅憑此前綴不會隱藏所有含方塊的自製骨骼。名稱恰好為 tag_name 的骨骼會受到特殊處理。請參閱名稱標籤錨點。

確定性輸出

FMM 對各骨骼的物品定義及模型的 display 區塊使用保留插入順序的對應表，以減少不必要的輸出變動。ZIP 寫入器也會固定項目的時間戳記。

這並不保證 ZIP 位元組完全相同：ZIP 寫入器依檔案系統順序走訪目錄，沒有排序項目。模型、材質、顯示 JSON、設定、產生器或伺服器版本的變更，也可能合理地改變資源包。

如果資源包雜湊意外改變，除了檢查產生時的輸入，也應比較壓縮檔項目的內容與順序。僅憑重複下載無法判斷原因。

重新載入行為

執行 /fmm reload 時，FMM 先匯入內容並準備候選物品、附魔與配方目錄，同時讓目前的執行階段保持運作。如果準備失敗，就拒絕重新載入並保留目前目錄。準備成功後會：

先清除作用中的模型、擺設、偽裝、腳本執行個體、監聽器狀態和腳本冷卻儲存，再重新建立。
重新載入設定和配方。
重建 output/FreeMinecraftModels 資料夾。
重新產生 output/FreeMinecraftModels.zip。
若 ResourcePackManager 已啟用，執行 resourcepackmanager reload。
排定於 40 tick 後在主執行緒觸發 FmmReloadedEvent，讓相依外掛重新建立模型附件。

FMM 會先將壓縮檔寫入 output/FreeMinecraftModels.zip.pending，再將它移動覆蓋 FreeMinecraftModels.zip。若寫入或移動失敗，產生過程就會失敗，先前的 ZIP 則保持不變。完整的 ZIP 不代表已送達，因此也請驗證 ResourcePackManager 的傳送及用戶端接受情況。完整重新載入與匯入內容更新的差異，請參閱設定。

預設輸出路徑​

產生的內容​

顯示模型輸出（1.21.4+）​

粒子精靈圖​

ResourcePackManager 附屬檔案​

Bedrock 自訂實體套件​

弓與弩條件性物品輸出​

弓的輸出​

弩的輸出​

輸出位置​

Minecraft 26.1+ 相容性修正​

確定性輸出​

重新載入行為​