---
name: playable_hud_layout.aicomponent
description: 可玩广告 HUD（顶/底预留区 + 棋盘可用矩形）框架无关布局规范。约束 Agent：在 responsive_2d_layout Layout Canon 下如何划分屏幕、导出高度常量、z-order；默认 Phaser 实现见 top_ui_bar / bottom_ui_bar。
triggers: 需要摆放顶部 HUD、底部条、计算棋盘可用区域，或统一 HUD 与棋盘的垂直扣减规则时触发。
---

# 可玩 HUD 屏幕分区（Playable HUD Layout）

本 skill **不包含**具体引擎代码，只定义 **框架无关** 的分区合同；缩放数学见 `responsive_2d_layout.aicomponent` **第一节 Layout Canon**。

---

## 规范（Layout Canon）

### 1. 纵向三层模型

在已应用安全区 inset 后的运行时矩形 \((W_r, H_r)\) 内，自下而上约定：

1. **底区（Bottom band）**：高度 \(H\_{\text{bottom}} = h\_{\text{bottom,dp}} \cdot \text{vScale}\)。`h_bottom,dp` 默认与 `GameConfig.GAME_BOTTOM_UI_BAR_HEIGHT`（如 110）一致，**单点配置**；可放置 CTA、品牌条或策略性留白。
2. **中间区（Play area）**：供棋盘 / 世界内容；高度  
   \(H\_{\text{mid}} = H_r - H\_{\text{top}} - H\_{\text{bottom}}\)。  
   **禁止** 在棋盘布局器内硬编码「整屏高度」而不扣顶底。
3. **顶区（Top band）**：高度 \(H\_{\text{top}} = h\_{\text{top,dp}} \cdot \text{vScale}\)。`h_top,dp` 由顶部 HUD skill 导出（如 `GAME_TOP_UI_BAR_HEIGHT`）。

### 2. 横向与尺寸

- 顶/底区 **背景与通栏控件** 宽度为 \(W_r\)。
- 顶区内子控件（命、计时、进度）的间距与字号遵循 Canon：**dp × uiScale**（或垂向间距用 **vScale** 与顶栏内部约定一致）。

### 3. z-order（渲染与交互）

约定自上而下（**数值更大者更靠前**）：

| 层级（概念） | 相对深度 | 说明 |
|-------------|---------|------|
| 棋盘 / 玩法世界 | 基准（如 0–200） | 主游玩内容 |
| 顶栏 / 底栏 HUD | 高于棋盘（如 500） | 始终可操作、不被棋盘遮挡 |
| 指引层 | 高于 HUD | 见 `playable_guidance_layer.aicomponent` |
| 全屏结算 | 最高 | 见 `playable_end_screen_layout.aicomponent` |

具体 depth 数值可由项目统一常量表定义，但 **相对顺序不得颠倒**。

### 4. Agent 义务

1. 棋盘可用高度必须使用 **\(H_{\text{mid}}\)** 或等价推导，与 `grid_board_layout` / 输入层的扣减一致。
2. 若仅实现顶栏而未装底栏组件，**仍须**在布局算式中保留 `h_bottom,dp`，除非项目显式改为 0。
3. 所有 `h_* ,dp` 常量须在单一配置或导出处维护，禁止魔法数分散在多个文件且互不引用。

---

## 与实现 skill 的对应关系

| 合同项 | Phaser 参考实现 |
|--------|----------------|
| 顶区 + `h_top,dp` | `top_ui_bar.aicomponent` → `GAME_TOP_UI_BAR_HEIGHT` |
| 底区 + `h_bottom,dp` | `bottom_ui_bar.aicomponent` → `GAME_BOTTOM_UI_BAR_HEIGHT`（与 `GameConfig` 对齐） |
| 中间区几何 | `grid_board_layout.aicomponent` |

---

## Recipe

| 决策 | 原因 |
|------|------|
| **框架无关规范** | 顶/中/底三层分区模型在 Phaser 和 Three.js 中都适用；若写入 phaser 相关 skill，Three.js 项目无法引用同一 HUD 约定 |
| **高度常量单点配置** | 顶/底栏高度（dp 值）必须在一处定义，棋盘布局和 UI 条同时引用；多处写死魔法数字是最常见的布局 bug 来源 |
| **z-order 约束明确** | 棋盘/HUD/指引/结算四层的相对顺序不得颠倒；显式文档约束比代码注释更易被 Agent 发现和遵从 |

## Adapter

- **Role**: `playableHudLayout` — 可玩 HUD 三层屏幕分区规范（顶/中/底 + z-order），无代码产出
- **Provides**: 纵向三层模型规范、高度常量命名约定（`GAME_TOP_UI_BAR_HEIGHT`、`GAME_BOTTOM_UI_BAR_HEIGHT`）、z-order 约束文档
- **Requires**: `responsive_2d_layout.aicomponent`（uiScale / vScale / W_r / H_r 定义）
- **Consumed by**: `top_ui_bar.aicomponent`、`bottom_ui_bar.aicomponent`（实现约定中的顶/底区）、`grid_board_layout.aicomponent`（棋盘高度扣减参考）、`playable_guidance_layer.aicomponent`（层级关系参考）
- **Integration point**: 无代码集成点；Agent 加载后按规范约束实现各 HUD 组件

## Imports

- `responsive_2d_layout.aicomponent`（**硬依赖**：uiScale / vScale / \(W_r,H_r\) 定义）

## Scaffold

本 skill **无** scaffold 文件；仅规范文档。落地代码见上表。

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - layout: HUD / play-area vertical contract from SKILL.md sections above
outputs:
  - hudBandHeights: design-dp constants and formulas using vScale
  - zOrderRules: relative ordering among board, HUD, guidance, end screen
```