ChronicleOfTheImmortalClan/docs/MOD_GUIDE.md

MOD 开发教程 · Chronicle of the Immortal Clan

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

---

目录

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

{
  "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 一个"五脏俱全"的示意壳（啃编排用）

{
  "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 事件字段表

{
  "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 选项数组

"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）详解

"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 完整示例（可直接用）

{
  "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 字段表

{
  "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 完整示例

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

---

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

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

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

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

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

---

6. 能力四：灾因（calamities）

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

"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 起物品表接口已开放，背包/卖出/服丹全走物品表）。

"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！产物没有物品表定义 = 幽灵物品——炼出来在背包里看不见、卖不掉、不能用。标准的配合写法：

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

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

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

"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）做覆写——调供需、池深、潮汐、灾年概率、战争疲劳等。白名单机制：只认常数表内键，乱写的键被忽略（不报错不算错）。

"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）——六类生态

"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）——含四流派效果

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

"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 效果

"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 效果

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

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

"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 层

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

"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

"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 实样：

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

战备解军 data 实样：

{
  "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 可以注册自定义奇观类型，加入年首种子派生选取池：

"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-* 前缀保护防劫持。

_{⚔️ 本文档随游戏版本更新（0.1.37）。字段若有新增，此处先行。}