planning_notes/npc/hostile/implementation/HEALTH_UI_VISUAL_GUIDE.md

# Health UI Display - What Changed

## Before ❌

```
Problem: Health UI not visible
- Emoji hearts (❤️ 💔 🖤)
- Inline CSS styles (position: fixed; z-index: 100)
- Z-index too low (100 < inventory's 1000)
- Never appears on screen
```

## After ✅

```
Solution: Health UI now displays properly
- PNG icon hearts (assets/icons/heart.png)
- Proper CSS file (css/health-ui.css)
- Z-index: 1100 (above inventory)
- Appears above inventory when damaged
```

## Visual Layout

```
┌──────────────────────────────────────────────────────────┐
│                                                          │
│           ❤️  ❤️  ❤️  ❤️  💔                            │
│         (Health UI - NEW z-index: 1100)                │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │                                                    │ │
│  │              [Game World]                         │ │
│  │         Player running around                     │ │
│  │                                                    │ │
│  │                                                    │[I] │
│  │                                                    │[n] │
│  │                                                    │[v] │
│  │                                                    │[e] │
│  └────────────────────────────────────────────────────┘ │
│         Inventory UI (z-index: 1000)          │
│                                               │
└──────────────────────────────────────────────┘
```

## Code Changes Summary

### Change 1: Image-Based Hearts

**Before:**
```javascript
const heart = document.createElement('div');
heart.textContent = '❤️';  // Emoji
```

**After:**
```javascript
const heart = document.createElement('img');
heart.src = 'assets/icons/heart.png';  // PNG icon
```

### Change 2: Proper CSS Styling

**Before:**
```javascript
this.container.style.cssText = `
  z-index: 100;  // TOO LOW
  display: none;
`;
```

**After:**
```css
#health-ui-container {
  z-index: 1100;  /* ABOVE inventory (z-index: 1000) */
  display: flex;
}
```

### Change 3: CSS File Created

**New file:** `css/health-ui.css`
```css
z-index: 1100;              /* Key fix */
pointer-events: none;       /* Don't block clicks */
background: rgba(0, 0, 0, 0.8);  /* Dark background */
border: 2px solid #333;     /* Pixel-art style */
image-rendering: pixelated; /* Crisp icons */
```

## Heart Display Examples

### Full Health (Hidden)
```
Status: No damage taken
Display: [HIDDEN]
Console: (health-ui not showing)
```

### Partially Damaged
```
Player HP: 60 / 100 (3/5 hearts)
Display: ❤️  ❤️  ❤️  🖤  🖤
Status: UI visible above inventory
```

### Half Damage
```
Player HP: 50 / 100 (2.5/5 hearts)
Display: ❤️  ❤️  💔  🖤  🖤
Status: UI visible above inventory
```

### Nearly Dead
```
Player HP: 10 / 100 (0.5/5 hearts)
Display: 💔  🖤  🖤  🖤  🖤
Status: UI visible above inventory
```

## Z-Index Hierarchy

```
2000  ┌─────────────────────────┐
      │  Minigames (laptop)     │
      │  person-chat, phone     │
1100  ├─────────────────────────┤
      │  Health UI ← NEW!       │
1000  ├─────────────────────────┤
      │  Inventory UI           │
      │  Notifications          │
 100  ├─────────────────────────┤
      │  Other elements         │
  0   └─────────────────────────┘
```

## Asset Files

```
assets/icons/
├── heart.png       ← Full heart (used for full AND empty with opacity)
├── heart-half.png  ← Half heart (for remainder)
└── (other icons)
```

## Files Changed

✏️ **js/ui/health-ui.js** - Updated to use PNG icons
🆕 **css/health-ui.css** - New CSS file with proper styling
📝 **index.html** - Added CSS link

## Event Flow

```
Combat happens
    ↓
Player takes damage
    ↓
combatSystem emits: CombatEvents.PLAYER_HP_CHANGED
    ↓
HealthUI.updateHP() called
    ↓
Health UI shows (if hp < maxHP)
    ↓
Hearts update: ❤️ ❤️ 💔 🖤 🖤
    ↓
Health UI displays above inventory ✅
```

