代码结构整理

src/source/TetrisRogue.cpp

@@ -1,6 +1,14 @@
 #include "stdafx.h"
 #include "TetrisLogicInternal.h"
 
+/**
+ * @brief Rogue 创新玩法独立实现文件。
+ *
+ * 本文件集中放置从基础俄罗斯方块版本扩展出的创新设计，包括强化池、
+ * 等级成长、特殊方块、主动技能、难度收缩、连锁奖励和升级选择流程。
+ * 代码保持过程式函数组织，不使用 class、继承或多态。
+ */
+
 enum UpgradeId
 {
     UPGRADE_SCORE_MULTIPLIER = 0,
@@ -127,6 +135,9 @@ static void ApplyUpgradeById(int upgradeId, int targetPieceType, int applyCount)
 static void ApplyDestinyCurse();
 static void ClearLockedRows();
 
+/**
+ * @brief 限制 Rogue 模式的下一方块预览数量。
+ */
 static int GetNextPreviewLimit()
 {
     if (currentMode != MODE_ROGUE)
@@ -147,6 +158,9 @@ static int GetNextPreviewLimit()
     return rogueStats.previewCount;
 }
 
+/**
+ * @brief 获取 Rogue 难度系统当前封锁的底部行数。
+ */
 int GetRogueLockedRows()
 {
     if (currentMode != MODE_ROGUE)
@@ -162,11 +176,17 @@ int GetRogueLockedRows()
     return rogueStats.lockedRows > kMaxRogueLockedRows ? kMaxRogueLockedRows : rogueStats.lockedRows;
 }
 
+/**
+ * @brief 计算当前模式下棋盘可操作区域的高度。
+ */
 int GetRoguePlayableHeight()
 {
     return nGameHeight - GetRogueLockedRows();
 }
 
+/**
+ * @brief 清空 Rogue 模式中被难度系统封锁的底部区域。
+ */
 static void ClearLockedRows()
 {
     int lockedRows = GetRogueLockedRows();
@@ -184,6 +204,9 @@ static void ClearLockedRows()
     }
 }
 
+/**
+ * @brief 根据经过时间推进 Rogue 难度、封锁行数和下落速度。
+ */
 void AdvanceRogueDifficulty(int elapsedMs)
 {
     if (currentMode != MODE_ROGUE || currentScreen != SCREEN_PLAYING || suspendFlag || gameOverFlag || elapsedMs <= 0)
@@ -232,6 +255,9 @@ void AdvanceRogueDifficulty(int elapsedMs)
     SetFeedbackMessage(lockedRowsChanged ? _T("战场收缩") : _T("压力升高"), difficultyDetail, 12);
 }
 
+/**
+ * @brief 读取指定强化在当前 Rogue 属性中的等级或拥有状态。
+ */
 static int GetUpgradeCurrentLevel(int upgradeId)
 {
     switch (upgradeId)
@@ -319,6 +345,9 @@ static int GetUpgradeCurrentLevel(int upgradeId)
     }
 }
 
+/**
+ * @brief 返回进化类强化在界面中展示的合成路线说明。
+ */
 const TCHAR* GetUpgradeSynthesisPath(int upgradeId)
 {
     switch (upgradeId)
@@ -346,6 +375,9 @@ const TCHAR* GetUpgradeSynthesisPath(int upgradeId)
     }
 }
 
+/**
+ * @brief 获取指定强化的基础稀有度分类。
+ */
 static int GetUpgradeBaseRarity(int upgradeId)
 {
     switch (upgradeId)
@@ -390,6 +422,9 @@ static int GetUpgradeBaseRarity(int upgradeId)
     }
 }
 
+/**
+ * @brief 判断指定强化是否已被更高阶合成强化替代。
+ */
 static bool IsUpgradePrerequisiteConsumed(int upgradeId)
 {
     switch (upgradeId)
@@ -425,6 +460,9 @@ static bool IsUpgradePrerequisiteConsumed(int upgradeId)
     }
 }
 
+/**
+ * @brief 根据当前局势动态计算强化选项的抽取权重。
+ */
 static int GetUpgradeDynamicWeight(const UpgradeEntry& entry)
 {
     int weight = entry.baseWeight;
@@ -484,6 +522,9 @@ static int GetUpgradeDynamicWeight(const UpgradeEntry& entry)
     return weight < 1 ? 1 : weight;
 }
 
+/**
+ * @brief 把方块类型编号转换为界面展示用的短名称。
+ */
 static const TCHAR* GetPieceShortName(int pieceType)
 {
     static const TCHAR* kNames[7] =
@@ -499,6 +540,9 @@ static const TCHAR* GetPieceShortName(int pieceType)
     return kNames[pieceType];
 }
 
