ChronicleOfTheImmortalClan/docs/MOD_GUIDE.md

MOD 开发教程 · Chronicle of the Immortal Clan

版本 0.1.35·《涤荡·向新》 · MOD_SCHEMA_VERSION = 1 本教程即全部所需：你不需要读任何源码或类型文件——所有 MOD 能用的字段、取值、默认值、坑点都写在这里。 照例动手即可：最快 5 分钟做出你的第一个 MOD。

---

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

1. MOD 是纯 JSON，零脚本。没有代码、没有沙箱、没有 eval——永远不会"写挂"游戏本体。
2. 五个安全红线（违反会导致 MOD 无效或世界怪，但不会崩存档）：
   • id 全局唯一：只有 [a-z0-9-]、长度 2~32（小写字母/数字/连字符/下划线）
   • 事件 id 不能与游戏内置事件或其它已装 MOD 事件重复（安装时会被拒绝，报具体冲突名）
   • 不碰任何 rng 字段（MOD 里没有 rng 概念——随机数值一律由游戏引擎生成）
   • 数值建议贴近内置量级（模板 power 60400、事件 weight 0100、成本不比顶级丹厚）
   • 数据口全图（0.1.35 共 15 口）：事件 / 世界模板 / 词库 / 灾因 / 丹方 / 铸器 / 世界数值 / 物品 / 功法 / 建筑 / 职事 / 志向 / 阵型 / 性格 / 数值 patch——按需自取，见 §3~§9.6

---

1. 五分钟上手

第 1 步：放文件

在你的游戏用户目录下建 mods 文件夹（没有就建一个），文件名随意，但要：

• 后缀 .json 或 .cotymod（两种都行，内容完全一样）
• 文件名 [a-z0-9-].json（建议与 MOD id 同名：hello-world.json）

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

第 2 步：复制这个文件

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

{
  "id": "hello-world",
  "name": "你好世界",
  "version": "1.0.0",
  "schema": 1,
  "author": "你的名字",
  "description": "我的第一个 MOD：家族来了一位卖豆腐的老伯。",
  "data": {}
}

第 3 步：装上看效果

游戏内 → 设置 → MOD 层 → 扫描目录 → 列表里出现 hello-world.json → 点 安装 → 提示"MOD 安装完成"。

看效果的验证方法：MOD 层插件表格里出现 MOD·你好世界 v1.0.0 · content · 你的名字。新开一局时 NewGame 预览页会标注「已装入 MOD：你好世界」。

只有 data 段为空时这个 MOD 什么都不会改。想改世界的活往下看。

---

2. MOD 包结构总览

一个 MOD = 一个 JSON 对象，全部字段如下（标 ✅ 的必填）：

{
  "id": "jiangnan-feng",        // ✅ MOD 唯一 id（[a-z0-9-]{2,32}）
  "name": "江南遗风",            // ✅ 显示名
  "version": "1.0.0",           // ✅ 版本号（semver：主.次.补）
  "schema": 1,                  // 建议：格式版本，目前恒写 1
  "author": "风雅散人",          // 建议：作者名（会显示在设置页）
  "description": "一句话说来意。", // 建议：说明文字
  "gameVersion": "0.1.30",      // 可选：为哪个游戏版本做的（仅展示）
  "depends": ["other-mod-id"],  // 可选：依赖的其它 MOD id（未装会拒绝安装）
  "conflicts": ["old-mod-id"],  // 可选：与哪些 MOD 互斥（已装会拒绝安装）
  "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 */ ]
  },
  "kind": "content"   // 类型标签（content 内容/data 实体/rules 规则——仅展示与归类）
}

安装行为承诺（0.1.30 全部兑现）：

• 安装时自动检查：事件 id 冲突 → 拒绝并报具体名；其余字段不合规 → 警告但安装（你可能想修正）
• 启用/停用随插件开关；卸载时 MOD 改过的一切自动还原（词库/灾因/配方/数值全摘，只删自己加的词条）
• 存档携带 MOD 状态；下次读档自动重装；换电脑或删文件 → 读档提示"缺失 MOD"
• 只影响新开档：历史存档的世界不会因你装/卸 MOD 改变

