ChronicleOfTheImmortalClan/docs/MOD_GUIDE.md

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

版本 0.1.26·《墨规清辉》 · 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 单文件）

{
  "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 追加 */ ]
  }
}

3. 事件（events）

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

{
  "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）

{
  "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）

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

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

6. 配方（pills / forges）

{ "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 60400、weight 0100、成本仅低于内置顶级丹）。
5. 命名唯一：id/event id/模板 id/灾因名/配方 output 五个命名空间全部唯一。

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

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

9. 打包与分发

• 单文件 .cotymod（= JSON）直接分发；放入 userData/mods/ 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
• 注意：MOD 只影响新开档的世界生成；已开档不受影响（世界种已落档）。

---

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