thzxx
c9fca1b0b1
重构自 0.1.32 全量底稿(551 行完整示例/字段表/排版保留),精确打补丁: §0 红线 5 口→15 口全图;§2 新增 2.1 data 全景表(世界侧/内容面/配方/patch 四组); §7/§8 红牌(产出必先立名——含内置丹方参照);§9 worldNum 补 warFatigue/断供四键+池底-拒单分离说明; §9.5 功法重排(四流派效果表+量级参照+元素时节共鸣+平衡提醒); 新增 §9.6 patch 层(规则/mult-add/日志/卸载复原/worldNum 区别); §10 速查表全表格化:丹药 5/兵器 6(战力列)/功法 23 全列(流派效果)/建筑 14(产物列)/秘境含 m-wonder 注; §13 官方示例实样 JSON(风物集/战备解军)+灵纹刃立名修正注;FAQ 补 Q8/Q9;尾注四版;更新戳 0.1.35
696 lines
33 KiB
Markdown
696 lines
33 KiB
Markdown
# 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 60~400、事件 weight 0~100、成本不比顶级丹厚）
|
||
- 数据口全图（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`）：
|
||
|
||
```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", // ✅ 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 选项数组
|
||
|
||
```jsonc
|
||
"options": [
|
||
{
|
||
"label": "称谢收下", // ✅ 按钮文字
|
||
"hint": "获得灵石 20", // 悬停提示（写不写都行）
|
||
"eff": { "res": { "stones": 20 } } // ✅ 效果（见 3.4 效果表）
|
||
},
|
||
{
|
||
"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.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）
|
||
|
||
```jsonc
|
||
"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 完整示例（可直接用）
|
||
|
||
```jsonc
|
||
"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": ["氏", "族", "轩"] // 后缀（默认 氏/氏/宗/寨/门；自定义时替换组合）
|
||
}
|
||
```
|
||
|
||
> 建议 `regions` 与你的模板 `region` 一致——这样"渔隐柴氏"的世界感统一。卸载时只会撤掉你加的词条，不会污染默认库。
|
||
|
||
---
|
||
|
||
## 6. 能力四：灾因（calamities）
|
||
|
||
给世界加一种"灾年"（与内置旱灾/蝗灾/兽潮同机制——全链路自动生效：减产/市场冲击/快讯/史册）。
|
||
|
||
```jsonc
|
||
"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-` 前缀的丹在"服丹"时走内置逻辑）。
|
||
|
||
```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（材料搭配），这章已够；需要"全新药效"留给未来版本。
|
||
|
||
---
|
||
|
||
> **红牌（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 起的正式玩法；武器**必须有对应物品条目**才能被装备）。
|
||
|
||
```jsonc
|
||
"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 | 断供拒单线 |
|
||
|
||
```jsonc
|
||
"worldNum": {
|
||
"calamityChance": 0.28,
|
||
"greatNewbornChance": 0.08
|
||
}
|
||
```
|
||
|
||
> `marketRebalance`（0.025）与 `poolFloorPct`（0.35）是平衡核心，**不建议** MOD 修改（改了容易让价格/池系统黏糊）。卸载时数值自动还原。
|
||
|
||
---
|
||
|
||
## 9.5 内容面扩展（0.1.31：物品/功法/建筑/职事/志向/阵型/性格）
|
||
|
||
七个新口全部纯数据；**内置条目不可覆盖**（同名 id 被跳过——防覆盖红线），只加新键。
|
||
|
||
### 物品（items）——配丹药/武器显示
|
||
```jsonc
|
||
"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 起含四流派效果
|
||
```jsonc
|
||
"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）
|
||
```jsonc
|
||
"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）
|
||
```jsonc
|
||
"posts": [
|
||
{ "id": "p-chashi", "effectType": "marketIncome", "value": 0.06, "max": 1, "desc": "坐市司货，坊市入息 +6%。" }
|
||
]
|
||
```
|
||
`effectType` 取值（对应内置效果）：`expAll / marketIncome / battlePower / cultivation / stamina / insight / feast`。
|
||
|
||
### 志向（aspirations）
|
||
```jsonc
|
||
"aspirations": [
|
||
{ "id": "a-chafan", "desc": "偶有茶会，心神宁和。", "effectType": "cult", "value": 0.04 }
|
||
]
|
||
```
|
||
`effectType`：`cult`（修为）/ `field`(产田)/ `market`（商市）/ `combat`（战力）/ `offspring`（生育）。
|
||
|
||
### 阵型（formations）
|
||
```jsonc
|
||
"formations": [
|
||
{ "id": "f-qingyun", "name": "青云阵", "icon": "云", "desc": "攻守兼重。", "atk": 1.05, "def": 1.05, "retreatWound": 1 }
|
||
]
|
||
```
|
||
|
||
### 性格（traits）
|
||
```jsonc
|
||
"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 顶层）
|
||
```jsonc
|
||
"kind": "content" // content(剧情/风物) | data(新实体：物品功法建筑) | rules(数值规则：worldNum/表达式)
|
||
```
|
||
仅用于设置页归类展示，不影响装载逻辑——**填不填都行**（不填默认 content）。
|
||
|
||
## 9.6 数值 patch 层（0.1.34）
|
||
|
||
**不改表结构、不加新实体**——只对"已存在"的表项改数值；打包/改值/回滚全自动。
|
||
|
||
```jsonc
|
||
"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
|
||
|
||
```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` → 所有字段即你所见。
|
||
|
||
**风物集** data 实样：
|
||
```jsonc
|
||
{ "worldgen": { "fams": ["吴","江","雨"], "regions": ["江南烟雨畔","吴淞江湾"], "styles": ["风雅世家","渔隐门"] },
|
||
"calamities": [{ "name": "瘴雨", "brief": "瘴雨连绵，田间霉蛀——灵植减产。", "family": { "lingcao": 0.75 }, "effect": { "lingcao": -0.2 } }] }
|
||
```
|
||
|
||
**战备解军** data 实样：
|
||
```jsonc
|
||
{ "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 全部规则。
|
||
|
||
<sub>⚔️ 本文档随游戏版本更新（0.1.35）。字段若有新增，此处先行。</sub>
|