# MOD 规范与范式标准 · Chronicle of the Immortal Clan

> 版本 **0.1.27·《活水长流》** · MOD_SCHEMA_VERSION = 1
> 每个 MOD 是一个**外部内容包**（纯 JSON，零脚本）；安装后成为插件一等子类，
> 享有插件的全部设施：持久化（随档）、启用/停用、依赖/冲突检查、卸载自动回滚。

---

## 1. 命名与版本

| 项 | 规范 |
|---|---|
| `id` | `^[a-z0-9][a-z0-9-_]{1,31}$`（小写+数字+连字符/下划线；**全局唯一**，安装冲突即拒绝） |
| `version` | semver：`major.minor.patch`（如 `1.0.0`） |
| `schema` | **0.1.26 起建议声明**：`"schema": 1`（与 MOD_SCHEMA_VERSION 对齐；不符给升级提示） |
| 文件名 | `<id>.cotymod`（推荐）或 `<id>.json`，置于 `userData/mods/` |
| `gameVersion` | 可选声明"对哪个游戏版本制作"（仅展示，不强制） |

## 2. 包结构（全 JSON 单文件）

```jsonc
{
  "id": "jiangnan-feng",        // 必填：全局唯一
  "name": "江南遗风",            // 必填
  "version": "1.0.0",           // 必填
  "schema": 1,                  // 建议：范式版本
  "author": "你的名号",          // 建议：玩家辨识
  "description": "一句话说明来意。", // 建议
  "depends": ["other-mod-id"],  // 先装依赖（转 mod- 前缀）
  "conflicts": ["other-mod-id"],
  "data": {
    "events": [ /* EventDef 追加：见 §3 */ ],
    "npcs": [ /* NpcFamilyDef 模板：见 §4 */ ],
    "worldgen": { "fams": [], "regions": [], "styles": [], "suffixes": [] },
    "calamities": [ { "name": "剑灾", "family": { "lingcao": 0.7 }, "effect": { "beastcore": 0.2 } } ],
    "pills": [ /* PillRecipe 追加 */ ],
    "forges": [ /* ForgeRecipe 追加 */ ]
  },
  "worldNum": { "calamityChance": 0.12, "npcTradeRate": 0.006 }  // 0.1.27：世界数值白名单覆写（见 §5.5）
}
```

## 3. 事件（events）

EventDef 全字段**纯数据**（与内置事件同构）：

```jsonc
{
  "id": "ev-jiangnan-rain",     // 全局唯一！与核心/已装池冲突 → 拒绝安装
  "name": "江南烟雨",
  "category": "daily",          // daily | major | fate
  "weight": 2,                  // 0~100（影响抽样概率）
  "once": false,
  "text": "蒙蒙细雨落长街。",
  "options": [
    { "label": "静听雨声", "hint": "无", "eff": { "rep": 1 } }
    // eff 字段见 data/events.ts EffectDef：res/rep/relation/addBuilding/
    // pillGain/mission/raid/flag/techniqueChance/artifactChance/addTech/
    // feisheng/tournament/formation/apprentice/trib
  ]
}
```

**红线**：事件运行期是引擎核心时序——你的 eff 只影响数据与状态，**不得新增 `rng` 消耗**（会移动全局随机序列）。

## 4. 世界模板（npcs）

```jsonc
{
  "id": "n-jiangnan-gu",        // 建议 n- 前缀（与新贵生成池合并）
  "name": "姑苏顾氏",
  "region": "江南烟雨港",        // 加入世界区域库
  "style": "风雅世家",
  "desc": "临水而居，诗酒传家。",
  "leaderRealm": "foundation",  // mortal|qi|foundation|core|nascent|spirit
  "initialPower": 150,          // 建议 60~400
  "powerGrowth": [3, 9],
  "sells": ["lingcao"],
  "buys": ["lingcao", "lingkuang"]
}
```

模板进入 worldgen 词库池：**玩家"新开档"时参与世界生成**（老档世界不变形）。
同 `worldgen` 段的 `fams/regions/styles/suffixes` 亦写入生成池。