+/**
+ * @brief 判断强化是否满足当前等级、前置和互斥条件。
+ */
 static bool IsUpgradeSelectable(const UpgradeEntry& entry)
 {
     if (IsUpgradePrerequisiteConsumed(entry.id))
@@ -581,6 +625,9 @@ static bool IsUpgradeSelectable(const UpgradeEntry& entry)
     return GetUpgradeCurrentLevel(entry.id) < entry.maxLevel;
 }
 
+/**
+ * @brief 查找棋盘中最高的已占用行，用于评估局势压力。
+ */
 static int GetTopOccupiedRow()
 {
     for (int i = 0; i < GetRoguePlayableHeight(); i++)
@@ -597,6 +644,9 @@ static int GetTopOccupiedRow()
     return -1;
 }
 
+/**
+ * @brief 计算底线清道夫触发一次自动清底需要的消行充能。
+ */
 static int GetSweeperThreshold()
 {
     int reduction = (rogueStats.sweeperLevel - 1);
@@ -604,6 +654,9 @@ static int GetSweeperThreshold()
     return threshold < 2 ? 2 : threshold;
 }
 
+/**
+ * @brief 根据爆破强化等级随机判定当前方块是否获得爆破特性。
+ */
 static bool RollExplosivePiece()
 {
     if (currentMode != MODE_ROGUE || rogueStats.explosiveLevel <= 0)
@@ -636,6 +689,9 @@ static bool RollExplosivePiece()
     return true;
 }
 
+/**
+ * @brief 根据激光强化等级随机判定当前方块是否获得激光特性。
+ */
 static bool RollLaserPiece()
 {
     if (currentMode != MODE_ROGUE || rogueStats.laserLevel <= 0)
@@ -661,6 +717,9 @@ static bool RollLaserPiece()
     return (rand() % 100) < chancePercent;
 }
 
+/**
+ * @brief 根据十字强化等级随机判定当前方块是否获得十字清除特性。
+ */
 static bool RollCrossPiece()
 {
     if (currentMode != MODE_ROGUE || rogueStats.crossPieceLevel <= 0)
@@ -686,6 +745,9 @@ static bool RollCrossPiece()
     return (rand() % 100) < chancePercent;
 }
 
+/**
+ * @brief 根据彩虹强化等级随机判定当前方块是否获得彩虹补洞特性。
+ */
 static bool RollRainbowPiece()
 {
     if (currentMode != MODE_ROGUE || rogueStats.rainbowPieceLevel <= 0)
@@ -701,11 +763,17 @@ static bool RollRainbowPiece()
     return (rand() % 100) < chancePercent;
 }
 
+/**
+ * @brief 判断棋盘格是否属于彩虹方块固定后的特殊格。
+ */
 bool IsRainbowBoardCell(int cellValue)
 {
     return cellValue == 8;
 }
 
+/**
+ * @brief 触发小型黑洞，随机吞噬限定数量的固定方块。
+ */
 int TriggerMiniBlackHole(int maxCellsToClear)
 {
     int blockCounts[8] = { 0 };
@@ -761,6 +829,9 @@ int TriggerMiniBlackHole(int maxCellsToClear)
     return clearedCellCount;
 }
 
+/**
+ * @brief 为当前活动方块刷新爆破、激光、十字和彩虹等特殊标记。
+ */
 void RollCurrentPieceSpecialFlags(bool allowRandomSpecials)
 {
     if (!allowRandomSpecials)
@@ -788,6 +859,9 @@ void RollCurrentPieceSpecialFlags(bool allowRandomSpecials)
     currentPieceIsRainbow = !currentPieceIsExplosive && !currentPieceIsLaser && !currentPieceIsCross && RollRainbowPiece();
 }
 
+/**
+ * @brief 以指定棋盘格为中心清除爆破范围内的固定方块。
+ */
 int ClearExplosiveAreaAt(int centerY, int centerX)
 {
     int radius = (currentMode == MODE_ROGUE && rogueStats.chainBombLevel > 0) ? 2 : 1;
@@ -818,6 +892,9 @@ int ClearExplosiveAreaAt(int centerY, int centerX)
     return clearedCellCount;
 }
 
+/**
+ * @brief 清除指定列中的所有固定方块并返回清除数量。
+ */
 int ClearColumnAt(int column)
 {
     int clearedCellCount = 0;
@@ -846,6 +923,9 @@ int ClearColumnAt(int column)
     return clearedCellCount;
 }
 
+/**
+ * @brief 清除指定行中的所有固定方块并返回清除数量。
+ */
 int ClearRowAt(int row)
 {
     int clearedCellCount = 0;
@@ -874,6 +954,9 @@ int ClearRowAt(int row)
     return clearedCellCount;
 }
 
