给 CWS 做了一套剧本系统与 Mod 平台（v1.0 Showcase）

[walthack]

TL;DR（中文）
我在 CWS 上以 fork 形式探索了一个方向——给模拟器加一层 通用 Scenario Engine 与 Mod 平台,让玩家可以导入预定义世界(而不是每次完全随机起手),同时给模组作者开放资源 / prompt / 本地化 / 谓词+效果四类覆写,Python hooks 则默认关闭走信任 modal。目前 fork 上做到 v1.0(tag v1.0.0-final,10 个 PR,后端 1694 pytest + 前端 571 vitest + Playwright Layer 3/4A 全绿)。想请教的是:这个方向是否符合 CWS 的长期规划?如果符合,最合适的 upstream 路径是什么?

---

TL;DR (EN)
I explored a direction on a fork of CWS — a generic Scenario Engine + Mod Platform. The engine lets players import pre-defined worlds instead of always starting from a fully-random sandbox; two bundled scenarios (liuchao 六朝, sanguo 三国) ship to prove it's generic, not 六朝-specific. The Mod Platform exposes overlays for assets / LLM prompts / locale / predicates+effects, plus a default-disabled Python hooks gate behind a trust modal. Currently at v1.0 on the fork (10 PRs, all engineering verifications green). The question I'd like to put to maintainers: does this direction fit CWS's long-term roadmap, and if so what would be the most appropriate upstreaming path?

---

背景

CWS 的核心魅力在「无预设剧本、涌现式叙事」,规则系统 + AI 决策跑出来的故事不可预测,这点本身就足够好。所以 fork 的出发点不是替换沙盒。

而是想试一种互补的玩法——在沙盒之外加一层「预定义初始世界」的入口。比如想让玩家「进入南北朝乱世」「三国早期」「或者自己写的某段架空朝代」,AI 仍然涌现剧情,但起手的政治版图 / 宗门分布 / 关键人物已有约束。这种玩法对历史背景党、剧本创作者、想做特定主题模组的人都比较友好。

为什么做这个系统

纯沙盒下,每局都是「白纸 + 同一套规则」——非常适合反复探索规则,但不太适合:

• 让玩家进入具体某段历史 / 某种世界设定(六朝、三国、修真宗门体系自定义……)
• 模组作者做主题型扩展(比如「魔门盛世」「上古洪荒」之类需要预设格局的世界)
• 创作者社区互相分享 scenario / mod,做生态

所以做了两件耦合的事:

• Scenario Engine —— 把「世界初始格局」变成可声明、可分发、可热替的资源;
• Mod 平台 —— 让上面的扩展能安全打包(默认禁 Python、需明确信任才允许执行)。

引擎层从一开始就按「通用」设计——sanguo 三国仙纪 存在的唯一目的就是证明引擎不是为 liuchao 特化的。

架构概览

Scenario Engine:

• 声明式 scenario.json(含 initial_state / avatars / relations / events)
• 包格式 .zip,带安全校验(zip-bomb / path-traversal / symlink / bundled-collision)
• 仓库 UI(Installed / Downloaded / Updates)+ 创建向导(6 步)+ LLM 辅助作者
• 指纹三态:unsigned / verified / modified
• 运行时热替(Advanced 模式下)+ verbatim 警告:"Hot-swap does not re-anchor time. Events scheduled before the current world time will not fire."

Mod 平台:

• 五种覆写:asset / llm-prompt / locale / predicate / effect
• 冲突 modal + 依赖检查
• 默认关闭 Python hooks,仅 Advanced Settings 中开启 + trust modal 二次确认后才允许执行
• Trust modal 文案 verbatim:"You are about to enable Python mod execution. Untrusted mods can do anything the game can do. Continue?"

后端结构:

