# Combat HUD Specification: The Tactical Interface

This document defines the UI overlay active during the `GAME_RUN` / `ACTIVE` phase. It communicates turn order, unit status, and available actions to the player.

## 1. Visual Description

**Layout:** A "Letterbox" style overlay that leaves the center of the screen clear for the 3D action.

### A. Top Bar (Turn & Status)

* **Turn Queue (Center-Left):** A horizontal list of circular portraits.

  * *Active Unit:* Larger, highlighted with a gold border on the far left.

  * *Next Units:* Smaller icons trailing to the right.

  * *Enemy Intent:* If an enemy is active, a small icon (Sword/Shield) indicates their planned action type.

* **Global Info (Top-Right):**

  * *Round Counter:* "Round 3"

  * *Threat Level:* "High" (Color coded).

### B. Bottom Bar (The Dashboard)

* **Unit Status (Bottom-Left):**

  * *Portrait:* Large 2D art of the active unit.

  * *Bars:* Health (Red), Action Points (Yellow), Charge (Blue).

  * *Buffs:* Small icons row above the bars.

* **Action Bar (Bottom-Center):**

  * A row of interactive buttons for Skills and Items.

  * *Hotkeys:* (1-5) displayed on the buttons.

  * *State:* Buttons go grey if AP is insufficient or Cooldown is active.

  * *Tooltip:* Hovering shows damage, range, and AP cost.

* **End Turn (Bottom-Right):**

  * A prominent button to manually end the turn early (saving AP or Charge).

### C. Floating Elements (World Space)

* **Damage Numbers:** Pop up over units when hit.

* **Health Bars:** Small bars hovering over every unit in the 3D scene (billboarded).

## 2. TypeScript Interfaces (Data Model)

```typescript
// src/types/CombatHUD.ts

export interface CombatState {
    /** The unit currently taking their turn */
    activeUnit: UnitStatus | null;
    
    /** Sorted list of units acting next */
    turnQueue: QueueEntry[];
    
    /** Is the player currently targeting a skill? */
    targetingMode: boolean;
    
    /** Global combat info */
    roundNumber: number;
}

export interface UnitStatus {
    id: string;
    name: string;
    portrait: string;
    hp: { current: number; max: number };
    ap: { current: number; max: number };
    charge: number; // 0-100
    statuses: StatusIcon[];
    skills: SkillButton[];
}

export interface QueueEntry {
    unitId: string;
    portrait: string;
    team: 'PLAYER' | 'ENEMY';
    /** 0-100 progress to next turn */
    initiative: number; 
}

export interface StatusIcon {
    id: string;
    icon: string; // URL or Emoji
    turnsRemaining: number;
    description: string;
}

export interface SkillButton {
    id: string;
    name: string;
    icon: string;
    costAP: number;
    cooldown: number; // 0 = Ready
    isAvailable: boolean; // True if affordable and ready
}

export interface CombatEvents {
    'skill-click': { skillId: string };
    'end-turn': void;
    'hover-skill': { skillId: string }; // For showing range grid
}