---
name: top_ui_bar.aicomponent
description: 顶部 UI 条容器骨架。在屏幕顶部显示生命值指示器、倒计时和进度条等子组件，导出 GAME_TOP_UI_BAR_HEIGHT 供棋盘布局计算使用。
triggers: 需要实现游戏顶部 HUD 布局容器时触发。
---

# 顶部 UI 条（Top UI Bar）

**屏幕分区与顶/底/棋盘 z-order** 见 `playable_hud_layout.aicomponent`（框架无关）；缩放数学见 `responsive_2d_layout.aicomponent` 第一节。

## Scaffold

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

## Recipe

| 决策 | 原因 |
|------|------|
| **导出高度常量给棋盘使用** | `GAME_TOP_UI_BAR_HEIGHT` 是顶部 UI 高度与棋盘布局之间的关键桥接；显式常量确保两者使用同一数值，不依赖运行时测量 |
| **容器 vs 散布组件** | 将 HeartDisplay、CountdownDisplay、ProgressDisplay 统一放入 TopUI 容器管理，简化 GameScene 的 create() 逻辑 |
| **遵从 HUD Layout 合同** | 顶栏高度与棋盘可用区域扣减通过 `playable_hud_layout.aicomponent` 约定，TopUI 不自行计算可用高度 |

## Adapter

- **Role**: `topUiBar` — 顶部 HUD 区域容器（生命值 + 倒计时 + 进度条）及高度常量提供者
- **Provides**: `GameTopUI` 类、`GAME_TOP_UI_BAR_HEIGHT` 常量（供棋盘布局扣减使用）
- **Requires**: `phaser.aicomponent`、`responsive_2d_layout.aicomponent`（屏幕缩放参数）
- **Consumed by**: `game_scene.aicomponent`（实例化 TopUI）、`grid_board_layout.aicomponent`（`topUIHeight` 参数中引用 `GAME_TOP_UI_BAR_HEIGHT`）
- **Integration point**: `src/game/scenes/GameUI/GameTopUI.ts` → `Game.create()` 中实例化并传入 `GAME_TOP_UI_BAR_HEIGHT` 到 `computeBoardLayout()`

## Imports

- `phaser.aicomponent` / `responsive_2d_layout.aicomponent`（硬依赖）

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: src/game/scenes/GameUI/GameTopUI.ts
outputs:
  - gameTopUI: GameTopUI class + GAME_TOP_UI_BAR_HEIGHT constant
```