@playcraft/skills 0.0.2

package/skills/tap_blast.aigameplay/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: tap_blast.aigameplay
+description: 点击连通区消除玩法封包 - 点击同色连通块消除的 PGS 实现，支持重力下落与补充，得分倍率随消除数量递增
+triggers: 点击消除,tap blast,连通区,flood fill,点击,tap,消除,blast,同色,connected,棋盘,grid,玩法,gameplay
+---
+
+# tap_blast.aigameplay
+
+点击连通区消除玩法封包。实现标准 tap blast 规则的 PGS JSON 和 reducer，玩家点击一个格子，若该格子与周围同色格子有连通区（≥2 个），则整个连通区消除，上方格子下落填充，再从顶部补充新格子。
+
+## Recipe
+
+- **玩法类型**：tap_blast（点击连通区消除）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `minConnectedCount`: 2（连通区至少 2 个同色格子才能消除）
+  - `gravityDirection`: down（消除后上方格子向下下落）
+  - `refillFromTop`: true（从顶部补充新格子）
+  - `scoreMultiplier`: true（消除格子越多，分数倍率越高）
+  - `mode`: moves（限步数模式，也支持 timer 模式）
+- **PGS Agent 操作流程**：
+  1. 读取 `ref/pgs-schema.json` 作为规则骨架起点
+  2. 读取 `ref/reducer.template.ts` 了解接口约束
+  3. 实现 `reducer.ts`，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` 以及**全部分步函数**
+  4. 运行 `ref/pgs-schema.json` 中的所有 `testCases`，全部通过后才算完成
+  5. 更新 manifest 的 `generation.pgsVersion` 和 `result.outputFile`
+- **可 fork 变体**：
+  - 限时模式：修改 `mode` 为 `timer`，添加 `timeLimitSeconds`
+  - 障碍格子：添加 `obstacle` 格子类型，不可消除
+  - 炸弹道具：消除 ≥5 格时生成炸弹，点击炸弹消除周围 3×3 区域
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(state, action)`、`getState(state)` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 禁止在渲染层使用 dispatch() 然后全量重建棋盘
+
+正确做法是**分步驱动动画链**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+// Step 1: 查找连通区（鼠标悬停时预高亮）
+const region = findConnectedRegion(state.board, col, row);
+if (region.length < config.minConnectedCount) { playInvalidTapAnimation(); return; }
+
+// Step 2: 消除连通区
+const { removedCells, score } = removeTiles(state, region);
+await playEliminateAnimation(removedCells);  // 对每个消除格子播放爆炸/缩小消失动画
+updateScoreUI(score);
+
+// Step 3: 重力下落
+const fallMoves = applyGravity(state.board, config.cols, config.rows);
+await playFallAnimation(fallMoves);  // 对每个下落格子播放 y-tween 动画
+
+// Step 4: 从顶部补充新格子
+const refills = refillBoard(state.board, config.cols, config.rows, config.colorCount);
+await playRefillAnimation(refills);  // 新格子从顶部滑入动画
+
+// Step 5: 检测胜败
+if (state.movesLeft <= 0) { state.score >= config.goalScore ? playWin() : playLose(); }
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `findConnectedRegion()` | `Cell[]` | 悬停高亮连通区轮廓（size < min → 红色提示） |
+| `removeTiles()` | `{ removedCells, score, multiplier }` | 对每个消除格子播放爆炸缩小动画，显示得分浮动文字 |
+| `applyGravity()` | `FallMove[]` | 对每个下落格子播放垂直 Tween 到新位置 |
+| `refillBoard()` | `RefillTile[]` | 创建新格子精灵并从 y=-cellSize 滑入 |
+| `calculateScore()` | `{ score, multiplier }` | 更新分数 UI + 显示倍率气泡 |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/tap_blast/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(state, action)` / `getState(state)` / `findConnectedRegion()` / `removeTiles()` / `applyGravity()` / `refillBoard()` / `calculateScore()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a tap blast (connected region elimination) core gameplay module following the PGS specification.
+  Write the PGS JSON with entities, rules, algorithm, and testCases.
+  Implement the reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - findConnectedRegion/removeTiles/applyGravity/refillBoard/calculateScore (分步函数，用于渲染层动画驱动)
+  Key constraints:
+    - Use BFS/DFS flood-fill to find connected same-color cells
+    - Minimum 2 connected cells required to eliminate
+    - After elimination, apply gravity (cells fall down to fill gaps column by column)
+    - Refill from top with random colors
+    - Score multiplier: base×1 for 2-3, ×2 for 4-6, ×3 for 7-9, ×5 for 10+
+    - Lose when moves exhausted and score < goalScore
+  The step-by-step functions are CRITICAL for tap-eliminate-fall-refill animation chain.
+  Run the testCases to verify the logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.

