刘泽铭的奇思妙想（PEAK 自定义物品模组）

原名「PEAK 自定义物品」。本模组基于 BepInEx 5 + PEAKLib，在运行时克隆游戏已有道具并注册为自定义物品。 不需要 Unity / AssetBundle——纯 C# + JSON 配置 + PNG 贴图即可造物。

---

一、模组功能（Features）

1. 配置驱动造物：写一份 itemconfig.json + 放几张 PNG，游戏里就出现对应道具，无需写代码、无需重新编译。
2. 生成概率可控（可继承模板）：每个物品可单独设生成概率（0~100%）；缺省时自动沿用模板物品的世界生成概率（如野生狗奶沿用"奶白金"的稀有度权重）。
3. 模板材质导出：dumpTemplateTexture: true 会在游戏启动后把模板的原生 3D 贴图 / 背包图标导出为 PNG，供你照着描图，描完再把 texture/icon 指向新图。
4. 机制字段：removeActions（移除模板继承的食用动作）、addActions（添加食用动作）、cooking（烹饪行为）、petrifyBomb（石化炸弹）等。
5. 可选集成 PEAK_MENU_CN（拓展但不依赖）：装了菜单会自动把新物品加进它的生成主列表；没装则静默跳过，模组其它功能照常。
6. 中文物品名显示（拓展功能）：见第四节。让 PEAK_MENU_CN 的物品列表优先显示中文，而不是英文预制体名。
7. 游戏内编辑器（F11）：常驻 UI，可实时调整/预览物品配置。
8. 石化炸弹管理器：常驻计时器，物品被食用销毁后效果仍继续。
9. 联机支持：房主同步生成，非房主等待房主广播，单机/联机都稳定。

---

二、如何部署（Deployment）

前置依赖

• BepInEx 5（BepInExPack_PEAK）——模组运行框架。
• PEAKLib.Core + PEAKLib.Items（com.github.PEAKModding.PEAKLib.*.dll）——社区 API，已随包提供。
• （可选）PEAK_MENU_CN：用于游戏内物品菜单拿取自定义物品 + 中文显示。

文件夹结构

模组整体放进 BepInEx/plugins/ 下的任意子文件夹（Thunderstore 风格，BepInEx 递归扫描）。一个物品一个文件夹：

BepInEx/plugins/
└── createitem/                      ← 模组文件夹（DLL + 各物品文件夹）
    ├── PeakCustomItemMod.dll       ← 模组本体
    ├── README.md                   ← 本说明
    ├── WildDogMilk/                ← 物品文件夹（文件夹名 = 注册名）
    │   ├── itemconfig.json         ← 这个物品的配置（只含 1 条）
    │   ├── WildDogMilk.png         ← 3D 模型贴图（可选）
    │   └── WildDogMilk_icon.png    ← 背包图标（可选）
    └── <其它物品>/...

部署步骤

1. 安装 BepInEx 5（把 BepInEx 解压到 PEAK 游戏根目录，确保生成 PEAK/BepInEx/）。
2. 把上面的 createitem/ 整个文件夹复制到 PEAK/BepInEx/plugins/。
3. 确认 PEAKLib.Core.dll / PEAKLib.Items.dll 也在 BepInEx/plugins/（随包自带）。
4. 启动游戏 → 进一局，配置的道具按 spawnChance 概率出现在玩家面前；或在 PEAK_MENU_CN 菜单里拿取。

验证

看游戏目录 BepInEx/LogOutput.log，出现类似日志即成功：

[Info   :刘泽铭的奇思妙想] 刘泽铭的奇思妙想 已加载（...配置条目数: 1）
[Info   :刘泽铭的奇思妙想] 已注册新道具: WildDogMilk (显示名: 野生狗奶, 模板: FortifiedMilk)
[Info   :刘泽铭的奇思妙想] 已在玩家面前生成 1 个自定义道具

---

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

1. 建物品文件夹

在 createitem/ 下新建 <ItemName>/，名字用英文、唯一，同时作为注册名。

2. 写 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": ""               // 已废弃，留空即可（沿用模板行为）
    }
  ]
}

