@playcraft/skills 0.0.2

package/skills/slide_out_to_tray_animation.aicomponent/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: slide_out_to_tray_animation.aicomponent
+description: 两阶段路径消除动画。阶段1：整条路径（多格精灵容器）沿方向匀速滑出棋盘边界。阶段2：head 精灵贝塞尔曲线飞入篮子目标槽位并缩放。用于箭头推出+篮子收集类玩法。
+triggers: 需要路径滑出动画、飞入篮子动画、两阶段消除动画时触发。
+---
+
+# 滑出棋盘+飞入篮子动画（Slide-Out to Tray Animation）
+
+## 说明
+
+专为"路径推出 → 收集到篮子"设计的两阶段动画：
+
+1. **阶段1 - 滑出**：创建临时容器包含路径所有精灵，Tween 沿方向滑出
+2. **阶段2 - 飞入**：保留 head 精灵，贝塞尔抛物线飞入篮子槽位，同时缩放+旋转回正
+
+## Scaffold
+
+| 目标路径 | 来源 | 说明 |
+|---------|-----|------|
+| `src/game/ui/AnimationManager.ts` | `ref/AnimationManager.ts` | 动画管理器 |
+
+## 关键接口
+
+```typescript
+class AnimationManager {
+  slideOutAndFlyToTray(
+    path: LevelPath,
+    stepsToExit: number,
+    boardRenderer: BoardRenderer,
+    trayRenderer: TrayRenderer,
+    trayInsertIndex: number,
+    onSlideComplete: () => void,
+    onFlyComplete: () => void,
+  ): void;
+
+  bounceIn(sprite: Phaser.GameObjects.Image): void;
+  playWinAnimation(): void;
+}
+```
+
+## Recipe
+
+| 决策 | 原因 |
+|------|------|
+| **两阶段分离** | 滑出（路径整体移动）和飞入（单个头部精灵曲线运动）是不同物理行为，分阶段更易调参，且两段可分别中断 |
+| **贝塞尔弧线** | 线性飞行感觉机械；抛物线弧度模拟真实抛体，视觉上更有"弹性"和"收集"感 |
+| **回调驱动完成信号** | `onSlideComplete` / `onFlyComplete` 让 GameScene 精确控制游戏状态更新时机（不在动画开始时更新，而在动画完成后更新）|
+
+## Adapter
+
+- **Role**: `slideOutToTrayAnimation` — 路径滑出棋盘+飞入篮子两阶段动画
+- **Provides**: `AnimationManager` 类（`slideOutAndFlyToTray()`、`bounceIn()`、`playWinAnimation()`）
+- **Requires**: `phaser.aicomponent`、`tray_container.aicomponent`（TrayRenderer 槽位坐标），与 `grid_board_layout.aicomponent` 间接依赖（通过 BoardRenderer）
+- **Consumed by**: `game_scene.aicomponent`（路径成功消除后调用 `slideOutAndFlyToTray()`）
+- **Integration point**: `src/game/ui/AnimationManager.ts` → `Game.ts` 在路径消除成功时触发
+
+## 可配参数
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| slideDuration | 350ms | 滑出阶段时长 |
+| flyDuration | 400ms | 飞入阶段时长 |
+| arcHeight | 60px | 贝塞尔曲线上拱高度 |
+| ease | "Power2" | 缓动函数 |

package/skills/slide_out_to_tray_animation.aicomponent/manifest.json