## Testing Checklist

- [ ] Load index.html in browser
- [ ] Take damage (get hit by hostile NPC)
- [ ] Health UI appears above inventory
- [ ] Hearts update correctly (full/half/empty)
- [ ] UI hides when health restored to full
- [ ] Icons are crisp and pixelated
- [ ] No console errors

## Quick Reference

| Element | Value |
|---------|-------|
| Z-Index | 1100 |
| Position | Top center, 60px from top |
| Positioning | Fixed (always visible when shown) |
| Full Heart Icon | assets/icons/heart.png |
| Half Heart Icon | assets/icons/heart-half.png |
| Empty Heart | heart.png at 0.2 opacity |
| Max Hearts | 5 (configurable via COMBAT_CONFIG.ui.maxHearts) |
| Max HP | 100 (20 HP per heart) |

## Pixel-Art Style

All images use:
```css
image-rendering: pixelated;        /* Standard */
image-rendering: -moz-crisp-edges; /* Firefox */
image-rendering: crisp-edges;      /* Chrome/Safari */
```

This ensures icons look crisp even when scaled, maintaining the pixel-art aesthetic.
Add Hostile NPC mode Fix NPC interaction and event handling issues - Added a visual problem-solution summary for debugging NPC event handling. - Resolved cooldown bug in NPCManager by implementing explicit null/undefined checks. - Modified PersonChatMinigame to prioritize event parameters over state restoration. - Updated security guard dialogue in Ink scenarios to improve interaction flow. - Adjusted vault key parameters in npc-patrol-lockpick.json for consistency. - Changed inventory stylesheet references to hud.css in test HTML files for better organization. feat(combat): Integrate chair kicking with punch mechanic Update chair interaction to use the punch system instead of direct kicking: Changes to interactions.js: - Modified swivel chair interaction to trigger player punch instead of directly applying kick velocity - Simplified chair interaction handler to just call playerCombat.punch() Changes to player-combat.js: - Extended checkForHits() to detect chairs in punch range and direction - Added kickChair() method that applies the same velocity calculation: - Calculates direction from player to chair - Applies 1200 px/s kick force in that direction - Triggers spin direction calculation for visual rotation - Adds visual feedback (flash chair, light screen shake) - Chairs now respond to punch AOE damage like hostile NPCs Now clicking a chair or pressing 'E' near it triggers a punch, and if the chair is in punch range and facing direction, it gets kicked with the original velocity physics. Multiple chairs can be kicked with one punch. feat(combat): Implement hostile NPC behavior and final integration (Phase 6-7) Complete hostile NPC combat system with chase behavior and integration: Phase 6: Hostile NPC Behavior - Modified npc-behavior.js determineState() to check hostile state from npcHostileSystem - Implemented updateHostileBehavior() with chase and attack logic: - NPCs chase player when hostile and in aggro range - NPCs stop and attack when in attack range - NPCs use directional movement with proper animations - Integration with npcCombat system for attack attempts - Added KO state check to prevent KO'd NPCs from acting Phase 7: Final Integration - Modified player.js to disable movement when player is KO - Added visual KO effect (50% alpha) to NPC sprites in npc-hostile.js - Connected all combat systems end-to-end: - Ink dialogue → hostile tag → hostile state → chase behavior → combat - Player interaction → punch → NPC damage → KO → visual feedback - NPC chase → attack → player damage → HP UI → game over Full combat loop now functional: hostile NPCs chase and attack player, player can punch hostile NPCs, complete visual/audio feedback, game over on KO. feat(combat): Add feedback, UI, and combat mechanics (Phase 2-5) Implement comprehensive combat feedback, UI, and mechanics: Phase 2: Enhanced Feedback Systems - damage-numbers.js: Floating damage numbers with object pooling - screen-effects.js: Screen flash and shake for combat feedback - sprite-effects.js: Sprite tinting, flashing, and visual effects - attack-telegraph.js: Visual indicators for incoming NPC attacks Phase 3: UI Components - health-ui.js: Player health display as hearts (5 hearts, shows when damaged) - npc-health-bars.js: Health bars above hostile NPCs with color coding - game-over-screen.js: KO screen with restart/main menu options Phase 4-5: Combat Mechanics - player-combat.js: Player punch system with AOE directional damage - npc-combat.js: NPC attack system with telegraph and cooldowns - Modified interactions.js to trigger punch on hostile NPC interaction - Integrated all systems into game.js create() and update() loops Combat now functional with complete visual/audio feedback pipeline. Player can punch hostile NPCs, NPCs can attack player, health tracking works. feat(combat): Add hostile NPC system foundation (Phase 0-1) Implement core hostile NPC combat system infrastructure: - Add #hostile tag handler to chat-helpers.js for Ink integration - Fix security-guard.ink to use proper hub pattern with -> hub instead of -> END - Add #hostile:security_guard tags to hostile conversation paths - Create combat configuration system (combat-config.js) - Create combat event constants (combat-events.js) - Implement player health tracking system with HP and KO state - Implement NPC hostile state management with HP tracking - Add combat debug utilities for testing - Add error handling utilities for validation - Integrate combat systems into game.js create() method - Create test-hostile.ink for testing hostile tag system This establishes the foundation for hostile NPC behavior, allowing NPCs to become hostile through Ink dialogue and tracking health for both player and NPCs. docs(npc): Apply codebase-verified corrections to hostile NPC plans Apply critical corrections based on actual codebase verification: CORRECTIONS.md (Updated): - ✅ Confirms #exit_conversation tag ALREADY IMPLEMENTED * Location: person-chat-minigame.js line 537 * No handler needed in chat-helpers.js - ❌ Hostile tag still needs implementation in chat-helpers.js - Provides exact code for hostile tag handler - Clarifies tag format: #hostile:npcId or #hostile (uses current NPC) - Updated action items to reflect what's already working INTEGRATION_UPDATES.md (New): - Comprehensive correction document - Issue 1 Corrected: Exit conversation already works - Issue 6 Corrected: Punch mechanics are interaction-based with AOE - Details interaction-based punch targeting: * Player clicks hostile NPC OR presses 'E' nearby * Punch animation plays in facing direction * Damage applies to ALL NPCs in range + direction (AOE) * Can hit multiple enemies if grouped (strategic gameplay) - Provides complete implementation examples - Removes complexity of target selection systems - Uses existing interaction patterns quick_start.md (Updated): - Removed exit_conversation handler (already exists) - Updated hostile tag handler code - Added punch mechanics design section - Clarified interaction-based targeting - Added troubleshooting for exit_conversation Key Findings: ✅ Exit conversation tag works out of the box ✅ Punch targeting uses existing interaction system (simpler!) ✅ AOE punch adds strategic depth without complexity ❌ Only ONE critical task remains: Add hostile tag to chat-helpers.js Impact: - Less work required (don't need exit_conversation handler) - Simpler implementation (use existing interaction patterns) - Better gameplay (AOE punches, directional attacks) - Clear path forward with exact code examples docs(npc): Add critical corrections and codebase integration review Add comprehensive review of hostile NPC plans against actual codebase: CORRECTIONS.md: - Identifies critical Ink pattern error (-> END vs -> hub) - Documents correct hub-based conversation pattern - Provides corrected examples for all Ink files - Explains why -> hub is required after #exit_conversation FORMAT_REVIEW.md: - Validates JSON scenario format against existing scenarios - Reviews NPC object structure and required fields - Documents correct Ink hub pattern from helper-npc.ink - Proposes hostile configuration object for NPC customization - Provides complete format reference and checklists review2/integration_review.md: - Comprehensive codebase analysis by Explore agent - Identifies 2 critical blockers requiring immediate attention: * Missing tag handlers for #hostile and #exit_conversation * Incorrect Ink pattern (-> END) in planning documents - Documents 4 important integration differences: * Initialization in game.js not main.js * Event dispatcher already exists (window.eventDispatcher) * Room transition behavior needs design decision * Multi-hostile NPC targeting needs design decision - Confirms 8 systems are fully compatible with plan - Provides existing code patterns to follow - Corrects integration sequence review2/quick_start.md: - Step-by-step guide for Phase 0-1 implementation - Includes complete code examples for critical systems - Browser console test procedures - Common issues and solutions - Success criteria checklist Key Findings: ✅ 90% compatible with existing codebase ❌ Must add tag handlers to chat-helpers.js before implementation ❌ Must fix all Ink examples to use -> hub not -> END ⚠️ Should follow game.js initialization pattern not main.js ⚠️ Should use existing window.eventDispatcher ⚠️ Need design decisions on room transitions and multi-targeting All critical issues documented with solutions ready. Implementation can proceed with high confidence after corrections applied. docs(npc): Add comprehensive planning documents for hostile NPC system Add detailed implementation plans for hostile NPC feature including: - Complete implementation plan with phase-by-phase breakdown - Architecture overview with system diagrams and data flows - Detailed TODO list with 200+ actionable tasks - Phase 0 foundation with design decisions and base components - Enhanced combat feedback implementation guide - Implementation roadmap with 6-day schedule Add comprehensive review documents: - Implementation review with risk assessment and recommendations - Technical review analyzing code patterns and best practices - UX review covering player experience and game feel Key features planned: - NPC hostile state triggered via Ink tags - Player health system with heart-based UI - NPC health bars and combat mechanics - Punch combat for both player and NPCs - Strong visual/audio feedback for combat - Game over system and KO states - Attack telegraphing for fairness - Enhanced NPC chase behavior with LOS - Debug utilities and error handling - Comprehensive testing strategy 2025-11-14 19:44:17 +00:00			`# Health UI Display - What Changed`

			`## Before ❌`

			```
			`Problem: Health UI not visible`
			`- Emoji hearts (❤️ 💔 🖤)`
			`- Inline CSS styles (position: fixed; z-index: 100)`
			`- Z-index too low (100 < inventory's 1000)`
			`- Never appears on screen`
			```

			`## After ✅`

			```
			`Solution: Health UI now displays properly`
			`- PNG icon hearts (assets/icons/heart.png)`
			`- Proper CSS file (css/health-ui.css)`
			`- Z-index: 1100 (above inventory)`
			`- Appears above inventory when damaged`
			```

			`## Visual Layout`

			```
			`┌──────────────────────────────────────────────────────────┐`
			`│ │`
			`│ ❤️ ❤️ ❤️ ❤️ 💔 │`
			`│ (Health UI - NEW z-index: 1100) │`
			`│ │`
			`│ ┌────────────────────────────────────────────────────┐ │`
			`│ │ │ │`
			`│ │ [Game World] │ │`
			`│ │ Player running around │ │`
			`│ │ │ │`
			`│ │ │[I] │`
			`│ │ │[n] │`
			`│ │ │[v] │`
			`│ │ │[e] │`
			`│ └────────────────────────────────────────────────────┘ │`
			`│ Inventory UI (z-index: 1000) │`
			`│ │`
			`└──────────────────────────────────────────────┘`
			```

			`## Code Changes Summary`

			`### Change 1: Image-Based Hearts`

			`Before:`
			```javascript
			`const heart = document.createElement('div');`
			`heart.textContent = '❤️'; // Emoji`
			```

			`After:`
			```javascript
			`const heart = document.createElement('img');`
			`heart.src = 'assets/icons/heart.png'; // PNG icon`
			```

			`### Change 2: Proper CSS Styling`

			`Before:`
			```javascript
			this.container.style.cssText = `
			`z-index: 100; // TOO LOW`
			`display: none;`
			`;
			```

			`After:`
			```css
			`#health-ui-container {`
			`z-index: 1100; /* ABOVE inventory (z-index: 1000) */`
			`display: flex;`
			`}`
			```

			`### Change 3: CSS File Created`

			New file: `css/health-ui.css`
			```css
			`z-index: 1100; /* Key fix */`
			`pointer-events: none; /* Don't block clicks */`
			`background: rgba(0, 0, 0, 0.8); /* Dark background */`
			`border: 2px solid #333; /* Pixel-art style */`
			`image-rendering: pixelated; /* Crisp icons */`
			```

			`## Heart Display Examples`

			`### Full Health (Hidden)`
			```
			`Status: No damage taken`
			`Display: [HIDDEN]`
			`Console: (health-ui not showing)`
			```

			`### Partially Damaged`
			```
			`Player HP: 60 / 100 (3/5 hearts)`
			`Display: ❤️ ❤️ ❤️ 🖤 🖤`
			`Status: UI visible above inventory`
			```

			`### Half Damage`
			```
			`Player HP: 50 / 100 (2.5/5 hearts)`
			`Display: ❤️ ❤️ 💔 🖤 🖤`
			`Status: UI visible above inventory`
			```

			`### Nearly Dead`
			```
			`Player HP: 10 / 100 (0.5/5 hearts)`
			`Display: 💔 🖤 🖤 🖤 🖤`
			`Status: UI visible above inventory`
			```

			`## Z-Index Hierarchy`

			```
			`2000 ┌─────────────────────────┐`
			`│ Minigames (laptop) │`
			`│ person-chat, phone │`
			`1100 ├─────────────────────────┤`
			`│ Health UI ← NEW! │`
			`1000 ├─────────────────────────┤`
			`│ Inventory UI │`
			`│ Notifications │`
			`100 ├─────────────────────────┤`
			`│ Other elements │`
			`0 └─────────────────────────┘`
			```

			`## Asset Files`

			```
			`assets/icons/`
			`├── heart.png ← Full heart (used for full AND empty with opacity)`
			`├── heart-half.png ← Half heart (for remainder)`
			`└── (other icons)`
			```

			`## Files Changed`

			`✏️ js/ui/health-ui.js - Updated to use PNG icons`
			`🆕 css/health-ui.css - New CSS file with proper styling`
			`📝 index.html - Added CSS link`

			`## Event Flow`

			```
			`Combat happens`
			`↓`
			`Player takes damage`
			`↓`
			`combatSystem emits: CombatEvents.PLAYER_HP_CHANGED`
			`↓`
			`HealthUI.updateHP() called`
			`↓`
			`Health UI shows (if hp < maxHP)`
			`↓`
			`Hearts update: ❤️ ❤️ 💔 🖤 🖤`
			`↓`
			`Health UI displays above inventory ✅`
			```

			`## Testing Checklist`

			`- [ ] Load index.html in browser`
			`- [ ] Take damage (get hit by hostile NPC)`
			`- [ ] Health UI appears above inventory`
			`- [ ] Hearts update correctly (full/half/empty)`
			`- [ ] UI hides when health restored to full`
			`- [ ] Icons are crisp and pixelated`
			`- [ ] No console errors`

			`## Quick Reference`

			`\| Element \| Value \|`
			`\|---------\|-------\|`
			`\| Z-Index \| 1100 \|`
			`\| Position \| Top center, 60px from top \|`
			`\| Positioning \| Fixed (always visible when shown) \|`
			`\| Full Heart Icon \| assets/icons/heart.png \|`
			`\| Half Heart Icon \| assets/icons/heart-half.png \|`
			`\| Empty Heart \| heart.png at 0.2 opacity \|`
			`\| Max Hearts \| 5 (configurable via COMBAT_CONFIG.ui.maxHearts) \|`
			`\| Max HP \| 100 (20 HP per heart) \|`

			`## Pixel-Art Style`

			`All images use:`
			```css
			`image-rendering: pixelated; /* Standard */`
			`image-rendering: -moz-crisp-edges; /* Firefox */`
			`image-rendering: crisp-edges; /* Chrome/Safari */`
			```

			`This ensures icons look crisp even when scaled, maintaining the pixel-art aesthetic.`