---

2.1 data 全景（0.1.35 十五口）

五个"世界侧"口（影响世界生成/天下演化）：

口	章节	一句话	卸载后
events	§3	随机剧情事件	从事件池摘除
npcs	§4	世界模板（新家族）	模板池摘除
worldgen	§5	词库（姓/地/风）	词库池按来源摘除
calamities	§6	灾因（旱/涝/蝗…）	灾因表按名摘除
worldNum	§9	世界基数覆写	复位

七个"内容面"口（0.1.31 起，全纯数据——内置条目不可覆盖，同名 id 被跳过并 warn）：items（§9.5）· techniques（§9.5）· buildings（§9.5）· posts（§9.5）· aspirations（§9.5）· formations（§9.5）· traits（§9.5）

两个"配方"口：pills（§7）· forges（§8）——产物必须先立名 items（0.1.33 红牌）。

一个"微调"口（0.1.34）：patch（§9.6）——对已存在表项改数值（mult 0.5~2 / add），卸载复原。

---

3. 能力一：事件（events）

事件 = 游戏过程中冒出的"情景选择"（和内置事件共用一套系统）。

3.1 字段表

字段	类型	必填	说明
id	string	✅	ev- 开头便于辨识；全游戏唯一（冲突→拒装）
name	string	✅	弹窗标题
category	string	✅	daily（日常）/ major（大事）/ fate（天命）。越高越少见
weight	number	✅	抽中权重，0~100。同类别内按权重随机
text	string	✅	事件正文
once	boolean	✖	true 则整局只发生一次
cond	object	✖	触发条件（见 3.3 条件表）——不写=任何年代都可能发生
options	array	✅	选项数组（1~4 个），见 3.2

3.2 选项数组

"options": [
  {
    "label": "称谢收下",        // ✅ 按钮文字
    "hint": "获得灵石 20",       // 悬停提示（写不写都行）
    "eff": { "res": { "stones": 20 } }  // ✅ 效果（见 3.4 效果表）
  },
  {
    "label": "婉拒",
    "hint": "什么都不变",
    "eff": {}
  }
]

3.3 条件表（cond）——事件何时发生

全部可选；写多个 = 同时满足（all）；"任一满足"用 any；"不满足"用 not。

"cond": {
  "minYear": 5,                            // 第五年及以后
  "minRep": 50,                            // 声望 ≥50
  "maxRep": 200,                           // 声望 ≤200
  "minGeneration": 3,                      // 至少第三代
  "minHeadRealm": "foundation",            // 家主最低境界（mortal/qi/foundation/core/nascent/spirit）
  "minMembers": 8,                         // 家族至少 8 人
  "minAdult": 3,                           // 适婚成人 ≥3
  "minBuilding": { "id": "danfang", "level": 2 },   // 某建筑 ≥Lv2（建筑 id 见 §10 速查）
  "minResource": { "id": "lingcao", "n": 50 },      // 库存某资源 ≥50
  "minTechCount": 3,                       // 家传功法 ≥3 部
  "flag": { "key": "anyKey", "eq": true }, // 家族某旗标为真
  "relation": { "npcId": "n-danxin", "lt": 0 },    // 与某天下家关系 <0
  "any": [ { "minRep": 100 }, { "minYear": 60 } ], // 任一满足
  "not": { "minYear": 3 }                  // 第三年以前
}

3.4 效果表（eff）——选中后发生什么

一个选项可以同时用好几个效果（写多个键）：

