PeakCustomItemMod

劉澤銘的奇思妙想（PEAK 自定義物品模組）

原名「PEAK 自定義物品」。本模組基於 BepInEx 5 + PEAKLib，在運行時克隆遊戲已有道具並註冊爲自定義物品。

不需要 Unity / AssetBundle——純 C# + JSON 配置 + PNG 貼圖即可造物。

一、模組功能（Features）

• 配置驅動造物：寫一份 itemconfig.json + 放幾張 PNG，遊戲裏就出現對應道具，無需寫代碼、無需重新編譯。
• 生成概率可控（可繼承模板）：每個物品可單獨設生成概率（0~100%）；缺省時自動沿用模板物品的世界生成概率（如野生狗奶沿用"奶白金"的稀有度權重）。
• 模板材質導出：dumpTemplateTexture: true 會在遊戲啓動後把模板的原生 3D 貼圖 / 背包圖標導出爲 PNG，供你照着描圖，描完再把 texture/icon 指向新圖。
• 機制字段：removeActions（移除模板繼承的食用動作）、addActions（添加食用動作）、cooking（烹飪行爲）、petrifyBomb（石化炸彈）等。
• 可選集成 PEAK_MENU_CN（拓展但不依賴）：裝了菜單會自動把新物品加進它的生成主列表；沒裝則靜默跳過，模組其它功能照常。
• 中文物品名顯示（拓展功能）：見第四節。讓 PEAK_MENU_CN 的物品列表優先顯示中文，而不是英文預製體名。
• 遊戲內編輯器（F11）：常駐 UI，可實時調整/預覽物品配置。
• 石化炸彈管理器：常駐計時器，物品被食用銷燬後效果仍繼續。
• 聯機支持：房主同步生成，非房主等待房主廣播，單機/聯機都穩定。

二、如何部署（Deployment）

前置依賴

• BepInEx 5（BepInExPack_PEAK）——模組運行框架。
• PEAKLib.Core + PEAKLib.Items（com.github.PEAKModding.PEAKLib.*.dll）——社區 API，已隨包提供。
• （可選）PEAK_MENU_CN：用於遊戲內物品菜單拿取自定義物品 + 中文顯示。

文件夾結構

模組整體放進 BepInEx/plugins/ 下的任意子文件夾（ 風格，BepInEx 遞歸掃描）。一個物品一個文件夾：

BepInEx/plugins/

└── createitem/ ← 模組文件夾（DLL + 各物品文件夾）

├── PeakCustomItemMod.dll ← 模組本體

├── README.md ← 本說明

├── WildDogMilk/ ← 物品文件夾（文件夾名 = 註冊名）

│ ├── itemconfig.json ← 這個物品的配置（只含 1 條）

│ ├── WildDogMilk.png ← 3D 模型貼圖（可選）

│ └── WildDogMilk_icon.png ← 背包圖標（可選）

└── /...

部署步驟

• 安裝 BepInEx 5（把 BepInEx 解壓到 PEAK 遊戲根目錄，確保生成 PEAK/BepInEx/）。
• 把上面的 createitem/ 整個文件夾複製到 PEAK/BepInEx/plugins/。
• 確認 PEAKLib.Core.dll / PEAKLib.Items.dll 也在 BepInEx/plugins/（隨包自帶）。
• 啓動遊戲 → 進一局，配置的道具按 spawnChance 概率出現在玩家面前；或在 PEAK_MENU_CN 菜單裏拿取。

驗證

看遊戲目錄 BepInEx/LogOutput.log，出現類似日誌即成功：

[Info:劉澤銘的奇思妙想] 劉澤銘的奇思妙想 已加載（...配置條目數: 1）

[Info:劉澤銘的奇思妙想] 已註冊新道具: WildDogMilk (顯示名: 野生狗奶, 模板: FortifiedMilk)

[Info:劉澤銘的奇思妙想] 已在玩家面前生成 1 個自定義道具

三、如何添加新物品（Add a new item）

• 建物品文件夾

在 createitem/ 下新建 /，名字用英文、唯一，同時作爲註冊名。

• 寫 itemconfig.json

