---
name: level_lifecycle.aicomponent
description: 关卡生命周期控制器。管理生命值扣除、超时处理、胜利/失败判断、GameOverPanel 展示和自动进入下一关逻辑。
triggers: 需要实现关卡的生命值、胜败判定和关卡流转逻辑时触发。
---

# 关卡生命周期控制器（Level Lifecycle Controller）

## 说明

`LevelLifecycle` 是关卡生命周期的状态机，管理：

- **生命扣除**（`loseLife`）：减少 `currentLives`，命归零时延迟显示失败面板
- **危险闪光**（`playDangerFrame`）：命不足时播放全屏 `nomove_hint` 图片闪烁
- **胜利流程**（`handleLevelSuccess`）：播放胜利动画，延迟后进入下一关或显示胜利面板
- **超时流程**（`handleTimeOut`）：倒计时归零触发失败
- **自动进关**（可配置）：胜利后是否自动进入下一关

## Scaffold

| 目标路径 | 来源 | 说明 |
|---------|-----|-----|
| `src/game/scenes/GameUI/LevelLifecycle.ts` | `ref/LevelLifecycle.ts` | 完整生命周期管理类 |

## Imports

- `phaser.aicomponent`（硬依赖：Phaser.Scene API）
- `level_state.aicomponent`（硬依赖：LevelManager 进关逻辑）
- `game_over_panel.aicomponent`（软槽位：胜利/失败面板展示）

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: src/game/scenes/GameUI/LevelLifecycle.ts
outputs:
  - levelLifecycle: LevelLifecycle class + LevelLifecycleGameRef interface
```

## 关键接口

```typescript
interface LevelLifecycleGameRef extends Phaser.Scene {
  currentLives: number;
  maxLives: number;
  isInputLocked: boolean;
  removedPaths: Set<number>;
  // ... 其他场景引用
}

class LevelLifecycle {
  loseLife(): void;                // 扣命（由 InputHandler 调用）
  playDangerFrame(): void;         // 危险闪光（命少时调用）
  handleLevelSuccess(): void;      // 通关（由 InputHandler 调用）
  handleTimeOut(): void;           // 超时（由 CountdownDisplay 调用）
}
```

## Recipe

| 决策 | 原因 |
|------|------|
| **状态机从 GameScene 中提取** | 关卡生命周期（扣命→危险→胜利→失败）是有限状态机，逻辑复杂；提取为独立类后 Game.ts 不膨胀，状态转换逻辑集中可测试 |
| **LevelLifecycleGameRef 接口** | 与 InputHandler 相同的接口解耦模式；LevelLifecycle 通过接口读写 Game 状态，不直接引用 Game 类，防止循环依赖 |
| **软槽位 gameOverDialog** | 胜败面板的视觉风格在不同 Remix 变体中不同；软槽位允许不改 LevelLifecycle 代码的前提下替换面板实现 |
| **危险闪光帧独立** | `playDangerFrame` 是低血量时的全屏 nomove_hint 闪烁，与"扣命"是两个不同的视觉事件；分离调用让触发时机更精确 |

## Adapter

- **Role**: `levelLifecycle` — 关卡生命周期状态机（扣命/超时/胜利/失败全流程）
- **Provides**: `LevelLifecycle` 类（`loseLife()`、`handleLevelSuccess()`、`handleTimeOut()`、`playDangerFrame()`），`LevelLifecycleGameRef` 接口
- **Requires**: `phaser.aicomponent`、`level_state.aicomponent`（LevelManager `nextLevel()`）、`game_over_panel.aicomponent`（软槽位 `gameOverDialog`）
- **Consumed by**: `game_scene.aicomponent`（持有实例，传给 `path_input_handler` 的 `attemptMovePath` 回调）
- **Integration point**: `src/game/scenes/GameUI/LevelLifecycle.ts` → `Game.create()` 中实例化并持有

## 软槽位说明

`gameOverDialog` 槽位使用 `matchBindingRoles: ["gameOverDialog"]`，允许替换为不同视觉风格的游戏结束面板。