+/**
+ * @brief 让彩虹方块尝试补齐其覆盖行内的空缺格。
+ */
 int TriggerRainbowRowCompletion(int minRow, int maxRow)
 {
     int filledCellCount = 0;
@@ -916,6 +999,9 @@ int TriggerRainbowRowCompletion(int minRow, int maxRow)
     return filledCellCount;
 }
 
+/**
+ * @brief 触发黑洞，吞噬棋盘中数量最多的一类固定方块。
+ */
 static int TriggerBlackHole()
 {
     int blockCounts[8] = { 0 };
@@ -970,6 +1056,9 @@ static int TriggerBlackHole()
     return clearedCellCount;
 }
 
+/**
+ * @brief 引爆清屏炸弹，清除当前可玩区域底部多行方块。
+ */
 int TriggerScreenBomb()
 {
     int clearedCellCount = 0;
@@ -1003,6 +1092,9 @@ int TriggerScreenBomb()
     return clearedCellCount;
 }
 
+/**
+ * @brief 围绕消行位置触发连锁火花，随机破坏附近固定方块。
+ */
 static int TriggerChainBlast(int lineAnchor)
 {
     if (currentMode != MODE_ROGUE || rogueStats.chainBlastLevel <= 0)
@@ -1044,6 +1136,9 @@ static int TriggerChainBlast(int lineAnchor)
     return clearedCellCount;
 }
 
+/**
+ * @brief 根据 Rogue 强化和权重系统随机生成下一个方块类型。
+ */
 static int RollNextPieceType()
 {
     if (currentMode == MODE_ROGUE && rogueStats.blockStormPiecesRemaining > 0)
@@ -1082,6 +1177,9 @@ static int RollNextPieceType()
     return rand() % 7;
 }
 
+/**
+ * @brief 尝试用稳定结构强化填补局部空洞并返回填补数量。
+ */
 int TryStabilizeBoard()
 {
     if (currentMode != MODE_ROGUE || rogueStats.stableStructureLevel <= 0)
@@ -1129,6 +1227,9 @@ int TryStabilizeBoard()
     return 0;
 }
 
+/**
+ * @brief 重置下一方块队列并按当前预览上限填充。
+ */
 void ResetNextQueue()
 {
     for (int i = 0; i < 3; i++)
@@ -1137,6 +1238,9 @@ void ResetNextQueue()
     }
 }
 
+/**
+ * @brief 取出队首方块并补充新的下一方块。
+ */
 int ConsumeNextType()
 {
     int nextType = nextTypes[0];
@@ -1146,6 +1250,9 @@ int ConsumeNextType()
     return nextType;
 }
 
+/**
+ * @brief 按 Rogue 规则计算指定消行数对应的基础得分。
+ */
 static int GetRogueScoreByLines(int linesCleared)
 {
     switch (linesCleared)
@@ -1158,6 +1265,9 @@ static int GetRogueScoreByLines(int linesCleared)
     }
 }
 
+/**
+ * @brief 按 Rogue 规则计算指定消行数对应的基础经验。
+ */
 static int GetRogueExpByLines(int linesCleared)
 {
     switch (linesCleared)
@@ -1170,6 +1280,9 @@ static int GetRogueExpByLines(int linesCleared)
     }
 }
 
+/**
+ * @brief 结算经验条并返回本次连续升级次数。
+ */
 static int ApplyLevelProgress(PlayerStats& stats)
 {
     int levelUps = 0;
@@ -1185,6 +1298,9 @@ static int ApplyLevelProgress(PlayerStats& stats)
     return levelUps;
 }
 
+/**
+ * @brief 触发升级冲击波，清除底部指定数量的行。
+ */
 static int TriggerUpgradeShockwave(int rowsToClear)
 {
     int clearedRows = 0;
@@ -1198,6 +1314,9 @@ static int TriggerUpgradeShockwave(int rowsToClear)
     return clearedRows;
 }
 
+/**
+ * @brief 按权重和当前局势生成升级菜单中的候选强化。
+ */
 static void FillUpgradeOptions()
 {
     int selectableIndexes[kUpgradePoolSize] = { 0 };
@@ -1289,6 +1408,9 @@ static void FillUpgradeOptions()
     }
 }
 
+/**
+ * @brief 综合难度、强化和临时状态计算 Rogue 模式下落间隔。
+ */
 int GetRogueFallInterval()
 {
     int baseInterval = 500 + rogueStats.slowFallStacks * 80;
@@ -1337,6 +1459,9 @@ int GetRogueFallInterval()
     return baseInterval;
 }
 
+/**
+ * @brief 根据强化编号把对应效果写入 Rogue 属性。
+ */
 static void ApplyUpgradeById(int upgradeId, int targetPieceType, int applyCount)
 {
     if (applyCount <= 0)
@@ -1518,6 +1643,9 @@ static void ApplyUpgradeById(int upgradeId, int targetPieceType, int applyCount)
     }
 }
 
