Files

T

thzxx d8d34fcb74 docs: MOD_GUIDE 同步 0.1.27

- 版本头 0.1.26→0.1.27；数据口五→六（新增 §5.5 世界数值 worldNum 白名单覆写）
- 安全红线补第 6 条（worldNum 只动白名单键）
- 依赖语义补充（注册库内自动先装）；§9 分发补「游戏内导出 MOD 集」
- 范式一句话更新（六口入炉）

2026-08-23 17:25:41 +08:00

6.9 KiB

Raw Blame History

MOD 规范与范式标准 · Chronicle of the Immortal Clan

版本 0.1.27·《活水长流》 · 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 单文件）

{
  "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 全字段纯数据（与内置事件同构）：

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

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

{ "name": "剑灾", "family": { "lingcao": 0.7 }, "effect": { "beastcore": 0.2 } }

name：全局唯一（与默认 6 灾 + 已装 MOD 冲突即忽略）
family：玩家家族生产乘量（1=正常）
effect：世界市场池冲击乘量（-0.3 意为减少 30%）
灾签与世界循环（减产/市价/快讯/体感）全链路自动生效——这是本作灾年机制的扩展口

5.5 世界数值（worldNum，0.1.27 起）

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

{ "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. 安全红线（必读）

零脚本：MOD 只含 JSON——不做 eval/沙箱/运行时代码。
不碰 World.rng：不新增随机消耗（见 §3 红线；否则世界确定性崩、金钟罩红）。
不改核心时序：不重排 phase、不覆盖 advanceMonth；扩展走事件池/模板/灾因/配方/词库五口。
语义克制：数值建议贴近现状量级（power 60~~400、weight 0~~100、成本仅低于内置顶级丹）。
命名唯一：id/event id/模板 id/灾因名/配方 output 五个命名空间全部唯一。
worldNum 只动白名单：覆写仅限 §5.5 列出的键（引擎 overrideWorldNum 校验），不碰 rebalance/池底等平衡核心。

8. 已验证的安装流程（行为承诺）

安装：World.installPlugin(modToPlugin(pack)) → 事件进池/模板注册/词库聚合/灾因入表/配方注册；
modPreflight 先行：id 冲突拒绝 + 范式警告；validateMod 深度校验（category/weight/境界/非负）；
启用/停用/卸载：插件双闸与自动回滚照常（卸载即全摘）；
存档：MOD 状态随 state.plugins 持久化，读档自动重装（版本不符跳过并提示）。

9. 打包与分发

单文件 .cotymod（= JSON）直接分发；放入 userData/mods/ 后游戏内「设置 → MOD 层 → 扫描目录 → 安装」。
游戏内导出（0.1.27）：「MOD 层 → 导出当前 MOD 集」会把当前启用的全部 MOD 合并为 mod-bundle-export.cotymod（含各包明细）——分享/备份走同一载入通道。
注意：MOD 只影响新开档的世界生成；已开档不受影响（世界种已落档）。

一句话范式：MOD = "给世界的材料包"——六口（事件/模板/词库/灾因/配方/世界数值）入炉，生成与演化由引擎统一烹调。

6.9 KiB Raw Blame History Unescape Escape