ChronicleOfTheImmortalClan/docs/MOD_GUIDE.md

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）

{
  "id": "tianxia-changxiao",
  "name": "天下长啸",
  "version": "1.0.0",
  "schema": 1,
  "author": "你",
  "description": "一支会喊一句口号的曲子。",
  "data": {
    "worldgen": { "fams": ["啸"], "regions": ["天穹岭"] }
  }
}

第 3 步：装上看效果

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

---

2. MOD 包结构总览

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

{
  "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 家——实际家数由种子决定，非全装即全出）。改已装世界不生效（世界形成为档记录）。

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

四组名字概率池，新档生成时抽查：

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

---

6. 能力四：灾因（calamities）

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

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

---

7. 能力五：丹方（pills）

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

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

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

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

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

"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)。

---

9.6 数值 patch 层（0.1.34）

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

"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

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

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