+/**
+ * @brief 为技能清除的格子结算得分和经验奖励。
+ */
 void AwardRogueSkillClearRewards(int clearedCells, int& scoreGain, int& expGain, bool allowLevelProgress)
 {
     scoreGain = 0;
@@ -1577,6 +1705,9 @@ void AwardRogueSkillClearRewards(int clearedCells, int& scoreGain, int& expGain,
     }
 }
 
+/**
+ * @brief 检查 Rogue 经验是否升级，并在需要时打开强化选择界面。
+ */
 void CheckRogueLevelProgress()
 {
     if (currentMode != MODE_ROGUE || currentScreen != SCREEN_PLAYING)
@@ -1624,6 +1755,9 @@ void CheckRogueLevelProgress()
     OpenUpgradeMenu();
 }
 
+/**
+ * @brief 对棋盘固定方块应用重力，使悬空方块自然下落。
+ */
 void ApplyBoardGravity()
 {
     int playableHeight = GetRoguePlayableHeight();
@@ -1648,6 +1782,9 @@ void ApplyBoardGravity()
     }
 }
 
+/**
+ * @brief 结算一次标准消行带来的 Rogue 得分、经验、连击和派生效果。
+ */
 void ApplyLineClearResult(int linesCleared)
 {
     if (linesCleared <= 0)
@@ -1929,6 +2066,9 @@ void ApplyLineClearResult(int linesCleared)
     currentFallInterval = GetRogueFallInterval();
 }
 
+/**
+ * @brief 应用命运轮盘的诅咒，提高下一次升级所需经验。
+ */
 static void ApplyDestinyCurse()
 {
     rogueStats.requiredExp = rogueStats.requiredExp * 125 / 100;
@@ -1938,6 +2078,9 @@ static void ApplyDestinyCurse()
     }
 }
 
+/**
+ * @brief 在升级选择结束后处理延迟触发的升级冲击波。
+ */
 static void ResolvePendingUpgradeShockwave()
 {
     if (pendingUpgradeShockwaveRows <= 0)
@@ -1984,12 +2127,18 @@ static void ResolvePendingUpgradeShockwave()
     }
 }
 
+/**
+ * @brief 重置 Rogue 模式中等待播放的特殊视觉事件。
+ */
 void ResetPendingRogueVisualEvents()
 {
     pendingUpgradeShockwaveRows = 0;
     pendingEvolutionImpactShockwave = false;
 }
 
+/**
+ * @brief 在 Rogue 模式中打开升级强化选择界面。
+ */
 void OpenUpgradeMenu()
 {
     if (currentMode != MODE_ROGUE || upgradeUiState.pendingCount <= 0)
@@ -2001,6 +2150,9 @@ void OpenUpgradeMenu()
     currentScreen = SCREEN_UPGRADE;
 }
 
+/**
+ * @brief 确认升级菜单中的选择并应用对应强化效果。
+ */
 void ConfirmUpgradeSelection()
 {
     if (currentScreen != SCREEN_UPGRADE || upgradeUiState.optionCount <= 0)
@@ -2205,6 +2357,9 @@ void ConfirmUpgradeSelection()
     PlayPendingLineClearEffect();
 }
 
+/**
+ * @brief 执行 Hold 操作，在备用仓与当前方块之间交换。
+ */
 void HoldCurrentPiece()
 {
     if (currentMode != MODE_ROGUE || currentScreen != SCREEN_PLAYING || suspendFlag || gameOverFlag)
@@ -2266,6 +2421,9 @@ void HoldCurrentPiece()
     }
 }
 
+/**
+ * @brief 响应玩家主动使用清屏炸弹的操作。
+ */
 void UseScreenBomb()
 {
     if (currentMode != MODE_ROGUE || currentScreen != SCREEN_PLAYING || suspendFlag || gameOverFlag)
@@ -2303,6 +2461,9 @@ void UseScreenBomb()
     ComputeTarget();
 }
 
+/**
+ * @brief 响应玩家主动释放黑洞的操作。
+ */
 void UseBlackHole()
 {
     if (currentMode != MODE_ROGUE || currentScreen != SCREEN_PLAYING || suspendFlag || gameOverFlag)
@@ -2364,6 +2525,9 @@ void UseBlackHole()
     ComputeTarget();
 }
 
+/**
+ * @brief 响应玩家主动使用空中换形，将当前方块重塑为 I 块。
+ */
 void UseAirReshape()
 {
     if (currentMode != MODE_ROGUE || currentScreen != SCREEN_PLAYING || suspendFlag || gameOverFlag)