键	写法	示例
res	资源增减（灵石/灵草/灵矿/兽核 + 丹药）	{"stones":-50,"lingcao":5}
rep	家族声望变动	{"rep":10}
relation	与天下各家关系（用 n- 家 id）	{"n-danxin":5,"n-nulei":-8}
pillGain	直接获得丹药	{"pill-qiyuan":1}
addTech	获得功法（t- id，见 §10）	{"addTech":"t-baihui"}
addBuilding	白得一座建筑（建筑 id）	{"addBuilding":"lingtian"}
memberBy	对族人施加（见 3.5）	{"by":"inspire","target":"all","n":3}
flag	设家族旗标（后续可被 cond 读取）	{"anyKey":true}
mission	触发某秘境（m- id）给家族	{"mission":"m-anmoku"}
raid	某家来犯	{"npcId":"n-nulei"}
techniqueChance	概率得功法（0~1）	{"techniqueChance":0.3}
artifactChance	概率得宝器	{"artifactChance":0.3}
tournament	触发大比	{"tournament":true}
apprentice	触发谒祖师	{"build":true}
trib	指定成员渡劫	{"memberId":"某成员id","mode":"rash"}（rash/guard/delay）
feisheng	飞升剧情	{"stay":false}

3.5 族人效果（memberBy）

"memberBy": {
  "by": "exp",        // exp 修为 / wound 受伤 / heal 治愈 / breakthrough 突破 / fatal 重伤 /
                      // repGain 名望 / inspire 心境 / loot 得财 / madness 入魔 / genius 顿悟
  "target": "all",    // random / head / youngest / oldest / highestPerception / highestPower / all
  "n": 3,             // 数量（all 时忽略）
  "desc": "此事传开，族人倍受鼓舞。"  // 可选描述
}

3.6 完整示例（可直接用）

"events": [
  {
    "id": "ev-jiangnan-rain",
    "name": "江南烟雨",
    "category": "daily",
    "weight": 3,
    "once": false,
    "cond": { "minYear": 2 },
    "text": "一连三日细雨，田垄新绿。一位老农挑着桑筐来访，自称是十里外的蚕桑户。",
    "options": [
      { "label": "留饭相谈", "hint": "灵草+3，声望+2", "eff": { "res": { "lingcao": 3 }, "rep": 2 } },
      { "label": "赠他盘缠", "hint": "灵石-15，好感+5", "eff": { "res": { "stones": -15 }, "relation": { "n-danxin": 5 } } },
      { "label": "笑笑送客", "hint": "无", "eff": {} }
    ]
  }
]

常见坑：

• weight 决定概率：一个 MOD 塞 20 个 weight:100 的事件会垄断剧情——引擎会自动按"插件池 ≤ 核心 50%"压缩，但文明开发请保持克制（日常事件推荐 1~5）
• id 撞名会被拒装——改名即可
• 事件正文/选项不要用半角引号冲突（JSON 标准转义 \"）

---

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

让这个世界"开局多一家"（或这家的某几族）。只影响新开档。

4.1 字段表

"npcs": [
  {
    "id": "n-gu-shi",              // ✅ 建议 n- 前缀；全局唯一
    "name": "姑苏顾氏",            // ✅ 显示名
    "region": "江南烟雨港",        // ✅ 势力所在地区（词库会被生成引用）
    "style": "风雅世家",           // ✅ 宗族风骨（剑修世家/丹道世家/商盟世族/兵修蛮门/符箓仙门/灵植谷户/阵道门阀/散修聚落…自由写）
    "desc": "临水而居，诗酒传家。",// ✅ 介绍
    "leaderRealm": "foundation",   // ✅ 宗主境界（4.2 取值）
    "initialPower": 150,           // ✅ 开局实力（建议 60~400；与开局难度会再乘系数）
    "powerGrowth": [3, 9],         // ✅ 年度成长范围 [最小, 最大]
    "sells": ["lingcao"],          // 可选：它卖什么给市场（资源 id）
    "buys": ["lingcao", "lingkuang"] // 可选：它买什么
  }
]

4.2 境界取值（所有用到境界的地方通用）

mortal（凡人）→ qi（练气）→ foundation（筑基）→ core（金丹）→ nascent（元婴）→ spirit（化神）

4.3 完整示例

