# MOD 开发教程 · Chronicle of the Immortal Clan
> 版本 **0.1.35·《荡涤·向新》** · MOD_SCHEMA_VERSION = 1 · 全口为纯 JSON（零脚本）

---

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

1. **MOD = 一个 JSON 文件**。放进 `mods/` 目录（游戏目录下），设置页 → MOD 层即可装卸——无任何构建工具。
2. **MOD 只影响新开档**。旧档的世界是"既成事实"——开档后世界自然演化不受 MOD 回溯；卸载还原 MOD 造成的**机制**（词库/灾因/配方/数值/注入条目），不回滚世界历史。游戏未正式发布（0.1.35 起无存档迁移），MOD 请对新档安装测试。

---

## 1. 五分钟上手

### 第 1 步：放文件
把 `.json`（或打包好的 `.cotymod`）放进游戏目录的 `mods/` 文件夹（含 `mods/` 本身时更稳）。文件名只用 `[a-z0-9-]`——**勿用中文/大写/空格**。

### 第 2 步：复制这个文件（最简 MOD）
```jsonc
{
  "id": "tianxia-changxiao",
  "name": "天下长啸",
  "version": "1.0.0",
  "schema": 1,
  "author": "你",
  "description": "一支会喊一句口号的曲子。",
  "data": {
    "worldgen": { "fams": ["啸"], "regions": ["天穹岭"] }
  }
}
```

### 第 3 步：装上看效果
设置页 → MOD 层 → 扫描（自动刷新列表）→ 点安装；**新开档** → 天下面板/事件里找痕迹。装卸后现有档的机制即还原/生效。

---

## 2. MOD 包结构总览

```jsonc
{
  "id": "my-pack",            // [a-z0-9-]，全局唯一
  "name": "我的包",
  "version": "1.0.0",
  "schema": 1,                // 范式版本（当前 = 1；缺失 → 提示）
  "author": "你",
  "description": "一句话",
  "kind": "content",          // content(剧情/风物) | data(新实体) | rules(数值规则)——仅归类展示
  "depends": ["other-pack"],  // 先装依赖，否则拒绝
  "conflicts": ["old-pack"],  // 与谁互斥，已装则拒绝
  "data": {
    // 五大延伸口 + 内容面七口 + patch 层——全可选，按需填
    "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 性格
    "patch": [...]          // §9.6 数值 patch
  }
}
```

---

## 3. 能力一：事件（events）
**入口：全游戏随机抽签（daily/major/fate 各池）与世代循环。** 每事件有起因条件与结局选项；事件 id 全局唯一（撞内置 → 该事件被忽略并 warn）。

### 3.1 字段表
```jsonc
{
  "id": "ev-changxiao2",
  "category": "daily",        // "daily"|"major"|"fate"
  "title": "……",
  "text": "……",
  "weight": 10,               // 0~100，池内比例权重
  "condition": { "minYear": 3, "maxYear": 20, "minRep": 20, "minPower": 80, "era": "shengshi" },
  "once": true,               // 全游戏只发生一次
  "cooldown": 24,             // 月数——离上次触发后冷却
  "options": [ { "label": "……", "eff": { "res": { "stones": 50, "lingcao": -3 }, "rep": 4, "relation": { "n-danxin": 5 } } } ]
}
```

### 3.2 条件（condition 可考键）
- `minYear/maxYear`（年）· `minAge/maxAge`（成员年龄）· `minRep`（声望）· `minPower/minPop` · `era`（shengshi/pingshi/luanshi/mofa）· `minSeason`。

