剑之心是一个配置即代码 (Configuration as Code) 的武侠RPG游戏引擎。通过编辑 YAML/Markdown 文件即可管理游戏内容(角色、招式、剧情、核心公式),无需修改代码。
- 数据驱动: 所有游戏内容都通过配置文件定义
- 热更新: 修改配置文件后自动生效,无需重启服务
- 可视化: 提供 Web Dashboard 进行数据管理和测试
- 扩展性: 支持动态属性扩展,轻松添加新机制
- 严格1对1交替:A选1招 → B选1招 → A选1招 → B选1招...
- 选招即切换:选完1个招式后立即轮到对方
- 提前锁定:任何时候都可点击"确定出招"不再选招
- 智能判定:双方都锁定(变值耗尽或主动确定)后才执行判定
每回合开始判定谁先行动:
- 先机值比较:上回合最后招式决定(进=+1, 中=0, 退=-1)
- 身属性比较:先机值相等时,身高者先手
- 默认规则:仍相等则主角先手
- 势是主观的:每人独立计算,可能双方都觉得优势/劣势
- 基于观察:势根据观察到的属性计算,不是真实属性
- 观察误差:智、觉高者误差小,能准确评估形势
- 每回合重判:包括第一回合就计算观察和势
心不是消耗品,而是抗压系数,决定如何处理势的心理压力:
| 心值 | 顺境表现 | 逆境表现 |
|---|---|---|
| 高心(70+) | 稳健 | 顿悟:劣势反转为优势! |
| 中心(50-70) | 正常 | 坚韧:抵御部分压力 |
| 低心(<50) | 骄傲:易露破绽 | 恐慌:劣势被严重放大 |
- 线性公式:战力 = 力×w + 身×w + 血(当前)×w + 气(当前)×w + ...
- 个性化权重:不同角色对血、气、力、身有不同权重
- 怕死者:血少战力暴跌(xue权重高)
- 悍不畏死:残血战力不降(xue权重极低)
- 气宗:气少战力暴跌(qi权重高)
- 外家:不依赖内力(qi权重低)
- 回合内交替选择招式,构建连招序列
- 每个招式消耗变值和气
- 剩余变值加成最后一个招式(约+5%/点)
| 等级 | 可见内容 | 条件 |
|---|---|---|
| A级 | 招式名+描述+全部效果 | 拥有对应知识标签 |
| B级 | 进/退/中 + buff效果 | 觉+智较高 |
| C级 | 仅进/退/中 | 觉+智一般 |
| D级 | 完全未知(???) | 觉+智低 或 对方隐蔽性高 |
| E级 | 特殊强制效果 | 剧情/特殊机制 |
- 血(生命): 归零即战败
- 气(内力): 施展招式的能量
- 变(变招余地): 每回合重置,限制选招次数
- 触发条件:大劣势(势<-0.5) + 使用进招
- 成长概率:15%(可配置)
- 成长效果:心属性永久+1
- 战斗中生效:成长后立即影响后续回合
- Markdown 格式剧情脚本
- 支持对话、选项、分支
- 属性检定和标签要求
- 无缝衔接战斗系统
- Python 3.10+
- 现代浏览器(Chrome/Firefox/Edge)
# 1. 克隆项目
git clone <repository-url>
cd SwordHeart_RPG
# 2. 安装依赖
pip install -r requirements.txt
# 3. 启动服务器
python run.py服务启动后,打开浏览器访问:
- 🎮 战斗试玩: http://localhost:8000/dashboard/gameplay.html
- 📊 数据仪表盘: http://localhost:8000/dashboard/
- 📜 剧情模式: http://localhost:8000/dashboard/story.html
- 📖 API 文档: http://localhost:8000/docs
进入战斗界面后:
- 选择角色:选择你的角色和对手
- 开始战斗:点击"⚔️ 开始战斗"按钮
- 观察势态:查看属性面板和心理活动面板
- 交替选招:
- 轮到你时,点击招式卡片选择1个招式
- 选择后立即轮到对方
- 可随时点击"✓ 确定出招"提前锁定
- 敌人回合:点击"⚔️ 敌人行动"让AI选招
- 执行判定:双方都锁定后,点击"⚡ 执行判定"
- 下一回合:查看先手判定结果,继续战斗
💡 技巧:
- 进招(红色)下回合先手,但攻击性强
- 退招(蓝色)下回合后手,但防御性强
- 中招(灰色)不影响先手,平衡型
- 剩余变值会加成最后一招,合理规划很重要!
- 逆境时使用进招有概率提升心属性!
SwordHeart_RPG/
├── app/ # 后端核心代码
│ ├── __init__.py # 模块初始化
│ ├── main.py # FastAPI 应用入口
│ ├── engine.py # 战斗引擎核心 v2.2
│ ├── loader.py # 数据加载器
│ └── watcher.py # 文件热更新监听
│
├── dashboard/ # 前端界面
│ ├── index.html # 数据仪表盘(数据管理+编辑)
│ ├── gameplay.html # 战斗界面(玩家 vs AI)v2.2
│ └── story.html # 剧情模式(对话+选择)
│
├── data/ # 【用户编辑区域】游戏数据
│ ├── config/
│ │ └── formulas.yaml # 全局公式配置
│ ├── characters/ # 角色定义
│ │ ├── hero.yaml
│ │ ├── bandit.yaml
│ │ └── boss_heihu.yaml
│ ├── skills/ # 招式定义
│ │ ├── taiji_sword.yaml
│ │ ├── basic_punch.yaml
│ │ └── boss_skills.yaml
│ └── story/ # 剧情脚本
│ └── chapter1.md
│
├── tools/ # 开发工具(可选)
│ ├── data_editor.py # 批量编辑工具
│ └── example_batch_edit.py
│
├── requirements.txt # Python 依赖
├── run.py # 启动脚本
└── README.md # 本文档
id: "player_01"
name: "李逍遥"
title: "蜀山弟子"
description: "天资聪颖的剑术天才"
# 基础属性
attributes:
li: 30 # 力:伤害基础
shen: 40 # 身:速度/闪避/影响被读招难度
ti: 50 # 体:生命与内力上限基础
zhi: 25 # 智:观察力/读招能力
jue: 60 # 觉:直觉/读招能力/势判断
xin: 50 # 心:逆境稳定性(可成长)
# 战斗资源
resources:
xue: 100 # 血(当前)
xue_max: 100 # 血上限
qi: 80 # 气(当前)
qi_max: 80 # 气上限
bian_max: 10 # 变值上限
# 战力权重配置 (v2.2新增)
combat_power_weights:
li: 1.5 # 力量权重
shen: 1.3 # 身法权重
ti: 1.0 # 体质权重
zhi: 0.6 # 智力权重
jue: 0.7 # 觉权重
xin: 0.4 # 心权重
xue: 1.0 # 当前血量权重(关键!)
qi: 0.6 # 当前气量权重(关键!)
# 知识标签(用于A级读招)
knowledge_tags:
- "太极剑法"
- "蜀山剑法"
# 经历标签(剧情判定/战斗修正)
tags:
- "剑术天才"
- "初出茅庐"
# 招式熟练度
mastery:
skill_taiji_guard: 5
skill_basic_slash: 10id: "skill_taiji_guard"
name: "揽雀尾"
type: "retreat" # advance(进)/retreat(退)/neutral(中)
category: "太极剑法"
description: "太极剑法起手式,以静制动"
# 消耗
cost_bian: "max(1, 3 - (mastery * 0.2))" # 变值消耗(支持公式)
cost_qi: "5" # 气消耗
# 读招相关
stealth: 0.1 # 隐蔽性(0-1)
knowledge_tag: "太极剑法" # 需要此标签才能A级读招
lock_bian: false # 是否锁定变招(使用后无法继续选招)
# 效果列表
effects:
- type: "damage" # 类型:damage/buff/debuff/heal/recover/charge
timing: "instant" # 时机:instant(判定阶段)/persistent(选中立即)/charge(蓄力)
name: "借力反击"
formula: "user.attributes.li * 0.5"
- type: "buff"
timing: "persistent"
name: "defense_up"
description: "防御姿态"
value: 20
duration: 1 # 持续回合数# 读招等级计算(返回0-4对应D/C/B/A级)
read_move_level_formula: >
min(3, max(0,
floor(
(observer.attributes.jue * 0.02 + observer.attributes.zhi * 0.015)
- (target.attributes.shen * 0.01)
- (skill_stealth * 2)
+ knowledge_bonus
)
))
# 观察误差(智觉越高误差越小)
observation_error_formula: >
max(0.05, 1.0 - (observer.attributes.zhi * 0.01 + observer.attributes.jue * 0.015))
# 剩余变值加成(每点+5%)
remaining_bian_bonus_formula: >
1 + (remaining_bian * 0.05)
# 心的成长
xin_growth_threshold: -0.5 # 势低于此值触发判定
xin_growth_chance: 0.15 # 成长概率
xin_growth_amount: 1 # 每次成长+1回合开始
↓
先手判定
- 比较先机值(上回合最后招式:进=1, 中=0, 退=-1)
- 先机值相等则比较身属性
- 仍相等则主角先手
↓
观察阶段 (v2.2)
- 双方观察对手,产生带误差的观察结果
- 智、觉高 → 误差小 → 观察准确
- 智、觉低 → 误差大 → 可能误判
↓
势的计算 (v2.2重构)
- 基于观察结果计算主观势
- 每人独立计算,可能都觉得优势或都觉得劣势
- 公式: 势 = (自己战力 / 观察到的敌人战力) - 1
↓
心的介入 (v2.2重构)
- 根据心值处理势的心理压力
- 高心+大劣势 → 【顿悟】属性反升
- 低心+大劣势 → 【恐慌】属性暴跌
↓
交替选招阶段(1对1严格交替)
先手方:选1招 ────→ 立即切换
后手方: 选1招 ────→ 立即切换
先手方: 选1招 ────→ 立即切换
后手方: 选1招 ────→ 立即切换
...(继续交替,直到双方都锁定)
任意时刻可点击"确定出招"提前锁定
↓
判定阶段(双方都锁定后触发)
├─ 读招:根据智、觉、身计算读招等级(A/B/C/D)
├─ 属性发挥:应用势心修正到实际属性
├─ 结算伤害:instant效果生效,使用实际属性计算
├─ 应用剩余变值加成到最后一招
└─ 判断胜负
↓
回合结束
├─ 变值重置
├─ buff/debuff持续-1
├─ 根据最后招式类型更新先机值
├─ 心的成长判定(逆境+进招有概率+1心)
└─ 进入下一回合(重新观察和计算势)
公式:
战力 = 力×w_li + 身×w_shen + 体×w_ti + 智×w_zhi + 觉×w_jue + 心×w_xin
+ 血(当前值)×w_xue + 气(当前值)×w_qi
权重配置:
combat_power_weights:
li: 1.5 # 属性权重
shen: 1.2
ti: 1.0
zhi: 0.5
jue: 0.5
xin: 0.3
xue: 0.8 # 血量权重(0.05-2.5)
qi: 0.5 # 气量权重(0.1-2.0)角色类型示例:
| 类型 | xue权重 | 效果示例 |
|---|---|---|
| 怕死刺客 | 2.5 | 血60→30,战力-75 |
| 普通人 | 0.8 | 血100→50,战力-40 |
| 悍不畏死 | 0.05 | 血140→20,战力仅-6 |
| 类型 | qi权重 | 效果示例 |
|---|---|---|
| 气宗 | 1.8 | 气150→50,战力-180 |
| 普通人 | 0.5 | 气100→50,战力-25 |
| 外家 | 0.1 | 气100→20,战力仅-8 |
每个角色都有自己的势:
- 玩家有
player.momentum_state(玩家觉得自己优/劣) - 敌人有
enemy.momentum_state(敌人觉得自己优/劣)
可能的情况:
- 双方都觉得自己优势(互相低估对方)
- 双方都觉得自己劣势(互相高估对方)
- 一方准确,一方误判
计算流程:
观察 → 战力评估 → 势判断 → 心介入 → 属性修正
顺境 (势 > 0.2):
- 凡人(心<50): 骄傲,修正×1.3
- 侠客(心50-70): 稳健,修正×0.8
- 宗师(心≥70): 冷静,修正×0.6
逆境 (势 < -0.2):
- 凡人(心<50): 恐慌,修正×1.5(劣势放大)
- 侠客(心50-70): 坚韧,修正×0.5(抵御压力)
- 宗师(心≥70): 顿悟,修正 = abs(势)×0.3(反转!)
- 严格1对1交替:A选1招 → 立即轮到B → B选1招 → 立即轮到A
- 不能连选:选完1招必须等对方行动后才能继续
- 提前锁定:任何时候都可点击"确定出招"不再选招
- 双方锁定:都锁定(变值耗尽或主动确定)后才执行判定
每回合开始判定谁先选招:
- 比较先机值(上回合最后招式决定):进招=+1,中招=0,退招=-1
- 先机值相等 → 比较身属性,高者先手
- 仍相等 → 默认主角先手
读招等级计算公式:
等级 = (觉×0.02 + 智×0.015) - (对方身×0.01) - (招式隐蔽性×2) + 知识加成
- 触发: 势 < -0.5 且使用进招
- 概率: 15%
- 效果: 心属性 +1(永久生效)
- 日志: 显示"磨练剑心",心值变化
【第1回合 - 李逍遥 vs 黑虎】
观察阶段:
李逍遥观察黑虎: 真实470 → 观察500 (高估!)
黑虎观察李逍遥: 真实372 → 观察350 (低估)
势的计算:
李逍遥战力: 372
李逍遥的势: 372/500 - 1 = -0.256 (劣势)
心志: 【侠客】坚韧 → 修正-12.8%
黑虎战力: 470
黑虎的势: 470/350 - 1 = +0.343 (优势)
心志: 【侠客】稳健 → 修正+27%
属性发挥:
李逍遥力: 基础30 → 实际26 (势心-4)
黑虎力: 基础55 → 实际70 (势心+15)
先手判定: 双方先机值都是0 → 比较身属性 → 李逍遥(身40) > 黑虎(身35) → 李逍遥先手
李逍遥选招:
1. 选择「横斩」(进招) → 消耗变值1.5 → 立即轮到黑虎
2. 黑虎选择「重拳」(进招) → 轮到李逍遥
3. 李逍遥选择「揽雀尾」(退招) → 轮到黑虎
4. 黑虎点击"确定出招" → 黑虎锁定
5. 李逍遥选择「快剑突刺」(进招),剩余3点变值
6. 李逍遥点击"确定出招" → 双方都锁定
执行判定:
- 读招: 李逍遥看清黑虎的招式(B级)
- 伤害结算: 使用实际属性计算
- 剩余变值加成: 李逍遥最后一招+15%
- 心的成长: 李逍遥逆境使用进招,15%概率心+1
回合结束:
- 李逍遥最后用「快剑突刺」(进招) → 先机值 = +1
- 黑虎最后用「重拳」(进招) → 先机值 = +1
【第2回合】
先手判定: 双方先机值都是+1 → 比较身属性 → 李逍遥先手
重新观察和计算势:
李逍遥血80,黑虎血150
战力重新计算(血气变化影响战力)
势重新判定...
| 接口 | 方法 | 说明 |
|---|---|---|
/api/data |
GET | 获取所有游戏数据 |
/api/data/characters |
GET | 获取所有角色 |
/api/data/skills |
GET | 获取所有招式 |
/api/data/formulas |
GET | 获取公式配置 |
/api/reload |
POST | 手动重载数据 |
| 接口 | 方法 | 说明 | v2.2变化 |
|---|---|---|---|
/api/combat/init |
POST | 初始化战斗 | 返回观察结果、势状态、属性分解 |
/api/combat/select_move |
POST | 选择招式(蓄招) | 返回属性分解 |
/api/combat/confirm |
POST | 确定出招 | 返回属性分解 |
/api/combat/read_move |
POST | 读招判定 | 无变化 |
/api/combat/judgment |
POST | 执行判定阶段 | 返回观察、势、属性分解 |
| 接口 | 方法 | 说明 |
|---|---|---|
/api/file/{type}/{id} |
GET | 获取文件原始内容 |
/api/save |
POST | 保存文件 |
/api/delete/{type}/{id} |
DELETE | 删除文件 |
| 接口 | 方法 | 说明 |
|---|---|---|
/api/story/parse/{id} |
GET | 解析剧情文件 |
完整 API 文档:http://localhost:8000/docs
- 访问数据仪表盘
- 点击右上角"编辑模式"
- 选择要编辑的文件
- 直接修改YAML/Markdown内容
- 点击"保存"
- 使用任意文本编辑器打开
/data目录下的文件 - 修改后保存
- 文件监听器会自动检测变更并热更新
from tools.data_editor import DataEditor, quick_create_character
editor = DataEditor(demo_mode=False)
# 创建新角色
char = quick_create_character(
id="new_hero",
name="新英雄",
title="侠客",
li=40, shen=35, ti=45, zhi=30, jue=35, xin=40
)
# 添加战力权重
char.combat_power_weights = {
"li": 1.5, "shen": 1.2, "ti": 1.0,
"zhi": 0.5, "jue": 0.5, "xin": 0.3,
"xue": 1.0, "qi": 0.6
}
editor.create_character(char)在角色YAML中添加:
combat_power_weights:
li: 1.5 # 力量权重
shen: 1.2 # 身法权重
ti: 1.0 # 体质权重
zhi: 0.5 # 智力权重
jue: 0.5 # 觉权重
xin: 0.3 # 心权重
xue: 0.8 # 血量权重(关键!)
qi: 0.5 # 气量权重(关键!)权重选择指南:
| 角色类型 | xue | qi | 说明 |
|---|---|---|---|
| 怕死的人 | 2.0-2.5 | 0.4-0.6 | 血少战力暴跌 |
| 正常人 | 0.6-1.2 | 0.4-0.6 | 血气适度影响 |
| 悍不畏死 | 0.05-0.2 | 0.1-0.3 | 血量几乎不影响 |
| 气宗高手 | 0.3-0.6 | 1.5-2.0 | 气少战力暴跌 |
| 外家高手 | 0.6-1.0 | 0.1-0.3 | 不依赖内力 |
系统支持动态属性扩展。例如添加"魅力"属性:
# 在角色文件中直接添加
attributes:
li: 30
# ... 其他属性
mei: 50 # 新属性:魅力公式中可以直接使用:user.attributes.mei * 0.5
所有公式支持:
- 基础运算:
+-*/% - 函数:
max()min()abs()round()floor()ceil() - 变量:
userobservertargetmasterymomentum等
示例:
cost_bian: "max(1, 5 - (user.attributes.shen * 0.02) - (mastery * 0.3))"- 左侧: 资源树(角色/招式/公式/剧情)
- 中间: 内容查看/编辑区(支持全屏编辑)
- 功能: 数据管理、在线编辑、热更新、YAML语法验证
- 双方状态卡片:血、气、变资源条
- 当前行动者高亮:蓝色=玩家回合,红色=敌人回合
- 回合信息:显示"🎯 你的回合"或"🎯 敌人回合"
- 先机值显示:实时显示双方先机值(影响下回合先手)
显示6个属性的详细分解:
- 基础值:角色原始属性
- Buff影响:来自招式/增益(绿色=正,红色=负)
- 势心影响:势与心的综合效果(紫色=正,橙色=负)
- 实际值:最终发挥属性(金色加粗)
显示双方的主观势和观察结果:
- 观察差值:真实战力 vs 观察战力
- 误差提示:高估/低估/准确判断
- 势态分析:原始势 → 心志判定 → 修正系数
- 特殊状态:顿悟/恐慌状态高亮显示
- 左侧:玩家已选招式列表(实时更新)
- 中间:战斗日志(按阶段分类:观察/势变/选招/伤害/成长)
- 右侧:敌方动向(读招结果,A/B/C/D级显示)
- 你的回合时:
- 显示所有可用招式卡片(颜色区分进/退/中)
- Hover招式:显示完整描述和详细信息 (v2.2新增)
- 点击招式后立即轮到对方
- 右上角有"✓ 确定出招"按钮(提前锁定)
- 敌人回合时:
- 显示"🎯 敌人回合"提示
- 点击"⚔️ 敌人行动"按钮让AI选招
- 双方都锁定时:
- 显示"⚡ 执行判定"按钮
- 显示双方选招数量
- 中心: 对话框(旁白、角色对话)
- 底部: 选项按钮(带属性/标签检定)
- 上方: 场景标题和描述
- 底部: 玩家状态栏
HOST = "127.0.0.1" # 监听地址
PORT = 8000 # 端口号
DEBUG = True # 调试模式(自动重载)
LOG_LEVEL = "info" # 日志级别DEBOUNCE_SECONDS = 0.5 # 防抖延迟
WATCH_EXTENSIONS = {'.yaml', '.yml', '.md'} # 监听文件类型RANDOM_SEED = None # 随机种子(None=随机,整数=固定)A: 检查文件格式是否正确。推荐使用数据仪表盘的编辑模式,会自动验证YAML格式。
A: 三种方式:
- 数据仪表盘 → 招式 → 点击"+"按钮
- 直接在
/data/skills/创建新YAML文件 - 使用
tools/data_editor.py批量创建
A: 这是交替选招机制的核心设计:
- ✅ 每次只能选1个招式,选完立即轮到对方
- ✅ 这样设计是为了增加策略性和互动感
- ✅ 可以随时点击"确定出招"提前结束选招
- ✅ 双方都确定或变值耗尽后才判定
A: 每回合开始判定谁先选招:
- 比较先机值(上回合最后招式:进=1, 中=0, 退=-1)
- 先机值相等 → 比较身属性
- 仍相等 → 主角优先
A: 这是读招系统的设计。根据你的智和觉属性,可能只能看到部分信息(D/C/B/A级)。提升智和觉属性,或使用相关知识标签可以看得更清楚。
A: 在角色YAML中添加 combat_power_weights 配置。怕死的角色设置高xue权重(2.0+),悍不畏死设置低xue权重(0.1-)。气宗设置高qi权重,外家设置低qi权重。
A: 这是主观势的设计。当双方智觉都低,观察误差大时,可能互相低估对方,导致都觉得自己占优势。这是符合现实的心理现象。
A: 在大劣势(势<-0.5)时使用进招,有15%概率心+1。成长后立即生效,影响后续回合的抗压能力。
A: 这取决于角色的 xue 权重配置。怕死的角色(xue=2.0+)血少战力暴跌,悍不畏死的角色(xue=0.1-)几乎不受影响。
- 主观势系统:每人独立计算势,基于观察结果
- 心的抗压机制:顺境/逆境不同表现,顿悟/恐慌状态
- 个性化战力判断:血气力身综合权重,线性公式
- 属性面板:显示基础/buff/势心/实际值
- 招式tooltip:hover显示完整描述
- 心的成长:逆境+进招有概率永久+1心
- 装备系统(武器、防具影响属性和权重)
- 技能树系统(招式升级和解锁)
- 战斗回放功能
- AI智能优化(根据势态和权重选择策略)
- AI认输/绝招系统(基于势和血气阈值)
- 多角色队伍战斗
- 世界地图系统
- 存档系统(包括心属性成长记录)
- 音效和背景音乐
- 剧情分支可视化编辑器
- 战力预测UI(选招前预测战后状态)
MIT License - 详见 LICENSE
感谢所有为本项目做出贡献的开发者!
Made with ❤️ for Chinese Wuxia RPG enthusiasts
⚔️ 江湖路远,愿你仗剑天涯 ⚔️
v2.2 - 势与心的博弈,战力的权衡