thzxx
6cbd604e24
AGENTS：金钟罩注释 0.1.24→0.1.28（指纹补盲清单：worldGen 摘要/sagaAnnals/distress/declineYears） README：测试数 69/2008 + 版本沿革 0.1.28 + 守护机制补「审计三轮」 PROJECT_MEMORY：时间线 0.1.28 + 教训 6e「承诺-实现间隙」+ 技术债更新（缓做项定案） MOD_GUIDE：版本 0.1.28 + 兑现注记（预检生产链/卸载真回滚/worldNum 接线/缺失提示/bundle 再导入闭环）
152 lines
7.4 KiB
Markdown
152 lines
7.4 KiB
Markdown
# MOD 规范与范式标准 · Chronicle of the Immortal Clan
|
||
|
||
> 版本 **0.1.28·《稳石》** · MOD_SCHEMA_VERSION = 1
|
||
> 每个 MOD 是一个**外部内容包**（纯 JSON，零脚本）；安装后成为插件一等子类，
|
||
> 享有插件的全部设施：持久化（随档）、启用/停用、依赖/冲突检查、卸载自动回滚。
|
||
|
||
---
|
||
|
||
## 1. 命名与版本
|
||
|
||
| 项 | 规范 |
|
||
|---|---|
|
||
| `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 对齐；不符给升级提示） |
|
||
| 文件名 | `<id>.cotymod`（推荐）或 `<id>.json`，置于 `userData/mods/` |
|
||
| `gameVersion` | 可选声明"对哪个游戏版本制作"（仅展示，不强制） |
|
||
|
||
## 2. 包结构（全 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 追加 */ ]
|
||
},
|
||
"worldNum": { "calamityChance": 0.12, "npcTradeRate": 0.006 } // 0.1.27：世界数值白名单覆写（见 §5.5）
|
||
}
|
||
```
|
||
|
||
## 3. 事件（events）
|
||
|
||
EventDef 全字段**纯数据**（与内置事件同构）：
|
||
|
||
```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
|
||
]
|
||
}
|
||
```
|
||
|
||
**红线**：事件运行期是引擎核心时序——你的 eff 只影响数据与状态，**不得新增 `rng` 消耗**（会移动全局随机序列）。
|
||
|
||
## 4. 世界模板（npcs）
|
||
|
||
```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"]
|
||
}
|
||
```
|
||
|
||
模板进入 worldgen 词库池：**玩家"新开档"时参与世界生成**（老档世界不变形）。
|
||
同 `worldgen` 段的 `fams/regions/styles/suffixes` 亦写入生成池。
|
||
|
||
## 5. 灾因（calamities）
|
||
|
||
```jsonc
|
||
{ "name": "剑灾", "family": { "lingcao": 0.7 }, "effect": { "beastcore": 0.2 } }
|
||
```
|
||
|
||
- `name`：全局唯一（与默认 6 灾 + 已装 MOD 冲突即忽略）
|
||
- `family`：**玩家家族**生产乘量（1=正常）
|
||
- `effect`：**世界市场**池冲击乘量（-0.3 意为减少 30%）
|
||
- 灾签与世界循环（减产/市价/快讯/体感）全链路自动生效——这是本作灾年机制的扩展口
|
||
|
||
## 5.5 世界数值（worldNum，0.1.27 起）
|
||
|
||
```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 分离）
|
||
}
|
||
```
|
||
|
||
- **白名单**：仅 `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 数据包内）已接线——安装覆写/卸载复位。
|
||
|
||
## 9. 打包与分发
|
||
|
||
- 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
|
||
- **游戏内导出**（0.1.27，0.1.28 闭环）：「MOD 层 → 导出当前 MOD 集」把当前启用的全部 MOD 合并为 `mod-bundle-export.cotymod`（含各包明细）；导出包可直接再导入（`modParse` 识别 `{app:'cotymod',bundle}` 逐包递归）——分享/备份同通道无断点。
|
||
- 注意：**MOD 只影响新开档**的世界生成；已开档不受影响（世界种已落档）。
|
||
|
||
---
|
||
|
||
**一句话范式**：MOD = "给世界的材料包"——六口（事件/模板/词库/灾因/配方/世界数值）入炉，生成与演化由引擎统一烹调。
|