diff --git a/docs/MOD_GUIDE.md b/docs/MOD_GUIDE.md index c495d9d..89999b3 100644 --- a/docs/MOD_GUIDE.md +++ b/docs/MOD_GUIDE.md @@ -1,160 +1,464 @@ -# MOD 规范与范式标准 · Chronicle of the Immortal Clan +# MOD 开发教程 · Chronicle of the Immortal Clan > 版本 **0.1.30·《兼济》** · MOD_SCHEMA_VERSION = 1 -> 每个 MOD 是一个**外部内容包**（纯 JSON，零脚本）；安装后成为插件一等子类， -> 享有插件的全部设施：持久化（随档）、启用/停用、依赖/冲突检查、卸载自动回滚。 +> **本教程即全部所需**：你不需要读任何源码或类型文件——所有 MOD 能用的字段、取值、默认值、坑点都写在这里。 +> 照例动手即可：最快 5 分钟做出你的第一个 MOD。 --- -## 1. 命名与版本 +## 0. 先读这两句（最重要） -| 项 | 规范 | -|---|---| -| `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 对齐；不符给升级提示） | -| 文件名 | `.cotymod`（推荐）或 `.json`，置于 `userData/mods/` | -| `gameVersion` | 可选声明"对哪个游戏版本制作"（仅展示，不强制） | +1. **MOD 是纯 JSON，零脚本**。没有代码、没有沙箱、没有 eval——永远不会"写挂"游戏本体。 +2. **五个安全红线**（违反会导致 MOD 无效或世界怪，但不会崩存档）： + - `id` 全局唯一：只有 `[a-z0-9-]`、长度 2~32（小写字母/数字/连字符/下划线） + - 事件 `id` 不能与游戏内置事件或其它已装 MOD 事件重复（安装时会被拒绝，报具体冲突名） + - 不碰任何 `rng` 字段（MOD 里没有 rng 概念——随机数值一律由游戏引擎生成） + - 数值建议贴近内置量级（模板 power 60~400、事件 weight 0~100、成本不比顶级丹厚） + - 五个数据口：**事件 / 世界模板 / 词库 / 灾因 / 配方** + 特殊口：**世界数值（worldNum）** -## 2. 包结构（全 JSON 单文件） +--- + +## 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`）： + +```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 对象，全部字段如下（标 ✅ 的必填）： ```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 追加 */ ] + "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 */ } + } +} +``` + +**安装行为承诺**（0.1.30 全部兑现）： +- 安装时自动检查：事件 id 冲突 → **拒绝**并报具体名；其余字段不合规 → **警告但安装**（你可能想修正） +- 启用/停用随插件开关；**卸载时 MOD 改过的一切自动还原**（词库/灾因/配方/数值全摘，只删自己加的词条） +- 存档携带 MOD 状态；下次读档自动重装；换电脑或删文件 → 读档提示"缺失 MOD" +- **只影响新开档**：历史存档的世界不会因你装/卸 MOD 改变 + +--- + +## 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 选项数组 + +```jsonc +"options": [ + { + "label": "称谢收下", // ✅ 按钮文字 + "hint": "获得灵石 20", // 悬停提示（写不写都行） + "eff": { "res": { "stones": 20 } } // ✅ 效果（见 3.4 效果表） }, - "worldNum": { "calamityChance": 0.12, "npcTradeRate": 0.006 } // 0.1.27：世界数值白名单覆写（见 §5.5） + { + "label": "婉拒", + "hint": "什么都不变", + "eff": {} + } +] +``` + +### 3.3 条件表（cond）——事件何时发生 + +全部可选；写多个 = 同时满足（`all`）；"任一满足"用 `any`；"不满足"用 `not`。 + +```jsonc +"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. 事件（events） +### 3.4 效果表（eff）——选中后发生什么 -EventDef 全字段**纯数据**（与内置事件同构）： +一个选项可以同时用好几个效果（写多个键）： + +| 键 | 写法 | 示例 | +|---|---|---| +| `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） ```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 - ] +"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": "此事传开，族人倍受鼓舞。" // 可选描述 } ``` -**红线**：事件运行期是引擎核心时序——你的 eff 只影响数据与状态，**不得新增 `rng` 消耗**（会移动全局随机序列）。 - -## 4. 世界模板（npcs） +### 3.6 完整示例（可直接用） ```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"] +"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 字段表 + +```jsonc +"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 完整示例 + +```jsonc +"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 姓氏库），注入的每一条都进生成抽签。 + +```jsonc +"worldgen": { + "fams": ["吴", "江", "雨"], // 姓氏词根（会与后缀组合：吴氏/吴宗/吴寨…） + "regions": ["江南烟雨畔", "吴淞江湾"], // 地区名 + "styles": ["风雅世家", "渔隐门"], // 风骨 + "suffixes": ["氏", "族", "轩"] // 后缀（默认 氏/氏/宗/寨/门；自定义时替换组合） } ``` -模板进入 worldgen 词库池：**玩家"新开档"时参与世界生成**（老档世界不变形）。 -同 `worldgen` 段的 `fams/regions/styles/suffixes` 亦写入生成池。 +> 建议 `regions` 与你的模板 `region` 一致——这样"渔隐柴氏"的世界感统一。卸载时只会撤掉你加的词条，不会污染默认库。 -## 5. 灾因（calamities） +--- + +## 6. 能力四：灾因（calamities） + +给世界加一种"灾年"（与内置旱灾/蝗灾/兽潮同机制——全链路自动生效：减产/市场冲击/快讯/史册）。 ```jsonc -{ "name": "剑灾", "family": { "lingcao": 0.7 }, "effect": { "beastcore": 0.2 } } +"calamities": [ + { + "name": "瘴雨", + "brief": "瘴雨连绵，田间霉蛀——灵植减产。", // 可选：灾年快讯文案（不写则自动用"XX——灵植减产，市价将行"） + "family": { "lingcao": 0.75 }, // 可选：家族生产乘量（1=正常；0.75=减产25%） + "effect": { "lingcao": -0.2 } // 可选：世界市场冲击（-0.2=市池减20%） + } +] ``` -- `name`：全局唯一（与默认 6 灾 + 已装 MOD 冲突即忽略） -- `family`：**玩家家族**生产乘量（1=正常） -- `effect`：**世界市场**池冲击乘量（-0.3 意为减少 30%） -- 灾签与世界循环（减产/市价/快讯/体感）全链路自动生效——这是本作灾年机制的扩展口 +- `family` 键支持：`lingcao / lingkuang / beastcore`（家族生产乘量） +- `effect` 键支持：`lingcao / lingkuang / beastcore`（世界池乘量） +- 灾年持续 6 月，会写进天下史册；**灾名全局唯一**（与内置重复会被忽略） -## 5.5 世界数值（worldNum，0.1.27 起） +--- + +## 7. 能力五：丹方（pills） + +给丹房加新丹药。**丹房等级门槛、材料、效果全由你定义**（服丹的修为增量由引擎按丹名归属自动处理——`pill-` 前缀的丹在"服丹"时走内置逻辑）。 + +```jsonc +"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（材料搭配），这章已够；需要"全新药效"留给未来版本。 + +--- + +## 8. 能力六：铸器配方（forges） + +给"定制"页加新兵刃（铸器是 0.1.16 起的正式玩法；武器**必须有对应物品条目**才能被装备）。 + +```jsonc +"forges": [ + { + "output": "weapon-lingwoon", // ✅ 武器 id（`weapon-` 前缀；内置有 weapon-fan/qi/ling/fa） + "name": "灵纹刃", + "stones": 700, + "lingkuang": 15, + "beastcore": 5, + "desc": "纹蕴灵光，锋锐无俦。" + } +] +``` + +--- + +## 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 | 断供拒单线 | ```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 分离） + "calamityChance": 0.28, + "greatNewbornChance": 0.08 } ``` -- **白名单**：仅 `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))` → 事件进池/模板注册/词库聚合/灾因入表/配方注册/worldNum 覆写； -- **预检已接生产（0.1.28）**：游戏内安装必走 `modPreflight`（事件 id 冲突拒绝装；范式警告 toast）；`validateMod` 深度校验（category/weight/境界/非负/空串/NaN 防护）； -- 启用/停用/卸载：插件双闸与自动回滚照常（**0.1.28 起卸载真正全摘**——词库池/灾因/配方/worldNum 按来源精确回滚，共享词条保留）； -- 存档：MOD 状态随 `state.plugins` 持久化，读档自动重装（版本不符跳过）；**缺失插件记 `state.pluginsMissing` 并提示**（"文件可能需重新放入 mods 目录"）； -- 世界数值：`worldNum`（§2 数据包内）已接线——安装覆写/卸载复位。 - -## 8.5 官方范例（0.1.30） - -游戏内置两枚示范包（设置 → MOD 层 → 内置仓库）可一键安装观摩： - -- **风物集**（`fenwu-ji`）：词库注入（吴/江/雨 + 江南烟雨畔）+ 灾因「瘴雨」（brief 文案示范）——看怎么做"地域风物包"。 -- **战备解军**（`zhanbei-xv`）：配方注入（灵纹刃）+ worldNum 覆写（供需微调）——看怎么做"数值平衡包"。 - -NewGame 开局预览会标注当前已装 MOD 集——**新档世界由 seed+MOD 集共同塑造**（老档不变形）。 - -## 9. 打包与分发 - -- 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。 -- **游戏内导出**（0.1.27，0.1.28 闭环）：「MOD 层 → 导出当前 MOD 集」把当前启用的全部 MOD 合并为 `mod-bundle-export.cotymod`（含各包明细）；导出包可直接再导入（`modParse` 识别 `{app:'cotymod',bundle}` 逐包递归）——分享/备份同通道无断点。 -- 注意：**MOD 只影响新开档**的世界生成；已开档不受影响（世界种已落档）。 +> `marketRebalance`（0.025）与 `poolFloorPct`（0.35）是平衡核心，**不建议** MOD 修改（改了容易让价格/池系统黏糊）。卸载时数值自动还原。 --- -**一句话范式**：MOD = "给世界的材料包"——六口（事件/模板/词库/灾因/配方/世界数值）入炉，生成与演化由引擎统一烹调。 +## 10. 速查表：内置 id 大全 + +### 资源 id（res / sells / buys / family / effect 通用） +`stones`（灵石）· `lingcao`（灵草）· `lingkuang`（灵矿）· `beastcore`（兽核） + +### 丹药 id（pillGain / res 可用） +`pill-qiyuan`（聚气丹）· `pill-ningyuan`（凝元丹）· `pill-pojing`（破境丹） + +### 武器 id（forge output / 掉落池） +`weapon-fan`（凡器）· `weapon-qi`（法器）· `weapon-ling`（灵器）· `weapon-fa`（法宝） + +### 功法 id（addTech；掉落池随机取用） +`t-qinglian`（青莲剑诀·剑修）· `t-canglei`（苍雷炼体功·体修）· `t-lieliuxin`（离火心经·丹修）· `t-houtu`（厚土镇岳功·体修）· `t-xuanyue`（玄月斩灵诀·剑修）· `t-baihui`（百草经·丹修） + +### 建筑 id（addBuilding / minBuilding） +`lingtian`（灵田）· `yaoyuan`（药园）· `lingkuang`（灵矿）· `fangshi`（坊市）· `danfang`（丹房）· `cangshu`（藏书阁）· `juling`（聚灵阵）· `yanwu`（演武场）· `dongfu`（洞府）· `zongci`（宗祠）· `lingshou`（灵兽园） + +### 天下家 id（relation / raid） +`n-xuanying`（玄影沈氏·剑修）· `n-danxin`（丹心木氏·丹道）· `n-sihai`（四海王氏·商盟）· `n-nulei`（怒雷祝氏·兵修）——注：**世界随机化后你家不一定有全部四家**；写它们不会报错，只是关系变化可能发生在"不存在的家"上（忽略即可）。 + +### 秘境 id（mission） +`m-anmoku`（暗墨林）· `m-xuangu`（玄冰谷）· `m-guzhan`（古战阵）· `m-lingshan`（灵鹫山）· `m-quanchen`（渊泉城） + +--- + +## 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——任意撞名 → 后装者会被拒/被忽略。用 `depends`/`conflicts` 声明关系（§2）。 + +--- + +## 12. 进阶：依赖、冲突与导出 + +### 12.1 depends / conflicts + +```jsonc +"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` → 所有字段即你所见。 + +--- + +**一句话总结**：MOD = 一个有 `data` 字段的 JSON。事件管"剧情事件"、模板管"新家族"、词库管"名字概率"、灾因管"灾年种类"、配方管"炼丹铸器"、worldNum 管"世界脾性"。装/卸/导出全在设置页，读档重装全自动。去写吧——这个世界等你的素材。 + +⚔️ 本文档随游戏版本更新（0.1.30）。字段若有新增，此处先行。