---
name: path_animation.aicomponent
description: 路径消除玩法的动画导演。负责消除成功的路径滑出动画、被阻挡时的抖动/闪光动画、以及胜利时的钻石粒子动画。
triggers: 需要为路径消除/阻挡/胜利事件添加视觉动画反馈时触发。
---

# 路径动画导演（Path Animation Director）

## 说明

`AnimationManager` 管理三类路径动画：

1. **消除滑出**（`animatePathOffBoard`）：路径成功消除后，沿 `direction` 方向用 Tween 动画将路径整体滑出棋盘边界，最后从棋盘移除
2. **阻挡震动**（`animateBlockedPath`）：路径被阻挡时，播放路径抖动 + 颜色闪红的反馈动画
3. **胜利钻石**（`playWinDiamondAnimation`）：所有路径消除后，播放全屏钻石粒子爆炸效果

## Scaffold

| 目标路径 | 来源 | 说明 |
|---------|-----|-----|
| `src/game/scenes/GameUI/AnimationManager.ts` | `ref/AnimationManager.ts` | 完整动画管理类 |

## Imports

- `phaser.aicomponent`（硬依赖：Phaser Tweens + GameObjects API）
- `path_renderer.aicomponent`（硬依赖：PathRenderer / PathTrackCell 类型）

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: src/game/scenes/GameUI/AnimationManager.ts
outputs:
  - animationManager: AnimationManager class (animatePathOffBoard / animateBlockedPath / playWinDiamondAnimation)
```

## Recipe

| 决策 | 原因 |
|------|------|
| **动画与游戏状态分离** | AnimationManager 通过回调（`onComplete`）通知游戏状态变更，不直接修改 `removedPaths` 等状态；状态变更时机由回调决定，动画完成后才生效 |
| **动画中锁定输入** | 路径滑出期间如允许新点击，可能导致状态不一致；`animatingPaths` Set 由 InputHandler 检查，AnimationManager 只管理动画本身 |
| **钻石粒子用 Graphics 实现** | 胜利粒子效果无需精灵资产，用 Graphics 随机绘制菱形；保持单一 skill 文件，零资产依赖 |

## Adapter

- **Role**: `pathAnimationDirector` — 路径消除/阻挡/胜利动画导演（Phaser Tweens 编排）
- **Provides**: `AnimationManager` 类（`animatePathOffBoard()`、`animateBlockedPath()`、`playWinDiamondAnimation()`、`resetBoardViewForWin()`）
- **Requires**: `phaser.aicomponent`（Tween + Graphics API）、`path_renderer.aicomponent`（PathRenderer / PathTrackCell 类型）
- **Consumed by**: `game_scene.aicomponent`（持有 AnimationManager，在消除/阻挡时调用对应方法）
- **Integration point**: `src/game/scenes/GameUI/AnimationManager.ts` → `Game.ts` 实例化并传给 InputHandler

## 关键接口

```typescript
class AnimationManager {
  // 路径成功消除的滑出动画
  animatePathOffBoard(
    pathIndex: number,
    dx: number, dy: number,       // 消除方向增量
    stepsToExit: number,          // 滑出步数
    isLastPath: boolean,          // 是否是最后一条路径
    onComplete: () => void,
  ): void;

  // 路径被阻挡的震动动画
  animateBlockedPath(
    pathIndex: number,
    dx: number, dy: number,
    stepsUntilBlock: number,
  ): void;

  // 全部路径消除后的钻石粒子动画
  playWinDiamondAnimation(): void;

  // 胜利前重置棋盘缩放和位置
  resetBoardViewForWin(): void;
}
```