141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
---
|
|
description: Combat HUD UI component - tactical interface overlay during combat phase
|
|
globs: src/ui/components/CombatHUD.js, src/ui/components/CombatHUD.ts, src/types/CombatHUD.ts
|
|
alwaysApply: 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)**
|
|
|
|
```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
|
|
}
|
|
```
|
|
|
|
## **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)
|
|
|
|
|