### 3.3 效果（eff 可考键）
| 键 | 含义 | 取值 |
|---|---|---|
| `res` | 物品增减 | Record<资源id, 数>（见 §10 速查表） |
| `rep` | 声望 | ±数 |
| `relation` | 对天下家关系 | Record<天下家id, ±数> |
| `memberBy` | 族内一人效果 | `{ spec: "male"\|"adult"\|"youngest", method: "qi"\|"health", amount }` |
| `addBuilding` | 直接建成建筑 | 建筑 id（§10） |
| `addTech` | 获得功法 | 功法 id（§10） |
| `pillGain` | 得丹药 | `{ "pill-qiyuan": 1 }` |
| `mission/raid/tribody` | 触发任务/袭击/渡劫 | 详见实际事件体（内部均走同 gate） |

> 事件闸纪律：`pendingEvent` 唯一入口是引擎 fire（0=普通遇占放弃 / 1=高优顶替）。

---

## 4. 能力二：世界模板（npcs）
新档世界生成池的候选家（worldgen 按池凑 4~8 家——实际家数由种子决定，非全装即全出）。**改已装世界不生效**（世界形成为档记录）。

```jsonc
"npcs": [{
  "id": "n-cangwu", "name": "苍梧氏", "region": "南岭苍梧", "style": "剑修世家",
  "desc": "苍梧山下养剑人家，锋芒内敛而傲骨铮铮。",
  "leaderRealm": "foundation",   // 境界取值见下
  "initialPower": 180,           // 建议 60~400（校验区间）
  "powerGrowth": [3, 9],         // 年成长区间
  "sells": ["pill-qiyuan"],      // 入市售品（§10 id）
  "buys": ["lingcao", "beastcore"]
}]
```

### 4.1 境界取值（所有用到境界的地方通用）
`mortal`（凡）· `qi`（炼气·min 0~8）· `foundation`（筑基）· `core`（金丹）· `nascent`（元婴）· `spirit`（化神）

---

## 5. 能力三：世界生成词库（worldgen）
四组名字概率池，新档生成时抽查：

```jsonc
"worldgen": {
  "styles": ["丹道世家", "商盟"],   // 家族风格——影响 sell/build/态度
  "regions": ["江南烟雨畔"],         // 地域——影响地形/灵势/掉落速记
  "fams": ["吴", "江"],             // 姓氏
  "suffixes": ["宗", "门"]          // 后缀——组合出家名
}
```

---

## 6. 能力四：灾因（calamities）
进入世界灾签循环（WORLDSIM.calamities 默认「旱灾/涝灾/蝗灾/疫病/兽潮/寒潮」——MOD 追加即参与）：

```jsonc
"calamities": [{
  "name": "瘴雨",
  "brief": "瘴雨连绵，田间霉蛀——灵植减产。",
  "family": { "lingcao": 0.75 },     // 家族减产乘（0.1.33 起真正计入生产）
  "effect": { "lingcao": -0.2 }      // 世界池冲击（CALAMITY_EFFECT 通道）
}]
```

---

## 7. 能力五：丹方（pills）
```jsonc
"pills": [{
  "output": "pill-biandan", "name": "便丹",
  "danfangLevel": 1,                // 丹房等级门槛 1~5（校验提醒）
  "stones": 20, "lingcao": 15, "beastcore": 0,
  "desc": "出门在外备着。"
}]
```
**红牌（0.1.33 生态纪律）**：`output` 必须同时出现在 `items`（§9.5）——产物无物品表定义 = 幽灵物品（不可见不可卖）。

---

## 8. 能力六：铸器配方（forges）
```jsonc
"forges": [{
  "output": "weapon-lingwoon", "name": "灵纹刃",
  "stones": 700, "lingkuang": 15, "beastcore": 5,
  "desc": "纹蕴灵光，锋锐无俦。"
}]
```
同样**必须先在 items 立名**——内置示例包 `zhanbei-xv` 已作出表率（0.1.35 修复了它原本"幽灵产出"的旧缺口）。

---

## 9. 能力七：世界数值（worldNum）
白名单覆写（仅 WORLDSIM 常数表内键生效，越界键忽略）——**卸载复位**。常用键：
```
marketDriftRate / marketRebalance / poolFloorPct / tradeFloorPct / tradeCeilPct
worldSupplyRate / worldDemandRate / npcTradeRate / warFatigueRise / warFatigueTempK
shortageLine / shortageMonths / shortagePrice / newSecretChance / greatNewbornChance
calamityChance / npcEventChance / newsEvery / tempEraK
```