@@ -0,0 +1,58 @@
+{
+  "schemaVersion": 1,
+  "atomId": "slide_out_to_tray_animation.aicomponent",
+  "bundleType": "aicomponent",
+  "category": "animation",
+  "mode": "fixed",
+  "label": {
+    "zh": "滑出棋盘+飞入篮子两阶段动画",
+    "en": "Slide-out + fly-to-tray two-phase animation"
+  },
+  "tags": ["animation", "slide-out", "fly", "tray", "bezier", "tween", "path", "arrow", "threejs", "3d"],
+  "bindingRoles": ["slideOutToTrayAnimation"],
+  "engineVariants": {
+    "phaser": {
+      "imports": ["phaser.aicomponent", "tray_container.aicomponent", "grid_board_layout.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/ui/AnimationManager.ts": { "source": "ref/AnimationManager.ts", "mode": "full", "weight": 10 }
+      }
+    },
+    "threejs": {
+      "imports": ["threejs.aicomponent", "tray_container.aicomponent", "grid_board_layout.aicomponent"],
+      "scaffoldFiles": {
+        "src/game/ui/AnimationManager3D.ts": { "source": "ref/AnimationManager3D.ts", "mode": "full", "weight": 10 },
+        "src/game/utils/BezierUtils.ts": { "source": "ref/BezierUtils.ts", "mode": "full", "weight": 10 }
+      }
+    }
+  },
+  "imports": [
+    { "slot": "engine",      "pinAtomId": "phaser.aicomponent",             "edgeKind": "requires", "bindAs": "engine" },
+    { "slot": "tray",        "pinAtomId": "tray_container.aicomponent",     "edgeKind": "requires", "bindAs": "tray" },
+    { "slot": "boardLayout", "pinAtomId": "grid_board_layout.aicomponent",  "edgeKind": "requires", "bindAs": "boardLayout" }
+  ],
+  "binding": {
+    "role": "slideOutToTrayAnimation",
+    "target": "src/game/ui/AnimationManager.ts",
+    "type": "code-module-reference"
+  },
+  "exports": [
+    { "name": "AnimationManager", "kind": "class", "location": "src/game/ui/AnimationManager.ts" },
+    { "name": "AnimationManager3D", "kind": "class", "location": "src/game/ui/AnimationManager3D.ts" },
+    { "name": "BezierUtils", "kind": "module", "location": "src/game/utils/BezierUtils.ts" }
+  ],
+  "neutralDescriptor": {
+    "geometry": "two-phase animation: slide path along direction until off-board, then fly head entity along bezier curve to tray target position",
+    "layers": ["animation-sequencing", "bezier-interpolation", "easing"],
+    "replaceable": ["slide duration", "fly duration", "arc height", "easing function"]
+  },
+  "usageHints": [
+    "两阶段动画：阶段1 整条路径沿方向滑出棋盘，阶段2 head 实体沿贝塞尔曲线飞入篮子",
+    "AnimationManager3D 需要每帧调用 update(dt) 驱动动画",
+    "3D 模式飞入弧线天然有 Y 轴高度（抛物线），视觉效果比 2D 更自然",
+    "BezierUtils.ts 提供纯数学贝塞尔插值，两端引擎实现均可复用"
+  ],
+  "files": {
+    "skill": "SKILL.md",
+    "ref": ["ref/AnimationManager.ts", "ref/AnimationManager3D.ts", "ref/BezierUtils.ts"]
+  }
+}

package/skills/slide_out_to_tray_animation.aicomponent/ref/AnimationManager.ts