## 5. 灾因（calamities）

```jsonc
{ "name": "剑灾", "family": { "lingcao": 0.7 }, "effect": { "beastcore": 0.2 } }
```

- `name`：全局唯一（与默认 6 灾 + 已装 MOD 冲突即忽略）
- `family`：**玩家家族**生产乘量（1=正常）
- `effect`：**世界市场**池冲击乘量（-0.3 意为减少 30%）
- 灾签与世界循环（减产/市价/快讯/体感）全链路自动生效——这是本作灾年机制的扩展口

## 5.5 世界数值（worldNum，0.1.27 起）

```jsonc
"worldNum": {
  "calamityChance": 0.12,      // 灾年概率（默认 0.18）
  "worldSupplyRate": 0.015,    // 世界月供给（默认 0.02）
  "worldDemandRate": 0.012,    // 世界月需求（默认 0.015）
  "npcTradeRate": 0.006,       // NPC 月贸易量（默认 0.008）
  "greatNewbornChance": 0.08,  // 新贵补位率（默认 0.06）
  "secretRecover": 1,          // 秘境灵气月恢复（默认 2）
  "tradeFloorPct": 0.3         // 断供拒单线（默认 0.35；勿与 poolFloorPct 分离）
}
```

- **白名单**：仅 `WORLDSIM` 表内数值键可覆写（未知键忽略）；覆写可随卸载自动复位；
- **纪律**：数值建议贴近现状量级；`marketRebalance`（弱锚定 0.025）与 `poolFloorPct` 属世界平衡核心，默认不建议 MOD 修改；
- 接口：`overrideWorldNum(key, value)` / `resetWorldNum()`（引擎侧），MOD 作者在文档注解即可。

## 6. 配方（pills / forges）

```jsonc
{ "output": "pill-jiujin", "name": "九金丹", "danfangLevel": 4,
  "stones": 500, "lingcao": 60, "beastcore": 12, "desc": "丹房四级：百年丹。",
  // forges 用: { "output": "weapon-xian", "stones": 900, "lingkuang": 20, "beastcore": 6, ... }
}
```

`output` 全局唯一；`danfangLevel` 建议 1~5（参与丹房门槛）；**成本非负**（校验警告）。

## 7. 安全红线（必读）

1. **零脚本**：MOD 只含 JSON——不做 eval/沙箱/运行时代码。
2. **不碰 `World.rng`**：不新增随机消耗（见 §3 红线；否则世界确定性崩、金钟罩红）。
3. **不改核心时序**：不重排 phase、不覆盖 advanceMonth；扩展走事件池/模板/灾因/配方/词库五口。
4. **语义克制**：数值建议贴近现状量级（power 60~400、weight 0~100、成本仅低于内置顶级丹）。
5. **命名唯一**：id/event id/模板 id/灾因名/配方 output 五个命名空间全部唯一。
6. **worldNum 只动白名单**：覆写仅限 §5.5 列出的键（引擎 `overrideWorldNum` 校验），不碰 rebalance/池底等平衡核心。

## 8. 已验证的安装流程（行为承诺）

- 安装：`World.installPlugin(modToPlugin(pack))` → 事件进池/模板注册/词库聚合/灾因入表/配方注册；
- `modPreflight` 先行：id 冲突拒绝 + 范式警告；`validateMod` 深度校验（category/weight/境界/非负）；
- 启用/停用/卸载：插件双闸与自动回滚照常（卸载即全摘）；
- 存档：MOD 状态随 `state.plugins` 持久化，读档自动重装（版本不符跳过并提示）。

## 9. 打包与分发

- 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
- **游戏内导出**（0.1.27）：「MOD 层 → 导出当前 MOD 集」会把当前启用的全部 MOD 合并为 `mod-bundle-export.cotymod`（含各包明细）——分享/备份走同一载入通道。
- 注意：**MOD 只影响新开档**的世界生成；已开档不受影响（世界种已落档）。

---

**一句话范式**：MOD = "给世界的材料包"——六口（事件/模板/词库/灾因/配方/世界数值）入炉，生成与演化由引擎统一烹调。