Skip to content

ROADMAP.md

Latest commit

 

History

History
228 lines (184 loc) · 10.2 KB

ROADMAP.md

File metadata and controls

228 lines (184 loc) · 10.2 KB
Raw

Gwent TTS 项目路线图

本文档记录 Gwent Tabletop Simulator 项目的开发路线，从当前进度到完整双人对局 Demo 的规划。

已完成（不需要再规划）

以下功能已在代码库中实现并可用：

  • GwentScript 编译器全链路：GC → AST → Python 编译流程完整可用
  • Python 后端骨架：Flask + Hypercorn + 事件系统基础架构已搭建
  • TTS Lua 端核心功能：
    • 区域检测与卡牌放置逻辑
    • Deploy 事件发送机制
    • 回合结算基础框架
    • 换牌阶段处理
    • 战力显示与状态 Token
    • 悬停描述显示
  • 初始发牌与换牌全流程：Lua 侧完整实现
  • Choose 交互机制：Lua 等待 → Python async Future → /choose 回调完整闭环

第一阶段：核心对战流程完善（1-3周）

目标：修复已知 Bug，补齐基础操作，实现稳定可玩的双人对局原型。

里程碑1.1：Lua 端关键 Bug 修复 √

  • 区域 Tag 大小写一致性：
    • 修复 onObjectEnterZone 中区域 Tag 大小写不一致问题（"ZoneMeleeA" vs "zoneMeleeA"）
    • 统一所有区域注册与检测的命名规范
  • 墓场跳转笔误修复：
    • 修正 graveB 的 jumpTo 处理中搜索错误区域的问题（第222行搜索的是 graveA 而非 graveB）
  • 回合结算防重复触发：
    • 在 onUpdate() 的回合结算逻辑中添加 stage guard
    • 设置 gameInfo.stage = "settling" 防止 stopA && stopB 同时为 true 时反复触发

里程碑1.2：ServerUtils 基础操作补齐 √

  • spawn(name) 实现：
    • 通过 database.json 查找卡牌 ID
    • 发送 spawnCard action 到 Lua 端
  • play(card) 实现：
    • 打出一张牌到场上的完整流程
    • 处理卡牌从手牌到战场的状态转换
  • filter_list() 逻辑完善：
    • 修复 ally/enemy 条件判断逻辑
    • 支持 Card 对象的派系判断，不仅限于颜色 string

里程碑1.3：Order 能力完整流程 ✅

  • Lua 端 Order 按钮处理：
    • ✅ 在 handleResponse 中添加 addButton action 响应
    • ✅ 动态给卡牌添加 Order 按钮
    • ✅ 实现 removeButton action 处理
  • Order 触发与回调：
    • ✅ 确保 Order 按钮点击后能正确触发 Python 后端的能力处理
    • ✅ 验证 Order 能力的异步等待与结果返回
    • ✅ 支持异步 Order 函数的执行（inspect + asyncio）
    • ✅ 添加 remove_button() ServerUtils 辅助函数

里程碑1.4：回合结算完整化 ✅

  • RoundEnd 事件触发：
    • ✅ 在 onUpdate() 回合结束后补 emit({type = "RoundEnd"})
    • ✅ 确保战场牌移位到墓场区域前触发事件
  • Python 后端 RoundEnd 分发：
    • ✅ 已有的事件订阅与分发机制自动支持 RoundEnd 事件
    • ✅ 验证有 RoundEnd 订阅的卡牌能正确触发
  • 示例卡牌：
    • ✅ 创建 card201727.py（基础RoundEnd效果）
    • ✅ 创建 card201728.py（伤害累积型RoundEnd效果）

第一阶段产出： 一个稳定的、无已知严重 Bug 的双人对局原型，支持基础出牌、Order 能力和回合结算。

第二阶段：松鼠派卡组批量编译与测试（4-8周）

目标：完成松鼠派所有卡牌的编译与效果验证，建立批量处理工作流。

里程碑2.1：批量编译工具链

  • 编译脚本开发：
    • 整理 GCodesOriginal/ 里松鼠派所有 .txt 文件清单
    • 编写批量编译脚本（循环调用 ASTToPython.py）
    • 自动生成 GCodes/ 目录下的 Python 文件
  • 编译失败记录：
    • 记录编译失败的 GC 语法点
    • 建立 compiler bug list 用于后续修复

里程碑2.2：编译器语法修复

  • 语法 Case 修复：
    • 分析编译失败的案例，定位 GC 语法解析问题
    • 修复 lexer/parser 中的语法处理逻辑
    • 重新编译验证修复效果
  • 回归测试：
    • 确保已编译通过的卡牌不受影响
    • 验证新修复的语法能正确处理边缘情况

里程碑2.3：卡牌效果逐一测试

  • TTS 中逐张测试：
    • 在 TTS 环境中加载编译出的松鼠派卡牌
    • 逐张测试卡牌触发效果是否正确
    • 记录 runtime bug 和效果偏差
  • 效果修正：
    • 根据测试结果修正卡牌 Python 代码
    • 更新编译器以生成更准确的代码

里程碑2.4：常用卡牌效果补齐

  • 高频卡牌优先：
    • 识别松鼠派卡组中的核心卡牌
    • 优先确保这些卡牌的效果完整可用
  • 特殊机制支持：
    • 实现松鼠派特有的机制（如复活、召唤、增益等）
    • 验证复杂连锁效果的正确性