@@ -0,0 +1,164 @@
+import * as Phaser from "phaser";
+import type { LevelPath } from "../logic/types";
+import { colorToTextureKey, directionToAngle, directionToDelta } from "../logic/types";
+import { GameConfig } from "../GameConfig";
+import { BoardRenderer } from "./BoardRenderer";
+import { TrayRenderer } from "./TrayRenderer";
+
+/**
+ * 动画管理器
+ * 整条路径滑出棋盘 → head 车飞入篮子 → 消除 → 抖动
+ */
+export class AnimationManager {
+  private scene: Phaser.Scene;
+
+  constructor(scene: Phaser.Scene) {
+    this.scene = scene;
+  }
+
+  /**
+   * 整条路径沿方向滑出棋盘，然后 head 飞入篮子
+   */
+  slideOutAndFlyToTray(
+    path: LevelPath,
+    stepsToExit: number,
+    boardRenderer: BoardRenderer,
+    trayRenderer: TrayRenderer,
+    trayInsertIndex: number,
+    onSlideComplete: () => void,
+    onFlyComplete: () => void,
+  ): void {
+    const { dx, dy } = directionToDelta(path.direction);
+    const cellSize = boardRenderer.cellSize;
+    const slideDistance = (stepsToExit + path.points.length) * cellSize;
+
+    // 创建一个容器来装整条路径的所有汽车
+    const slideContainer = this.scene.add.container(0, 0);
+    slideContainer.setDepth(1000);
+
+    const textureKey = colorToTextureKey(path.color);
+    const carSize = cellSize * GameConfig.CAR_CELL_RATIO;
+
+    // 为路径的每个点创建一辆车
+    const carSprites: Phaser.GameObjects.Image[] = [];
+    for (let ptIdx = 0; ptIdx < path.points.length; ptIdx++) {
+      const pt = path.points[ptIdx];
+      const worldPos = boardRenderer.getCellWorldPos(pt.y, pt.x);
+
+      const car = this.scene.add.image(worldPos.x, worldPos.y, textureKey);
+      car.setOrigin(0.5);
+
+      // 所有车统一朝向路径推出方向
+      car.setRotation(directionToAngle(path.direction));
+
+      const scale = Math.min(carSize / car.width, carSize / car.height);
+      car.setScale(scale);
+      slideContainer.add(car);
+      carSprites.push(car);
+    }
+
+    // 阶段 1：整条路径沿方向滑出
+    this.scene.tweens.add({
+      targets: slideContainer,
+      x: dx * slideDistance,
+      y: dy * slideDistance,
+      duration: 350,
+      ease: "Power2",
+      onComplete: () => {
+        // 销毁 body 车，保留 head 车做飞入动画
+        const headCar = carSprites[carSprites.length - 1];
+        for (let i = 0; i < carSprites.length - 1; i++) {
+          carSprites[i].destroy();
+        }
+        slideContainer.remove(headCar);
+        slideContainer.destroy();
+
+        // head 车的当前世界位置
+        const currentX = headCar.x + dx * slideDistance;
+        const currentY = headCar.y + dy * slideDistance;
+        headCar.setPosition(currentX, currentY);
+
+        onSlideComplete();
+
+        // 阶段 2：head 车飞入篮子
+        const toPos = trayRenderer.getSlotWorldPos(trayInsertIndex);
+        const midX = (currentX + toPos.x) / 2;
+        const midY = Math.min(currentY, toPos.y) - 60;
+
+        const traySize = Math.min(cellSize * 0.5, GameConfig.CAR_TRAY_SIZE);
+        const endScale = Math.min(traySize / headCar.width, traySize / headCar.height);
+        const startX = currentX;
+        const startY = currentY;
+        const startScale = headCar.scaleX;
+
+        this.scene.tweens.add({
+          targets: { t: 0 },
+          t: 1,
+          duration: GameConfig.FLY_DURATION,
+          ease: "Power2",
+          onUpdate: (_tween: Phaser.Tweens.Tween, target: { t: number }) => {
+            const t = target.t;
+            const px = (1 - t) * (1 - t) * startX + 2 * (1 - t) * t * midX + t * t * toPos.x;
+            const py = (1 - t) * (1 - t) * startY + 2 * (1 - t) * t * midY + t * t * toPos.y;
+            headCar.setPosition(px, py);
+            headCar.setScale(startScale + (endScale - startScale) * t);
+            headCar.setRotation(headCar.rotation * (1 - t * 0.5));
+          },
+          onComplete: () => {
+            headCar.destroy();
+            onFlyComplete();
+          },
+        });
+      },
+    });
+  }
+
+  /**
+   * 物品入场弹跳动画
+   */
+  bounceIn(sprite: Phaser.GameObjects.Image): void {
+    const targetScale = sprite.scaleX;
+    sprite.setScale(0);
+    this.scene.tweens.add({
+      targets: sprite,
+      scaleX: targetScale,
+      scaleY: targetScale,
+      duration: 200,
+      ease: "Back.easeOut",
+    });
+  }
+
+  /**
+   * 胜利粒子动画
+   */
+  playWinAnimation(): void {
+    const { width, height } = this.scene.scale;
+    const particles = 25;
+
+    for (let i = 0; i < particles; i++) {
+      const x = Phaser.Math.Between(Math.round(width * 0.1), Math.round(width * 0.9));
+      const y = Phaser.Math.Between(Math.round(height * 0.2), Math.round(height * 0.7));
+      const size = Phaser.Math.Between(8, 20);
+      const color = Phaser.Math.Between(0x000000, 0xffffff);
+
+      const particle = this.scene.add.graphics();
+      particle.fillStyle(color, 1);
+      particle.fillCircle(0, 0, size);
+      particle.setPosition(x, y);
+      particle.setAlpha(0);
+      particle.setDepth(2000);
+
+      this.scene.tweens.add({
+        targets: particle,
+        alpha: 1,
+        y: y - Phaser.Math.Between(50, 150),
+        scaleX: 0,
+        scaleY: 0,
+        duration: Phaser.Math.Between(600, 1200),
+        delay: i * 50,
+        ease: "Power2",
+        onComplete: () => particle.destroy(),
+      });
+    }
+  }
+}

