@playcraft/skills 0.0.2

package/skills/match-pop.aicomponent/manifest.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "atomId": "match-pop.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "animation",
+  "mode": "fixed",
+  "label": { "zh": "三消元素消除动画", "en": "Match-3 Element Pop Animation" },
+  "tags": ["animation", "match3", "pop", "disappear", "particle", "playcanvas", "phaser"],
+  "generation": {
+    "animationType": "tween",
+    "engineSupport": ["playcanvas", "phaser"],
+    "parameters": {
+      "punchScale": "number — scale overshoot at peak (default: 1.3)",
+      "duration": "number — total animation duration in ms (default: 300)",
+      "particles": "boolean — emit a burst of particles on pop (default: true)"
+    }
+  },
+  "files": { "skill": "SKILL.md", "playcanvas": "ref/playcanvas.js", "phaser": "ref/phaser.js" }
+}

package/skills/match-pop.aicomponent/ref/phaser.js

@@ -0,0 +1,30 @@
+// match-pop — Phaser 3 implementation
+
+function playMatchPop(scene, sprite, { punchScale = 1.3, duration = 300, destroyOnComplete = true } = {}) {
+  const chain = scene.tweens.chain({
+    targets: sprite,
+    tweens: [
+      {
+        scaleX: punchScale,
+        scaleY: punchScale,
+        duration: duration * 0.33,
+        ease: 'Cubic.Out',
+      },
+      {
+        scaleX: 0,
+        scaleY: 0,
+        alpha: 0,
+        duration: duration * 0.67,
+        ease: 'Cubic.In',
+        onComplete: () => {
+          if (destroyOnComplete) sprite.destroy();
+          else sprite.setVisible(false);
+        },
+      },
+    ],
+  });
+  return chain;
+}
+
+// Usage:
+// playMatchPop(this, tileSprite);

package/skills/match-pop.aicomponent/ref/playcanvas.js

@@ -0,0 +1,22 @@
+// match-pop — PlayCanvas implementation
+var MatchPop = pc.createScript('matchPop');
+MatchPop.attributes.add('punchScale', { type: 'number', default: 1.3 });
+MatchPop.attributes.add('duration', { type: 'number', default: 0.3 });
+
+MatchPop.prototype.play = function (onComplete) {
+    var entity = this.entity;
+    var base = entity.getLocalScale().clone();
+    var punch = new pc.Vec3(base.x * this.punchScale, base.y * this.punchScale, base.z);
+    var zero = new pc.Vec3(0, 0, 0);
+    var punchTime = this.duration * 0.33;
+    var fadeTime = this.duration * 0.67;
+
+    entity.tween(base)
+        .to(punch, punchTime, pc.QuadOut)
+        .then(entity.tween(punch).to(zero, fadeTime, pc.QuadIn))
+        .call(function () {
+            if (onComplete) onComplete();
+            entity.destroy();
+        })
+        .start();
+};

