Tereis/TODO.md

Rogue Tetris TODO List

说明：本清单基于 Rogue_Tetris_功能设计文档 整理，后续实现严格遵守以下约束：

• 不使用 class、继承、多态等面向对象特性
• 以 struct + 全局状态 + 纯函数/过程函数 + 模块化源文件 组织代码
• 保留当前原版俄罗斯方块玩法，作为“经典模式”
• 新增开始菜单，进入游戏前先选择模式
• 模式至少包含：经典模式、Rogue 模式
• 强化选择界面固定为“三选一”三个选项框，视觉参考《吸血鬼幸存者》
• 美术、图标、特效、音频先全部使用占位符资源

阶段 0：重构准备与技术基线

目标：在不破坏现有可运行版本的前提下，为肉鸽系统预留结构。

• 盘点当前全局变量、输入流程、计时器流程、渲染流程
• 明确哪些旧逻辑保留，哪些逻辑需要拆分成独立过程函数
• 明确保留当前版本作为“经典模式”基线，不把 Rogue 逻辑硬塞进唯一流程
• 设计新的状态拆分方案：游戏主状态、棋盘状态、当前方块状态、玩家成长状态、强化状态、UI 状态
• 增加“菜单状态 / 模式选择状态”设计
• 统一命名风格，避免后续继续扩散 type/state/nType 这类语义偏弱命名
• 明确“升级中暂停”和“普通暂停”是两个不同状态
• 确定占位符资源策略：纯色块、边框、占位图标、占位按钮

完成标准：

• 写出核心数据结构草案
• 写出模块拆分草案
• 当前版本仍可正常编译运行

阶段 1：开始菜单与模式选择

目标：先把“玩哪种模式”从启动流程里分出来，保证经典模式和 Rogue 模式能共存。

• 新增开始菜单界面，不启动即直接进入对局
• 菜单至少提供两个可选项：经典模式、Rogue 模式
• 增加菜单输入处理：上下/左右切换，确认进入
• 增加当前选中模式的高亮显示
• 增加菜单状态与对局状态之间的切换逻辑
• 从菜单进入经典模式时，沿用当前原版规则
• 从菜单进入 Rogue 模式时，进入带经验升级与强化的流程
• 预留未来扩展入口，如“退出游戏”或“帮助说明”

完成标准：

• 启动后先进入菜单
• 两种模式都能正常进入
• 经典模式不受 Rogue 功能影响

阶段 2：核心数据结构改造

目标：把当前普通俄罗斯方块状态扩展成可承载 Rogue 系统的数据。

• 新增 MenuState 或等效结构，记录菜单选项与当前选中项
• 新增 GameState 相关结构，记录运行态、暂停态、升级选择态、结算态
• 新增 ModeState 或模式标记，区分经典模式与 Rogue 模式
• 新增 PieceState 结构，管理当前方块、下一方块、目标落点、是否可 Hold
• 新增 PlayerStats 结构，包含分数、等级、经验、所需经验、连击、总消行数
• 新增 UpgradeEntry 结构，包含 id、名称、描述、分类、当前层数、是否可重复
• 新增 UpgradeRuntime 结构，保存已获得强化和运行时效果值
• 新增 UiState 结构，保存当前三个升级选项、当前高亮项、弹窗可见性
• 将现有散落的全局变量逐步收敛到几个结构体中
• 保留纯过程式调用，不引入成员函数

完成标准：

• 代码中已能通过结构体访问大部分核心状态
• 不再继续新增零散全局变量

阶段 3：经典模式与 Rogue 模式分流

目标：先把公共逻辑和模式专属逻辑分开，避免后续互相污染。

• 抽离经典模式与 Rogue 模式共享的核心逻辑：移动、旋转、落地、消行、渲染基础棋盘
• 经典模式保持当前简单计分与基础 UI
• Rogue 模式单独接入经验、等级、强化、升级界面
• 输入处理按模式分流，避免经典模式响应强化界面按键
• 渲染流程按模式分层：公共层、经典模式层、Rogue 模式层

完成标准：

• 两种模式共用一套基础方块逻辑
• Rogue 新功能不会破坏经典模式

阶段 4：分数、经验、等级主循环

目标：把“消行 -> 得分 -> 获得经验 -> 触发升级”接入 Rogue 模式主循环。

• 重写消行结算函数，返回本次消除行数
• 按文档接入基础得分：1/2/3/4 行分别对应不同分值
• 按文档接入经验收益：1/2/3/4 行分别给予不同 EXP
• 接入倍率计算：分数倍率、经验倍率、四消奖励、连击奖励
• 新增升级判定函数，支持一次结算后连续升多级
• 升级触发时停止下落计时与普通输入
• 在右侧信息面板显示等级、EXP、所需 EXP、当前已获得强化摘要

完成标准：