package/skills/slide_out_to_tray_animation.aicomponent/ref/AnimationManager3D.ts

@@ -0,0 +1,198 @@
+import * as THREE from "three";
+import { quadraticBezier3D, easeOutQuad, lerp, type Vec3 } from "./BezierUtils";
+
+export interface SlideOutConfig {
+  slideDuration?: number;  // 滑出时长 ms，默认 350
+  flyDuration?: number;    // 飞入时长 ms，默认 400
+  arcHeight?: number;      // 飞入弧线高度（世界单位），默认 2.0
+}
+
+interface ActiveAnimation {
+  type: "slide" | "fly";
+  elapsed: number;
+  duration: number;
+  // slide 专用
+  container?: THREE.Group;
+  slideDirection?: THREE.Vector3;
+  slideDistance?: number;
+  // fly 专用
+  mesh?: THREE.Mesh;
+  startPos?: Vec3;
+  controlPos?: Vec3;
+  endPos?: Vec3;
+  startScale?: number;
+  endScale?: number;
+  // 回调
+  onComplete: () => void;
+}
+
+/**
+ * Three.js 3D 滑出+飞入两阶段动画管理器
+ *
+ * 阶段1：整条路径（Group）沿方向滑出棋盘
+ * 阶段2：Head 模型沿 3D 贝塞尔曲线飞入篮子位置（带 Y 轴弧线）
+ */
+export class AnimationManager3D {
+  private scene: THREE.Scene;
+  private config: Required<SlideOutConfig>;
+  private activeAnimations: ActiveAnimation[] = [];
+
+  constructor(scene: THREE.Scene, config?: SlideOutConfig) {
+    this.scene = scene;
+    this.config = {
+      slideDuration: config?.slideDuration ?? 350,
+      flyDuration: config?.flyDuration ?? 400,
+      arcHeight: config?.arcHeight ?? 2.0,
+    };
+  }
+
+  /**
+   * 执行完整的滑出+飞入动画
+   * @param pathMeshes 路径上所有 cell 的 Mesh 数组
+   * @param direction 滑出方向 { dx, dz }
+   * @param stepsToExit 到边界的格子数
+   * @param cellSize 格子大小
+   * @param targetPos 篮子目标位置（世界坐标）
+   * @param onSlideComplete 滑出完成回调
+   * @param onFlyComplete 飞入完成回调
+   */
+  slideOutAndFlyToTray(
+    pathMeshes: THREE.Mesh[],
+    direction: { dx: number; dz: number },
+    stepsToExit: number,
+    cellSize: number,
+    targetPos: THREE.Vector3,
+    onSlideComplete: () => void,
+    onFlyComplete: () => void,
+  ): void {
+    if (pathMeshes.length === 0) {
+      onSlideComplete();
+      onFlyComplete();
+      return;
+    }
+
+    // 阶段1：创建容器，所有 mesh 放入其中统一移动
+    const container = new THREE.Group();
+    const meshPositions: THREE.Vector3[] = [];
+
+    for (const mesh of pathMeshes) {
+      meshPositions.push(mesh.position.clone());
+      container.add(mesh);
+      // mesh 在 container 内保持世界位置
+      mesh.position.copy(mesh.position);
+    }
+    this.scene.add(container);
+
+    const slideDistance = (stepsToExit + pathMeshes.length) * cellSize;
+    const slideDir = new THREE.Vector3(direction.dx, 0, direction.dz).normalize();
+
+    // 启动滑出动画
+    this.activeAnimations.push({
+      type: "slide",
+      elapsed: 0,
+      duration: this.config.slideDuration / 1000,
+      container,
+      slideDirection: slideDir,
+      slideDistance,
+      onComplete: () => {
+        // 滑出完成：取出 head mesh 做飞入，销毁其余
+        const headMesh = pathMeshes[pathMeshes.length - 1];
+        const headWorldPos = new THREE.Vector3();
+        headMesh.getWorldPosition(headWorldPos);
+
+        // 销毁 body meshes
+        for (let i = 0; i < pathMeshes.length - 1; i++) {
+          const m = pathMeshes[i];
+          m.geometry.dispose();
+          (m.material as THREE.Material).dispose();
+        }
+        container.remove(headMesh);
+        this.scene.remove(container);
+
+        // head 放回场景
+        headMesh.position.copy(headWorldPos);
+        this.scene.add(headMesh);
+
+        onSlideComplete();
+
+        // 阶段2：head 飞入篮子
+        const startPos: Vec3 = { x: headWorldPos.x, y: headWorldPos.y, z: headWorldPos.z };
+        const endPos: Vec3 = { x: targetPos.x, y: targetPos.y, z: targetPos.z };
+
+        // 控制点：中间位置 + Y 轴抬升
+        const controlPos: Vec3 = {
+          x: (startPos.x + endPos.x) / 2,
+          y: Math.max(startPos.y, endPos.y) + this.config.arcHeight,
+          z: (startPos.z + endPos.z) / 2,
+        };
+
+        this.activeAnimations.push({
+          type: "fly",
+          elapsed: 0,
+          duration: this.config.flyDuration / 1000,
+          mesh: headMesh,
+          startPos,
+          controlPos,
+          endPos,
+          startScale: headMesh.scale.x,
+          endScale: headMesh.scale.x * 0.5,
+          onComplete: () => {
+            this.scene.remove(headMesh);
+            headMesh.geometry.dispose();
+            (headMesh.material as THREE.Material).dispose();
+            onFlyComplete();
+          },
+        });
+      },
+    });
+  }
+
+  /**
+   * 每帧更新（驱动动画）
+   * @param dt 帧间隔（秒）
+   */
+  update(dt: number): void {
+    for (let i = this.activeAnimations.length - 1; i >= 0; i--) {
+      const anim = this.activeAnimations[i];
+      anim.elapsed += dt;
+      const t = Math.min(anim.elapsed / anim.duration, 1);
+      const eased = easeOutQuad(t);
+
+      if (anim.type === "slide" && anim.container && anim.slideDirection) {
+        // 滑出：容器沿方向平移
+        const dist = eased * anim.slideDistance!;
+        anim.container.position.copy(anim.slideDirection.clone().multiplyScalar(dist));
+      } else if (anim.type === "fly" && anim.mesh && anim.startPos && anim.controlPos && anim.endPos) {
+        // 飞入：贝塞尔曲线
+        const pos = quadraticBezier3D(anim.startPos, anim.controlPos, anim.endPos, eased);
+        anim.mesh.position.set(pos.x, pos.y, pos.z);
+
+        // 缩放插值
+        const scale = lerp(anim.startScale!, anim.endScale!, eased);
+        anim.mesh.scale.setScalar(scale);
+
+        // 旋转衰减
+        anim.mesh.rotation.y *= (1 - eased * 0.5);
+      }
+
+      if (t >= 1) {
+        anim.onComplete();
+        this.activeAnimations.splice(i, 1);
+      }
+    }
+  }
+
+  /**
+   * 是否有动画正在播放
+   */
+  isAnimating(): boolean {
+    return this.activeAnimations.length > 0;
+  }
+
+  /**
+   * 销毁
+   */
+  destroy(): void {
+    this.activeAnimations = [];
+  }
+}