3. 标准流程（每次加物品照做）

1. 建 <ItemName>/ 文件夹 + itemconfig.json。
2. 用 templateMatch + templateValue 指向游戏内模板道具（决定外观/基础行为）。
3. spawnChance: null 沿用模板稀有度；想固定概率就写数值。
4. 首次想要自定义贴图：设 dumpTemplateTexture: true → 进游戏 → 自动导出 <name>_template_source.png + <name>_template_icon_source.png → 照着画 → 把 texture/icon 指向新 PNG → dumpTemplateTexture 改回 false。
5. （可选）用 addActions/removeActions/cooking/petrifyBomb 调整机制。
6. 重启游戏生效（开启 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", "野生狗奶" },

然后重新编译部署（见第五节）。补丁的三级回落逻辑：

1. 自带中文映射表（命中即显示，如上面的 WildDogMilk → 野生狗奶）
2. 其次 游戏内置中文 item.GetName()（游戏语言为简体中文时）
3. 最后回落英文预制体名

没生效怎么办（调试）

如果加了映射表仍显示英文，多半是键名与实际 GameObject 名不符。确认方法：

• 看 BepInEx/LogOutput.log 里本模组生成自定义物品的日志，其中会打印 prefab 名（形如 Mr.PeakCustomItems:WildDogMilk）；
• 或看 BepInEx/ItemDump.txt，搜你的物品，看 prefab= 后的实际名；
• 把 Map 的键改成那个实际名即可。

---

五、迁移到其他编程工具 / 重新编译（Build & Migrate）

源码在 plugin/ 目录，用 Visual Studio / Rider / VS Code + C# 插件 / 任意支持 .NET 的工具打开 PeakCustomItemMod.csproj 即可。

编译要求

• .NET SDK 8（仅用于编译；运行时仍是游戏自带的 Unity Mono）。
• 目标框架 netstandard2.1。
• 不依赖 NuGet：所有引用都是游戏本地 DLL（PeakCustomItemMod.csproj 里用绝对路径指向 PEAK/PEAK_Data/Managed 与 PEAK/BepInEx/core、PEAK/BepInEx/plugins）。换机器时只需把这两个路径改成本机 PEAK 安装路径。

编译与自动部署

cd plugin
dotnet build -c Debug

编译完成后 csproj 会自动：

1. 把新 PeakCustomItemMod.dll 复制到 PEAK/BepInEx/plugins/createitem/；
2. 运行 tools/SyncAndPack.ps1 重打包迁移 ZIP（PEAK自定义物品模组-迁移包-自动生成.zip）。

⚠️ 迁移禁忌：不要改 GUID

Plugin.cs 里的 [BepInPlugin("Mr.PeakCustomItems", "刘泽铭的奇思妙想", "1.10.30")] 中：

• 第二个参数（显示名） 随便改，就是你在模组列表/日志里看到的名字（本模组已改成"刘泽铭的奇思妙想"）。
• 第一个参数 Mr.PeakCustomItems（GUID）切勿随意更改！ 它是网络预制体 ID 前缀（Mr.PeakCustomItems:WildDogMilk）和 itemID 的生成依据，还被写进 PEAK_MENU_CN 的配置标记与你已有的游戏存档。改 GUID 会让旧存档里的自定义物品全部失效、与菜单集成断裂。 改名只改显示名即可。

文件清单（plugin/）

文件	作用
Plugin.cs	模组入口（注册/生成轮询、F11 编辑器、石化炸弹管理器、中文显示集成挂载）
ChineseDisplayNameIntegration.cs	中文显示补丁（反射打 PEAK_MENU_CN，含强制刷新）
ChineseNameMap.cs	中文映射表（自定义物品汉化在这里加条目）
Items/	物品注册/配置加载/贴图导出/编辑器/石化炸弹等核心逻辑
PeakCustomItemMod.csproj	工程文件（netstandard2.1，本地 DLL 引用）

---

六、卸载

删除 BepInEx/plugins/createitem/ 整个文件夹即可，不影响游戏与其它模组。