• runtime / service / API 三层
• 所有写状态走串行化 mutation 入口(避免与 Simulator.step() 并发写 world)
• 稳定 /api/v1/query|command/* 命名空间
• 涉及决策的 19 份 ADR:ADR-005 → ADR-023,在 docs/adr/

功能展示

(取自 fork main 分支,完整 10 张截图在 docs/release-artifacts/v1.0/screenshots/)

新建游戏 — Scenario 选择

Scenario 仓库 — Installed / Downloaded / Updates + Create + Import

Mod 管理 — Python hooks 默认关闭

Python hooks 信任 modal

验证情况(v1.0.0-final,2026-06-05)

层	结果
后端 pytest	1694 通过 / 3 既有失败 / 2 跳过(3 个失败属 Stage 2b 宗门测试,与 v1.0 无关)
前端 vitest	571 通过 / 8 既有失败(RoleplayDock localStorage,与 v1.0 无关)
启动 smoke	3/3 通过(无 flag / --scenario=liuchao / --scenario=sanguo)
Playwright Layer 3(Python 闸)	6/6 通过
Playwright Layer 4A(scenario E2E)	7/7 通过
Playwright Layer 4 LLM 作者	2/2 跳过 with reason(测试环境无 API key,自动跳过是设计行为)

完整报告:docs/release-verification-report.md

想请教的问题

这个 fork 一开始就是按「保持与上游方向兼容」的原则推进的,但要不要 / 怎么 upstream 一直是个问号。具体想请教维护者几个问题:

1. 方向上:「让玩家导入预定义世界」这个能力,是否符合 CWS 的长期规划?还是与「纯涌现」哲学有冲突,更适合永远留在 fork / 第三方模组的层面?
2. 若方向 OK:最适合的 upstream 路径是什么?(按 PR 顺序逐个提到上游 main / 先开 RFC 讨论架构 / 先做某一小块的小验证 / 或其他建议?)
3. 架构上:有没有维护者已有的偏好或正在规划中的方向,会让我现在做的某些部分需要先调整?比如 mutation 串行化入口、/api/v1 命名空间、ADR 体系等,是否与你们正在推进的方向冲突?
4. 取舍上:如果你们觉得某些部分(比如 Python hooks gate、LLM 辅助作者、指纹校验)不适合上游主线,也希望直接说——剔除哪些片段会让其余部分更容易合入?

不论结论是「合入」「不合入」还是「先放着观察」,反馈对 fork 的下一步规划都有价值。如果合适也可以约个更细的同步(异步留言 / Discord / B 站均可)。

---

English summary

I built a generic Scenario Engine and Mod Platform on top of CWS (fork: walthack/cultivation-world-simulator @ v1.0.0-final). The motivation is to complement — not replace — CWS's pure-sandbox emergent storytelling, by letting players import pre-defined worlds (e.g. 六朝 Six Dynasties, 三国 Three Kingdoms) as the starting frame, while AI agents still drive the rest emergently. Two bundled scenarios (liuchao, sanguo) ship specifically to prove the engine isn't specialized for one period.

The Mod Platform exposes five overlay types — asset, llm-prompt, locale, predicate, effect — and includes a Python hooks safety gate that is disabled by default and requires both an Advanced Settings toggle and a trust-modal confirmation before any custom Python is allowed to execute. Backend uses a runtime / service / API layering with a single serialized mutation entry-point under /api/v1/query|command/*. 19 ADRs (ADR-005 → ADR-023) record the key design decisions.

Engineering state at v1.0.0-final: backend 1694 pytest passing, frontend 571 vitest passing, Playwright Layer 3 (Python gate) 6/6, Layer 4A (scenario engine end-to-end) 7/7, all green. Full verification report at docs/release-verification-report.md; ADRs at docs/adr/; 10-shot release pack at docs/release-artifacts/v1.0/screenshots/.

The question I'd like to put to the maintainers: does this "import a pre-defined world" direction fit CWS's long-term roadmap, or does it conflict with the pure-emergence philosophy and belong permanently in a third-party fork / mod layer? If it does fit, what's the most appropriate upstreaming path — per-PR series, an RFC-style discussion first, a small validation slice, or something else? Are there architectural preferences I should adapt to first?

Feedback either way — yes / no / let it sit — would be genuinely useful for planning the next step on the fork. Happy to follow up async or via Discord / Bilibili as you prefer.