---
name: tutorial_overlay.aicomponent
description: 新手引导浮层。在第一、二关展示步进式操作引导（高亮指定路径 + 手指动画），帮助玩家快速理解点击消除玩法。
triggers: 需要实现试玩广告的新手引导或操作提示浮层时触发。
---

# 新手引导浮层（Tutorial Overlay）

**指引层深度、遮罩/挖洞/手指缩放合同** 见 `playable_guidance_layer.aicomponent`；与顶栏关系见 `playable_hud_layout.aicomponent`。

## Scaffold

`src/game/scenes/GameUI/TutorialManager.ts`

## Recipe

| 决策 | 原因 |
|------|------|
| **仅在前 1-2 关激活** | 新手引导覆盖太多关卡会让熟悉玩法的用户烦躁；仅第一、二关引导，之后让玩家自由探索 |
| **高亮+手指组合** | 单独高亮目标路径告诉玩家"点哪里"，手指动画告诉玩家"怎么操作"；两者配合降低学习门槛 |
| **软槽位 tutorialPointer** | 不同 Remix 可以有不同风格的引导手指图（卡通、写实等）；软槽位允许资产替换 |

## Adapter

- **Role**: `tutorialOverlay` — 前 1-2 关步进式新手引导浮层（高亮路径 + 手指动画）
- **Provides**: `TutorialManager` 类（步进状态机，`startTutorial(level)`、`onPathEliminated(pathIndex)`）
- **Requires**: `phaser.aicomponent`、`tutorialPointer`（软槽位：引导手指图标）
- **Consumed by**: `game_scene.aicomponent`（在 `create()` 中实例化，前两关激活；InputHandler 的消除回调中调用 `onPathEliminated`）
- **Integration point**: `src/game/scenes/GameUI/TutorialManager.ts` → `Game.create()` 中条件初始化

## Imports

- `phaser.aicomponent`（硬依赖）
- `tutorialPointer`（软槽位：引导手指图标，可替换）

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: src/game/scenes/GameUI/TutorialManager.ts
outputs:
  - tutorialManager: TutorialManager class
```