# MOD 开发教程 · Chronicle of the Immortal Clan

> 版本 **0.1.41·《天命·兑现》** · MOD_SCHEMA_VERSION = 1 · 全口纯 JSON（零脚本）
> **本教程即全部所需**：你不需要读任何源码或类型文件——所有 MOD 能用的字段、取值、默认值、坑点、示例都写在下面。
> 照例动手即可：最快 5 分钟做出你的第一个 MOD。

---

## 目录

- [0. 先读这两句（最重要）](#0-先读这两句最重要)
- [1. 五分钟上手](#1-五分钟上手)
- [2. MOD 包结构总览](#2-mod-包结构总览)
- [3. 能力一：事件（events）](#3-能力一事件events)
- [4. 能力二：世界模板（npcs）](#4-能力二世界模板npcs)
- [5. 能力三：生成词库（worldgen）](#5-能力三生成词库worldgen)
- [6. 能力四：灾因（calamities）](#6-能力四灾因calamities)
- [7. 能力五：丹方（pills）](#7-能力五丹方pills)
- [8. 能力六：铸器配方（forges）](#8-能力六铸器配方forges)
- [9. 能力七：世界数值（worldNum）](#9-能力七世界数值worldnum)
- [9.5 内容面扩展（物品/功法/建筑/职事/志向/阵型/性格）](#95-内容面扩展物品功法建筑职事志向阵型性格)
- [9.6 数值 patch 层](#96-数值-patch-层)
- [10. 速查表：内置 id 大全](#10-速查表内置-id-大全)
- [11. 排错 FAQ](#11-排错-faq)
- [12. 进阶：依赖、冲突与导出](#12-进阶依赖冲突与导出)
- [13. 官方范例（可拆解学习）](#13-官方范例可拆解学习)

---

## 0. 先读这两句（最重要）

1. **MOD 是纯 JSON，零脚本**。没有代码、没有沙箱、没有 eval——永远不会"写挂"游戏本体。装错了最多报"校验失败"，把文件删了就好。
2. **MOD 只影响新开档**。旧档的世界是"既成事实"——开档后世界自然演化不受 MOD 回溯；卸载只还原 MOD 造成的**机制**（词库/灾因/配方/数值/注入条目），不会回滚世界历史。想验证 MOD 效果，**务必新开档**。

### 零 B 君护航：安装即校验

每个 MOD 在安装前都会过一遍 `validateMod` 预检（0.1.28 起）——不对的地方会在安装界面提示原因（不装也不崩）。安全的数值区间：

| 项目 | 安全区间 | 违例后果 |
|---|---|---|
| `id` | `[a-z0-9-]`，长 2~32 | 解析失败（拒绝） |
| 事件 id | 全局唯一（与内置、其它 MOD 都不撞） | 安装被拒并报冲突名 |
| 模板 `initialPower` | 60~400 | warning（仍可装） |
| 事件 `weight` | 0~100 | warning |
| 丹方等级 | 1~5 | warning |
| 功法 `expBonus` | ≤ 0.5 | warning |
| 功法 `powerBonus` | ≤ 1 | warning |
| patch `mult` | 0.5 ~ 2（或 add 实数，二选一） | 拒绝 |
| 材料成本 | ≥ 0 | warning |

> **不碰任何 `rng` 字段**：MOD 里没有随机数的概念——所有随机数值（事件抽签、天气、掉落）一律由游戏引擎生成，你只挂牌子。

---

## 1. 五分钟上手

### 第 1 步：放文件

在你的游戏用户目录下建 `mods` 文件夹（没有就建一个），把 MOD 文件放进去：

```
Windows: %APPDATA%/Electron/mods/
Linux:   ~/.config/Electron/mods/
macOS:   ~/Library/Application Support/Electron/mods/
```

文件要求：
- 后缀 `.json` 或 `.cotymod`（两种都行，内容完全一样；`.cotymod` 只是"已打包分享"的惯例）
- 文件名只用 `[a-z0-9-]`（建议与 MOD `id` 同名：`hello-world.json`）——**勿用中文/大写/空格/点**（点留给后缀）

### 第 2 步：复制这个文件

最小可用 MOD（直接存为 `hello-world.json`）：

```jsonc
{
  "id": "hello-world",                        // 唯一 id（[a-z0-9-]，2~32 长度）
  "name": "你好世界",                          // 显示名（随便写中文）
  "version": "1.0.0",                          // 版本（改动必升——读档重装按 id+version 匹配）
  "schema": 1,                                 // 范式版本（当前 = 1；缺失会提示但可加载）
  "author": "你的名字",                         // 建议填（玩家辨识）
  "description": "我的第一个 MOD：家族来了一位卖豆腐的老伯。",
  "kind": "content",                           // content|data|rules（仅设置页归类展示）
  "data": {}
}
```

> **`data` 为空 = 这个 MOD 什么都不会改**。想改世界的活往下看 §3~§9.6，往 `data` 里加键。

### 第 3 步：装上看效果

游戏内 → **设置 → MOD 层 → 扫描目录** → 列表里出现 `hello-world.json` → 点 **安装** → 提示"MOD 安装完成"，插件表格里出现 `MOD·你好世界 v1.0.0 · content · 你的名字`。

**想立刻看到效果**？把这个最小模版换一个真的能动的版本（§3 完整的"卖豆腐的"事件示例），或直接装官方范例（§13），新开一局去"天下"面板找痕迹。

---

## 2. MOD 包结构总览

### 2.1 顶层字段

| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `id` | ✅ | string | 全局唯一标识（`[a-z0-9-]`，2~32 长度）——安装/卸载/读档重装全靠它 |
| `name` | ✅ | string | 中文显示名 |
| `version` | ✅ | string | 语义化版本（改内容必升——读档重装要求同 id 同版本） |
| `schema` | 建议 | number | 范式版本 = 1（写 `1` 即可；缺失会有提示，不影响安装） |
| `author` | 建议 | string | 作者名 |
| `description` | 可选 | string | 一句话介绍（显示在列表） |
| `gameVersion` | 可选 | string | 为哪个游戏版本写的（仅展示） |
| `kind` | 可选 | string | `content`（剧情/风物）\| `data`（新实体）\| `rules`（数值规则）——仅分类展示 |
| `depends` | 可选 | string[] | 依赖的 MOD id（先装依赖，未装 → 拒绝） |
| `conflicts` | 可选 | string[] | 相斥的 MOD id（对方已装 → 拒绝） |
| `data` | ✅ | object | **全部功能键的入口**（下表） |

### 2.2 `data` 十五口全景

| 分组 | 口 | 章节 | 一句话 | 卸载后 |
|---|---|---|---|---|
| 世界侧 | `events` | §3 | 随机剧情事件（抽签进族中日常/家国大事/乾坤造化） | 从事件池摘除 |
| 世界侧 | `npcs` | §4 | 世界模板（新档世界生成候选家） | 模板池摘除 |
| 世界侧 | `worldgen` | §5 | 词库（姓氏/地域/风格/后缀） | 词库池按来源摘除 |
| 世界侧 | `calamities` | §6 | 灾因（旱灾/涝灾/蝗灾/疫病/兽潮/寒潮 之外的自家灾年） | 灾因表按名摘除 |
| 世界侧 | `worldNum` | §9 | 世界常数覆写（供需/池深/潮汐/灾年概率……） | 复位 |
| 配方 | `pills` | §7 | 丹方（丹房等级门槛+材料+灵石） | 丹方表摘除 |
| 配方 | `forges` | §8 | 铸器配方（灵矿+兽核+灵石→兵刃） | 配方表摘除 |
| 内容面 | `items` | §9.5 | 物品表新条目（资源/材料/丹药/符箓/灵酿/兵器六类） | 从数据包摘除 |
| 内容面 | `techniques` | §9.5 | 功法（含四流派效果） | 注入条目按 id 摘除 |
| 内容面 | `buildings` | §9.5 | 建筑（产线/功能类） | 从建筑表摘除 |
| 内容面 | `posts` | §9.5 | 职事（坊市入息等加成） | 摘除 |
| 内容面 | `aspirations` | §9.5 | 志向（修为/战斗/市贸/产田/生育/声望） | 摘除 |
| 内容面 | `formations` | §9.5 | 阵型（攻击/防御/撤退伤） | 摘除 |
| 内容面 | `traits` | §9.5 | 性格（修为/突破/战力/魅力/售价加成） | 摘除 |
| 内容面 | `wonders` | §9.7 | 世界奇观类型（零 rng 种子派生选取——自定义奇观加入年首判定池） | 摘除 |
| 微调 | `patch` | §9.6 | 对**已存在**表项改数值（mult 或 add）——不改结构只改数 | 按插件归属复原 |

### 2.3 一个"五脏俱全"的示意壳（啃编排用）

```jsonc
{
  "id": "shiyi-quan",
  "name": "示意全包",
  "version": "0.1.0",
  "schema": 1,
  "author": "示例",
  "kind": "data",
  "data": {
    "events":        [ /* §3 */ ],
    "npcs":          [ /* §4 */ ],
    "worldgen":      { /* §5 */ },
    "calamities":    [ /* §6 */ ],
    "pills":         [ /* §7 */ ],
    "forges":        [ /* §8 */ ],
    "worldNum":      { /* §9 */ },
    "items":         [ /* §9.5 */ ],
    "techniques":    [ /* §9.5 */ ],
    "buildings":     [ /* §9.5 */ ],
    "posts":         [ /* §9.5 */ ],
    "aspirations":   [ /* §9.5 */ ],
    "formations":    [ /* §9.5 */ ],
    "traits":        [ /* §9.5 */ ],
    "wonders":       [ /* §9.7 */ ],
    "patch":         [ /* §9.6 */ ]
  }
}
```

---

## 3. 能力一：事件（events）

**这是什么**：剧情触发器。安装后进入游戏随机事件池，按 `category` 分成三类池子，每月抽签；命中的事件弹出一道"选择"（Modal），你为玩家准备 1~4 个选项，每个选项有不同的**效果**。

**什么时候发生**：事件池抽签（日常/大事/造化各自独立）；`weight` 越大越容易被抽到；`once` 事件发生后永不再来；`cooldown` 是冷却月数。

### 3.1 事件字段表

```jsonc
{
  "id": "ev-senlin",             // 唯一 id（禁止与内置/已装 MOD 撞）
  "name": "森林深处",             // 显示名
  "category": "daily",           // daily(族中日常) | major(家国大事) | fate(乾坤造化)
  "weight": 10,                  // 池内绝对权重 0~100（建议 3~25）
  "once": false,                 // 是否全游戏只发生一次（默认 false）
  "cond": {                      // 触发条件（全部满足才可能被抽到；整段可选）
    "minYear": 3,                // 年份下限
    "minRep": 20,                // 声望下限
    "minBuilding": { "id": "danfang", "level": 2 }   // 建筑等级要求
  },
  "text": "……",                  // 正文（事件描述，写小说家一点）
  "options": [ /* §3.2 */ ]
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 唯一（小写字母/数字/连字符/下划线） |
| `name` | string | 标题（显示在事件框顶部） |
| `category` | string | `daily` 族中日常（常见）\| `major` 家国大事（中频）\| `fate` 乾坤造化（稀有） |
| `weight` | number | 池内权重（0~100）。同池内按比例抽签 |
| `once` | boolean | true=一生一次（之后 `completedEvents` 不再抽） |
| `cond` | object | 触发条件（见 §3.3 全表——不写=无条件） |
| `text` | string | 正文 |
| `options` | array | 选项（1~4 个） |

### 3.2 选项数组

```jsonc
"options": [
  {
    "label": "换！",                       // 选项按钮文字
    "hint": "灵草-5，聚气丹+1",             // 选项小字提示（建议写人话）
    "eff": { "res": { "lingcao": -5 }, "pillGain": { "pill-qiyuan": 1 } },
    "note": "（可写一段结算后的话）"         // 可选
  },
  { "label": "送他些斋饭", "hint": "灵石-10，声望+2", "eff": { "res": { "stones": -10 }, "rep": 2 } },
  { "label": "赶走", "hint": "无", "eff": {} }
]
```

### 3.3 触发条件（cond）全表

一个事件可以同时用多个键（全部满足才算"命中"）；也支持组合：

| 键 | 写法 | 含义 |
|---|---|---|
| `minYear` / `maxYear` | `10` / `50` | 年份窗口（避免开局就出某些事件） |
| `minGeneration` | `3` | 代数下限 |
| `minHeadRealm` | `"core"` | 家主最低境界（取值见 §4.1 境界表） |
| `minBuilding` | `{ "id": "danfang", "level": 2 }` | 某建筑至少到某级 |
| `minRep` / `maxRep` | `20` / `80` | 声望窗口 |
| `minResource` | `{ "id": "lingcao", "n": 100 }` | 库存下限 |
| `minAdult` / `maxAdult` | `4` / `8` | 成年（16+）人数窗口 |
| `minMembers` | `10` | 总人口下限 |
| `eligibleAdult` | `3` | 可婚配（未婚成年）下限 |
| `relation` | `{ "npcId": "n-danxin", "gt": 30 }` | 与某天下家关系（gt/lt 可只用其一） |
| `flag` | `{ "key": "someKey", "eq": true }` | 家族旗标匹配（详见 §3.5 旗标） |
| `hasMeditation` | `true` | 有一人正在闭关（冥想） |
| `noWarForYears` | `2` | 未被袭击至少 N 年 |
| `minTechCount` | `3` | 已藏功法数下限 |
| `all` / `any` / `not` | `[Cond]` / `[Cond]` / `Cond` | 组合词：全满足/任一满足/取反（可嵌套） |

### 3.4 选项效果（eff）全表

| 键 | 类型 | 写法示例 | 含义 |
|---|---|---|---|
| `res` | object | `{ "stones": 50, "lingcao": -3 }` | 资源增减（§10 资源 id；数量可为负——**减不得超库存**） |
| `rep` | number | `4` | 家族声望 ± |
| `relation` | object | `{ "n-danxin": 5, "n-nulei": -8 }` | 对某几家 +关系-关系（世界家 id §10） |
| `addBuilding` | string | `"lingtian"` | 白得一座建筑（§10 建筑 id） |
| `memberBy` | object | `{ "by": "heal", "target": "youngest" }` | 对族人施加随机/指定一人的效果（§3.5 详解） |
| `pillGain` | object | `{ "pill-qiyuan": 1 }` | 直接获得丹药（§10 丹 id） |
| `mission` | string | `"m-anmoku"` | 触发该秘境任务（§10 秘境 id） |
| `raid` | object | `{ "npcId": "n-nulei" }` | 某天下家来犯（袭击事件） |
| `flag` | object | `{ "myFlag": true }` | 设家族旗标（可被 cond 读取/其它事件调用） |
| `techniqueChance` | number | `0.3` | 概率获得一部功法（0~1） |
| `artifactChance` | number | `0.3` | 概率获得一件兵器 |
| `addTech` | string | `"t-baihui"` | 直接获得指定功法（§10 功法 id） |
| `feisheng` | object | `{ "stay": false }` | 触飞升剧情（stay=false 是强者飞升/留下） |
| `tournament` | boolean | `true` | 触发五年大比 |
| `formation` | string | `"vanguard"` | 指定阵型 |
| `apprentice` | object | `{ "build": true }` | 触发求经台/寄读 |
| `trib` | object | `{ "memberId": "x1", "mode": "rash" }` | 指定成员渡劫（rash 硬渡/guard 护法/delay 压制） |

> **一个选项可同时写多个效果键**——例如 `{ "res": {...}, "rep": 4, "relation": {...} }` 三合一。无效果就 `{}`。

### 3.5 族人效果（memberBy）详解

```jsonc
"memberBy": { "by": "heal", "target": "youngest", "n": 5 }
```

| `by`（做什么） | 含义 |
|---|---|
| `exp` | 修为增加（`n` 为月量） |
| `wound` | 受伤（`n` 为伤量） |
| `heal` | 治疗（`n` 为疗量） |
| `breakthrough` | 触发一次突破判定 |
| `fatal` | 直接陨落（慎用！） |
| `repGain` | 个人修善声望 |
| `inspire` | 士气/励族 |
| `loot` | 个人得货 |
| `madness` | 心智失乱 |
| `genius` | 天骄之资（稀有待遇） |

| `target`（对谁） | 含义 |
|---|---|
| `random` | 随机一人 |
| `head` | 家主 |
| `youngest` | 最年幼 |
| `oldest` | 最年长 |
| `highestPerception` | 悟性最高 |
| `highestPower` | 战力最高 |
| `highestFortune` | 气运最高 |
| `all` | 全体族人 |

### 3.6 完整示例（可直接用）

```jsonc
{
  "id": "ev-doufu",
  "name": "豆腐老伯",
  "category": "daily",
  "weight": 12,
  "once": true,
  "cond": { "minYear": 2, "minRep": 10 },
  "text": "天还没亮，一名挑着豆腐担的老伯在祖宅门外叫卖。他说祖上受过先辈恩惠，今日来谢——不收钱，只求族人尝尝他的手艺。",
  "options": [
    { "label": "尝一碗", "hint": "灵草+3，声望+2",
      "eff": { "res": { "lingcao": 3 }, "rep": 2 } },
    { "label": "请他进屋喝口茶", "hint": "灵石-20，封藏一部功法（20% 得《百草经》）",
      "eff": { "res": { "stones": -20 }, "techniqueChance": 0.2 } },
    { "label": "送他几册农书", "hint": "灵草-5，信任+1",
      "eff": { "res": { "lingcao": -5 }, "flag": { "doufuTrust": true } } }
  ]
}
```

> `flag` 用法进阶：A 事件设 `flag: { "doufuTrust": true }` → B 事件条件写 `cond: { "flag": { "key": "doufuTrust", "eq": true } }`——做成"系列剧情"。

> **例行检查**：事件 id 别撞内置（内置事件在 `src/renderer/game/data/events.ts`——最省事办法是懒人前缀：`ev-mymod-`）。

---

## 4. 能力二：世界模板（npcs）

**这是什么**：新档世界生成时的**候选家族池**。worldgen 每次开档按池子凑 4~8 家（名册随机）——你的模板**有机会**被选中入世，一旦选中，它将作为 NPC 家族参与天下演化（贸易/结盟/袭扰/换代/覆灭）。

**什么时候生效**：只在新世界生成时（模板会参与）。开档后天下家已定——不会再变（世界形成为档记录）。

### 4.1 字段表

```jsonc
{
  "id": "n-cangwu",                 // 唯一（同样 [a-z0-9-]）
  "name": "苍梧氏",                  // 家名
  "region": "南岭苍梧",              // 地域（显示/影响区域风味）
  "style": "剑修世家",               // 风格（世界词库 styles 也可以是候选；这里写死）
  "desc": "苍梧山下养剑人家，锋芒内敛而傲骨铮铮。",
  "leaderRealm": "foundation",       // 家主境界（见下表）
  "initialPower": 180,              // 起始实力 60~400
  "powerGrowth": [3, 9],           // 每年实力成长区间 [min,max]
  "sells": ["pill-qiyuan"],         // 入市售品（§10 资源/成品 id）
  "buys": ["lingcao", "beastcore"]  // 入市求购
}
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `id` | ✅ | 唯一 |
| `name` | ✅ | 中文家名 |
| `region` | ✅ | 地域（新贵世代可用 woldgen `regions` 词库——你家取现成地域也行） |
| `style` | ✅ | 风格（标注型；剑修/丹道/商盟/兵修…） |
| `desc` | ✅ | 简介 |
| `leaderRealm` | ✅ | 家主境界：`mortal` 凡 / `qi` 炼气 / `foundation` 筑基 / `core` 金丹 / `nascent` 元婴 / `spirit` 化神 |
| `initialPower` | ✅ | 实力 60~400 |
| `powerGrowth` | ✅ | [min,max] 年成长（min ≤ max） |
| `sells` | 可选 | 售品（API：入市即贸易表） |
| `buys` | 可选 | 求购（同上） |

### 4.2 境界取值（全游戏通用 `REALMS`）

| 值 | 中文 | 年寿元 |
|---|---|---|
| `mortal` | 凡人 | 75 |
| `qi` | 炼气 | 150 |
| `foundation` | 筑基 | 220 |
| `core` | 金丹 | 340 |
| `nascent` | 元婴 | 520 |
| `spirit` | 化神 | 850 |

（对外只写大境界；小境界炼气 0~8 层随数值演化由引擎管理。）

### 4.3 完整示例

```jsonc
{
  "id": "n-juemai", "name": "绝脉氏", "region": "北原寒漠", "style": "兵修门阀",
  "desc": "荒原上以猎妖为生的铁血之家，活人于死地，出手绝不留情。",
  "leaderRealm": "core", "initialPower": 210, "powerGrowth": [3, 10],
  "sells": ["shoupi", "beastcore"], "buys": ["lingcao", "lingkuang"]
}
```

---

## 5. 能力三：生成词库（worldgen）

**这是什么**：四组**名字/风味池**——开档时世界从池子抽组合（家姓×地域×风格×后缀），决定"天下名卷"的自然涌现感。

```jsonc
"worldgen": {
  "styles": ["丹道世家", "商盟", "猎妖门"],   // 家族风格词
  "regions": ["江南烟雨畔", "北疆雪原"],       // 地域词
  "fams": ["吴", "江", "雨"],                 // 姓氏
  "suffixes": ["宗", "门", "寨"]              // 家名后缀（家族名 = 姓+后缀）
}
```

| 池 | 含义 | 示例 |
|---|---|---|
| `styles` | 家族风格（影响言行/售品倾向设定） | `丹道世家`、`剑修世家`、`渔隐门` |
| `regions` | 地域（影响区域灵势） | `江南烟雨畔`、`吴淞江湾` |
| `fams` | 姓氏 | `吴`、`江` |
| `suffixes` | 家名后缀 | `宗`、`门` |

> 自己造的词会在**下一新档**出现；老档历史不变。喜欢"天下永远有"某个家族？那就用 §4 npcs 模板。

---

## 6. 能力四：灾因（calamities）

**这是什么**：灾年（旱灾/涝灾/蝗灾/疫病/兽潮/寒潮 是世界内置的六种）——你的 MOD 可以**追加**新的灾因，进世界灾签循环：年首抽灾 → 6 个月减产/困扰 → 散去。

```jsonc
"calamities": [{
  "name": "瘴雨",                     // 灾名（唯一——与内置灾因同名会被拒）
  "brief": "瘴雨连绵，田间霉蛀——灵植减产。",   // 灾年提示语
  "family": { "lingcao": 0.75 },      // 家族减产乘（0.1.33 起真正计入月产——须填）
  "effect": { "lingcao": -0.2 }       // 天下市场冲击（世界池现货下调）
}]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `name` | ✅ | 灾名（唯一；DEFAULT_CALAMITIES 里已有六种：旱灾/涝灾/蝗灾/疫病/兽潮/寒潮——同名被拒） |
| `brief` | 建议 | 灾年提示文案（历史记录/新闻引用） |
| `family` | 建议 | 家族侧减产乘：`{ 资源id: 乘数 }`（0.7=打七折；≤1 减产，>1 增产——兽潮就可以整点猎获） |
| `effect` | 建议 | 世界池侧冲击：`{ 资源id: 增减量 }`（世界市场实际库存起落） |

---

## 7. 能力五：丹方（pills）

**这是什么**：丹房的炼丹配方。丹房等级、原料、灵石齐了之后玩家可以在"工坊"页点炼丹（0.1.30 起物品表接口已开放，背包/卖出/服丹全走物品表）。

```jsonc
"pills": [{
  "output": "pill-biandan",           // 成品丹 id（**必须同时在 §9.5 items 立名**！）
  "name": "便丹",
  "danfangLevel": 1,                  // 丹房门槛（1~5）
  "stones": 20,                       // 灵石成本
  "lingcao": 15,                      // 灵草成本
  "beastcore": 0,                     // 兽核成本
  "desc": "出门在外备着。"
}]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `output` | ✅ | 丹 id（`pill-` 前缀惯例；且**物品表必须有同名 item**——见红牌） |
| `name` | ✅ | 丹名 |
| `danfangLevel` | ✅ | 丹房等级门槛（1~5，超出提示 warning） |
| `stones` / `lingcao` / `beastcore` | ✅ | 三原料成本（非负） |
| `desc` | ✅ | 丹说明（物品表 desc 同步显示） |

> 🔴 **0.1.33 红牌（血泪教训）**：`output` 必须同时写进 §9.5 的 `items`！产物没有物品表定义 = **幽灵物品**——炼出来在背包里看不见、卖不掉、不能用。标准的配合写法：
> ```jsonc
> "pills": [{ "output": "pill-biandan", "name": "便丹", "danfangLevel": 1, "stones": 20, "lingcao": 15, "beastcore": 0, "desc": "出门在外备着。" }],
> "items": [{ "id": "pill-biandan", "name": "便丹", "kind": "pill", "basePrice": 60, "desc": "出门在外备着。", "icon": "丹" }]
> ```

**内置丹方参照**（照这个量级走）：

| 丹方 | 丹房 | 材料 | 售价 |
|---|---|---|---|
| `pill-qiyuan` 聚气丹 | 1 级 | 灵草15 | 45 |
| `pill-ningyuan` 凝元丹 | 2 级 | 灵草25+兽核4 | 150 |
| `pill-pojing` 破境丹 | 3 级 | 灵草40+兽核10 | 480 |
| `pill-heling` 和灵丹 | 2 级 | 灵草20+兽核8 | 120 |
| `pill-xudan` 虚元丹 | 4 级 | 灵草50+兽核16 | 320 |

---

## 8. 能力六：铸器配方（forges）

**这是什么**：自造兵器的配方（灵矿+兽核+灵石→武器），无建筑门槛——数值即门槛（成本低=品质低）。

```jsonc
"forges": [{
  "output": "weapon-gangchi",        // 兵器 id（**同样必须先立名 items**）
  "name": "罡齿刃",
  "stones": 800,
  "lingkuang": 16,
  "beastcore": 5,
  "desc": "咬罡崩铁，斩山如泥。"
}]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `output` | ✅ | 兵器 id；**红牌同 §7**：物品表必须有同名 item |
| `name` | ✅ | 兵名 |
| `stones` / `lingkuang` / `beastcore` | ✅ | 三成本（非负） |

> 🔴 **红牌同 §7**——范例（注意 `items` 里 `artifact` 类 + `basePrice`）：
> ```jsonc
> "forges": [{ "output": "weapon-gangchi", "name": "罡齿刃", "stones": 800, "lingkuang": 16, "beastcore": 5, "desc": "咬罡崩铁。" }],
> "items": [{ "id": "weapon-gangchi", "name": "罡齿刃", "kind": "artifact", "basePrice": 900, "desc": "咬罡崩铁。", "icon": "罡" }]
> ```

**武器强度表**（`ARTIFACT_POWER`——决定装备后的战力百分比）：

| 兵器 | 战力 |
|---|---|
| `weapon-fan` 凡器 | +10% |
| `weapon-qi` 法器 | +25% |
| `weapon-yu` 玉澜刃 | +40% |
| `weapon-lingwoon` 灵纹刃(官范例) | +35% |
| `weapon-ling` 灵器 | +50% |
| `weapon-fa` 法宝 | +90% |

> 自己铸兵器的战力怎么定？**不能直接给定**（铸器表没有战力字段）——想给玩家武器设满配，请在 §11 用 `ARTIFACT_POWER` 内部映射（MOD 不可覆写内置映射；**建议在 items 定义时参考上表量级定价**：法器 450/灵器 1400/法宝 3600）。

---

## 9. 能力七：世界数值（worldNum）

**这是什么**：对**世界常数表**（WORLDSIM）做覆写——调供需、池深、潮汐、灾年概率、战争疲劳等。白名单机制：**只认常数表内键**，乱写的键被忽略（不报错不算错）。

```jsonc
"worldNum": {
  "worldSupplyRate": 0.02,     // 世界月供给上浮（更富饶的世界）
  "calamityChance": 0.1,       // 灾年概率调低（温和天下）
  "newSecretChance": 0.06      // 新秘境现身率上浮
}
```

### 全键列表（取值均为"数值"，单位见注释）

**市场/池**（0.1.32 起实体化——详见 README"市场实体化"）：

| 键 | 默认 | 含义 |
|---|---|---|
| `marketDriftRate` | 0.03 | 月波动幅度 |
| `marketRebalance` | 0.025 | 弱锚定强度（**勿调回 0.1+**——锚死供需失去意义） |
| `priceFloor` / `priceCeil` | 0.55 / 2.3 | 相对基准价上下限 |
| `worldSupplyRate` | 0.02 | 世界月供给 |
| `worldDemandRate` | 0.015 | 世界常驻需求 |
| `npcTradeRate` | 0.6 | NPC 贸易频率 |
| `tradeFloorPct` | 0.35 | **拒单线**（池比 < 此值玩家停手断供） |
| `poolFloorPct` | 0.25 | **池底**（市场永不清零；**低手线分离**——别改回同值，0.1.20 语义已废） |
| `tradeCeilPct` | 8 | 池上限 |

**潮汐/灵气**：

| 键 | 默认 | 含义 |
|---|---|---|
| `tideCycle` | 96 | 潮汐周期（月） |
| `tideSupplySpan` | 0.35 | 潮汐对供给的摆动 |
| `longWave` / `longWaveSpan` | 120 / 0.08 | 十年长波周期/振幅 |
| `tideMin` / `tideMax` | 0.65 / 1.35 | 潮汐上下限 |
| `secretRecover` / `secretRecoverHi` | 2 / 5 | 秘境灵气月恢复（常/潮高） |
| `secretConsume` | 6 | 单次探索消耗 |

**时代/灾**：

| 键 | 默认 | 含义 |
|---|---|---|
| `tempEraK` | 0.8 | 世界温度对 era 转移强度（下界已钳 0.05——不再零/负） |
| `greatNewbornChance` | 0.06 | 年首新贵补位率（乱世×2） |
| `allianceGriefRaid` | 0.012 | 盟约连坐的袭扰概率 |
| `calamityChance` | 0.18 | 灾年概率 |
| `calamityMonths` | 6 | 灾年持续月数 |
| `npcEventChance` | 0.05 | NPC 互攻年首诗签率 |
| `newsEvery` / `newsKeep` | 24 / 120 | 天下快讯节奏/留档条数 |

**0.1.34 新键（战争疲劳/断供/新秘境）**：

| 键 | 默认 | 含义 |
|---|---|---|
| `warFatigueRise` | 0.008 | 每次乱象（互攻）累积的战争疲劳 |
| `warFatigueTempK` | 0.6 | 疲劳对世界温度的冷降幅度（打不动即荒年） |
| `shortageLine` | 0.7 | 断供警戒线（池/基准低于此起计） |
| `shortageMonths` | 3 | 连续月数触发断供应急（价 ×1.5 + 广播） |
| `shortagePrice` | 1.5 | 断供价乘 |
| `newSecretChance` | 0.04 | 年首新秘境现身概率（乱世×2） |

---

## 9.5 内容面扩展（物品/功法/建筑/职事/志向/阵型/性格）

七口全纯数据；**内置条目不可覆盖**（同名 id 被跳过并 warn——防覆盖红线），只加新键。凡"新实体"口都自动进入游戏各面（背包/市场/建/配/装等）。

### 9.5.1 物品（items）——六类生态

```jsonc
"items": [
  { "id": "pill-biandan", "name": "便丹", "kind": "pill", "basePrice": 60, "desc": "出门在外备着。", "icon": "丹" },
  { "id": "weapon-gangchi", "name": "罡齿刃", "kind": "artifact", "basePrice": 900, "desc": "咬罡崩铁。", "icon": "罡" }
]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `id` | ✅ | 唯一（`[a-z0-9-]`） |
| `name` | ✅ | 名字 |
| `kind` | ✅ | 六类：`resource` 资源 / `material` 材料 / `pill` 丹药 / `talisman` 符箓 / `brew` 灵酿 / `artifact` 兵器 |
| `basePrice` | ✅ | 基准价（市场行情按此波动；>0） |
| `desc` | ✅ | 描述 |
| `icon` | ✅ | **单字汉字**（印章字符——游戏内无 emoji 字体，别写 emoji/多字） |

**六类生态说明**（每类都有"出口"才闭环）：

| kind | 游戏内行为 |
|---|---|
| `resource` | 基础资源（世界池/生产/市场全链） |
| `material` | 素材（入世界池参与呼吸+NPC 贸易；灵玉/灵木/兽皮等天然材料即此列） |
| `pill` | 丹药（服丹加修为——需丹方生产） |
| `talisman` | 符箓（开战胜耗：风符×1.12 / 山符×1.15+受创减半——金钟罩零 rng 结算） |
| `brew` | 灵酿（渡劫受重创后自动回气+5） |
| `artifact` | 兵器（成员可装备——战力按 ARTIFACT_POWER 表） |

> **四同步纪律**（0.1.32，想进世界循环的 *material/resource* 必须 4 件事齐）：① 本表定义 → ② POOL_BASE（世界池基准）→ ③ MARKET_IDS（市场循环键位）→ ④ worldgen marketOffset（开档偏移）。只做完① = "躺仓库"（能背包不能世界呼吸）。丹药/符箓/灵酿/兵器**不需要**世界池（玩家自制/市场购）。

### 9.5.2 功法（techniques）——含四流派效果

```jsonc
"techniques": [
  { "id": "t-lingwu", "name": "灵雾心法", "grade": 1, "element": "水", "path": "丹修",
    "expBonus": 0.11, "powerBonus": 0.12, "desc": "雾气绕身，吐纳绵长。" },
  { "id": "t-xiashuang", "name": "霞霜剑歌", "grade": 2, "element": "水", "path": "剑修",
    "expBonus": 0.14, "powerBonus": 0.17,
    "critChance": 0.1, "guardBonus": 0.1, "tribBonus": 0.04, "secretBonus": 0.1,
    "desc": "霞染霜锋，剑歌行处皆败。"
  }
]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `id` | ✅ | 唯一（`t-` 惯例） |
| `name` | ✅ | 功法名 |
| `grade` | ✅ | 品阶 1~4（影响市价/掉率/求学经库边际） |
| `element` | ✅ | `木/金/水/火/土/雷`——**元素×时令共鸣**（春木夏火秋金冬水，季修 ×1.04；土系恒应 ×1.02 四季皆宜） |
| `path` | ✅ | 流派标签：剑修/体修/丹修/阵修/符修/御灵…（自由填） |
| `expBonus` | ✅ | 修炼加速（建议 0.08~0.28） |
| `powerBonus` | ✅ | 战力加成（建议 0.05~0.38） |
| `critChance` | 可选 | **暴击**：战斗阵亡率压制（建议 0.05~0.12） |
| `guardBonus` | 可选 | **受创减免**：战斗受伤折减（建议 0.15~0.3） |
| `tribBonus` | 可选 | **渡劫加成**：渡劫成功率 +（建议 0.03~0.09） |
| `secretBonus` | 可选 | **秘境收获**：任务掉落乘放大（建议 0.1~0.2） |
| `desc` | ✅ | 描述 |

> 新功法自动进：藏书阁可购（grade≤3 才入市）/ 秘境掉落 / 拍卖 / 求经台。
> **平衡提醒**（validateMod 检查）：`expBonus ≤ 0.5`、`powerBonus ≤ 1`（超了 warning）。
> 参阅内置 23 本量级（§10 速查表功法表——照档位编，别造出"二品武功碾压天阶"）。

### 9.5.3 建筑（buildings）

```jsonc
"buildings": [
  { "id": "b-chalu", "name": "茶园", "icon": "茗", "desc": "清茶待客，悦人悦己。", "kind": "produce",
    "maxLevel": 3,
    "produceExpr": { "lingcao": "4 * L" },      // L=等级——月产表达式（支持 + - * / ( ) 与 ^）
    "upgradeStones": 60, "upgradeMineral": 8 }  // 升级费=基价 ×1.6^(L-1) / 灵矿×L
]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `id` | ✅ | 唯一 |
| `name` / `icon` / `desc` | ✅ | 显示（icon 单字汉字符号） |
| `kind` | ✅ | `produce`（月产）\| `function`（加成——function 型建议少碰，数据面以 produceExpr 为主） |
| `maxLevel` | ✅ | 最高等级 |
| `produceExpr` | produce 必填 | 月产表达式：`{ 资源id: "公式" }`——公式中 `L`=当前等级；数学符号（+ - * / ( ) ^）——**0.1.36 起由纯解析器 arith 求值（CSP 禁 eval——表达式无脚本化能力，字母/函数名一律视为非法），引擎内置与 MOD 表达式同一求值器** |
| `upgradeStones` | ✅ | 升级灵石基价（1.6^(L-1) 递增） |
| `upgradeMineral` | ✅ | 升级灵矿（×L） |

> 建筑自动出现在领地页可建/可升。**消耗式建筑**（如符箓坊：扣符纸+灵木产符箓——0.1.33 引入）**不要**用 produceExpr 泛化——泛化只做纯产出。

### 9.5.4 职事（posts）——5 效果

```jsonc
"posts": [
  { "id": "p-chashi", "name": "茶司", "effectType": "marketIncome", "value": 0.06, "max": 1, "desc": "坐市司货，坊市入息 +6%。" }
]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `id` | ✅ | 唯一 |
| `name` | ✅ | 职事名 |
| `effectType` | ✅ | **真实取值**：`expAll`（全体修炼）/ `marketIncome`（坊市入息）/ `battlePower`（战力）/ `meditation`（闭关效率）/ `familyRep`（家族声望） |
| `value` | ✅ | 效果强度（小数：0.06=+6%） |
| `max` | ✅ | 可设人数上限 |
| `desc` | ✅ | 描述 |

### 9.5.5 志向（aspirations）——6 效果

```jsonc
"aspirations": [
  { "id": "a-chafan", "name": "茶饭闲人", "desc": "偶有茶会，心神宁和。", "effectType": "cult", "value": 0.04 }
]
```

| `effectType` 真实取值 | 含义 |
|---|---|
| `cult` | 修炼加速 |
| `battle` | 战力（注意：是 **battle** 不是 combat——0.1.31 早期文档曾误写） |
| `market` | 市场经济（坊市/贸易） |
| `field` | 灵田产降（农务） |
| `offspring` | 生育/姻缘 |
| `rep` | 声望 |

### 9.5.6 阵型（formations）

```jsonc
"formations": [
  { "id": "f-qingyun", "name": "青云阵", "icon": "云", "desc": "攻守兼重。", "atk": 1.05, "def": 1.05, "retreatWound": 1 }
]
```
`atk`（攻倍）/ `def`（防倍）/ `retreatWound`（撤退伤乘）：围绕 1.0 设计（0.9~1.15 区间是合理动态）。

### 9.5.7 性格（traits）

```jsonc
"traits": [
  { "id": "t-yaxi", "name": "雅细", "desc": "心细如发，炼丹养生。", "bonus": { "expBonus": 0.03, "charmBonus": 0.05, "danger": 0 } }
]
```

`bonus` 键（映射到引擎的 TraitDef 平铺字段）：

| bonus 键 | 含义 | 建议量级 |
|---|---|---|
| `expBonus` | 修为加成 | 0.02~0.08 |
| `breakBonus` | 突破成功率 | 0.02~0.06 |
| `windBonus` | 战力 | 0.02~0.1 |
| `charmBonus` | 魅力（姻缘/招募） | 0.02~0.1 |
| `priceMult` | 售价加成 | 0.02~0.08 |
| `danger` | 风险（性情偏激/祸患 0~1） | 0~1 |

---

## 9.6 数值 patch 层

**这是什么**：不改表结构、不加新实体——只对**已存在**表项改数值（打包/改值/回滚全自动）。适合"风味包调平衡"（比如你的主题包想让聚气丹便宜两成）。

```jsonc
"patch": [
  { "target": "technique", "id": "t-qinglian", "mult": 0.9 },   // 青莲剑诀全部数值 ×0.9
  { "target": "item", "id": "pill-qiyuan", "add": -10 }         // 聚气丹基价 -10
]
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `target` | ✅ | `technique` / `item`（`building` 记于文——表项结构复杂，建议不碰） |
| `id` | ✅ | 表内已有条目 id |
| `mult` | 二选一 | 乘数（0.5~2，越界 → 安装拒绝） |
| `add` | 二选一 | 实数增量 |

**规则**：
1. `mult`/`add` **二选一**，同给 → 拒绝；
2. 只对**已定义数值键**生效：功法改 `expBonus/powerBonus/critChance/guardBonus/tribBonus/secretBonus`；物品改 `basePrice`（钳 ≥1）；
3. **目标字段缺失 → warn 日志**（`[patch] 功法 xx 无字段 yy`）——绝不清空吞；
4. **仅新开档生效**；卸载复原（0.1.35 按插件归属——只弹本家，互不侵扰）；
5. 与 `worldNum` 区别：`worldNum` 改**全局世界常数**，`patch` 改**表项数据**——可并用。

---

## 10. 速查表：内置 id 大全

### 10.1 资源/材料 id（res / sells / buys / family / effect 通用）

- **资源**：`stones`（灵石）· `lingcao`（灵草）· `lingkuang`（灵矿）· `beastcore`（兽核）
- **材料七种**（0.1.32）：`lingyu` 灵玉 · `lingmu` 灵木 · `shoupi` 兽皮 · `lingguo` 灵果 · `linglu` 灵露 · `dansha` 丹砂 · `fuzhi` 符纸
- **符箓**：`talisman-feng` 风符（开战全体 ·1.12）· `talisman-shan` 山符（开战 ·1.15 + 受创减半）
- **灵酿**：`brew-niang`（渡劫伤后回气 +5）

**材料来源速记**（与玩法真实对应）：灵玉 ← 玄冰谷/古战阵掉落+市场；灵木 ← 灵木坊（建筑）+暗墨林；兽皮 ← 灵兽园/古战阵/兽潮灾年；灵果 ← 灵果园；丹砂/灵露/符纸 ← 市场购买为主。

### 10.2 丹药 id（pillGain / res 可用 / 丹方）

| id | 丹名 | 丹房 | 材料 | 说明 |
|---|---|---|---|---|
| `pill-qiyuan` | 聚气丹 | 1 级 | 灵草15 | 炼气期主修 |
| `pill-ningyuan` | 凝元丹 | 2 级 | 灵草25+兽核4 | 筑基以上 |
| `pill-pojing` | 破境丹 | 3 级 | 灵草40+兽核10 | 渡劫药力（tribBoost） |
| `pill-heling` | 和灵丹 | 2 级 | 灵草20+兽核8 | 0.1.33 新丹方 |
| `pill-xudan` | 虚元丹 | 4 级 | 灵草50+兽核16 | 0.1.33 新丹方 |

### 10.3 兵器 id（forge output / 掉落 / 装备）

| id | 兵名 | 战力 | 说明 |
|---|---|---|---|
| `weapon-fan` | 凡器 | +0.10 | 基本位 |
| `weapon-qi` | 法器 | +0.25 | 蕴灵 |
| `weapon-ling` | 灵器 | +0.50 | 有灵 |
| `weapon-fa` | 法宝 | +0.90 | 罕世 |
| `weapon-yu` | 玉澜刃 | +0.40 | 0.1.33 灵木铸器 |
| `weapon-lingwoon` | 灵纹刃 | +0.35 | 官方范例包产出（0.1.35 立名修复） |

### 10.4 功法 id（23 本全列）

| id | 名称 | 品阶 | 流派效果 |
|---|---|---|---|
| `t-qinglian` | 青莲剑诀 | 1 | — |
| `t-canglei` | 苍雷炼体功 | 1 | — |
| `t-xuanyue` | 玄月斩灵诀 | 1 | — |
| `t-lieliuxin` | 离火心经 | 1 | — |
| `t-houtu` | 厚土镇岳功 | 1 | — |
| `t-baihui` | 百草经 | 1 | — |
| `t-zidian` | 紫电惊雷诀 | 1 | crit 0.10 |
| `t-xuanbing` | 玄冰凝甲功 | 1 | guard 0.20 |
| `t-zhenyu` | 阵纹天书 | 2 | — |
| `t-hanyu` | 寒玉心法 | 2 | — |
| `t-liehuo` | 烈火焚空诀 | 2 | — |
| `t-wanjian` | 万剑归一诀 | 2 | — |
| `t-yushen` | 驭兽真解 | 2 | — |
| `t-danding` | 丹鼎护道妙典 | 2 | trib 0.06 |
| `t-fengyu` | 风遁青冥诀 | 2 | secret 0.20 |
| `t-shanling` | 山灵镇岳录 | 2 | guard 0.20 + crit 0.05 |
| `t-shiling` | 时灵应候诀 | 2 | secret 0.10 |
| `t-geling` | 化灵经 | 3 | — |
| `t-jiuxiao` | 九霄龙吟诀 | 3 | — |
| `t-tianya` | 天涯孤鸿法 | 3 | — |
| `t-lanhai` | 澜海听涛经 | 3 | trib 0.09 + secret 0.15 |
| `t-qiankun` | 乾坤七星阵 | 4 | — |
| `t-xiantian` | 先天混元功 | 4 | — |

### 10.5 建筑 id（14 座）

| id | 名 | 类型 | 产物/说明 |
|---|---|---|---|
| `lingtian` | 灵田 | produce | 灵草（月产 L 倍） |
| `yaoyuan` | 药园 | produce | 灵草 + 兽核（3 级起） |
| `lingkuang` | 灵矿 | produce | 灵矿 |
| `fangshi` | 坊市 | produce(stones) | 灵石月入 |
| `danfang` | 丹房 | function | 炼丹（craftChance 随级） |
| `cangshu` | 藏书阁 | function | 功法购入/求经 |
| `juling` | 聚灵阵 | function | 修炼 expBonus |
| `yanwu` | 演武场 | function | 战力 + 悟位积累（0.1.34） |
| `dongfu` | 洞府 | function | 闭关 |
| `zongci` | 宗祠 | function | 祭祖 |
| `lingshou` | 灵兽园 | produce | 兽核（概率） |
| `lingguoyuan` | 灵果园 | produce | 灵果（0.1.32） |
| `lingmufang` | 灵木坊 | produce | 灵木（0.1.32） |
| `fuzhifang` | 符箓坊 | produce(消耗式) | 耗符纸×2+灵木×2/级→风符；叁级→山符（0.1.33） |

### 10.6 天下家 id（relation / raid）

`n-xuanying` 玄影沈氏 · `n-danxin` 丹心木氏 · `n-sihai` 四海王氏 · `n-nulei` 怒雷祝氏——**新档 worldgen 随机凑 4~8 家，你家不一定全有**；写不存在的也不报错，只是关系变化落空。新贵家族 id 是 `n-new-…`（世界新贵+你的模板家混出），写不得——只用上面四家作为"保底名册"。

### 10.7 秘境 id（missionId）

| id | 名 | 风险 | 掉落特征 |
|---|---|---|---|
| `m-anmoku` | 暗墨林 | 0.5 | 灵草/兽核 |
| `m-xuangu` | 玄冰谷 | 0.65 | 灵矿/灵玉/兽皮 |
| `m-guzhan` | 古战阵 | 0.75 | 灵矿/灵玉/兽皮 |
| `m-lingshan` | 灵鹫山 | 0.85 | 灵草/兽核（高难） |
| `m-tiankeng` | 天坑 | 0.9 | 兽核/高阶战利 |

> **0.1.34 起世界年首会灵机现身 `m-wonder-*` 新秘境**（随 seed/年号派生，档档不同）——引擎双向回退，你的 `sendMission` 对 wonder id 也完全可用；放心引用或观望。

---

## 11. 排错 FAQ

**Q1：扫描后列表里没有我的文件？**
- 文件名后缀必须是 `.json` 或 `.cotymod`；文件名 `[a-z0-9-]`（勿用中文文件名）
- 确认路径（§1 第 1 步）；扫描后没有提示"已扫描 mods 目录"？——就是路径错了

**Q2：点安装提示"MOD 解析失败：缺失/非法的 MOD id"？**
- 缺 `id` 字段或 `id` 用了中文/大写/`.`；按 §2 修。**另外**：如果你把**存档导出文件**误放进了 mods 目录，也会报这个错——那是存档，请删除或移到别处（或用游戏内"导入存档"）。

**Q3：提示"MOD 安装被拒绝：事件 id 冲突：xxx"？**
- 你的事件 `id` 与内置/已装 MOD 重复——改个不重名的 id 即可（用 `ev-你的前缀-` 最省心）。

**Q4：装上了但游戏里没见反应？**
- **先确认是"新开档"**：MOD 只影响新世界生成与装载；已开的档不会变。
- 事件类：检查 `category` 与 `weight`（`daily`/`major`/`fate` 各自独立抽签，weight 太小+类别太稀有会很少见）。
- 模板类：新开档后去"天下"面板看"群雄谱"。
- 物品/功法/建筑类：直接去对应页面（背包/藏书阁/领地）核对。

**Q5：卸载后世界还变着？**
- 世界状态（已发生的演化）是"既成事实"——卸载只还原 MOD 造成的**机制**（词库/灾因/配方/数值/注入条目），不会回滚开档后世界自然发生的事。这与游戏规则一致：**装 MOD 改变世界的历史**。如果希望干净世界，用没装 MOD 时的新档。

**Q6：读档提示"缺失 MOD"？**
- MOD 的文件被移动/删了，或游戏版本变化导致版本不符。把文件放回 `mods` 目录（同 id 同版本）再进档即可。

**Q7：我的 MOD 与别人冲突？**
- 检查两个 MOD 是否用了相同事件 id / 灾因名 / 丹方 output / 模板 id / 功法 id——任意撞名 → 后装者会被拒/被忽略（同 id 功法撞内置 → `[MOD:xxx]` 日志提示跳过）。用 `depends`/`conflicts` 声明关系（§2）。

**Q8：`patch` 改了没生效？**
- 查三事：① `target`/`id` 是否精确表内项；② `mult` 是否 0.5~2（越界会**拒绝**而非忽略）；③ 目标字段是否存在（功法没定义某效果键 → `[patch] 功法 xx 无字段 yy` 日志。补上该效果字段再 patch 即可）。
- 注意 `patch` **只改表项**，世界常数用 `worldNum`；两者作用范围不同。

**Q9：带 `patch` / 新功法的 MOD，老档读档正常吗？**
- MOD 只作用于**新开档**；老档装载 MOD 只影响"此刻起"的机制拼接，数值 patch 不会追溯已建世界。想验证效果请新开档。

---

## 12. 进阶：依赖、冲突与导出

### 12.1 depends / conflicts

```jsonc
"depends": ["fenwu-ji"],    // 必须先装「风物集」；未装 → 拒绝
"conflicts": ["old-pack"]   // 与「old-pack」互斥；对方已装 → 拒绝
```

### 12.2 导出与分享

- 设置页 → MOD 层 → **导出当前 MOD 集**：把你已装的全部 MOD 打包成一个 `mod-bundle-export.cotymod`（合包）。
- 同伴把这个文件放进他们的 `mods` 目录，安装时**逐包**装好（0.1.28 起完全闭环）。
- 你的 `.cotymod` 文件就是打包好的 MOD——直接发文件即可，无需任何构建工具。

### 12.3 读档重装纪律

- MOD 状态随存档保存；重装要求**同 id 同版本**（版本差 → 跳过并提示"缺失"）。
- 所以**改动 MOD 务必升 `version`**（如 1.0.0 → 1.0.1），否则老档可能静默跳过新包。

---

## 13. 官方范例（可拆解学习）

游戏内置两枚官方包（设置 → MOD 层 → 内置仓库，一键安装）：

| 包 | 教会你 |
|---|---|
| **风物集**（`fenwu-ji`） | 词库注入 + 灾因（含 brief 文案）——"做地域风物" |
| **战备解军**（`zhanbei-xv`） | 铸器配方 + worldNum 覆写——"做数值平衡" |

拆解方法：安装后 → 导出当前 MOD 集 → 用文本编辑器打开 `mod-bundle-export.cotymod` → 所有字段即你所见。

**风物集** data 实样：
```jsonc
{
  "worldgen": { "fams": ["吴", "江", "雨"], "regions": ["江南烟雨畔", "吴淞江湾"], "styles": ["风雅世家", "渔隐门"] },
  "calamities": [{ "name": "瘴雨", "brief": "瘴雨连绵，田间霉蛀——灵植减产。", "family": { "lingcao": 0.75 }, "effect": { "lingcao": -0.2 } }]
}
```

**战备解军** data 实样：
```jsonc
{
  "forges": [{ "output": "weapon-lingwoon", "name": "灵纹刃", "stones": 700, "lingkuang": 15, "beastcore": 5, "desc": "纹蕴灵光，锋锐无俦。" }],
  "worldNum": { "worldSupplyRate": 0.018, "worldDemandRate": 0.014 }
}
```
> 注意战备解军示范了**配方产物先在 items 立名**（灵纹刃物品表 0.1.35 修复过的正确姿势）——你说它名字里有"灵"有"纹"却不给物品表，它就真的只是"铸器单子上画出的一把虚影"。

---

### 9.7 世界奇观类型扩展（wonders） · 0.1.37 新增

0.1.37 引入**世界奇观**——年首种子派生判定（零 rng 消耗），4 种内置奇观：灵气涌潮 / 古遗迹现身 / 天降祥瑞 / 灵脉枯竭。

MOD 可以注册**自定义奇观类型**，加入年首种子派生选取池：

```jsonc
"wonders": [
  {
    "kind": "star_fall",        // 唯一 id（不可与内置 tide_surge/ancient_ruin/heaven_bless/qi_wane 冲突）
    "name": "星陨天落",          // 中文名称
    "desc": "天外陨星坠落——灵气激荡，宝材出世。",  // 描述文本
    "duration": 12,              // 持续月数（0 = 一次性）
    "effect": "tide_up",         // 持续效果：tide_up=灵气增益 / tide_down=灵气衰减 / none=无
    "oneshot": "loot"            // 一次性效果：bless=灾年消弭+声望+5 / loot=随机资源获取 / none=无
  }
]
```

**字段说明**：

| 字段 | 必填 | 取值 | 说明 |
|------|------|------|------|
| `kind` | ✓ | 唯一字符串 | 奇观类型 id（与内置+已注册不冲突） |
| `name` | ✗ | 字符串 | 中文名（缺省"异变"） |
| `desc` | ✗ | 字符串 | 描述（缺省"天地异变，灵机暗涌。"） |
| `duration` | ✗ | 0~60 | 持续月数（缺省 0=一次性） |
| `effect` | ✗ | `tide_up`/`tide_down`/`none` | 持续月度效果（缺省 `none`） |
| `oneshot` | ✗ | `bless`/`loot`/`none` | 出现时一次性效果（缺省 `none`） |

> **零 rng 保证**：奇观判定使用种子哈希派生（`seed ^ year ^ npcSuccessions`），不消耗 `rng.next()` 序列——金钟罩确定性不受影响。
> **因果事件**：事件选项 `eff.karma` 可正可负——MOD 事件天然支持因果变动（无需额外口）。
> **worldNum 白名单**：`wonderChance`（0.08）/ `karmaDecayRate`（0.1）/ `karmaHighThreshold`（30）/ `karmaLowThreshold`（-20）可经 `data.worldNum` 覆写。

---

**一句话总结**：MOD = 一个有 `data` 字段的 JSON。事件管"剧情"、模板管"新家族"、词库管"名字概率"、灾因管"灾年种类"、丹方铸器管"炼丹造兵"、worldNum 管"世界脾性"、内容面八口管"新物品/功法/建筑/职事/志向/阵型/性格/奇观"、patch 管"已有表项微调"。装/卸/导出全在设置页，读档重装全自动。去写吧——这个世界等你的素材。

> 0.1.32 玩注：资源循环已是六类生态（资源/材料/丹药/符箓/灵酿/兵器），新物产入池即参与世界呼吸与 NPC 贸易——写材料口别怕世界吃不进去。
> 0.1.33 闭环注：符箓开战即耗（风符×1.12/山符×1.15+减伤——零 rng 结算），灵酿渡劫伤后自动回气；丹方/铸器产出物 ALL 必须先在物品表立名（否则幽灵物品不可见不可卖）。
> 0.1.34 功法注：四流派效果 crit/guard/trib/secret 全 optional——缺省零行为，金钟罩安全；元素时节共鸣 4 季同频（土系恒应）。
> 0.1.35 涤荡注：无存档迁移（游戏未发布——旧档随版本演进失效属预期）；`patch` 层按插件归属回滚；validate 覆盖 §12 全部规则。
> 0.1.37 因果奇观注：奇观零 rng（种子派生选取池含 MOD 扩展）；`eff.karma` 天然支持；`wonderChance`/`karmaDecayRate`/`karmaHighThreshold`/`karmaLowThreshold` 可经 worldNum 覆写；飞升事件 `ev-ascension-*` 前缀保护防劫持。

<sub>⚔️ 本文档随游戏版本更新（0.1.41）。字段若有新增，此处先行。</sub>