代码结构整理

src/include/TetrisLogicInternal.h

@@ -4,20 +4,97 @@
 
 extern Point pendingChainBombCenter;
 extern bool pendingChainBombFollowup;
+extern int pendingLineClearEffectTicks;
+extern int pendingLineClearEffectRows[8];
+extern int pendingLineClearEffectRowCount;
+extern int pendingLineClearEffectLineCount;
 
+/**
+ * @brief 计算指定方块在棋盘顶部的统一生成位置。
+ */
 Point GetSpawnPoint(int brickType);
+
+/**
+ * @brief 重置经典或 Rogue 模式使用的玩家统计数据。
+ */
 void ResetPlayerStats(PlayerStats& stats, bool useRogueRules);
+
+/**
+ * @brief 设置界面右侧显示的即时反馈标题、内容和持续时间。
+ */
 void SetFeedbackMessage(const TCHAR* title, const TCHAR* detail, int ticks);
+
+/**
+ * @brief 判断指定方块、旋转状态和位置是否可以合法放置。
+ */
 bool IsPiecePlacementValid(int pieceType, int pieceState, Point position);
+
+/**
+ * @brief 判断棋盘格是否为彩虹特殊方块。
+ */
 bool IsRainbowBoardCell(int cellValue);
+
+/**
+ * @brief 触发小型黑洞并返回被清除的固定方块数量。
+ */
 int TriggerMiniBlackHole(int maxCellsToClear);
+
+/**
+ * @brief 触发彩虹方块补洞效果并返回补齐格数。
+ */
 int TriggerRainbowRowCompletion(int minRow, int maxRow);
+
+/**
+ * @brief 引爆清屏炸弹并返回清除格数。
+ */
 int TriggerScreenBomb();
+
+/**
+ * @brief 清除指定中心点周围的爆破范围并返回清除格数。
+ */
 int ClearExplosiveAreaAt(int centerY, int centerX);
+
+/**
+ * @brief 清除指定列并返回清除格数。
+ */
 int ClearColumnAt(int column);
+
+/**
+ * @brief 清除指定行并返回清除格数。
+ */
 int ClearRowAt(int row);
+
+/**
+ * @brief 尝试填补局部空洞以稳定棋盘结构。
+ */
 int TryStabilizeBoard();
+
+/**
+ * @brief 为当前方块刷新 Rogue 特殊方块标记。
+ */
 void RollCurrentPieceSpecialFlags(bool allowRandomSpecials);
+
+/**
+ * @brief 暂存消行动画，等待升级选择结束后再播放。
+ */
+void QueueLineClearEffect(const int* rows, int rowCount, int linesCleared);
+
+/**
+ * @brief 尝试把旋转后的方块横向偏移指定格数后放置。
+ */
+bool TryRotateWithOffset(int nextState, int offsetX);
+
+/**
+ * @brief 重置下一方块预览队列。
+ */
 void ResetNextQueue();
+
+/**
+ * @brief 消费队首下一方块并补充新的预览方块。
+ */
 int ConsumeNextType();
+
+/**
+ * @brief 结算一次标准消行带来的 Rogue 玩法效果。
+ */
 void ApplyLineClearResult(int linesCleared);