package/skills/slide_out_to_tray_animation.aicomponent/ref/BezierUtils.ts

@@ -0,0 +1,59 @@
+/**
+ * 纯数学贝塞尔插值工具（引擎无关）
+ * 支持 2D 和 3D 贝塞尔曲线计算
+ */
+
+export interface Vec2 { x: number; y: number; }
+export interface Vec3 { x: number; y: number; z: number; }
+
+/**
+ * 二次贝塞尔曲线插值（2D）
+ * @param p0 起点
+ * @param p1 控制点
+ * @param p2 终点
+ * @param t 插值参数 [0, 1]
+ */
+export function quadraticBezier2D(p0: Vec2, p1: Vec2, p2: Vec2, t: number): Vec2 {
+  const mt = 1 - t;
+  return {
+    x: mt * mt * p0.x + 2 * mt * t * p1.x + t * t * p2.x,
+    y: mt * mt * p0.y + 2 * mt * t * p1.y + t * t * p2.y,
+  };
+}
+
+/**
+ * 二次贝塞尔曲线插值（3D）
+ * @param p0 起点
+ * @param p1 控制点
+ * @param p2 终点
+ * @param t 插值参数 [0, 1]
+ */
+export function quadraticBezier3D(p0: Vec3, p1: Vec3, p2: Vec3, t: number): Vec3 {
+  const mt = 1 - t;
+  return {
+    x: mt * mt * p0.x + 2 * mt * t * p1.x + t * t * p2.x,
+    y: mt * mt * p0.y + 2 * mt * t * p1.y + t * t * p2.y,
+    z: mt * mt * p0.z + 2 * mt * t * p1.z + t * t * p2.z,
+  };
+}
+
+/**
+ * 缓动函数：easeOutQuad
+ */
+export function easeOutQuad(t: number): number {
+  return 1 - (1 - t) * (1 - t);
+}
+
+/**
+ * 缓动函数：easeInOutQuad
+ */
+export function easeInOutQuad(t: number): number {
+  return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+}
+
+/**
+ * 线性插值
+ */
+export function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}