第二阶段产出： 松鼠派完整卡组的所有卡牌编译通过且效果可用，建立可持续的批量编译与测试工作流。

第三阶段：多阵营支持与完整对局（9-12周）

目标：扩展至多阵营支持，实现完整的选卡、换牌、三局两胜流程。

里程碑3.1：完整双人对局流程

  • 选卡阶段：
    • 实现玩家选择起始卡组的界面与逻辑
    • 支持从牌库中选择符合规则的卡牌组成卡组
  • 换牌阶段完善：
    • 优化换牌阶段的 UI 反馈
    • 确保换牌逻辑与规则一致（最多换几张、是否可见等）
  • 三局两胜流程：
    • 实现完整的三局对战流程
    • 每局结束后正确结算胜负
    • 累计两胜后结束整场对局

里程碑3.2：第二个阵营支持

  • 阵营选择：
    • 在现有松鼠派基础上，增加至少一个阵营（如北方王国或怪物）
    • 复用 L1-B 完成的编译流程处理新阵营卡牌
  • 跨阵营对战：
    • 验证不同阵营之间的卡牌效果兼容性
    • 测试阵营特有机制的交互（如北方的天气、怪物的吞噬等）

里程碑3.3：效果触发完整性验证

  • 常用牌效果全覆盖：
    • 确保所有常用卡牌的效果都能正确触发
    • 验证被动能力、Order 能力、Deploy 能力等各类触发时机
  • 边界情况处理：
    • 测试空手牌、空战场、同时触发等边界情况
    • 修复潜在的崩溃或逻辑错误

里程碑3.4：用户体验优化

  • UI 反馈增强：
    • 优化卡牌悬停描述的显示
    • 增强战力变化的视觉反馈
    • 改进状态 Token 的展示方式
  • 错误提示友好化：
    • 当卡牌效果触发失败时给出明确提示
    • 记录详细日志便于调试

第三阶段产出： 支持至少两个阵营的完整双人对局 Demo，走完选卡、换牌、出牌、三局两胜的全流程，效果正确触发。

常态化事项（同步进行，不设死线）

目标：持续改善代码质量、内容覆盖与用户体验，不阻塞里程碑推进。

架构与代码质量

  • 数据与逻辑分离：
    • 所有卡牌数据存储在独立 JSON/数据库中，不内嵌在游戏逻辑里
    • 保持 Python 后端与 Lua 前端的清晰职责划分
  • 模块化通信：
    • 通过事件系统实现前后端解耦
    • 确保事件数据结构使用简单字典/基本类型，便于调试与迁移
  • 代码重构与清理：
    • 随功能推进定期清理废弃代码
    • 保持模块单一职责，避免循环导入

内容填充

  • 卡牌池扩展：
    • 持续扩充各阵营卡牌的编译覆盖率
    • 目标覆盖所有常用卡牌和核心机制
  • 卡牌效果验证：
    • 建立卡牌效果测试用例库
    • 自动化测试常见触发场景

基础 UI/UX

  • 视觉反馈：
    • 卡牌移动、翻转、战力变化等操作的平滑动画
    • 关键事件（如回合开始、卡牌触发）的明显提示
  • DPI 与分辨率适配：
    • 确保 TTS 中 UI 元素在不同分辨率下正常显示

关键原则（贯穿始终）

  • 每个里程碑结束，都必须是一个可玩版本。 宁可功能少，也不能是半成品代码。
  • 批量编译的工作流必须稳定可靠。 这是扩展多阵营的基础。
  • 卡牌效果的准确性优先于数量。 一张正确触发的牌比十张有 Bug 的牌更有价值。

近期日任务计划（第 1-2 周）

天 任务 所属里程碑
Day 1 修复 onObjectEnterZone 的 Tag 大小写问题；修复 graveB jumpTo 笔误 M1.1
Day 2 在 onUpdate() 的回合结算逻辑加 stage guard（设置 gameInfo.stage = "settling" 防止重复触发） M1.1
Day 3 Lua 端 handleResponse 添加 addButton action 处理 —— 动态加 Order 按钮 M1.3
Day 4 整理 GCodesOriginal/ 文件清单，写一个批量编译脚本（循环调用 ASTToPython.py） M2.1
Day 5 批量编译松鼠派牌，记录编译失败的 GC 语法点（作为 compiler bug list） M2.1
Day 6 修复编译失败的语法 case，重新编译 M2.2
Day 7 在 TTS 中逐张测试编译出来的松鼠派牌效果，记录 runtime bug M2.3
Day 8 在 ServerUtils 实现 spawn(cardName) —— 通过 database.json 查找 id，发送 spawnCard action M1.2
Day 9 Lua 端处理 spawnCard action —— 调用 getNameIdAndSummonCard() M1.2
Day 10 补充 emit({type = "RoundEnd"}) + Python 后端 RoundEnd 事件分发 + 创建示例卡牌 M1.4 ✅

长期目标概览

目标层级 目标名称 描述 当前差距
L1-A 完整双人对局 Demo 走完选卡换牌出牌三局两胜全流程，效果正确触发 主流程已通，需要修复细节 bug、补齐常用牌效果
L1-B 松鼠派完整卡组 松鼠派所有牌的 GC 编译或手写效果通过 只有少数几张（162106等），需要批量编译
L1-C 多阵营支持 再加至少一个阵营（如北方王国/怪物）可完整对战 依赖 L1-B 完成后复用流程

最后更新：2026年5月17日 - 里程碑1.4已完成