package/skills/tap_blast.aigameplay/manifest.json

@@ -0,0 +1,153 @@
+{
+  "schemaVersion": 1,
+  "atomId": "tap_blast.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "点击连通区消除玩法",
+    "en": "Tap blast connected region gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "tap-blast",
+    "casual",
+    "grid",
+    "flood-fill",
+    "eliminate",
+    "core"
+  ],
+  "bindingRoles": [
+    "gameplayRule"
+  ],
+  "imports": [
+    {
+      "slot": "engine",
+      "pinAtomId": "phaser.aicomponent",
+      "edgeKind": "requires",
+      "bindAs": "engine"
+    },
+    {
+      "slot": "bgMusic",
+      "description": "背景循环音乐",
+      "bindAs": "bgm",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "bgMusic"
+      ],
+      "allowedBundleTypes": [
+        "aiaudio"
+      ],
+      "constraints": {
+        "loop": true
+      }
+    },
+    {
+      "slot": "background",
+      "description": "游戏背景图",
+      "bindAs": "bg",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "backgroundTexture"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "winPanel",
+      "description": "通关反馈面板视觉",
+      "bindAs": "winPanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "successFeedbackPanel"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "losePanel",
+      "description": "失败反馈面板视觉",
+      "bindAs": "losePanel",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "failFeedbackPanel"
+      ],
+      "allowedBundleTypes": [
+        "aiimage"
+      ]
+    },
+    {
+      "slot": "tutorial",
+      "description": "新手引导浮层",
+      "bindAs": "tutorial",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tutorialOverlay"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    },
+    {
+      "slot": "endScreen",
+      "description": "可玩广告结算屏（含 CTA 按钮）",
+      "bindAs": "endScreen",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "playableEndScreenLayout"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    }
+  ],
+  "generation": {
+    "kind": "pgs",
+    "pgsVersion": "1.0",
+    "gameplayType": "tap_blast",
+    "rules": {
+      "minConnectedCount": 2,
+      "gravityDirection": "down",
+      "refillFromTop": true,
+      "scoreMultiplier": true,
+      "mode": "moves"
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/tap_blast/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(state, action)",
+        "getState(state)",
+        "findConnectedRegion(board, col, row)",
+        "removeTiles(state, cells)",
+        "applyGravity(board, cols, rows)",
+        "refillBoard(board, cols, rows, colorCount)",
+        "calculateScore(cellCount, config)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

package/skills/tap_blast.aigameplay/ref/pgs-schema.json

@@ -0,0 +1,208 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 点击连通区消除玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "tap_blast",
+  "entities": {
+    "board": {
+      "type": "grid",
+      "cols": 8,
+      "rows": 8,
+      "description": "游戏棋盘，默认 8×8 格子"
+    },
+    "tile": {
+      "type": "cell-item",
+      "colorCount": 5,
+      "description": "棋盘格子上的彩色方块，共 5 种颜色"
+    },
+    "score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前得分"
+    },
+    "moves": {
+      "type": "counter",
+      "initial": 30,
+      "description": "剩余步数（由 config 覆盖）"
+    },
+    "goalScore": {
+      "type": "target",
+      "description": "目标分数，达到后胜利（由 config.level 覆盖）"
+    }
+  },
+  "rules": {
+    "tap_connected_region": {
+      "description": "玩家点击一个格子，通过 BFS/DFS 找到所有相邻同色连通格子。若连通区大小 ≥ minConnectedCount 则全部消除",
+      "algorithm": "flood_fill",
+      "connectivity": "orthogonal",
+      "minConnectedCount": 2,
+      "rejectIfTooSmall": true
+    },
+    "score_multiplier": {
+      "description": "消除格子越多，分数倍率越高",
+      "baseScorePerTile": 30,
+      "multiplierThresholds": [
+        { "count": 2,  "multiplier": 1,  "description": "2-3 格：×1 倍" },
+        { "count": 4,  "multiplier": 2,  "description": "4-6 格：×2 倍" },
+        { "count": 7,  "multiplier": 3,  "description": "7-9 格：×3 倍" },
+        { "count": 10, "multiplier": 5,  "description": "10+ 格：×5 倍" }
+      ]
+    },
+    "gravity": {
+      "description": "消除后，上方格子逐列向下坠落填充空位",
+      "direction": "down",
+      "mode": "column_by_column"
+    },
+    "refill": {
+      "description": "重力下落后，顶部空位补充随机颜色的新格子",
+      "from": "top",
+      "distribution": "uniform"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：tap → flood-fill → remove → gravity → refill → win/lose 检测",
+    "steps": [
+      "1. 玩家点击某个格子 (col, row)",
+      "2. BFS/DFS 找到该格子所在的同色连通区（findConnectedRegion）",
+      "3. 若连通区大小 < minConnectedCount，拒绝并提示（不消耗步数）",
+      "4. 消除连通区所有格子（removeTiles），steps - 1，计算得分（含倍率）",
+      "5. 执行重力：每列中空格上方的格子向下补位（applyGravity）",
+      "6. 顶部补充新的随机格子（refillBoard）",
+      "7. 检测胜败条件：steps 归零？score 达标？"
+    ]
+  },
+  "winCondition": {
+    "type": "score_goal",
+    "description": "在 moves 耗尽前达到目标分数（由 config.goalScore 定义）"
+  },
+  "loseCondition": {
+    "type": "moves_exhausted_without_goal",
+    "description": "moves 归零且 score < goalScore"
+  },
+  "testCases": [
+    {
+      "id": "tc_basic_tap_eliminate",
+      "description": "基础消除：点击连通区 ≥2，消除成功，步数 -1",
+      "initialState": {
+        "board": [
+          [1, 1, 1, 2, 2, 2, 3, 3],
+          [1, 2, 3, 2, 1, 3, 2, 1],
+          [3, 3, 2, 1, 2, 1, 3, 2],
+          [2, 1, 1, 3, 3, 2, 1, 3],
+          [1, 3, 2, 1, 2, 3, 2, 1],
+          [3, 2, 1, 2, 1, 1, 3, 2],
+          [2, 1, 3, 3, 2, 2, 1, 3],
+          [1, 2, 2, 1, 3, 1, 2, 3]
+        ],
+        "score": 0,
+        "moves": 20
+      },
+      "action": { "type": "tap", "col": 0, "row": 0 },
+      "expectedState": {
+        "eliminatedCount": { "min": 2 },
+        "scoreGained": { "min": 60 },
+        "movesLeft": 19,
+        "gravityApplied": true,
+        "boardRefilled": true
+      }
+    },
+    {
+      "id": "tc_invalid_tap_isolated",
+      "description": "无效点击：孤立格子，连通区仅 1 格，不消除，不扣步数",
+      "initialState": {
+        "board": [
+          [1, 2, 3, 2, 3, 2, 3, 2],
+          [2, 3, 2, 3, 2, 3, 2, 3],
+          [3, 2, 3, 2, 3, 2, 3, 2],
+          [2, 3, 2, 3, 2, 3, 2, 3],
+          [3, 2, 3, 2, 3, 2, 3, 2],
+          [2, 3, 2, 3, 2, 3, 2, 3],
+          [3, 2, 3, 2, 3, 2, 3, 2],
+          [2, 3, 2, 3, 2, 3, 2, 3]
+        ],
+        "score": 100,
+        "moves": 10
+      },
+      "action": { "type": "tap", "col": 0, "row": 0 },
+      "expectedState": {
+        "eliminatedCount": 0,
+        "scoreGained": 0,
+        "movesLeft": 10,
+        "tapRejected": true
+      }
+    },
+    {
+      "id": "tc_score_multiplier",
+      "description": "大连通区消除：≥10 格，触发 ×5 倍率",
+      "initialState": {
+        "board": [
+          [1, 1, 1, 1, 1, 2, 3, 2],
+          [1, 1, 1, 1, 1, 3, 2, 3],
+          [1, 1, 2, 3, 2, 1, 3, 2],
+          [2, 3, 2, 1, 3, 2, 1, 3],
+          [3, 2, 3, 2, 1, 3, 2, 1],
+          [2, 3, 2, 3, 2, 1, 3, 2],
+          [3, 2, 3, 2, 3, 2, 1, 3],
+          [2, 3, 2, 3, 2, 3, 2, 1]
+        ],
+        "score": 0,
+        "moves": 15
+      },
+      "action": { "type": "tap", "col": 0, "row": 0 },
+      "expectedState": {
+        "eliminatedCount": { "min": 10 },
+        "scoreGained": { "min": 1500 },
+        "multiplierApplied": 5,
+        "movesLeft": 14
+      }
+    },
+    {
+      "id": "tc_win_condition",
+      "description": "胜利：本次消除后得分达到目标",
+      "initialState": {
+        "board": [
+          [2, 2, 2, 2, 3, 1, 3, 1],
+          [2, 2, 2, 3, 1, 3, 1, 3],
+          [3, 1, 3, 1, 3, 1, 3, 1],
+          [1, 3, 1, 3, 1, 3, 1, 3],
+          [3, 1, 3, 1, 3, 1, 3, 1],
+          [1, 3, 1, 3, 1, 3, 1, 3],
+          [3, 1, 3, 1, 3, 1, 3, 1],
+          [1, 3, 1, 3, 1, 3, 1, 3]
+        ],
+        "score": 900,
+        "goalScore": 1000,
+        "moves": 5
+      },
+      "action": { "type": "tap", "col": 0, "row": 0 },
+      "expectedState": {
+        "win": true,
+        "score": { "min": 1000 }
+      }
+    },
+    {
+      "id": "tc_lose_condition",
+      "description": "失败：最后一步消除后步数归零，分数未达标",
+      "initialState": {
+        "board": [
+          [1, 1, 3, 2, 3, 2, 3, 2],
+          [3, 2, 3, 2, 3, 2, 3, 2],
+          [2, 3, 2, 3, 2, 3, 2, 3],
+          [3, 2, 3, 2, 3, 2, 3, 2],
+          [2, 3, 2, 3, 2, 3, 2, 3],
+          [3, 2, 3, 2, 3, 2, 3, 2],
+          [2, 3, 2, 3, 2, 3, 2, 3],
+          [3, 2, 3, 2, 3, 2, 3, 2]
+        ],
+        "score": 400,
+        "goalScore": 1000,
+        "moves": 1
+      },
+      "action": { "type": "tap", "col": 0, "row": 0 },
+      "expectedState": {
+        "movesLeft": 0,
+        "win": false,
+        "gameOver": true
+      }
+    }
+  ]
+}

package/skills/tap_blast.aigameplay/ref/reducer.template.ts

@@ -0,0 +1,202 @@
+/**
+ * tap_blast.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部跑完整个 tap → remove → gravity → refill
+ * 流程后只返回最终状态，中间过程（哪些格子被消除、哪些格子下落了、
+ * 新补充了什么）全部丢失。
+ *
+ * 渲染层需要分步动画（消除爆炸 → 下落 Tween → 顶部补充滑入），
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入 Tween 动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type TapBlastConfig = {
+  /** 棋盘列数，默认 8 */
+  cols: number;
+  /** 棋盘行数，默认 8 */
+  rows: number;
+  /** 格子颜色数量，默认 5 */
+  colorCount: number;
+  /** 消除连通区的最小格子数，默认 2 */
+  minConnectedCount: number;
+  /** 游戏模式：限步数或限时 */
+  mode: 'moves' | 'timer';
+  /** 初始步数（mode='moves' 时有效） */
+  initialMoves?: number;
+  /** 倒计时秒数（mode='timer' 时有效） */
+  timeLimitSeconds?: number;
+  /** 目标分数 */
+  goalScore: number;
+  /** 每格基础得分 */
+  baseScorePerTile: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type TapBlastAction =
+  | { type: 'tap'; col: number; row: number }
+  | { type: 'tick'; deltaMs: number }  // 倒计时模式下每帧调用
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+/** 格子颜色，0 ~ colorCount-1，null 表示空格 */
+export type TileColor = number | null;
+
+export type TapBlastState = {
+  /** 棋盘格子，board[col][row]，0 = 顶部，rows-1 = 底部 */
+  board: TileColor[][];
+  /** 当前得分 */
+  score: number;
+  /** 剩余步数（moves 模式） */
+  movesLeft: number;
+  /** 剩余时间（毫秒，timer 模式） */
+  timeLeftMs?: number;
+  /** 游戏是否结束 */
+  gameOver: boolean;
+  /** 是否胜利 */
+  win: boolean;
+  /** 上一次 tap 是否因连通区太小被拒绝 */
+  lastTapRejected: boolean;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 格子坐标 */
+export type Cell = { col: number; row: number };
+
+/** 重力下落：某格子从 fromRow 下落到 toRow */
+export type FallMove = {
+  col: number;
+  fromRow: number;
+  toRow: number;
+};
+
+/** 新补充的格子 */
+export type RefillTile = {
+  col: number;
+  row: number;
+  color: number;
+};
+
+/** 消除结果 */
+export type RemoveResult = {
+  /** 被消除的格子列表 */
+  removedCells: Cell[];
+  /** 本次消除获得的得分 */
+  score: number;
+  /** 得分倍率 */
+  multiplier: number;
+};
+
+/** 得分计算结果 */
+export type ScoreResult = {
+  score: number;
+  multiplier: number;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态，随机填满棋盘
+ */
+export declare function init(config: TapBlastConfig): TapBlastState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - tap：查找连通区，消除，下落，补充（一步到位）
+ * - tick：更新倒计时（timer 模式）
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: TapBlastState, action: TapBlastAction): TapBlastState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: TapBlastState): TapBlastState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * findConnectedRegion：从 (col, row) 出发进行 BFS/DFS 洪水填充，
+ * 返回所有与该格子同色且正交相连的格子坐标列表。
+ *
+ * 场景层在鼠标悬停时调用，用于高亮连通区轮廓预览。
+ * 若返回长度 < config.minConnectedCount，显示红色禁止提示。
+ */
+export declare function findConnectedRegion(
+  board: TileColor[][],
+  col: number,
+  row: number,
+): Cell[];
+
+/**
+ * removeTiles：从棋盘移除指定格子列表（置为 null），计算得分
+ *
+ * 场景层在连通区确认后调用，播放格子爆炸消失动画。
+ * cells 通常来自 findConnectedRegion 的结果。
+ */
+export declare function removeTiles(
+  state: TapBlastState,
+  cells: Cell[],
+  config: TapBlastConfig,
+): RemoveResult;
+
+/**
+ * applyGravity：执行重力下落，每列中空格上方的格子向下补位。
+ * 返回每个移动格子的下落信息。
+ *
+ * 场景层根据 FallMove[] 对每个格子精灵播放 y-tween 动画。
+ */
+export declare function applyGravity(
+  board: TileColor[][],
+  cols: number,
+  rows: number,
+): FallMove[];
+
+/**
+ * refillBoard：从顶部补充随机颜色格子填满空位。
+ * 返回新补充的格子信息。
+ *
+ * 场景层根据 RefillTile[] 创建新精灵并从 y=-cellSize 处 tween 滑入。
+ */
+export declare function refillBoard(
+  board: TileColor[][],
+  cols: number,
+  rows: number,
+  colorCount: number,
+): RefillTile[];
+
+/**
+ * calculateScore：根据消除格子数量和配置计算得分与倍率
+ *
+ * 倍率规则（默认）：
+ * - 2-3 格：×1
+ * - 4-6 格：×2
+ * - 7-9 格：×3
+ * - 10+ 格：×5
+ */
+export declare function calculateScore(
+  cellCount: number,
+  config: TapBlastConfig,
+): ScoreResult;