---
name: playable_guidance_layer.aicomponent
description: 可玩广告指引层（新手引导、高亮、手指提示、轻提示）框架无关布局与交互规范。约束遮罩、挖洞、pointer 缩放与深度；步进教程见 tutorial_overlay。
triggers: 需要新手引导、无步进提示、高亮棋盘区域、手指动画，或统一指引层与 HUD/棋盘的遮挡关系时触发。
---

# 可玩指引层布局（Playable Guidance Layer）

本 skill 定义 **指引 / 教程 / 轻提示** 的框架无关合同；坐标系与 **uiScale / vScale** 见 `responsive_2d_layout.aicomponent` **第一节**。

---

## 规范（Layout Canon）

### 1. 层级

- 指引层 **高于** 棋盘与 Gameplay 世界内容。
- 指引层 **低于** 全屏结算层（`playable_end_screen_layout`）。若同时存在，应 **先结束教程** 或 **将 tutorial 收纳在结算容器内**（少见）。

与 `playable_hud_layout`：**默认** 顶栏不被教程遮罩遮挡（玩家仍能看到命/时间时可读）；若全屏 darken 教程，须 **整体提高 darken 的 depth** 但仍 **低于** 顶栏 depth，或 **同时** 在教程中复述关键 HUD 信息——二者选一应项目一致。

### 2. 视觉结构

1. **可选全屏半透层**：`alpha` 建议 0.35–0.6；颜色深色系以保证挖洞对比。
2. **挖洞（Spotlight）**：对准目标区域，洞缘可软边；洞区域须与 **实际可点热区** 对齐（考虑 uiScale 后的最小点击 44pt 等价）。
3. **Pointer（手指）**：素材见 `figer_icon.aiimage` 等；尺寸 **dp × uiScale**，摆动动画幅度亦按 uiScale 缩放，避免大屏夸张。

### 3. 类型区分

| 类型 | 行为 | 备注 |
|------|------|------|
| **步进教程** | 多步、阻塞直到点击目标 | `tutorial_overlay.aicomponent` |
| **单条轻提示** | Toast / 横幅、限时消失 | 同一 depth 合同，可不挖洞 |
| **僵局提示** | 如无可走步 | 可配合 `nomove_hint_overlay` 素材 |

### 4. Agent 义务

- 指引用字号、描边、间距：**dp × uiScale**；自屏幕边缘的位移：**vScale**。
- **禁止** 在指引层使用与全局不同的自创缩放比。
- 教程步进状态机与玩法偶合时，须在 skill 文档或代码注释中标明 **与关卡索引的触发条件**（如前 1–2 关）。

---

## 与实现 skill 的对应关系

| 合同项 | Phaser 参考 |
|--------|------------|
| 步进引导 | `tutorial_overlay.aicomponent` |
| 手指素材 | `figer_icon.aiimage`（软槽位） |

---

## Recipe

| 决策 | 原因 |
|------|------|
| **框架无关规范** | 指引层 z-order bug（手指在 HUD 后面、挖洞与实际点击热区错位）在 Phaser 和 Three.js 中都会出现；统一规范防止两个实现走向不同约定 |
| **指引层低于结算层** | 结算出现时通常已关闭教程；明确约定避免教程遮罩挡住胜利面板的 CTA 按钮 |
| **Spotlight 热区对齐要求** | 挖洞区域必须与实际可点击区域完全对齐；错位会让玩家点了"高亮区域"却没有响应，严重损害体验 |

## Adapter

- **Role**: `playableGuidanceLayout` — 指引/新手教程层深度与遮罩规范，无代码产出
- **Provides**: 指引层深度约定（高于棋盘/HUD，低于结算）、Spotlight 对齐要求、Pointer 缩放规范文档
- **Requires**: `responsive_2d_layout.aicomponent`、`playable_hud_layout.aicomponent`（层级关系参考）
- **Consumed by**: `tutorial_overlay.aicomponent`（按此规范设置 TutorialManager 的 depth 和挖洞逻辑）
- **Integration point**: 无代码集成点；Agent 加载后按规范实现 TutorialManager 的视觉层级

## Imports

- `responsive_2d_layout.aicomponent`（硬依赖）
- 建议加载 `playable_hud_layout.aicomponent` 以统一 depth 合同

## Scaffold

无 scaffold。

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - layout: guidance layer depth, dimmer, spotlight, pointer scaling rules
outputs:
  - guidanceZOrder: relative to board, HUD, end screen
  - pointerAndMarginRules: dp * uiScale; edge offsets with vScale
```