---

## 9.5 内容面扩展（物品/功法/建筑/职事/志向/阵型/性格）
纯数据口；**内置条目不可覆盖**（同 id 被跳过并 warn——防覆盖红线），只加新键。

### 物品（items）——k 六类生态
```jsonc
"items": [
  { "id": "pill-biandan", "name": "便丹", "kind": "pill", "basePrice": 60, "desc": "……", "icon": "丹" },
  { "id": "weapon-lingwoon", "name": "灵纹刃", "kind": "artifact", "basePrice": 700, "desc": "……", "icon": "纹" }
]
```
`kind` 六值（0.1.32 起）：`resource`（资源）/ `material`（素材：灵玉灵木兽皮灵果等——入世界池参与呼吸）/ `pill`（丹药）/ `talisman`（符箓·开战武备自动消耗）/ `brew`（灵酿·渡劫伤后自动回气）/ `artifact`（兵器·装备）。**四同步纪律**：新资源进世界循环必须同时办 4 件事（ITEMS 定义 + POOL_BASE + MARKET_IDS + worldgen marketOffset），否则"只躺仓库"。

### 功法（techniques）——含四流派效果
```jsonc
"techniques": [{
  "id": "t-lingwu", "name": "灵雾心法",
  "grade": 1,                     // 1~4（品阶：市价/掉率/求学池下限）
  "element": "水",                // 木金水火土雷——与时令共鸣（春木夏火秋金冬水；土恒应×1.02）
  "path": "丹修",                 // 剑修/体修/丹修/阵修/符修/御灵……自由
  "expBonus": 0.11, "powerBonus": 0.12,
  "critChance": 0.08,             // 流派效果（0.1.34，全 optional——缺省零行为）
  "guardBonus": 0.2,              //   暴击：战斗阵亡压制 / 受创减免：战斗受伤折减
  "tribBonus": 0.05,              //   渡劫成功率加成
  "secretBonus": 0.15,            //   秘境收获放大
  "desc": "雾气绕身，吐纳绵长。"
}]
```
新功法进入：藏书阁可购（grade≤3）/ 秘境掉落 / 拍卖 / 求经台——全自动入列。**平衡提醒**：validateMod 检查 `expBonus≤0.5 / powerBonus≤1`（警告非阻断）。