"npcs": [
  {
    "id": "n-jiang-yu",
    "name": "渔隐柴氏",
    "region": "江南烟雨港",
    "style": "渔隐门",
    "desc": "一叶扁舟渡南北，渔篓里尽是江湖事。",
    "leaderRealm": "qi",
    "initialPower": 120,
    "powerGrowth": [2, 7],
    "sells": ["beastcore"],
    "buys": ["lingcao"]
  }
]

常见坑：power 太低的新家开局会被默认为"衰微家"（power<150 且景气低持续 8 年会覆灭）——这不是 bug，是世界的淘汰规律；建议新家 initialPower ≥ 120。

---

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

让新世界"这个时代容易出什么名字/哪里的家族"。词库会混入自家词库（默认 4 系 12 姓氏库），注入的每一条都进生成抽签。

"worldgen": {
  "fams": ["吴", "江", "雨"],            // 姓氏词根（会与后缀组合：吴氏/吴宗/吴寨…）
  "regions": ["江南烟雨畔", "吴淞江湾"],    // 地区名
  "styles": ["风雅世家", "渔隐门"],       // 风骨
  "suffixes": ["氏", "族", "轩"]         // 后缀（默认 氏/氏/宗/寨/门；自定义时替换组合）
}

建议 regions 与你的模板 region 一致——这样"渔隐柴氏"的世界感统一。卸载时只会撤掉你加的词条，不会污染默认库。

---

6. 能力四：灾因（calamities）

给世界加一种"灾年"（与内置旱灾/蝗灾/兽潮同机制——全链路自动生效：减产/市场冲击/快讯/史册）。

"calamities": [
  {
    "name": "瘴雨",
    "brief": "瘴雨连绵，田间霉蛀——灵植减产。",   // 可选：灾年快讯文案（不写则自动用"XX——灵植减产，市价将行"）
    "family": { "lingcao": 0.75 },               // 可选：家族生产乘量（1=正常；0.75=减产25%）
    "effect": { "lingcao": -0.2 }                // 可选：世界市场冲击（-0.2=市池减20%）
  }
]

• family 键支持：lingcao / lingkuang / beastcore（家族生产乘量）
• effect 键支持：lingcao / lingkuang / beastcore（世界池乘量）
• 灾年持续 6 月，会写进天下史册；灾名全局唯一（与内置重复会被忽略）

---

7. 能力五：丹方（pills）

给丹房加新丹药。丹房等级门槛、材料、效果全由你定义（服丹的修为增量由引擎按丹名归属自动处理——pill- 前缀的丹在"服丹"时走内置逻辑）。

"pills": [
  {
    "output": "pill-biandan",    // ✅ 丹药 id（pill-QIANSUO 命名：`pill-` + 拼音/英文短名）；需安装或存有对应描述（见坑）
    "name": "便丹",
    "danfangLevel": 1,           // ✅ 丹房等级门槛（1~5）
    "stones": 30,                // ✅ 灵石成本
    "lingcao": 8,                // ✅ 灵草成本
    "beastcore": 0,              // ✅ 兽核成本（0 也可以）
    "desc": "出门在外备着。"
  }
]

为什么需要 items 配套：丹药在背包与卖出时要有"名号/图标"，由物品表供应——MOD 需要一个配套物品条目（同时给物品表与丹方）。0.1.30 起物品表接口暂未开放：丹方会入"可炼制"列表、服丹修为增加，但背包显示用惯例名。建议先只做"专用丹方"主题，或等 item 表开放（在开发中）——文档会第一时间更新。

若你只想做"经济型" mod（材料搭配），这章已够；需要"全新药效"留给未来版本。

---

红牌（0.1.33 生态纪律）：output 必须同时出现在 §9.5 items 里——产物没有物品表定义 = 幽灵物品（炼出来不可见、不可卖、不可装备）。内置丹方参考：聚气 pill-qiyuan/凝元 pill-ningyuan/破境 pill-pojing/和灵 pill-heling/虚元 pill-xudan（丹房等级 1/2/3/2/4）。

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

给"定制"页加新兵刃（铸器是 0.1.16 起的正式玩法；武器必须有对应物品条目才能被装备）。