package/skills/match3_core.aigameplay/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: match3_core.aigameplay
+description: 三消核心玩法封包 - 标准三消消除规则的 PGS 实现，可替换消除元素和视觉主题
+triggers: 三消,match3,消除,match,配对,pair,棋盘,board,玩法,gameplay,核心,core,grid
+---
+
+# match3_core.aigameplay
+
+三消核心玩法封包。实现标准三消规则的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer，玩家通过交换相邻元素消除 3 个或更多同类元素。
+
+## Recipe
+
+- **玩法类型**：match-3（三消消除）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `minMatchCount`: 3（最少匹配数）
+  - `swapDirection`: orthogonal（只能水平/垂直交换）
+  - `gravityDirection`: down（消除后元素向下坠落）
+  - `refillFromTop`: true（从顶部补充新元素）
+- **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 变体**：
+  - 连线消除：修改 `swapDirection` 为 `any`，允许连线
+  - 爆炸道具：在 rules 中添加 bomb_trigger 特殊消除规则
+  - 彩虹元素：添加 wildcard 类型元素
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 禁止在渲染层使用 dispatch() 然后全量重建棋盘
+
+常见错误：
+```ts
+// ❌ 错误做法：调用 dispatch 拿到最终 board，然后全部销毁精灵重建
+const newState = dispatch(state, { type: 'swap', from, to });
+destroyAllSprites();     // 视觉上 = 整页刷新
+createAllSprites(newState.board);
+```
+
+正确做法是**分步驱动动画链**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+// Step 1: 验证交换
+const { valid, board, matches } = trySwap(state, from, to);
+if (!valid) { playRevertAnimation(); return; }
+
+// Step 2: 消除动画（只销毁匹配的格子）
+state.board = board;
+removeMatches(state.board, matches);
+await playEliminationAnimation(matches);  // 只对 matches 中的格子做缩小消失动画
+
+// Step 3: 下落动画（只移动受影响的格子）
+const fallMoves = applyGravity(state.board, cols, rows);
+await playFallAnimation(fallMoves);       // 只对有 FallMove 的精灵做 tween
+
+// Step 4: 补充动画（只创建新格子）
+const refills = refillBoard(state.board, cols, rows, colorCount);
+await playRefillAnimation(refills);       // 只为新格子创建精灵并从顶部滑入
+
+// Step 5: 检查连消
+const newMatches = findAllMatches(state.board, cols, rows);
+if (newMatches.length > 0) { goto Step 2; }  // cascade 循环
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `trySwap()` | `{ valid, board, matches }` | swap tween → 有效则继续，无效则 revert tween |
+| `removeMatches()` | `Set<"col,row">` | 对命中的精灵播放 scale→0 + fade 动画 |
+| `applyGravity()` | `FallMove[]` | 对每个 move 的精灵播放 y-tween 到新行位置 |
+| `refillBoard()` | `RefillTile[]` | 在目标位置创建新精灵，从 y=-cellSize 处 tween 滑入 |
+| `findAllMatches()` | `MatchResult[]` | 如非空则继续 cascade 循环 |
+| `calculateMatchScore()` | `number` | 更新 score UI |
+
+### 动画期间的输入锁定
+
+场景层在整个 cascade 动画链执行期间必须锁定输入（`isAnimating = true`），
+防止玩家在下落/补充过程中触发新的 swap 导致状态不一致。
+动画链全部完成后才解锁（`isAnimating = false`）。
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/match3/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `trySwap()` / `findAllMatches()` / `removeMatches()` / `applyGravity()` / `refillBoard()` / `calculateMatchScore()` / `hasValidMoves()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a match-3 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 (一体化接口，用于测试)
+    - trySwap/findAllMatches/removeMatches/applyGravity/refillBoard/calculateMatchScore/hasValidMoves (分步函数，用于渲染层动画驱动)
+  The step-by-step functions are CRITICAL — the rendering layer (GameScene) must use them to drive animations.
+  Do NOT expect the rendering layer to call dispatch() — that would force a full board rebuild and break visual continuity.
+  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/match3_core.aigameplay/manifest.json

@@ -0,0 +1,107 @@
+{
+  "schemaVersion": 1,
+  "atomId": "match3_core.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": { "zh": "三消核心玩法", "en": "Match-3 core gameplay" },
+  "tags": ["gameplay", "match3", "casual", "grid", "eliminate", "core"],
+  "bindingRoles": ["gameplayRule"],
+  "imports": [
+    { "slot": "engine",      "pinAtomId": "phaser.aicomponent",          "edgeKind": "requires",      "bindAs": "engine" },
+    { "slot": "boardLayout", "pinAtomId": "grid_board_layout.aicomponent","edgeKind": "requires",      "bindAs": "boardLayout" },
+    {
+      "slot": "bgMusic",
+      "description": "背景循环音乐",
+      "bindAs": "bgm",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["bgMusic"],
+      "allowedBundleTypes": ["aiaudio"],
+      "constraints": { "loop": true }
+    },
+    {
+      "slot": "tileSet",
+      "description": "牌面贴图组（三消块的视觉贴图集）",
+      "bindAs": "tiles",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["tileTextureSet"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "background",
+      "description": "游戏背景图",
+      "bindAs": "bg",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["backgroundTexture"],
+      "allowedBundleTypes": ["aiimage"]
+    },
+    {
+      "slot": "levelDataPack",
+      "description": "关卡数据包",
+      "bindAs": "levels",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": ["levelDataPack"],
+      "allowedBundleTypes": ["aiconfig"]
+    },
+    {
+      "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"]
+    }
+  ],
+  "generation": {
+    "kind": "pgs",
+    "pgsVersion": "1.0",
+    "gameplayType": "match3",
+    "rules": {
+      "minMatchCount": 3,
+      "swapDirection": "orthogonal",
+      "gravityDirection": "down",
+      "refillFromTop": true
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": { "testCasesMustPass": true }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/match3/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)", "dispatch(action)", "getState()",
+        "trySwap(state, from, to)",
+        "findAllMatches(board, cols, rows)",
+        "removeMatches(board, matches)",
+        "applyGravity(board, cols, rows)",
+        "refillBoard(board, cols, rows, colorCount)",
+        "calculateMatchScore(matches, config)",
+        "hasValidMoves(state)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,154 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 三消核心玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "match3",
+  "entities": {
+    "board": {
+      "type": "grid",
+      "cols": 8,
+      "rows": 8,
+      "description": "游戏棋盘，8×8 格子"
+    },
+    "tile": {
+      "type": "cell-item",
+      "colorCount": 6,
+      "description": "棋盘格子上的消除元素，共 6 种颜色/类型"
+    },
+    "score": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前得分"
+    },
+    "moves": {
+      "type": "counter",
+      "initial": 30,
+      "description": "剩余步数（由 config 覆盖）"
+    }
+  },
+  "rules": {
+    "swap": {
+      "description": "玩家交换相邻两个格子（上下左右），若交换后产生 ≥3 连，则有效；否则回退",
+      "swapDirection": "orthogonal",
+      "revertIfNoMatch": true
+    },
+    "match": {
+      "description": "消除连续 ≥3 个同类型格子（水平或垂直）",
+      "minCount": 3,
+      "directions": ["horizontal", "vertical"],
+      "scorePerTile": 50,
+      "bonusThresholds": [
+        { "count": 4, "bonus": 100, "description": "消除 4 个获得额外 100 分" },
+        { "count": 5, "bonus": 300, "specialTile": "bomb", "description": "消除 5 个生成炸弹特殊块" }
+      ]
+    },
+    "gravity": {
+      "description": "消除后，上方格子向下坠落填充空位",
+      "direction": "down"
+    },
+    "refill": {
+      "description": "坠落后，顶部补充新的随机格子",
+      "from": "top",
+      "distribution": "uniform"
+    },
+    "cascade": {
+      "description": "每次补充后重新检查是否有新的匹配，连续消除（连消）",
+      "enabled": true
+    }
+  },
+  "algorithm": {
+    "description": "主循环：swap → match → cascade → win/lose 检测",
+    "steps": [
+      "1. 玩家选择两个相邻格子 swap",
+      "2. 检测 swap 后是否产生 match（≥3 连）",
+      "3. 若无 match，回退 swap；steps 不消耗",
+      "4. 若有 match，消除匹配格子，计分，steps - 1",
+      "5. 触发 gravity（上方格子下坠）",
+      "6. 顶部 refill 新格子",
+      "7. 检测新格子是否产生 cascade match，若有则回到步骤 4",
+      "8. cascade 结束后检测胜败条件"
+    ]
+  },
+  "winCondition": {
+    "type": "score_goal",
+    "description": "在 moves 耗尽前达到目标分数（由 config 中 level.goalScore 定义）"
+  },
+  "loseCondition": {
+    "type": "moves_exhausted",
+    "description": "moves 归零且未达到胜利条件"
+  },
+  "testCases": [
+    {
+      "id": "tc_basic_match",
+      "description": "基础三消：水平三连消除",
+      "initialState": {
+        "board": "3×1 横排三个相同颜色的格子（例如 Red Red Red）",
+        "moves": 5
+      },
+      "action": { "type": "swap", "from": [3, 0], "to": [4, 0] },
+      "expectedState": {
+        "matchedCount": 3,
+        "scoreGained": 150,
+        "movesLeft": 4,
+        "boardRefilled": true
+      }
+    },
+    {
+      "id": "tc_invalid_swap",
+      "description": "无效交换：交换后无三连，步数不扣",
+      "initialState": {
+        "board": "交换后不形成三连的两个格子",
+        "moves": 5
+      },
+      "action": { "type": "swap", "from": [0, 0], "to": [1, 0] },
+      "expectedState": {
+        "matchedCount": 0,
+        "scoreGained": 0,
+        "movesLeft": 5,
+        "swapReverted": true
+      }
+    },
+    {
+      "id": "tc_cascade",
+      "description": "连消：消除后新格子产生新匹配",
+      "initialState": {
+        "board": "消除一组后，下落的格子正好形成新的三连",
+        "moves": 3
+      },
+      "action": { "type": "swap", "from": [2, 7], "to": [3, 7] },
+      "expectedState": {
+        "cascadeCount": { "min": 2 },
+        "scoreGained": { "min": 300 },
+        "movesLeft": 2
+      }
+    },
+    {
+      "id": "tc_win",
+      "description": "胜利：达到目标分数",
+      "initialState": {
+        "score": 950,
+        "goalScore": 1000,
+        "moves": 2
+      },
+      "action": { "type": "swap", "from": [0, 0], "to": [1, 0] },
+      "expectedState": {
+        "win": true,
+        "score": { "min": 1000 }
+      }
+    },
+    {
+      "id": "tc_lose",
+      "description": "失败：步数耗尽未达目标",
+      "initialState": {
+        "score": 500,
+        "goalScore": 1000,
+        "moves": 1
+      },
+      "action": { "type": "swap", "from": [0, 0], "to": [1, 0] },
+      "expectedState": {
+        "movesLeft": 0,
+        "win": false,
+        "gameOver": true
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,191 @@
+/**
+ * match3_core.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部跑完整个 cascade 循环后只返回最终状态，
+ * 中间过程（哪些格子被消除、哪些格子下落、新补充了什么）全部丢失。
+ *
+ * 渲染层需要分步动画（消除动画 → 下落动画 → 补充动画 → 检查连消），
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间插入 Tween 动画。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、快速跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type Match3Config = {
+  /** 棋盘列数，默认 8 */
+  cols: number;
+  /** 棋盘行数，默认 8 */
+  rows: number;
+  /** 元素颜色/类型数量，默认 6 */
+  colorCount: number;
+  /** 初始步数 */
+  initialMoves: number;
+  /** 目标分数（score_goal 模式） */
+  goalScore?: number;
+  /** 倒计时秒数（time_clear 模式） */
+  timeLimitSeconds?: number;
+  /** 每格消除基础得分 */
+  scorePerTile: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type Match3Action =
+  | { type: 'swap'; from: [col: number, row: number]; to: [col: number, row: number] }
+  | { type: 'tick'; deltaMs: number }  // 倒计时模式下每帧调用
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type TileColor = number;  // 0 ~ colorCount-1，null 表示空格
+
+export type Match3State = {
+  /** 棋盘格子，board[col][row] */
+  board: (TileColor | null)[][];
+  /** 当前得分 */
+  score: number;
+  /** 剩余步数 */
+  movesLeft: number;
+  /** 剩余时间（毫秒，倒计时模式） */
+  timeLeftMs?: number;
+  /** 游戏是否结束 */
+  gameOver: boolean;
+  /** 是否胜利 */
+  win: boolean;
+  /** 上一次 swap 是否因无效而回退 */
+  lastSwapReverted: boolean;
+  /** 上一次操作触发的连消次数 */
+  lastCascadeCount: number;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** 匹配结果 */
+export type MatchResult = {
+  /** 被匹配到的格子坐标列表 */
+  cells: Array<{ col: number; row: number }>;
+  /** 连续匹配的数量（3/4/5+） */
+  count: number;
+};
+
+/** 重力下落：某格子从 fromRow 下落到 toRow */
+export type FallMove = {
+  col: number;
+  fromRow: number;
+  toRow: number;
+};
+
+/** 新补充的棋子 */
+export type RefillTile = {
+  col: number;
+  row: number;
+  color: TileColor;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态，随机填满棋盘（确保初始无三连）
+ */
+export declare function init(config: Match3Config): Match3State;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - swap：交换两格，检测消除、计分、下落、补充、连消（一步到位）
+ * - tick：更新倒计时（time_clear 模式）
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: Match3State, action: Match3Action): Match3State;
+
+/**
+ * getState：返回当前状态快照（通常直接返回 state，供外部读取）
+ */
+export declare function getState(state: Match3State): Match3State;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * trySwap：仅验证交换是否有效，不执行后续 cascade。
+ * 返回交换后的棋盘副本和第一轮匹配结果。
+ *
+ * 场景层在 swap 动画播放完毕后调用此函数：
+ * - valid=false → 播放回退动画
+ * - valid=true → 继续调用 removeMatches → animateElimination → applyGravity → ...
+ */
+export declare function trySwap(
+  state: Match3State,
+  from: [col: number, row: number],
+  to: [col: number, row: number],
+): { valid: boolean; board: (TileColor | null)[][]; matches: MatchResult[] };
+
+/**
+ * findAllMatches：检测棋盘上所有 ≥3 连匹配
+ * 场景层在 refill 动画结束后调用，检查是否有连消
+ */
+export declare function findAllMatches(
+  board: (TileColor | null)[][],
+  cols: number,
+  rows: number,
+): MatchResult[];
+
+/**
+ * removeMatches：从棋盘移除匹配的格子（置为 null）
+ * 场景层在消除动画播放期间/之后调用，同步逻辑状态
+ */
+export declare function removeMatches(
+  board: (TileColor | null)[][],
+  matches: MatchResult[],
+): Set<string>;  // 返回被移除的格子 key "col,row"
+
+/**
+ * applyGravity：执行重力下落，返回每个移动的格子信息
+ * 场景层根据 FallMove[] 播放下落 Tween 动画
+ */
+export declare function applyGravity(
+  board: (TileColor | null)[][],
+  cols: number,
+  rows: number,
+): FallMove[];
+
+/**
+ * refillBoard：从顶部补充空位，返回新格子信息
+ * 场景层根据 RefillTile[] 创建新精灵并播放滑入动画
+ */
+export declare function refillBoard(
+  board: (TileColor | null)[][],
+  cols: number,
+  rows: number,
+  colorCount: number,
+): RefillTile[];
+
+/**
+ * calculateMatchScore：计算一轮匹配的得分
+ */
+export declare function calculateMatchScore(
+  matches: MatchResult[],
+  config: Match3Config,
+): number;
+
+/**
+ * hasValidMoves：检查棋盘是否还有可用的合法交换
+ * 若无可用移动则需要洗牌
+ */
+export declare function hasValidMoves(state: Match3State): boolean;