@playcraft/skills 0.0.2

package/skills/left_right_parkour.aigameplay/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: left_right_parkour.aigameplay
+description: 左右选择跑酷玩法封包 - 角色自动向前跑，玩家在门板节点选左或右，影响属性变化，以最高分到达终点
+triggers: 跑酷,parkour,runner,跑步,run,左右,left,right,选择,choose,door,门板,gate,得分,score,生命,lives,属性,stat
+---
+
+# left_right_parkour.aigameplay
+
+左右选择跑酷玩法封包。实现门板二选一跑酷规则的 PGS JSON 和 reducer，角色自动向前跑，玩家在每个门板节点选择左或右，不同选择带来不同属性变化（得分±、生命±、速度±），目标是以最高分和充足生命通过所有门板抵达终点。
+
+## Recipe
+
+- **玩法类型**：left_right_parkour（左右选择跑酷）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `gateCount`: 10（默认门板数量，由关卡配置覆盖）
+  - `initialLives`: 3（初始生命值）
+  - `initialScore`: 0（初始得分）
+  - `initialSpeed`: 1.0（初始速度倍率）
+  - `loseOnZeroLives`: true（生命归零则游戏结束）
+  - `winOnAllGatesPassed`: true（通过所有门板且生命 > 0 则胜利）
+  - 每个门板 gate 包含 left_option 和 right_option，各含 effect（score±、lives±、speed±、item）
+- **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 变体**：
+  - 三选一模式：将 gate 改为 `left/middle/right` 三个选项
+  - 连续效果门板：某些门板的效果会影响后续 N 个门板（buff/debuff）
+  - 无限模式：gateCount 为无限，按距离计分，直到生命耗尽
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 选择动画必须使用分步函数驱动
+
+正确做法是**分步驱动动画链**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+// Step 1: 玩家点击左/右门板，应用效果
+const effect = state.gates[state.currentGateIndex][direction + '_option'].effect;
+const afterChoice = applyGateChoice(state, state.currentGateIndex, direction);
+
+// Step 2: 播放选择穿越动画
+await playGatePassAnimation(direction, effect);
+// 若 effect.score > 0 → 飘金币+分数
+// 若 effect.lives < 0 → 扣血特效 + 红闪屏
+// 若 effect.speed > 0 → 速度提升粒子效果
+
+// Step 3: 前进到下一个门板
+const nextState = advanceToNextGate(afterChoice);
+
+// Step 4: 检测游戏结束
+if (checkGameOver(nextState)) {
+  const finalScore = calculateFinalScore(nextState);
+  showGameOverPanel(finalScore);
+} else if (nextState.currentGateIndex >= nextState.gates.length) {
+  // 所有门板通过 → 胜利
+  const finalScore = calculateFinalScore(nextState);
+  showWinPanel(finalScore);
+} else {
+  // 显示下一个门板
+  renderNextGate(nextState.gates[nextState.currentGateIndex]);
+}
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `applyGateChoice()` | `ParkourState` | 穿门特效 + 属性浮动文字（+100分、-1命等）|
+| `advanceToNextGate()` | `ParkourState` | 角色向前跑动画，推进门板 |
+| `checkGameOver()` | `boolean` | 游戏结束特效（生命耗尽闪烁）|
+| `calculateFinalScore()` | `number` | 最终分数结算动画 |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/left_right_parkour/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(state, action)` / `getState(state)` / `applyGateChoice(gateIndex, direction)` / `advanceToNextGate()` / `checkGameOver()` / `calculateFinalScore()`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a left-right choice parkour gameplay module following the PGS specification.
+  Write the PGS JSON with entities (runner with position/score/lives/speed, gates with
+  left_option/right_option containing effects, current_gate_index, game_state),
+  rules (choose_left/choose_right applying gate effects, advance, check_lives, check_finish),
+  algorithm, and testCases (at least 3: choose left to win, choose right to lose, accumulate score).
+  Implement reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - applyGateChoice/advanceToNextGate/checkGameOver/calculateFinalScore (分步函数，用于渲染层动画驱动)
+  Gate effects can modify: score (±), lives (±), speed (±), or grant items.
+  Game over when lives <= 0. Win when all gates passed with lives > 0.
+  Run all testCases to verify logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.

package/skills/left_right_parkour.aigameplay/manifest.json

@@ -0,0 +1,165 @@
+{
+  "schemaVersion": 1,
+  "atomId": "left_right_parkour.aigameplay",
+  "bundleType": "aigameplay",
+  "category": "gameplay",
+  "mode": "fixed",
+  "label": {
+    "zh": "左右选择跑酷玩法",
+    "en": "Left-Right Choice Parkour gameplay"
+  },
+  "tags": [
+    "gameplay",
+    "parkour",
+    "runner",
+    "choice",
+    "casual",
+    "action"
+  ],
+  "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": "levelDataPack",
+      "description": "关卡门板配置数据",
+      "bindAs": "levels",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "levelDataPack"
+      ],
+      "allowedBundleTypes": [
+        "aiconfig"
+      ]
+    },
+    {
+      "slot": "tutorial",
+      "description": "新手引导浮层",
+      "bindAs": "tutorial",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "tutorialOverlay"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    },
+    {
+      "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": "endScreen",
+      "description": "可玩广告结算屏（含 CTA 按钮）",
+      "bindAs": "endScreen",
+      "required": false,
+      "edgeKind": "compatibleWith",
+      "matchBindingRoles": [
+        "playableEndScreenLayout"
+      ],
+      "allowedBundleTypes": [
+        "aicomponent"
+      ]
+    }
+  ],
+  "generation": {
+    "kind": "pgs",
+    "pgsVersion": "1.0",
+    "gameplayType": "left_right_parkour",
+    "rules": {
+      "gateCount": 10,
+      "initialLives": 3,
+      "initialScore": 0,
+      "initialSpeed": 1.0,
+      "loseOnZeroLives": true,
+      "winOnAllGatesPassed": true
+    }
+  },
+  "result": {
+    "outputFile": "reducer.ts",
+    "format": "typescript",
+    "constraints": {
+      "testCasesMustPass": true
+    }
+  },
+  "binding": {
+    "role": "gameplayRule",
+    "target": "game/gameplay/left_right_parkour/reducer.ts",
+    "type": "gameplay-module-reference",
+    "constraints": {
+      "interface": [
+        "init(config)",
+        "dispatch(state, action)",
+        "getState(state)",
+        "applyGateChoice(state, gateIndex, direction)",
+        "advanceToNextGate(state)",
+        "checkGameOver(state)",
+        "calculateFinalScore(state)"
+      ]
+    }
+  },
+  "files": {
+    "skill": "SKILL.md",
+    "pgsSchema": "ref/pgs-schema.json",
+    "reducerTemplate": "ref/reducer.template.ts"
+  }
+}

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

@@ -0,0 +1,200 @@
+{
+  "_comment": "PGS (PlayCraft Gameplay Schema) 参考骨架 - 左右选择跑酷玩法。Agent 以此为起点编写或 fork 玩法规则。",
+  "version": "1.0",
+  "gameplayType": "left_right_parkour",
+  "entities": {
+    "runner": {
+      "type": "player-character",
+      "description": "跑酷角色，自动向前移动",
+      "fields": {
+        "position": "number，当前门板索引（已通过的门板数量）",
+        "score": "number，当前累计得分",
+        "lives": "number，当前剩余生命值（初始为 config.initialLives）",
+        "speed": "number，当前速度倍率（影响动画速度，初始为 config.initialSpeed）",
+        "items": "string[]，已收集的道具列表"
+      }
+    },
+    "gate": {
+      "type": "choice-node",
+      "description": "门板选择节点，包含左右两个选项",
+      "fields": {
+        "id": "number，门板索引",
+        "position": "number，在关卡中的位置",
+        "left_option": {
+          "label": "string，左门显示文字（如 '+100分'）",
+          "effect": {
+            "score": "number，得分变化（正/负）",
+            "lives": "number，生命值变化（正/负）",
+            "speed": "number，速度倍率变化（如 +0.1 表示提速）",
+            "item": "string | null，获得的道具（null=无）"
+          }
+        },
+        "right_option": {
+          "label": "string，右门显示文字（如 '-1命'）",
+          "effect": {
+            "score": "number，得分变化",
+            "lives": "number，生命值变化",
+            "speed": "number，速度倍率变化",
+            "item": "string | null，获得的道具"
+          }
+        }
+      }
+    },
+    "currentGateIndex": {
+      "type": "counter",
+      "initial": 0,
+      "description": "当前待通过的门板索引"
+    },
+    "gameState": {
+      "type": "enum",
+      "values": ["running", "game_over", "win"],
+      "initial": "running",
+      "description": "游戏总状态"
+    }
+  },
+  "rules": {
+    "choose_left": {
+      "description": "玩家选择左门，应用 left_option.effect",
+      "precondition": "gameState === 'running'",
+      "effect": [
+        "runner.score += gate.left_option.effect.score",
+        "runner.lives += gate.left_option.effect.lives",
+        "runner.speed += gate.left_option.effect.speed",
+        "若 gate.left_option.effect.item !== null，将道具加入 runner.items"
+      ]
+    },
+    "choose_right": {
+      "description": "玩家选择右门，应用 right_option.effect",
+      "precondition": "gameState === 'running'",
+      "effect": [
+        "runner.score += gate.right_option.effect.score",
+        "runner.lives += gate.right_option.effect.lives",
+        "runner.speed += gate.right_option.effect.speed",
+        "若 gate.right_option.effect.item !== null，将道具加入 runner.items"
+      ]
+    },
+    "advance": {
+      "description": "通过当前门板后，前进到下一个门板",
+      "effect": "currentGateIndex += 1；runner.position = currentGateIndex"
+    },
+    "check_lives": {
+      "description": "每次应用效果后检测生命值",
+      "condition": "runner.lives <= 0",
+      "result": "gameState = 'game_over'"
+    },
+    "check_finish": {
+      "description": "检测是否已通过所有门板",
+      "condition": "currentGateIndex >= gates.length",
+      "result": "gameState = 'win'"
+    }
+  },
+  "algorithm": {
+    "description": "主循环：跑向门板 → 玩家选择 → 应用效果 → 检测结束",
+    "steps": [
+      "1. 初始化关卡：加载 gates 配置，设置 runner 初始属性",
+      "2. 显示当前门板 gates[currentGateIndex] 的左右选项",
+      "3. 玩家点击左门或右门",
+      "4. 调用 applyGateChoice(state, currentGateIndex, direction) 应用效果",
+      "5. 检测 runner.lives <= 0 → gameState = 'game_over'",
+      "6. 若未结束，调用 advanceToNextGate(state)：currentGateIndex + 1",
+      "7. 检测 currentGateIndex >= gates.length → gameState = 'win'",
+      "8. 若游戏继续，回到步骤 2 显示下一个门板",
+      "9. 游戏结束时调用 calculateFinalScore(state) 计算最终分数（加成奖励）"
+    ]
+  },
+  "winCondition": {
+    "type": "reach_finish",
+    "description": "通过所有门板且 runner.lives > 0（currentGateIndex >= gates.length && lives > 0）"
+  },
+  "loseCondition": {
+    "type": "lives_depleted",
+    "description": "runner.lives <= 0"
+  },
+  "testCases": [
+    {
+      "id": "tc_choose_left_win",
+      "description": "全选左门通关：所有门板选左，均为正效果，成功到达终点",
+      "initialState": {
+        "runner": { "position": 0, "score": 0, "lives": 3, "speed": 1.0, "items": [] },
+        "gates": [
+          { "id": 0, "left_option": { "label": "+100分", "effect": { "score": 100, "lives": 0, "speed": 0, "item": null } }, "right_option": { "label": "-1命", "effect": { "score": 0, "lives": -1, "speed": 0, "item": null } } },
+          { "id": 1, "left_option": { "label": "+200分", "effect": { "score": 200, "lives": 0, "speed": 0, "item": null } }, "right_option": { "label": "-2命", "effect": { "score": 0, "lives": -2, "speed": 0, "item": null } } }
+        ],
+        "currentGateIndex": 0,
+        "gameState": "running"
+      },
+      "actions": [
+        { "type": "choose", "direction": "left" },
+        { "type": "choose", "direction": "left" }
+      ],
+      "expectedState": {
+        "runner": { "score": 300, "lives": 3 },
+        "currentGateIndex": 2,
+        "gameState": "win"
+      }
+    },
+    {
+      "id": "tc_choose_right_lose",
+      "description": "选右门失败：选择扣命门板导致生命归零，游戏结束",
+      "initialState": {
+        "runner": { "position": 0, "score": 0, "lives": 1, "speed": 1.0, "items": [] },
+        "gates": [
+          { "id": 0, "left_option": { "label": "+50分", "effect": { "score": 50, "lives": 0, "speed": 0, "item": null } }, "right_option": { "label": "陷阱！-3命", "effect": { "score": 0, "lives": -3, "speed": 0, "item": null } } }
+        ],
+        "currentGateIndex": 0,
+        "gameState": "running"
+      },
+      "actions": [
+        { "type": "choose", "direction": "right" }
+      ],
+      "expectedState": {
+        "runner": { "score": 0, "lives": -2 },
+        "gameState": "game_over"
+      }
+    },
+    {
+      "id": "tc_accumulate_score",
+      "description": "累计得分：多个门板混合选择，验证分数正确累加",
+      "initialState": {
+        "runner": { "position": 0, "score": 0, "lives": 3, "speed": 1.0, "items": [] },
+        "gates": [
+          { "id": 0, "left_option": { "label": "+100分", "effect": { "score": 100, "lives": 0, "speed": 0, "item": null } }, "right_option": { "label": "+50分 +速度", "effect": { "score": 50, "lives": 0, "speed": 0.2, "item": null } } },
+          { "id": 1, "left_option": { "label": "+150分 -1命", "effect": { "score": 150, "lives": -1, "speed": 0, "item": null } }, "right_option": { "label": "+80分", "effect": { "score": 80, "lives": 0, "speed": 0, "item": null } } },
+          { "id": 2, "left_option": { "label": "道具", "effect": { "score": 0, "lives": 0, "speed": 0, "item": "shield" } }, "right_option": { "label": "+200分", "effect": { "score": 200, "lives": 0, "speed": 0, "item": null } } }
+        ],
+        "currentGateIndex": 0,
+        "gameState": "running"
+      },
+      "actions": [
+        { "type": "choose", "direction": "left" },
+        { "type": "choose", "direction": "left" },
+        { "type": "choose", "direction": "right" }
+      ],
+      "expectedState": {
+        "runner": { "score": 450, "lives": 2, "speed": 1.0, "items": [] },
+        "currentGateIndex": 3,
+        "gameState": "win",
+        "note": "score=100+150+200=450, lives=3-1=2, 第3关选右得200分"
+      }
+    },
+    {
+      "id": "tc_speed_and_item",
+      "description": "速度与道具效果：选择含速度加成和道具的门板，验证属性正确更新",
+      "initialState": {
+        "runner": { "position": 0, "score": 0, "lives": 3, "speed": 1.0, "items": [] },
+        "gates": [
+          { "id": 0, "left_option": { "label": "磁铁道具+速度", "effect": { "score": 0, "lives": 0, "speed": 0.5, "item": "magnet" } }, "right_option": { "label": "+100分", "effect": { "score": 100, "lives": 0, "speed": 0, "item": null } } }
+        ],
+        "currentGateIndex": 0,
+        "gameState": "running"
+      },
+      "actions": [
+        { "type": "choose", "direction": "left" }
+      ],
+      "expectedState": {
+        "runner": { "speed": 1.5, "items": ["magnet"] },
+        "gameState": "win"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,194 @@
+/**
+ * left_right_parkour.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部执行完整的选择+效果应用+状态检测后只返回最终状态，
+ * 中间过程（门板穿越动画、属性浮动文字、生命值变化特效）全部丢失。
+ *
+ * 渲染层需要在每个步骤间播放相应动画，因此必须使用下方「分步函数」。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、关卡预演分析。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type GateEffect = {
+  /** 得分变化（正=加分，负=扣分） */
+  score: number;
+  /** 生命值变化（正=加命，负=扣命） */
+  lives: number;
+  /** 速度倍率变化（正=提速，负=减速，如 +0.1） */
+  speed: number;
+  /** 获得的道具（null 表示无道具） */
+  item: string | null;
+};
+
+export type GateOption = {
+  /** 门板显示文字（如 '+100分'、'-1命'） */
+  label: string;
+  /** 选择此选项的效果 */
+  effect: GateEffect;
+};
+
+export type Gate = {
+  /** 门板唯一索引 */
+  id: number;
+  /** 左门选项 */
+  left_option: GateOption;
+  /** 右门选项 */
+  right_option: GateOption;
+};
+
+export type ParkourConfig = {
+  /** 关卡中的门板列表（按顺序排列） */
+  gates: Gate[];
+  /** 初始生命值，默认 3 */
+  initialLives: number;
+  /** 初始得分，默认 0 */
+  initialScore: number;
+  /** 初始速度倍率，默认 1.0 */
+  initialSpeed: number;
+  /** 胜利时的分数加成（可选，如距离奖励） */
+  finishBonusScore?: number;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type ParkourAction =
+  | { type: 'choose'; direction: 'left' | 'right' }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type Runner = {
+  /** 已通过的门板数量（当前所在位置） */
+  position: number;
+  /** 当前累计得分 */
+  score: number;
+  /** 当前剩余生命值 */
+  lives: number;
+  /** 当前速度倍率 */
+  speed: number;
+  /** 已收集的道具列表 */
+  items: string[];
+};
+
+export type GamePhase = 'running' | 'game_over' | 'win';
+
+export type ParkourState = {
+  /** 跑酷角色状态 */
+  runner: Runner;
+  /** 所有门板配置 */
+  gates: Gate[];
+  /** 当前待通过的门板索引 */
+  currentGateIndex: number;
+  /** 游戏阶段 */
+  gameState: GamePhase;
+  /** 最终得分（游戏结束后计算，运行中为 null） */
+  finalScore: number | null;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+/** applyGateChoice 返回值（含效果详情，供渲染层播放动画） */
+export type GateChoiceResult = {
+  /** 更新后的游戏状态 */
+  state: ParkourState;
+  /** 本次选择应用的效果 */
+  appliedEffect: GateEffect;
+  /** 选择方向 */
+  direction: 'left' | 'right';
+  /** 是否因此导致生命值归零（触发 game over 动画） */
+  causedGameOver: boolean;
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态
+ */
+export declare function init(config: ParkourConfig): ParkourState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ * - choose：选择当前门板的左/右选项，应用效果，检测生命值和完成条件
+ * - reset：重置到初始状态
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: ParkourState, action: ParkourAction): ParkourState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: ParkourState): ParkourState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * applyGateChoice：应用指定门板的选择效果，更新 runner 属性。
+ *
+ * 场景层在玩家点击左/右门板后调用：
+ * - 更新 runner.score / runner.lives / runner.speed / runner.items
+ * - 若 lives <= 0，设置 gameState = 'game_over'
+ * - 返回 GateChoiceResult 包含效果详情（供渲染层播放浮动文字动画）
+ *
+ * @param state       当前游戏状态（不可变）
+ * @param gateIndex   目标门板索引（通常为 currentGateIndex）
+ * @param direction   选择方向：'left' 或 'right'
+ * @returns           选择结果（含更新后状态和效果详情）
+ */
+export declare function applyGateChoice(
+  state: ParkourState,
+  gateIndex: number,
+  direction: 'left' | 'right',
+): GateChoiceResult;
+
+/**
+ * advanceToNextGate：前进到下一个门板。
+ *
+ * 场景层在门板穿越动画播放完毕后调用：
+ * - currentGateIndex + 1
+ * - runner.position 更新
+ * - 若 currentGateIndex >= gates.length，设置 gameState = 'win'
+ *
+ * @param state   当前游戏状态（不可变）
+ * @returns       更新后的游戏状态
+ */
+export declare function advanceToNextGate(state: ParkourState): ParkourState;
+
+/**
+ * checkGameOver：检测游戏是否已结束（生命归零）。
+ *
+ * 场景层在 applyGateChoice 动画播放完毕后调用，判断是否触发 Game Over 演出。
+ *
+ * @param state   当前游戏状态
+ * @returns       true 表示游戏已结束（lives <= 0）
+ */
+export declare function checkGameOver(state: ParkourState): boolean;
+
+/**
+ * calculateFinalScore：计算最终得分（含通关加成）。
+ *
+ * 场景层在胜利或游戏结束时调用，用于显示结算面板。
+ * 若 gameState === 'win'，在基础 score 上叠加 finishBonusScore。
+ * 若 gameState === 'game_over'，返回当前 score（无加成）。
+ *
+ * @param state   当前游戏状态（gameState 应为 'win' 或 'game_over'）
+ * @returns       最终分数
+ */
+export declare function calculateFinalScore(state: ParkourState): number;