package/skills/slot_machine.aigameplay/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: slot_machine.aigameplay
+description: 老虎机转轮玩法封包 - 经典3轴转轮老虎机，支持连线中奖、Wild通配符和Scatter散布奖励
+triggers: 老虎机,slot,转轮,reel,spin,旋转,赌博,casino,中奖,win,连线,payline,wild,scatter,符号,symbol
+---
+
+# slot_machine.aigameplay
+
+老虎机转轮玩法封包。实现经典3轴（可扩展至5轴）转轮老虎机规则的 PGS JSON 和 reducer，玩家下注并旋转转轮，按连线规则判定中奖，支持 Wild 通配符和 Scatter 散布奖励。
+
+## Recipe
+
+- **玩法类型**：slot_machine（老虎机转轮）
+- **参考文件**：
+  - `ref/pgs-schema.json`：PGS (PlayCraft Gameplay Schema, 玩法定义规范) 规则骨架（entities、rules、algorithm、testCases）
+  - `ref/reducer.template.ts`：reducer 接口约束模板（`init` / `dispatch` / `getState` + 分步函数）
+- **核心规则**：
+  - `reelCount`: 3（默认3转轮，可配置为5）
+  - `symbolsPerReel`: 3（每轮显示3个符号，形成3行×3列展示区）
+  - `paylines`: 5条连线（水平3条 + 对角线2条）
+  - `wildSymbol`: WILD（通配符，可替代任意普通符号）
+  - `scatterSymbol`: SCATTER（散布，≥3个出现在任意位置触发奖励，不受连线限制）
+  - `scatterMinCount`: 3（触发散布奖励所需最少数量）
+  - `rngType`: uniform（均匀随机，可扩展为权重随机）
+- **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 变体**：
+  - 5轴老虎机：修改 `reelCount` 为5，增加更多连线
+  - 权重随机：将 `rngType` 改为 `weighted`，配置各符号出现概率
+  - 免费旋转：Scatter 触发 `freeSpins` 次数而非直接奖励
+
+## Result
+
+- **产物文件**：`reducer.ts`
+- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
+- **验证**：所有 testCases 必须通过
+
+## 渲染集成（⚠️ 场景层必读）
+
+### 设计原则：逻辑与动画分离
+
+reducer 提供两套接口：
+
+| 接口 | 适用场景 | 特点 |
+|------|---------|------|
+| `dispatch()` | 无头测试、AI 模拟、跳过动画 | 一步到位，只返回最终状态 |
+| 分步函数 | **渲染层/GameScene** | 逐步执行，返回中间过程数据 |
+
+### ⚠️ 转轮动画必须使用分步函数驱动
+
+正确做法是**分步驱动动画链**：
+
+```ts
+// ✅ 正确做法：逐步调用分步函数，每步之间插入动画
+// Step 1: 执行旋转（获取结果，但先不显示）
+const spinResult = spin(state);
+// spinResult.reels = [['A','A','A'], ['7','W','7'], ['S','S','K']]
+
+// Step 2: 依次停止各转轮动画（每个转轮延迟约500ms）
+for (let i = 0; i < reelCount; i++) {
+  await stopReelAnimation(i, spinResult.reels[i]);  // 转轮停止动画
+  await delay(500);
+}
+
+// Step 3: 计算连线和奖励
+const matches = evaluatePaylines(spinResult.reels, paylines, symbolDefs);
+const payout = calculatePayout(matches, state.currentBet);
+
+// Step 4: 高亮中奖连线
+if (matches.length > 0) {
+  await playWinAnimation(matches, payout);  // 高亮连线 + 金币动画
+}
+
+// Step 5: 检查 Scatter
+const scatterResult = checkScatter(spinResult.reels);
+if (scatterResult.triggered) {
+  await playScatterAnimation(scatterResult.count);  // Scatter 爆炸动画
+}
+```
+
+### 分步函数返回值与动画映射
+
+| 分步函数 | 返回值 | 场景层动画 |
+|---------|--------|-----------|
+| `spin()` | `SpinResult` | 各转轮滚动然后依次停止 |
+| `evaluatePaylines()` | `PaylineMatch[]` | 高亮中奖连线，显示连线路径 |
+| `calculatePayout()` | `number` | 金币飞入动画，余额增加特效 |
+| `checkScatter()` | `{ triggered, count, bonus }` | Scatter 标记高亮 + 散布奖励动画 |
+
+## Binding
+
+- **Binding Role**：`gameplayRule`
+- **挂载目标**：`game/gameplay/slot_machine/reducer.ts`
+- **引用类型**：`gameplay-module-reference`
+- **接口契约**：`init(config)` / `dispatch(state, action)` / `getState(state)` / `spin()` / `evaluatePaylines(result, paylines, symbols)` / `calculatePayout(matches, bet)` / `checkScatter(result)`
+
+## Skill Definition
+
+tools:
+  - bash
+  - write
+  - read
+prompt_extension: |
+  You are implementing a slot machine gameplay module following the PGS specification.
+  Write the PGS JSON with entities (reels, paylines, symbols with isWild/isScatter, bet, balance, spin_result),
+  rules (spin with RNG, evaluate_paylines, wild_substitution, scatter_bonus, payout_calculation),
+  algorithm, and testCases (at least 3: 3-match win, no match, scatter bonus trigger).
+  Implement reducer.ts with:
+    - init/dispatch/getState (一体化接口，用于测试)
+    - spin/evaluatePaylines/calculatePayout/checkScatter (分步函数，用于渲染层动画驱动)
+  Wild symbols substitute for any non-scatter symbol in payline evaluation.
+  Scatter bonus triggers when ≥3 scatter symbols appear anywhere (not payline-constrained).
+  Payout = bet × multiplier, where multiplier comes from symbol match table.
+  Run all testCases to verify logic before finalizing.
+  Apply the Binding to wire the reducer into the game's gameplay module path.