---
name: debug_overlay.aicomponent
description: 开发调试覆盖层。在游戏画面上叠加可视化调试信息：格子坐标、碰撞区域、命中范围、方向向量、FPS、关卡切换控制。通过 DebugConfig 开关控制。
triggers: 调试,debug,overlay,格子坐标,碰撞可视化,FPS,开发工具,dev tools
---

# 开发调试覆盖层（Debug Overlay）

## 说明

在 Game 场景上叠加半透明调试信息层，帮助开发者快速定位问题：

- **格子坐标网格** — 每个格子中心显示 `(col,row)` 文字
- **碰撞区域高亮** — 被路径占据的格子用半透明色块标记
- **点击命中范围** — 显示每个箭头头部的点击判定圆形
- **方向向量** — 从箭头头部画出方向辅助线到棋盘边界
- **路径索引** — 每条路径显示 `#0` `#1` 编号
- **FPS / 内存** — 左上角实时帧率
- **关卡切换** — 底部 ← → 按钮快速切换关卡

## Scaffold

| 目标路径 | 来源 | 说明 |
|---------|-----|------|
| `src/game/scenes/GameUI/DebugOverlay.ts` | `ref/DebugOverlay.ts` | 完整调试覆盖层 |

## 开关控制

在 `DebugConfig.ts` 中添加：

```typescript
/** 是否显示调试覆盖层 */
export const SHOW_DEBUG_OVERLAY = true; // 发布前改为 false
```

在 `Game.ts` 的 `create()` 末尾：

```typescript
if (SHOW_DEBUG_OVERLAY) {
  new DebugOverlay(this);
}
```

## Recipe

| 决策 | 原因 |
|------|------|
| **独立组件，条件加载** | 调试渲染在发布版本中必须零开销；独立 class + 单一开关标志（`SHOW_DEBUG_OVERLAY`）保证发布时完整移除，不影响游戏逻辑 |
| **Graphics 叠加而非精灵** | 调试信息（坐标网格、碰撞区域）是动态内容，用 Phaser Graphics API 绘制无需额外资产文件 |
| **可视化命中范围** | 箭头头部的点击判定圆是最常见的调试需求（用户反馈"点不到"），优先可视化 |

## Adapter

- **Role**: `debugOverlay` — 开发期可视化调试层（生产构建中条件禁用）
- **Provides**: `DebugOverlay` 类（格子坐标、碰撞区域、FPS、关卡切换 UI）
- **Requires**: `phaser.aicomponent`、`grid_board_layout.aicomponent`（格子坐标计算）
- **Consumed by**: `game_scene.aicomponent`（在 `Game.create()` 末尾条件实例化）
- **Integration point**: `src/game/scenes/Game.ts` → `if (SHOW_DEBUG_OVERLAY) new DebugOverlay(this)`

## Imports

- `phaser.aicomponent`（硬依赖）
- `grid_board_layout.aicomponent`（硬依赖：格子坐标计算）

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: ref/DebugOverlay.ts
outputs:
  - debugOverlay: DebugOverlay class
```