### 建筑（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
}]
```
- `kind`：`produce`（月产——用 produceExpr）；`function`（加成）——加成类请保守（白名单表达式只解析自家键）。
- 建筑自动出现在领地页可建可升；**消耗式生产**（如符箓坊：扣符纸产符）勿用表达式泛化——泛化只做纯产出。

### 职事（posts）
```jsonc
"posts": [{ "id": "p-chashi", "effectType": "marketIncome", "value": 0.06, "max": 1, "desc": "坐市司货，坊市入息+6%。" }]
```
`effectType`：`expAll / marketIncome / battlePower / cultivation / stamina / insight / feast`。

### 志向（aspirations）
```jsonc
"aspirations": [{ "id": "a-chafan", "desc": "偶有茶会，心神宁和。", "effectType": "cult", "value": 0.04 }]
```
`effectType`：`cult`（修为）/ `field`（产田）/ `market`（商市）/ `combat`（战力）/ `offspring`（生育）。

### 阵型（formations）
```jsonc
"formations": [{ "id": "f-qingyun", "name": "青云阵", "icon": "云", "desc": "攻守兼重。", "atk": 1.05, "def": 1.05, "retreatWound": 1 }]
```

### 性格（traits）
```jsonc
"traits": [{ "id": "t-yaxi", "name": "雅细", "desc": "心细如发。", "bonus": { "expBonus": 0.03, "charmBonus": 0.05, "danger": 0 } }]
```
`bonus`：`expBonus / breakBonus / windBonus / charmBonus / priceMult / danger(0~1)`。

---

## 9.6 数值 patch 层（0.1.34）
对**已存在表项**做局部改值——不做新实体：`mult`（0.5~2）或 `add`（实数）二选一。

```jsonc
"patch": [
  { "target": "technique", "id": "t-qinglian", "mult": 0.9 },       // 青莲剑诀全数值×0.9
  { "target": "item", "id": "pill-qiyuan", "add": -10 }             // 聚气丹基价-10
]
```
- 规则：`mult` 限 0.5~2（超出 → 拒绝）；`mult/add` 勿同给；只对**已定义数值键**生效（缺键字段 → warn 跳过）。
- **仅新档生效；卸载复原**（按 id 归属逐个插件回滚）。
- debug 建议：同 id 功法冲突时设置页会看到`[MOD:xxx] 功法同 id 已存在（内置优先，新增跳过）`日志。

---

## 10. 速查表：内置 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）

### 丹药（产出自丹方）
`pill-qiyuan`（聚气·丹房1级）· `pill-ningyuan`（凝元·2级）· `pill-pojing`（破境·3级）· `pill-heling`（和灵·2级·0.1.33）· `pill-xudan`（虚元·4级·0.1.33）

### 兵器（forge output）
`weapon-fan`（凡器0.1）· `weapon-qi`（法器0.25）· `weapon-ling`（灵器0.5）· `weapon-fa`（法宝0.9）· `weapon-yu`（玉澜刃0.4）· `weapon-lingwoon`（灵纹刃0.35·官方示例包）

### 功法（23 本）
剑修：`t-qinglian` 青莲剑诀 · `t-xuanyue` 玄月斩灵诀 · `t-hanyu` 寒玉心法 · `t-liehuo` 烈火焚空诀 · `t-wanjian` 万剑归一诀 · `t-jiuxiao` 九霄龙吟诀
体修：`t-canglei` 苍雷炼体功 · `t-houtu` 厚土镇岳功 · `t-xiantian` 先天混元功 · `t-xuanbing` 玄冰凝甲功(guard) · `t-shanling` 山灵镇岳录(guard+crit)
丹修：`t-lieliuxin` 离火心经 · `t-baihui` 百草经 · `t-danding` 丹鼎护道妙典(trib)
阵修：`t-zhenyu` 阵纹天书 · `t-qiankun` 乾坤七星阵
符修：`t-geling` 化灵经 · `t-tianya` 天涯孤鸿法 · `t-fengyu` 风遁青冥诀(secret) · `t-lanhai` 澜海听涛经(trib+secret) · `t-shiling` 时灵应候诀(secret)
御灵：`t-yushen` 驭兽真解
新锐：`t-zidian` 紫电惊雷诀(crit，一阶剑修)

### 建筑（建/升/领地）
`lingtian` 灵田 · `yaoyuan` 药园 · `lingkuang` 灵矿 · `fangshi` 坊市 · `danfang` 丹房 · `cangshu` 藏书阁 · `juling` 聚灵阵 · `yanwu` 演武场 · `dongfu` 洞府 · `zongci` 宗祠 · `lingshou` 灵兽园 · `lingguoyuan` 灵果园 · `lingmufang` 灵木坊 · **`fuzhifang` 符箓坊（消耗式：耗符纸×2+灵木×2/级→风符1；叁级→山符±1）**

### 天下家 id
`n-xuanying` 玄影沈氏 · `n-danxin` 丹心木氏 · `n-sihai` 四海王氏 · `n-nulei` 怒雷祝氏——**新档 worldgen 随机凑 4~8 家，你家不一定全有**；关系/raid 写不存在的 id 不报错，只是落空。

### 秘境 id（missionId）
`m-anmoku` 暗墨林 · `m-xuangu` 玄冰谷 · `m-guzhan` 古战阵 · `m-lingshan` 灵鹫山 · `m-tiankeng` 天坑——**0.1.34 起世界年首会灵机现身 `m-wonder-*`（种子派生生成，档档不同）**；你的 `sendMission` 对 wonder 也是通的（引擎双向回退）。

---

## 11. 排错 FAQ

**Q1：扫描后列表里没有我的文件？** 文件名 `[a-z0-9-]`（勿中文/大写）；`mods/` 路径对；`.json/.cotymod` 后缀。检查后“已扫描 mods 目录”提示是否出现。

**Q2：提示"MOD 解析失败：缺失/非法的 MOD id"？** 缺 `id` 或含中文/大写/`.`；也防误把**存档导出**放进了 mods 目录。

**Q3：提示"MOD 安装被拒绝：事件 id 冲突：xxx"？** 与内置/已装重名——改名。

**Q4：装上了但没见反应？** 先确认**新开档**（MOD 只影响新世界生成与装载）；事件类查 category/weight；模板类去"天下·群雄谱"看。

**Q5：卸载后世界还变着？** 世界演化既成事实不可回滚（与游戏规则一致）；要干净世界用无 MOD 的新档。

**Q6：读档提示"缺失 MOD"？** MOD 文件移动/删除/版本不符——放回 `mods`（同 id 同版本）。改动 MOD 务必升 `version`。

**Q7：MOD 间冲突？** 撞 id（事件/灾因名/丹方 output/模板 id）→ 后装被忽略/拒绝；用 `depends/conflicts` 声明。同名功法冲突后装会被**跳过并记 `[MOD:xxx]` 日志**——看设置页。

**Q8：patch 不生效？** 确认 `target/id` 精确匹配表内项；`mult` 界内；效果字段缺失 → `[patch] 功法 xx 无字段 yy` 日志提示补效果字段。

---

## 12. 进阶：依赖/导出/重装

### 12.1 depends / conflicts
```jsonc
"depends": ["fenwu-ji"],   // 先装风物集；未装 → 拒绝
"conflicts": ["old-pack"]  // 相斥
```

### 12.2 导出与分享
设置页 → MOD 层 → **导出 MOD 集** → 打包 `mod-bundle-export.cotymod`；同伴放入 `mods/` 逐一安装。`.cotymod` 即文件压缩包——直接分发。

### 12.3 读档重装
MOD 状态随存档保存；重装要求**同 id 同版本**——升 `version` 是 mod 生态建议（否则老档静默跳过新包）。

---

## 13. 官方范例（内置仓库 · 纯 JSON 范式教学）

| 包 | 教什么 |
|---|---|
| **风物集** `fenwu-ji` | 词库注入 + 灾因（brief/family/effect）——"做地域风物" |
| **战备解军** `zhanbei-xv` | 铸器配方 + worldNum 覆写——"做数值平衡"；0.1.35 起配方产物在物品表有定义（示范四同步） |

拆解：安装后 → 导出 MOD 集 → 打开 `mod-bundle-export.cotymod`，字段与本文一一对应。

---

**一句话总结**：MOD = 一个有 `data` 字段的 JSON。事件管"剧情"、模板管"新家族"、词库管"名字"、灾因管"灾年"、配方管"炼丹铸器"、worldNum 管"脾性"、七口管"新内容门面"、patch 管"旧表微调"。装/卸/导出全在设置页，读档重装全自动。去写吧——这个世界等你的素材。
> 0.1.33 闭环注：丹方/铸器产出物 ALL 必须先在物品表立名（四同步纪律）；符箓开战即耗（零 rng）。
> 0.1.34 功法注：four 流派效果 crit/guard/trib/secret 全 optional——缺省零行为，金钟罩安全。
> 0.1.35 涤荡注：无存档迁移 + patch 层按插件归属回滚 + validateMod 覆盖 pace/tag 全部校验规则（详见 §12）。

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