• 消行后可以稳定增加分数和经验
• 达到阈值后必定进入升级选择状态

阶段 5：强化池与三选一系统

目标：先完成最关键的 Rogue 核心体验。

• 建立强化池初始化函数，不使用类，采用静态数组或 std::vector<UpgradeEntry>
• 先实现一批 P1 基础强化，优先选 6 个左右最稳定的：
• score_multiplier
• combo_bonus
• slow_fall
• preview_plus_one
• exp_multiplier
• last_chance
• 随机抽取 3 个不重复选项，避免当前局内明显无效选项
• 支持重复强化的层数叠加
• 选中后立即应用效果并返回游戏
• 为后续强化扩展预留 applyUpgradeById() 分发函数

完成标准：

• 每次升级都稳定弹出三个选项框
• 选择任一选项后效果立即生效

阶段 6：升级界面 UI

目标：实现参考《吸血鬼幸存者》的三选一视觉结构，先用占位表现。

• 增加全屏或半透明遮罩，压暗游戏场景
• 中央显示三个横向或纵向排列的选项框
• 每个选项框至少包含：占位图标、强化名、强化说明、强化分类、当前层数
• 支持键盘选择：A/D 或方向键切换，Enter/Space 确认
• 高亮态、选中态、禁用态视觉区分明确
• 保证三个框尺寸一致、布局稳定，不因文本长度错位
• 右侧现有信息面板在升级状态下保留或弱化显示，但不能抢焦点
• 占位资源统一放入 assets，命名先按 placeholder_*

完成标准：

• 升级界面可以独立显示
• 三个选项框可操作、可确认、可关闭
• 视觉结构已经接近目标形式，后续只需替换资源

阶段 7：玩法强化第一轮

目标：把最影响体验的几个强化真正接入玩法。

• 分数倍率：影响所有结算得分
• 连击奖励：连续多次成功消行追加奖励
• 慢速下落：降低自然下落速度
• 额外预览：从 1 个 Next 扩展到 2~3 个
• EXP 强化：提升经验获取倍率
• 最后一搏：失败前自动清除底部 3 行，仅触发一次

完成标准：

• 每个强化都能在实际对局中观察到效果
• 强化效果叠加后不会引发明显逻辑冲突

阶段 8：特殊机制第二轮

目标：在主体验稳定后再上特殊规则，避免一开始把复杂度拉满。

• Hold 功能改造成可解锁能力，而不是默认启用
• 扩展更多预览块显示
• 清扫者：累计消行触发底部清除
• 爆破方块：生成特殊方块并实现 3x3 清除
• 减压：升级后清除最高占用行
• 稳定结构：小概率自动填补邻近空洞
• 双倍成长 / 赌徒 / 方块改运等特殊强化

完成标准：

• 至少 2 个特殊机制能稳定跑通
• 不会明显破坏基础俄罗斯方块节奏

阶段 9：界面补全与反馈

目标：让系统信息足够清楚，不靠猜测理解机制。

• 右侧面板补充等级、EXP 条、强化列表、当前倍率
• 增加本次结算浮动提示：+Score、+EXP、Level Up
• 为特殊强化增加简短提示文案
• 增加暂停、升级、失败三种不同遮罩样式
• 增加占位图标、占位按钮、占位边框资源
• 检查中文排版、字号、留白、长文本换行

完成标准：

• 玩家能看懂自己为什么升级、为什么得分变化

阶段 10：平衡与稳定性

目标：把版本从“能跑”拉到“能玩”。

• 调整等级需求曲线
• 调整强化出现权重，避免过强或无效强化频繁出现
• 调整下落速度、经验速度、升级频率
• 修复升级状态下的非法输入问题
• 修复连续升级、失败复活、爆破消行等边界问题
• 增加最基础回归测试清单

回归检查：

• 开局正常生成方块
• 消行得分与经验正确
• 升级必出 3 个选项框
• 选择后恢复游戏且不丢状态
• 复活、暂停、失败、重开互不冲突

建议实现顺序

1. 先做阶段 1 到阶段 3，把“菜单选模式 + 经典 / Rogue 分流”打通。
2. 再做阶段 4 到阶段 6，完成 Rogue 的经验升级与三选一界面。
3. 然后做阶段 7，把第一批基础强化真正接上。
4. 最后做阶段 8 到阶段 10，补特殊机制、表现和调平衡。

当前最近一轮执行清单

• 加入开始菜单状态
• 做出模式选择菜单占位 UI
• 接入 经典模式 / Rogue 模式 两个入口
• 建立新的状态结构体与头文件声明
• 拆分经典模式与 Rogue 模式主循环
• 重写消行结算返回值
• 加入 PlayerStats
• 加入经验与升级判定
• 加入升级状态切换
• 做出三个升级选项框的占位 UI
• 接入第一批 6 个基础强化