"forges": [
  {
    "output": "weapon-lingwoon",   // ✅ 武器 id（`weapon-` 前缀；内置有 weapon-fan/qi/ling/fa）
    "name": "灵纹刃",
    "stones": 700,
    "lingkuang": 15,
    "beastcore": 5,
    "desc": "纹蕴灵光，锋锐无俦。"
  }
]

---

红牌（0.1.33 生态纪律）：output 同样必须先立名 items（内置参照：凡器 weapon-fan/法器 weapon-qi/灵器 weapon-ling/法宝 weapon-fa/玉澜刃 0.1.33 weapon-yu/灵纹刃 官方示例 weapon-lingwoon）。另：铸器不带建筑门槛、数值即门槛——stones/lingkuang/beastcore 的三成本既是成本也是难度。

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

微调"世界的脾气"。白名单键（只允许改这些；写别的键会被忽略、但不会报错）：

键	默认	说明
calamityChance	0.18	灾年概率（0.5 = 几乎年年灾）
worldSupplyRate	0.02	世界月供给
worldDemandRate	0.015	世界月需求
npcTradeRate	0.008	NPC 月贸易量
greatNewbornChance	0.06	新贵补位率
secretRecover	2	秘境灵气月恢复
tradeFloorPct	0.35	断供拒单线

"worldNum": {
  "calamityChance": 0.28,
  "greatNewbornChance": 0.08
}

marketRebalance（0.025）与 poolFloorPct（0.35）是平衡核心，不建议 MOD 修改（改了容易让价格/池系统黏糊）。卸载时数值自动还原。

---

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

七个新口全部纯数据；内置条目不可覆盖（同名 id 被跳过——防覆盖红线），只加新键。

物品（items）——配丹药/武器显示

"items": [
  { "id": "pill-biandan", "name": "便丹", "kind": "pill", "basePrice": 60, "desc": "出门在外备着。", "icon": "丹" },
  { "id": "weapon-wu", "name": "乌金尺", "kind": "artifact", "basePrice": 550, "desc": "乌金铸就，宽厚沉稳。", "icon": "玄" }
]

kind 取值（0.1.32 六值）：resource（资源）/ material（素材：灵玉灵木兽皮灵果等） / pill（丹药）/ talisman（符箓：开战武备自动消耗） / brew（灵酿：渡劫伤后自动回气） / artifact(兵器)。加了物品后：丹方（§7）/铸器（§8）与市场/背包自动可见。

功法（techniques）——0.1.34 起含四流派效果

"techniques": [
  { "id": "t-lingwu", "name": "灵雾心法", "grade": 1, "element": "水", "path": "丹修",
    "expBonus": 0.11, "powerBonus": 0.12, "desc": "雾气绕身，吐纳绵长。" },
  { "id": "t-hanfeng", "name": "寒锋慢斩诀", "grade": 2, "element": "水", "path": "剑修",
    "expBonus": 0.15, "powerBonus": 0.18,
    "critChance": 0.1,              // 流派效果（全 optional，缺省零行为）
    "guardBonus": 0.25,
    "tribBonus": 0.05,
    "secretBonus": 0.15,
    "desc": "剑藏寒锋，斩人有思。" }
]

• grade 1~4（品阶：市价/掉率/求学经库门槛）；element 木/金/水/火/土/雷；path 剑修/体修/丹修/阵修/符修/御灵自由
• 四流派效果（0.1.34 全 optional）——缺省即零行为：

  字段	作用	参考量级
  critChance	暴击：战斗败亡率压制	0.05~0.12
  guardBonus	受创减免：战斗受伤折减	0.15~0.3
  tribBonus	渡劫成功率加成	0.03~0.09
  secretBonus	秘境收获放大	0.1~0.2

