# mud20 **Repository Path**: chenxu8888/mud20 ## Basic Information - **Project Name**: mud20 - **Description**: 配置驱动的修仙文字 MUD(引擎/内容/服务端/前端) - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-19 - **Last Updated**: 2026-10-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 修仙 / 武侠 文字游戏内核 P0(可运行骨架) 一个**配置驱动**的游戏内核:引擎不认识"武功""丹药""门派", 它只认识 **实体 / 属性 / 标签 / 效果 / 条件 / 事件**。 所有游戏内容写在 `content/*.yaml` 里,加内容不改代码。 --- ## 30 秒跑起来 ```bash cd mud20 # ── 单机内核(依赖只有 pyyaml,不需要数据库) python main.py --auto 3 # 自动演示 3 场战斗(非交互) python main.py # 交互模式:修炼 / 突破 / 服药 / 采集 / 历练 python simulate.py --n 300 # 批量统计:胜率 / 平均回合 / 平均伤害 python balance.py # 数值平衡对照:只改数字,胜率立刻变 python demo_extend.py # 扩充演练:运行时加 Boss + 武学 + 命令,不改代码 python tests/test_kernel.py # 22 条内核回归测试 # ── 多人在线(需要 PostgreSQL;本机已装 18 就直接用它) pip install -r requirements.txt # 建角色和库(仅首次,需 sudo) sudo -u postgres psql -c "CREATE ROLE mud LOGIN PASSWORD 'mud';" sudo -u postgres psql -c "CREATE DATABASE mud OWNER mud;" export MUD_DATABASE_URL=postgresql+asyncpg://mud:mud@127.0.0.1:5432/mud python run_server.py # 浏览器打开 http://127.0.0.1:8000 python tests/test_server.py # 账号 / 存档 / 资源 / 共享世界 集成测试 ``` 单机依赖只有 `pyyaml`;多人在线另需 `fastapi / uvicorn / sqlalchemy / asyncpg`。 连不上数据库时 `tests/test_server.py` 会自动跳过,不会阻塞内核测试。 --- ## 目录结构 ``` mud20/ ├── engine/ 内核(不含任何具体数值,也不知道有没有网络) │ ├── entity.py 实体 + 属性三层聚合 │ ├── expr.py 值 / 条件求值(纯函数) │ ├── effects.py 效果虚拟机(原子指令集)★灵魂 │ ├── combat.py 回合制战斗 + 内置 AI 策略 │ ├── commands.py 命令注册表(玩家能做什么也是配置) │ ├── content.py 内容加载 + 引用完整性校验(Fail Fast) │ ├── extensions.py 逃生舱:call 扩展注册表 + 调用计数 │ ├── builtins.py 内置扩展(突破 / 采集 / 遇敌…) │ ├── resources.py 资源节点:定义 / 实时增长 / 采集 │ ├── world.py 世界状态 + snapshot/restore 契约 │ ├── narrator.py 文本渲染(可替换为 LLM Narrator) │ └── engine.py 顶层门面 ├── server/ ★多人在线层(引擎不知道它存在) │ ├── db.py SQLAlchemy async + asyncpg,建表与执行 │ ├── auth.py 口令散列(scrypt)+ 会话令牌 │ ├── repository.py PostgreSQL 仓储(World ↔ 关系表) │ ├── combat.py 可暂停的战斗会话(等玩家点按钮) │ ├── service.py 账号 / 角色 / 世界 / 战斗编排(含并发锁) │ ├── app.py HTTP API │ └── static/ Web 前端(index.html / style.css / app.js) ├── content/ ★全部游戏内容 │ ├── attributes.yaml 属性 + 派生公式 │ ├── statuses.yaml 状态(中毒 / 心魔 / 眩晕 / 剑意) │ ├── skills.yaml 武学(玩家 4 / 怪物 2 / Boss 2) │ ├── items.yaml 丹药 / 材料 / 装备词条 / 采集产出 │ ├── entities.yaml 玩家模板 / NPC 1 / 怪 2 / Boss 1(含掉落表 loot) │ ├── resources.yaml ★资源节点(产出 / 库存 / 恢复 / 门槛 / 风险) │ ├── tables.yaml 查表型数值(突破消耗 / 成功率 / 失败反噬) │ └── commands.yaml 玩家命令(含菜单分组) ├── main.py / simulate.py / balance.py / bench.py / demo_extend.py ├── run_server.py 启动多人在线服务器 ├── docker-compose.yml 一键起 PostgreSQL └── tests/test_kernel.py + tests/test_server.py ``` --- ## 三条铁律(决定了这个内核能长多大) 1. **引擎不认识业务概念**:加"傀儡""洞府""炼丹"只是加 tag + 属性 + 配置。 2. **效果执行是纯数据变换**:`f(state, effect, rng) → (new_state, events)`。 时间和随机都从外部注入,所以**同 seed 战斗 100% 可复现**、可存档、可回放、可服务端校验。 3. **系统层尽量薄**:能下沉到配置的就下沉。命令注册表也在配置里, 所以加玩法不会退化成改代码。 --- ## 效果虚拟机:所有内容是同一种东西 技能、丹药、装备词条、状态、任务奖励,在引擎眼里**完全同构**: ```yaml - id: skill.qingfeng_sword name: 青锋剑诀 cost: {resource: mp, amount: 12} cooldown: 2 target: {scope: enemies, limit: 1} effects: - cost: {resource: mp, amount: 12, from: caster} - set_var: {name: dmg, value: {calc: [mul, {attr: {of: caster, path: atk}}, 1.7]}} - set_var: {name: dmg, value: {calc: [sub, {var: dmg}, {attr: {of: target, path: def}}]}} - if: if: {chance: {attr: {of: caster, path: crit_chance}}} then: - set_var: {name: dmg, value: {calc: [mul, {var: dmg}, {attr: {of: caster, path: crit_mult}}]}} - emit: {type: critical, tpl: "剑光暴涨,正中{target}要害!"} - damage: {to: target, amount: {var: dmg}, types: [physical, sword]} - apply_status: {to: caster, status: status.qingfeng_buff, duration: 2} ``` 指令集(刻意**非图灵完备**,换取可静态分析 / 可回滚 / 可服务端校验): | 类 | 指令 | |---|---| | 流程 | `seq` `if` `foreach` `repeat` `while(必须带 max_iter)` `abort` | | 属性 | `add_attr` `set_attr` `set_var` | | 加成 | `add_modifier` `remove_modifier`(flat / inc / more 三层) | | 状态 | `apply_status` `remove_status` | | 战斗 | `damage` `heal` `cost` | | 物品/标志 | `give_item` `take_item` `set_flag` `clear_flag` | | 输出 | `emit`(结构化事件 + 文本模板 + 插槽) | | 逃生舱 | `call`(调注册的原生函数,用于"特殊效果由开发实现") | --- ## 属性系统:为什么 Modifier 必须带 source ``` 最终值 = (base + Σflat) × (1 + Σinc) × Π(1 + more) ``` 每层加成都记 `source`。否则加了 50 件装备后,"脱下装备属性没还原" "两个 buff 叠加打架"会逼你重写系统。 --- ## 扩充:三步,零代码 1. 往 `content/` 加 YAML 条目(新 Boss / 新武学 / 新状态) 2. 想让玩家能触发?加一条命令,带上 `menu: {group, order}` 3. 跑起来——菜单里已经出现了 **运行时扩充**也可以(`demo_extend.py` 演示了这条路,AI 生成的内容就走它): ```python engine.add_content({"skills": [...], "protos": [...], "commands": [...]}) ``` 写错会被**启动即拒绝**并定位到节点: ``` 新内容校验失败: - skill:skill.broken[0].add_attr: 未定义的属性 ' nonexistent_attr' ``` --- ## 逃生舱与"晋升"机制 表达不了的效果用 `call` 调原生函数(如 `cultivation.breakthrough` 的 查表 + 概率 + 失败反噬)。但每次调用都会计数: ```python from engine import extensions extensions.stats() # {'skill.use': 12, 'cultivation.breakthrough': 3, ...} ``` 某个函数高频出现 → 说明配置语言表达力不够 → **它该晋升为内置 opcode**。 这条反馈回路是配置体系持续进化的关键。 --- --- ## 一、存储:为什么换成 PostgreSQL **结论:多人在线必须换,且成本极低——引擎一行没改。** | 维度 | JSON 文件(现状) | PostgreSQL(现在) | |---|---|---| | 并发写 | 整文件覆盖,两人同时存档必丢数据 | 行级 upsert,事务保证 | | 崩溃恢复 | 上次自动存档之后全丢 | 已提交即持久化 | | 掉线/重启 | 内存态丢失 | 从库里恢复世界与角色 | | 查询 | 只能全量反序列化后遍历 | 按 `owner_id` 查角色、按 `team` 查阵营 | | 部分回档 | 做不到 | 单独回滚某个玩家实体 | | 单机调试 | 极简,零依赖 | 需要起服务 | 取舍:JSON 存档**保留**(`engine.world.JsonRepository`),单机入口、批量模拟、回归测试继续用它; 多人在线走 `server/repository.py` 的 `PostgresRepository`。两者实现的是同一份契约: ```python snapshot() -> dict # 世界导出为纯数据 restore(data) # 从纯数据恢复 ``` ### 准备数据库 三种方式任选其一: **当前服务器用的是本机 PostgreSQL 18**(集群 `18/main`,端口 5432),不是 Docker。 ```bash # 1) 本机已装 PostgreSQL(推荐,需要 sudo 建角色和库) sudo -u postgres psql -c "CREATE ROLE mud LOGIN PASSWORD 'mud';" sudo -u postgres psql -c "CREATE DATABASE mud OWNER mud;" export MUD_DATABASE_URL=postgresql+asyncpg://mud:mud@127.0.0.1:5432/mud # 2) 已有库,直接指过去 export MUD_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname # 3) 换到没有本地 PG 的机器时才用 Docker(镜像同为 postgres:18) docker compose up -d ``` 启动时日志会打印实际连上的数据库版本,可据此确认: `数据库:PostgreSQL 18.6 ...`。 表会在服务启动时自动创建(`CREATE TABLE IF NOT EXISTS`),不需要手工迁移脚本。 ### 表结构 | 表 | 作用 | |---|---| | `users` | 账号(用户名唯一 + scrypt 口令散列 + 盐) | | `sessions` | 会话令牌(可撤销、带过期时间) | | `players` | `user_id → entity_id` 的绑定 | | `world_state` | 单行:世界 `tick` / `flags` / 实体计数器 | | `entities` | 一行一实体:`data` JSONB + 冗余列 `team / alive / owner_id` | 为什么实体内部仍是 JSONB:`modifiers / statuses / inventory` 本身是半结构化数据, 硬拆成五张表只会让"给状态加一个字段"变成一次数据库迁移。 而 `owner_id / team / alive` 冗余成真列,是为了能按玩家、按阵营查询。 ### 会话与口令 - 口令:`hashlib.scrypt`(stdlib,内存硬化 KDF),避免 bcrypt 的本地编译依赖 - 会话:随机令牌存库,可撤销、可过期——比无状态 JWT 更适合"踢下线 / 封号" - 上规模时:sessions 换 Redis、口令换 argon2,接口不变 --- ## 二、多人在线:共享世界 + 每账号一角色 ``` 浏览器 ──HTTP──> FastAPI ──> GameService ──> 一把 asyncio.Lock ──> 共享 World │ └──> PostgreSQL(自动存档 + 退出时落盘) ``` 要点: 1. **世界只有一份**:所有玩家的角色、资源节点、临时怪物都在同一个 `World` 里, 所以"资源被别人采光了"是真实发生的,而不是各玩各的平行宇宙。 2. **每账号一角色**:注册时从 `char.disciple` 模板生成,实体 id 固定 `player.`, 读档后稳定找回。 3. **并发**:所有改动世界的操作串行化在同一把 `asyncio.Lock` 里, 不存在"两个人同时采到最后一枚灵石"。 4. **战斗按人分会话**:引擎新增了 `combat_for(actor)` / `start_combat(..., actor=actor)`, 单机那条路径(全局 `engine.combat`)完全保留,22 条老测试照常通过。 5. **自动存档**:默认每 30 秒一次,另有退出 / 注册 / 战斗结束时立即落盘。 --- ## 三、资源采集玩法 定义全部在 `content/resources.yaml`,引擎只提供"增长 + 采集"两个动作。 **三条规则(都是设计者可调的旋钮):** 1. **节点即实体**:资源节点是普通 `Entity`(tag `resource_node`), 不引入新实体类型——符合"万物皆 Entity,只靠 tags 区分"。 2. **按真实时间增长**:`stock = min(capacity, stock + regen_per_minute × 已过分钟数)`。 * 读时结算,不需要后台定时器,也不存定时器状态 * 离线也增长——下线再回来,灵石矿已经恢复了 * 所有玩家共享同一份库存 → 天然形成"晚一步就没了"的竞争 3. **采集 = 扣库存 + 产出物品 + 消耗世界时间 + 小概率惊动妖兽** ```yaml - id: node.black_iron_vein name: 玄铁矿脉 item: item.iron_ore # 产出什么 yield: {min: 1, max: 2} # 一次采多少 capacity: 15 # 库存上限 regen_per_minute: 0.35 # 每分钟恢复多少 ticks: 30 # 一次采集消耗多少世界时间 required_realm: 2 # 境界门槛:逼玩家先修炼 encounter_chance: 0.18 # 采集风险 encounter_protos: [monster.wolf, monster.bandit] ``` 采集接在逃生舱上(`call: resource.gather`),因此改产出、改风险、改门槛都不碰代码。 如果哪天发现"采集"被高频调用到需要更细的表达,它就该晋升为内置 opcode—— 这正是 `extensions.stats()` 那条反馈回路的用途。 --- ## 四、Web 前端 `server/static/` 三个文件,原生 JS,无构建步骤: - 注册 / 登录(令牌存 localStorage) - 道体面板:气血 / 内力条、境界、修为、战力、状态、背包 - 行事菜单:**由 `commands.yaml` 生成**,加一条命令 Web 上自动多一个按钮 - 见闻日志:事件流渲染(按事件类型着色) - 天材地宝:资源面板带库存条与"开采"按钮,12 秒轮询刷新 - 战斗面板:回合、敌我血量、可用招式 / 丹药 / 遁走 / 托管(AI 代打) - 山门同道:世界里其他修士的境界排行 前端不含任何玩法规则——所有规则都在服务端配置里。 ### 从别的机器访问 服务**默认只听 `127.0.0.1`**(安全默认,外部连不上)。要让局域网内其他设备访问: ```bash python run_server.py --host 0.0.0.0 --port 8000 # 或 export MUD_HOST=0.0.0.0 sudo ufw allow from 192.168.1.0/24 to any port 8000 proto tcp ``` 同网段设备打开 `http://<本机局域网IP>:8000` 即可。 从公网访问还需要:路由器端口转发(外网 8000 → 内网 192.168.1.x:8000)+ `sudo ufw allow 8000/tcp`。 更安全的做法是走隧道,公网不暴露端口: ```bash ssh -L 8000:127.0.0.1:8000 user@服务器 # 本机打开 http://127.0.0.1:8000 # 或用 Tailscale / frp / ngrok 做内网穿透 ``` ⚠️ 当前是明文 HTTP,口令在链路上未加密。放到公网前请挂一层 HTTPS 反向代理 (Nginx + Let's Encrypt / Caddy 均可,引擎与前端都不用改)。 --- ## P0 有意没做的事(下一阶段) | 项 | 说明 | |---|---| | 场系统 / 世界间关联 | 你已明确"特殊效果由开发实现",故不进配置语言;留 `call` 接入 | | 装备穿脱 opcode | 词条配置已就绪(`item.qingfeng_sword`),差 `equip` 指令 | | 地图 / 场景移动 | 加 `Zone` + `teleport` 指令即可 | | 任务 / 对话树 | 节点图配置 + 每节点挂 Effect,引擎不用改 | | LLM Narrator | `narrator.py` 留接口,替换 TemplateNarrator 即可 | | 玩家间交互(PvP / 交易 / 门派) | 世界已共享、角色已落库,缺的是对应命令配置 | | WebSocket 推送 | 现在是 12 秒轮询;换成推送只需改 `server/app.py` 的传输方式 | | 效果事务回滚 | 目前 cost 不足时 Abort 只中断后续,未回滚已执行部分 | --- ## 验收对照 | 目标 | 状态 | |---|---| | ≥1 玩家、≥1 属性、≥1 怪、能战斗 | ✅ 玩家模板 + 属性 12 / 怪 2 + Boss 1 | | 统计战斗结局 | ✅ `simulate.py`(胜率 / 回合 / 输出 / 承伤 / 余血,`--gear` 量成长上限)、`balance.py` | | 引擎性能基准 | ✅ `bench.py`(属性求值 / 批量模拟 / 存档快照) | | 内容可配置扩充 | ✅ `demo_extend.py` 运行时加 Boss+武学+命令,零代码 | | 命令可配置 + 菜单自动生成 | ✅ `commands.yaml` 9 条,新命令自动出现在菜单与 Web | | 配置错误 Fail Fast | ✅ 未知指令 / 未定义属性 / 未注册函数 / 资源引用,启动即报 | | 同 seed 可复现 | ✅ 测试 `test_combat_is_reproducible` | | 存档读档 | ✅ JSON(单机)+ PostgreSQL(多人) | | 22 条内核回归测试 | ✅ 全通过 | | 多用户同时在线 | ✅ 注册 / 登录 / 会话,共享世界,一把锁串行化 | | 资源采集玩法 | ✅ 4 处产地,实时增长、共享库存、境界门槛、采集风险 | | Web 页面可玩 | ✅ `server/static/`,登录→修炼→采集→历练→战斗全流程 |