| name | rimworld-modding |
| description | RimWorld mod 制作全流程指南——覆盖环境搭建、XML Def 系统、C# 开发、Harmony 补丁、
资源制作和 Steam Workshop 发布。适用于零基础到进阶的 RimWorld 1.6 mod 开发者。
跨平台支持 Claude Code / TRAE / Copilot CLI / Codex / Gemini CLI / Cursor 等主流 AI 编程工具。
触发词：RimWorld, 环世界, rimworld, RW, mod, Mod, 模组, Def, XML, ThingDef,
Harmony, Patch, 补丁, 武器, 建筑, 物品, 生物, 植物, 派系, 事件,
Steam Workshop, 创意工坊, C#, DLL, 编译
|
RimWorld Mod 制作指南
🧠 核心决策：何时调 MCP，何时直接用模板
三层决策——每次接收 mod 制作请求时，按以下优先级判断：
用户请求
│
├─ ① 有模板？ ─── 武器/服装/建筑/资源/配方/Harmony/ThingComp
│ └─ ✅ 直接用模板生成，不调 MCP（模板已验证过原版结构）
│
├─ ② 报错/调试？ ─── 红字/白窗/崩溃/NullReferenceException
│ └─ 🔍 调 MCP 查错误原因、搜索类似问题（MCP 不可用则 grep）
│
└─ ③ 无模板的新类型？ ─── 植物/生物/派系/事件/地形/Hediff/研究...
└─ 📡 调 MCP 查原版 Def 结构 → 模仿写出 Def → 存储为新模板
模板 ↔ Def 类型对照表
| 用户需求 | 对应模板 | MCP？ |
|---|
| 近战武器 | templates/weapon-melee.xml | ❌ 免 |
| 远程武器 | templates/weapon-ranged.xml | ❌ 免 |
| 服装/护甲/头饰 | templates/apparel.xml | ❌ 免 |
| 原材料/建筑材料 | templates/resource-stuff.xml | ❌ 免 |
| 建筑/工作台 | templates/building.xml | ❌ 免 |
| 制作配方 | templates/recipe.xml | ❌ 免 |
| Harmony 补丁 | templates/harmony-patch.cs | ❌ 免 |
| C# ThingComp | templates/thingcomp.cs | ❌ 免 |
| 修改原版（XML） | references/04-xml-patching.md | ❌ 免 |
| 植物 / 生物 / 派系 / 事件 | 无模板 | 📡 MCP |
| 地形 / Hediff / 研究 / 工作 | 无模板 | 📡 MCP |
| 任何错误排查 | references/08-debugging.md | 🔍 MCP |
⚙️ RimSage MCP 配置
如果还没有配置，参考 .mcp.json.example 创建项目级配置，或运行平台对应的 MCP 添加命令。
首次索引需 30-60 分钟。详见 references/11-platform-adaptation.md。
MCP 不可用时：降级为本地 grep 搜索 RimWorld/Data/Core/Defs/。
MCP 三件套（仅在上表标明 📡 或 🔍 时使用）
| 场景 | 用这个工具 | 示例 |
|---|
| 无模板 → 查原版 Def 结构 | get_def_details | get_def_details("Plant_TreeOak") |
| 无模板 → 搜索实现模式 | search_rimworld_source | "plant def wild cluster" |
| 报错 → 查错误原因 | search_rimworld_source | "NullReferenceException food" |
新类型模板创建流程（场景 ③）
用户要求无模板类型
→ ① MCP 查原版类似 Def（get_def_details + search_rimworld_source）
→ ② 写出完整可用的 Def（带中文注释，遵循下方"模板格式规范"）
→ ③ Write 模板到文件系统（绝对路径，不能用对话中输出代替）
→ ④ 更新 SKILL.md 两处列表（见下方"存储与更新清单"）
→ ✅ 下次同类型请求直接免 MCP
📋 存储与更新清单（每次创建新模板后必须逐项完成）：
| # | 操作 | 工具 | 目标位置 |
|---|
| 1 | 写入模板文件 | Write | templates/<新类型>.xml（或用 .cs 后缀） |
| 2 | 添加到"模板 ↔ Def 类型对照表" | Edit | SKILL.md 顶部表格——新增一行，标记 ❌ 免 |
| 3 | 添加到"子文件索引 → 代码模板" | Edit | SKILL.md 底部 templates/ 列表——新增条目 |
📐 模板格式规范（Write 模板文件时必须遵守）：
<?xml version="1.0" encoding="utf-8"?> 开头（XML 模板）- 注释块（
<!-- ... -->）包含：
- 模板类型名称 + 验证状态
- 原版参考路径（哪个原版 XML 文件）
- ParentName 继承链（完整层级）
- 关键设计决策说明
- 所有用户自定义值使用
<YourXxx> 占位符（如 <YourPrefix>_Thing_<YourName>）
- 关键字段附带中文行内注释（含可选值列表/合法范围）
- 文件末尾保留一个空行
💡 模板示例参考：打开任意现有模板（如 templates/weapon-melee.xml）查看注释头和占位符风格，新模板应与之保持一致。
🧠 学习系统
每次加载此 Skill 时，必须先读取 learnings/errors.txt 中的历史错误记录，
并在后续工作中避免重复犯错。
排查完错误并修复后，必须将关键教训总结为一句话追加到 learnings/errors.txt。
格式：YYYY-MM-DD | <类别> | <一句话总结>
| 类别 | 适用场景 |
|---|
| XML | ThingDef/RecipeDef/Def 属性写错、枚举值错误、ParentName 错误 |
| C# | 编译错误、空引用、类型错误、DLL 加载问题 |
| Harmony | Patch ID 冲突、补丁未生效、Prefix/Postfix 签名错误 |
| Path | 文件路径错误、资源缺失、加载顺序问题 |
| Other | 上述类别之外的错误 |
此文件仅在 rimworld-modding skill 上下文中读取，其他场景不读取。
核心工作流：测试版先行（Test → Verify → Formalize）
所有 mod 生成后，默认先生成测试版本。开发者确认无 bug 后，再正规化并可选发布。
用户需求 → 生成测试版 Mod → 开发者进游戏测试
├─ 有 bug → 修复 → 重新测试
└─ 确认无误 → 正规化 → 可选：上传 Steam
测试版 vs 正规版：测试版快速迭代验证；正规版清理命名、补全 About.xml、准备发布。
快速导航
根据你的需求，我会自动加载对应的参考文档和模板。
我想...
| 需求 | 加载内容 |
|---|
| 🆕 新建一个 mod 项目 | workflows/new-mod.md + references/02-project-structure.md |
| ⚔️ 添加武器/物品/建筑/服装/植物 | references/03-xml-defs.md + 对应 templates/*.xml |
| 🔧 修改原版机制/打补丁 | references/04-xml-patching.md（XML）/ references/06-harmony.md（C#） |
| 💻 编写 C# 代码/DLL | references/05-csharp-basics.md |
| 🎵 用 Harmony 拦截方法 | references/06-harmony.md + templates/harmony-patch.cs |
| 🖼️ 添加纹理/音效资源 | references/07-assets.md |
| 🐛 排查报错/崩溃/红字 | references/08-debugging.md |
| 📖 查看历史错误记录 | learnings/errors.txt（自动读取） |
| ✅ 测试通过，正规化 mod | workflows/formalize-mod.md |
| 📦 批量处理多个需求 | workflows/batch-process.md + templates/requirements-template.md |
| 📦 发布到 Steam Workshop | references/09-workshop.md |
| 📖 查询 API/类/方法 | references/10-api-reference.md（建议先接入 RimSage MCP） |
| 🔄 适配其他 AI 平台 | references/11-platform-adaptation.md（Copilot/Codex/Gemini 等工具映射） |
核心原则
1. 命名规范
- 前缀：所有 defName 和 C# 类名使用唯一前缀（由用户自行选择，如
RCS_、AWE_ 等），避免 mod 冲突
- namespace：
你的前缀.Mod名（由用户根据前缀确定）
- packageId：
你的用户名.mod名（全小写，无空格，用户自行填写，如 steamid.modname）
- 作者名：所有
<author>、作者字段必须由用户自行填写，AI 不预设作者信息
2. 版本注意
- 目标版本：RimWorld 1.6
- Unity 版本：2022.3.35
- .NET Framework：4.7.2+
- 每个 reference 文件顶部标注适用版本和最后更新日期
3. 安全实践
- 始终在
[StaticConstructorOnStartup] 中初始化 Harmony
- Harmony patch 方法使用唯一的 patch ID
- ExposeData 中正确保存/加载自定义数据
- 避免在构造函数中做重型操作
- 优先使用 PatchOperations 而非直接修改原版文件
4. ⚖️ 法律边界——什么能做，什么不能
Ludeon Studios 积极支持 mod 制作——官方 Wiki 有完整 modding 教程，Steam Workshop 是官方集成渠道。但以下底线不可越过：
✅ 完全合法——放心做
| 行为 | 依据 |
|---|
| 编写原创 XML Def | RimWorld 公开数据接口 |
| 用原版 ParentName 继承 | 等同于调用公开 API |
| 模仿原版 Def 结构 | 等同于参考 API 文档 |
| 用 dnSpy / MCP 查原版代码 | mod 社区标准做法（官方 Wiki C# 教程第一页就教你用 dnSpy） |
| 发布原创 mod 到 Steam Workshop | 官方支持的发布渠道 |
❌ 绝对禁止
| 行为 | 原因 |
|---|
| 复制原版 C# 源码到你的 mod | 侵犯 Ludeon 版权 |
| 打包原版 DLL（Assembly-CSharp.dll 等）到你的 mod | 侵犯版权 |
| 复制其他 mod 的代码/资产/贴图 | 侵犯原作者权利 |
| 使用第三方 IP（宝可梦、星战、漫威等）的角色/名称/资产 | 商标/版权侵权 |
| 使用 AI 生成的、明显抄袭第三方 IP 的贴图 | 版权风险 |
⚠️ 灰色地带（允许但有风险）
| 行为 | 建议 |
|---|
| 受其他游戏启发的武器/物品（如彩虹喵喵剑 ≈ Meowmere） | ✅ 合法——灵感不侵权，名称/设计要是原创的 |
| 反编译查看原版方法签名 | ✅ 行业惯例——只查 API，不抄实现 |
| 参考原版数值（如 Gladius 伤害=16）来平衡你的武器 | ✅ 参考值范围，不直接复制 |
核心原则：你的 mod 可以模仿原版结构和 API 用法，但代码和资产必须是原创的。不确定时，问开发者确认。
4. 学习策略
- 先查速查表：
references/10-api-reference.md 覆盖高频 API
- 再看源码：优先使用 RimSage MCP 搜索 RimWorld 源码
- 模仿原版：
RimWorld/Data/Core/Defs/ 中的原版 Def 是最好的参考。优先使用 RimSage MCP 直接查询原版结构，避免凭记忆猜测 ParentName 或字段名。
5. AI 生成标注
每次生成 mod 后，必须在以下位置标注 AI 辅助生成，确保玩家可发现且不影响游戏体验：
- About.xml 的
<description> 末尾 — 添加一行 [AI 辅助生成]，玩家在 Mod 列表中查看信息时可见
- Steam Workshop 页面描述 — 在描述开头或末尾标注"本 Mod 部分内容由 AI 辅助生成"
- C# 代码文件头部注释（如 Harmony 补丁）— 添加
// AI 辅助生成，开发者审查代码时可见
- 不在 label、defName、游戏内图标等影响实际游玩体验的位置标注
6. ⚠️ 三层决策详解
① 有模板 → 直接用，不调 MCP
模板内的字段名、枚举值、ParentName 继承链、Comps 配置均已在编写时对照原版验证。直接使用模板生成，仅替换 <Your...> 占位符即可。模板是经过验证的，无须重复验证。
用户: "生成一把近战等离子剑"
→ 加载 templates/weapon-melee.xml
→ 填入用户指定的伤害/冷却/材质/科技等级
→ 直接输出 Def + 贴图路径 + 配方配置
→ 不调 MCP
② 报错/调试 → 调 MCP 查原因
当用户报告游戏内错误（红字、白窗、崩溃、异常行为）时，用 MCP 搜索错误信息、查看相关方法源码，找出根本原因。
用户: "我的 mod 报 NullReferenceException at Pawn.Tick"
→ search_rimworld_source("Pawn Tick")
→ 查相关方法签名和调用链
→ 定位问题代码 → 给出修复方案
MCP 不可用时：用 grep 搜原版 Defs 目录 + dnSpy 反编译 C#。
③ 无模板的新类型 → MCP 查 → 写 → ⚠️ 存模板
遇到模板未覆盖的 Def 类型（如植物、生物、派系等），完整流程如下：
用户: "帮我添加一种新植物"
→ ① 查对照表，确认当前无 plants.xml 模板
→ ② MCP: get_def_details("Plant_TreeOak") → 了解原版 Def 结构（字段名、继承、Comps）
→ ③ MCP: search_rimworld_source("plant def wild") → 确认关键字段的用法模式
→ ④ 根据原版结构写出完整 Def + 中文注释（遵循模板格式规范）
→ ⑤ ⚠️ Write 到 templates/plant.xml（skill 的 templates/ 目录下）
（必须用 Write 工具写入文件系统，不能在对话中输出就算完！）
→ ⑥ Edit SKILL.md 对照表：添加 `| 植物 | templates/plant.xml | ❌ 免 |`
→ ⑦ Edit SKILL.md 索引：添加 `- templates/plant.xml — 植物 Def`
→ ✅ 完成——下次遇到植物请求直接免 MCP，加载模板即可
⚠️ 关键提醒：步骤⑤（Write 文件）和⑥⑦（更新 SKILL.md）最容易遗漏！
如果只生成了 Def 但没有写入文件系统，下次同类请求时模板仍然不存在，又会重复 MCP 查询。
生成新模板 = 写入文件 + 更新 SKILL.md，缺一不可。
反面教材（RainbowCatSword 犯过的错）：
- ❌
techLevel 凭记忆写 Ultratech → 实际是 Ultra（如果先用模板就不会错）
- ❌
extraMeleeDamages 凭记忆加 Class="DamageWorker_AddInjury" → 模板已标明不需要 Class
教训：有模板就不用 MCP——模板就是为了消灭凭记忆猜测。无模板才调 MCP——查出来、写下来、存下来。
外部工具协作
优先级
① 有模板 → 直接用模板 → 不调任何外部工具
② 无模板 → MCP > grep > dnSpy
③ 有错误 → MCP > grep > dnSpy
RimSage MCP（有模板时跳过，无模板或报错时第一选择）
详见顶部"核心决策"章节。
grep（MCP 不可用时的兜底）
grep -r "extraMeleeDamages" "D:/steam/steamapps/common/RimWorld/Data/Core/Defs/" | head -10
grep -r 'Name="BaseMeleeWeapon"' "D:/steam/steamapps/common/RimWorld/Data/Core/Defs/"
grep -rh "techLevel" "D:/steam/steamapps/common/RimWorld/Data/Core/Defs/" | sort -u | head -20
dnSpy（第三选择——反编译 C# 源码）
无网络时用 dnSpy 打开 <RimWorld>/RimWorldWin64_Data/Managed/Assembly-CSharp.dll。
资源链接
子文件索引
知识参考 (references/)
references/01-environment.md — 环境搭建references/02-project-structure.md — Mod 项目结构references/03-xml-defs.md — XML Def 系统references/04-xml-patching.md — XML PatchOperationsreferences/05-csharp-basics.md — C# Mod 开发references/06-harmony.md — Harmony 补丁references/07-assets.md — 资源制作references/08-debugging.md — 调试与排错references/09-workshop.md — Steam Workshop 发布references/10-api-reference.md — API 速查表references/11-platform-adaptation.md — 跨平台适配（TRAE/Copilot/Codex/Gemini 工具映射）
代码模板 (templates/)
templates/weapon-melee.xml — 近战武器 Deftemplates/weapon-ranged.xml — 远程武器 Deftemplates/harmony-patch.cs — Harmony 补丁骨架templates/building.xml — 建筑 Def（Phase 2）templates/recipe.xml — 配方 Def（Phase 2）templates/thingcomp.cs — ThingComp 骨架templates/apparel.xml — 服装/护甲 Def（含衣物、护甲、头饰注释）templates/resource-stuff.xml — 原材料/建筑材料 Def（含 stuffProps 完整注释）templates/requirements-template.md — 批量需求文件格式模板
错误学习 (learnings/)
learnings/errors.txt — 历史错误记录（每次加载 Skill 时自动读取）
工作流 (workflows/)
workflows/new-mod.md — 从零创建 mod（测试版先行）workflows/formalize-mod.md — 测试通过后正规化 + 可选发布workflows/debug-crash.md — 崩溃排查workflows/add-item.md — 添加物品workflows/add-building.md — 添加建筑workflows/batch-process.md — 批量处理需求清单workflows/patch-vanilla.md — 修改原版