• 元素×时令共鸣（0.1.34）：春木/夏火/秋金/冬水——修炼 expBonus 额外 ×1.04；土系恒应 ×1.02（4 季皆宜，0.1.35）
• 新功法将进入：藏书阁可购（grade≤3）/ 秘境掉落 / 拍卖 / 求经台
• 平衡提醒：validateMod 检查 expBonus ≤ 0.5 / powerBonus ≤ 1（警告级，不阻断）

建筑（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
]

• kind：produce（月产）/ function（加成（function 型加成用 worldNum 风格暂不支持自定义配方——建议 produce 为主））
• 建筑自动出现在领地页可建/可升；生产表达式白名单安全（数学符号 + L，别的符号被忽略）

职事（posts）

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

effectType 取值（对应内置效果）：expAll / marketIncome / battlePower / cultivation / stamina / insight / feast。

志向（aspirations）

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

effectType：cult（修为）/ field(产田)/ market（商市）/ combat（战力）/ offspring（生育）。

阵型（formations）

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

性格（traits）

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

bonus 键：expBonus（修为）/ breakBonus（突破成功率）/ windBonus（战力）/ charmBonus（魅力）/ priceMult（售价）/ danger（风险 0~1——性情中的祸患）。

kind 类型（manifest 顶层）

"kind": "content"   // content(剧情/风物) | data(新实体：物品功法建筑) | rules(数值规则：worldNum/表达式)

仅用于设置页归类展示，不影响装载逻辑——填不填都行（不填默认 content）。

9.6 数值 patch 层（0.1.34）

不改表结构、不加新实体——只对"已存在"的表项改数值；打包/改值/回滚全自动。

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

规则（validateMod 预检 + 运行时双重把关）：

• mult 限 0.5 ~ 2（越界 → MOD 拒绝）；add 为实数
• mult / add 二选一，勿同给（同给 → 拒绝）
• 只对已定义数值键生效：功法作用于 expBonus/powerBonus/critChance/guardBonus/tribBonus/secretBonus；物品作用于 basePrice（钳制 ≥1）
• 目标字段缺失 → warn 日志（[patch] 功法 xx 无字段 yy），绝不静默吞
• 仅新开档生效；卸载复原（0.1.35 归属到每个插件——卸载只弹本家，互不侵扰）
• 与 worldNum 区别：worldNum 改全局世界常数，patch 改表项数据——两者可并用

---

10. 速查表：内置 id 大全

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

• 资源：stones（灵石）· lingcao（灵草）· lingkuang（灵矿）· beastcore（兽核）
• 材料（0.1.32 新材料七种）：lingyu（灵玉）· lingmu（灵木）· shoupi（兽皮）· lingguo（灵果）· linglu（灵露）· dansha（丹砂）· fuzhi（符纸）
• 符箓：talisman-feng（风符·开战武备消耗）· talisman-shan（山符）
• 灵酿：brew-niang（灵酿·渡劫伤后回气）
• 来源速记（与玩法真实对应）：灵玉←玄冰谷/古战阵掉落+市场；灵木←灵木坊（建筑）+暗墨林；兽皮←灵兽园/古战阵/兽潮灾年；灵果←灵果园；丹砂/灵露/符纸←市场购买为主

丹药 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 新丹方

武器 id（forge output / 掉落池 / ARTIFACT_POWER）

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 立名修复）

功法 id（addTech；掉落池随机取用）——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	—

建筑 id（addBuilding / minBuilding / produceExpr）——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）

天下家 id（relation / raid）

n-xuanying（玄影沈氏·剑修）· n-danxin（丹心木氏·丹道）· n-sihai（四海王氏·商盟）· n-nulei（怒雷祝氏·兵修）——注：世界随机化后你家不一定有全部四家；写它们不会报错，只是关系变化可能发生在"不存在的家"上（忽略即可）。

秘境 id（mission）

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 即可。

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 修复过的正确姿势）。

---

一句话总结：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 季同频（土系恒应）。MOD 功法别拿这个当"必填"——只填想要的即可。 0.1.35 涤荡注：无存档迁移（游戏未发布——旧档随版本演进失效属预期）；patch 层按插件归属回滚；validate 覆盖 §12 全部规则。

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