貼圖文件名相對本文件夾，支持 // 與 / / 註釋。最小示例（野生狗奶）：

{

"items": [

{

"name": "WildDogMilk", // 註冊名（英文，唯一，= 文件夾名）

"displayName": "野生狗奶", // 遊戲內顯示名（物品提示/屬性面板）

"templateMatch": "contains", // 模板匹配方式：exact(精確) / contains(包含) / tag(標籤)

"templateValue": "milk", // 模板關鍵詞（如 "Energy Drink" / "milk" / "Berry"）

"spawnChance": null, // null = 沿用模板稀有度；寫 0~100 才覆蓋

"spawn": true, // 是否在玩家面前生成（false 則只註冊進列表）

"dumpTemplateTexture": false, // true = 啓動後導出模板原圖供描圖（描完改回 false）

"texture": "WildDogMilk.png", // 3D 模型貼圖（留空 = 繼承模板）

"icon": "WildDogMilk_icon.png", // 背包圖標（留空 = 繼承模板）

"removeActions":, // 移除模板繼承的食用動作（按需）

"addActions":, // 添加食用動作（ModifyStatus/RestoreHunger/ApplyAffliction...）

"cooking": null, // 烹飪行爲（Explode/ChangeAfflictionTime...）

"petrifyBomb": null // 石化炸彈（baseDuration/buffAfflictions...）

// "behavior": "" // 已廢棄，留空即可（沿用模板行爲）

}

]

}

• 標準流程（每次加物品照做）
• 建 / 文件夾 + itemconfig.json。
• 用 templateMatch + templateValue 指向遊戲內模板道具（決定外觀/基礎行爲）。
• spawnChance: null 沿用模板稀有度；想固定概率就寫數值。
• 首次想要自定義貼圖：設 dumpTemplateTexture: true → 進遊戲 → 自動導出 _template_source.png + _template_icon_source.png → 照着畫 → 把 texture/icon 指向新 PNG → dumpTemplateTexture 改回 false。
• （可選）用 addActions/removeActions/cooking/petrifyBomb 調整機制。
• 重啓遊戲生效（開啓 liveReloadTexture 後改 PNG 可熱更新材質，無需重啓）。

參考範本：createitem/WildDogMilk/（petrifyBomb + 烹飪爆炸 + addActions 裝飾，配置最全）。

四、新物品漢化（顯示中文 / Localization）

爲什麼物品可能是英文？

PEAK_MENU_CN 的物品列表默認顯示英文預製體名（如 Glizzy、RopeCannon）。本模組用 ChineseDisplayNameIntegration（見 ChineseNameMap.cs / ChineseDisplayNameIntegration.cs）給它的顯示方法打補丁，讓列表優先顯示中文。該補丁純反射、不引用 PEAK_MENU_CN 程序集，PEAK_MENU_CN 沒裝時自動跳過，不影響本模組任何功能。

內置物品 → 設遊戲語言即可

把遊戲語言設爲簡體中文，絕大多數內置物品會直接走遊戲自帶翻譯（item.GetName()），無需任何配置。

自定義物品 → 在映射表裏加一條

打開 plugin/ChineseNameMap.cs，在 Map 裏按物品的運行時 GameObject 名（通常就是 itemconfig.json 的 name 字段）加一行：

{ "WildDogMilk", "野生狗奶" },

然後重新編譯部署（見第五節）。補丁的三級回落邏輯：

• 自帶中文映射表（命中即顯示，如上面的 WildDogMilk → 野生狗奶）
• 其次 遊戲內置中文 item.GetName()（遊戲語言爲簡體中文時）
• 最後回落英文預製體名

沒生效怎麼辦（調試）

如果加了映射表仍顯示英文，多半是鍵名與實際 GameObject 名不符。確認方法：

• 看 BepInEx/LogOutput.log 裏本模組生成自定義物品的日誌，其中會打印 prefab 名（形如 Mr.PeakCustomItems:WildDogMilk）；
• 或看 BepInEx/ItemDump.txt，搜你的物品，看 prefab= 後的實際名；
• 把 Map 的鍵改成那個實際名即可。

五、遷移到其他編程工具 / 重新編譯（Build & Migrate）

源碼在 p