aether-shards/.cursor/rules/ui/CombatHUD/RULE.md

description	globs	alwaysApply
Combat HUD UI component - tactical interface overlay during combat phase	src/ui/components/CombatHUD.js, src/ui/components/CombatHUD.ts, src/types/CombatHUD.ts	false

Combat HUD Rule

The Combat HUD is 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)

// 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
}

3. Conditions of Acceptance (CoA)

CoA 1: Real-Time Updates

• The HUD must update immediately when turn changes (via event listener)
• Health bars must reflect current HP after damage is dealt
• AP display must decrease when skills are used

CoA 2: Skill Availability

• Skills with insufficient AP must be visually disabled (greyed out)
• Skills on cooldown must show remaining turns
• Hovering a skill must highlight valid targets on the grid

CoA 3: Turn Queue Accuracy

• The queue must match the TurnSystem's predicted queue
• Enemy units in queue must show their team indicator

CoA 4: Event Communication

• Clicking a skill button must dispatch skill-click event
• Clicking "End Turn" must dispatch end-turn event
• The HUD must not directly call GameLoop methods (event-driven only)

4. Implementation Requirements

Create src/ui/components/CombatHUD.js as a LitElement:

1. Layout: Use CSS Grid/Flexbox for letterbox layout (top bar, bottom bar, clear center)
2. Data Binding: Subscribe to TurnSystem events (turn-start, turn-end) and GameLoop combat state
3. Turn Queue: Render circular portraits in a horizontal row, highlighting the active unit
4. Action Bar: Map unit's skills to buttons, showing AP cost and cooldown state
5. Event Handling: Dispatch custom events for skill clicks and end turn actions
6. Responsive: Support mobile (vertical stack) and desktop (horizontal layout)