thzxx
ba9766e152
【MOD 规范与范式（核心命题）】 - docs/MOD_GUIDE.md：完整作者守则——命名/id 规约/semver/schema:1/五数据口 （事件/模板/词库/灾因/配方）/依赖冲突/安全红线（无脚本·禁碰 rng·不动核心时序）/ 打包分发（.cotymod 单文件）/行为承诺 - validateMod 深度校验：category/weight/境界/负成本/非空/options.eff 形状 - modPreflight 权威冲突检测：findEvent（池+动态分支 raid/渡劫/大比/传薪全量） - MOD_SCHEMA_VERSION=1 + schema 声明与升级提示；PluginStatus.author 展示 【灾因归一化（平衡版落地）】 - calamities 由 as const 死表→聚合注册表（calamityNames/calamityFamilyOf/calamityEffectOf+addCalamity） - WorldSim 灾签/生产/Market 全链路走聚合读口——MOD 灾因（剑灾/灵潮湍变）进入世界循环 - 默认表不变→基准世界指纹零漂（clock.test 全绿实证） 【页面可读性（有点暗）】 - .dim #6d6150→#a99c80（3.4:1→7+:1）、.dim2 #96896e→#c3b595、.help-text 提亮、 .feed-item 显色 #efe4c9 + 灰金系 8 处提亮（styles.css 12+/11- 纯色值） - tests/contrast-readability.test.ts：WCAG 对比度审计（≥4.5:1）+ 历史暗色迁移断言 【测试】1047 全绿（47 套件）：mod-system 9（+validate/灾因/冲突/预检）、contrast 3； 【金钟罩】0.1.25 基线零漂；build 通过
130 lines
5.5 KiB
Markdown
130 lines
5.5 KiB
Markdown
# MOD 规范与范式标准 · Chronicle of the Immortal Clan
|
||
|
||
> 版本 **0.1.26·《墨规清辉》** · 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 追加 */ ]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 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%）
|
||
- 灾签与世界循环（减产/市价/快讯/体感）全链路自动生效——这是本作灾年机制的扩展口
|
||
|
||
## 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 五个命名空间全部唯一。
|
||
|
||
## 8. 已验证的安装流程（行为承诺）
|
||
|
||
- 安装：`World.installPlugin(modToPlugin(pack))` → 事件进池/模板注册/词库聚合/灾因入表/配方注册；
|
||
- `modPreflight` 先行：id 冲突拒绝 + 范式警告；`validateMod` 深度校验（category/weight/境界/非负）；
|
||
- 启用/停用/卸载：插件双闸与自动回滚照常（卸载即全摘）；
|
||
- 存档：MOD 状态随 `state.plugins` 持久化，读档自动重装（版本不符跳过并提示）。
|
||
|
||
## 9. 打包与分发
|
||
|
||
- 单文件 `.cotymod`（= JSON）直接分发；放入 `userData/mods/` 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
|
||
- 注意：**MOD 只影响新开档**的世界生成；已开档不受影响（世界种已落档）。
|
||
|
||
---
|
||
|
||
**一句话范式**：MOD = "给世界的材料包"——五口（事件/模板/词库/灾因/配方）入炉，生成与演化由引擎统一烹调。
|