BreakEscape/planning_notes/npc/hostile/review1/ux_review.md

# UX Review - NPC Hostile State Feature

## Player Experience Analysis

### Overview

This review examines the hostile NPC feature from a player experience perspective, focusing on clarity, feedback, fairness, and fun.

## 1. Combat Initiation

### Current Design
- Player triggers hostile state through dialogue choices
- NPC becomes hostile via `#hostile` tag
- Conversation exits immediately
- NPC begins chasing player

### UX Analysis

**Strengths:**
- Clear cause and effect (player choice → consequence)
- Immediate feedback (conversation exits)

**Concerns:**

#### C1: Sudden Transition
- **Issue**: Player might not realize NPC is now hostile
- **Impact**: Confusion, unexpected damage
- **Severity**: Medium

**Recommendation:**
Add transition feedback:
```
Player makes hostile dialogue choice
      ↓
Dialogue shows NPC angry response
      ↓
Screen flash or warning indicator
      ↓
Sound effect (alarm, anger)
      ↓
Conversation exits with visual cue
      ↓
Brief camera zoom/shake
      ↓
NPC begins chase
```

Visual indicators:
- Red screen flash when hostile triggered
- "!" exclamation mark above NPC head
- NPC sprite changes color briefly (red flash)
- Warning sound effect

#### C2: No Warning System
- **Issue**: Player can't tell NPC is about to become hostile
- **Impact**: Feels unfair, no chance to avoid
- **Severity**: Medium

**Recommendation:**
Add warning levels in dialogue:
- 😊 Neutral - No threat
- 😐 Annoyed - Low threat
- 😠 Angry - High threat (will become hostile soon)
- 💢 Hostile - Combat mode

Show indicator next to NPC portrait:
```
┌─────────────────────┐
│   Security Guard    │
│   😠 Angry          │
│                     │
│ "This is your       │
│  final warning!"    │
└─────────────────────┘
```

#### C3: Point of No Return Unclear
- **Issue**: Player doesn't know which choices lead to combat
- **Impact**: Accidental combat encounters
- **Severity**: Medium

**Recommendation:**
Add choice indicators:
```
+ [I'm just passing through]
+ [I need to access that door]
+ [Mind your own business] ⚠️ HOSTILE
+ [You can't tell me what to do] ⚠️ HOSTILE
```

Or color-code choices:
- Green: Safe/friendly
- Yellow: Risky
- Red: Will trigger combat

## 2. Combat Feedback

### Current Design
- Player presses SPACE to punch
- Walk animation plays with red tint
- Damage applied if in range
- NPC health bar updates

### UX Analysis

#### C4: Hit/Miss Unclear
- **Issue**: Player can't tell if punch connected
- **Impact**: Feels unresponsive
- **Severity**: High

**Recommendation:**
Add multi-layered feedback:

**Visual Feedback:**
- Hit:
  - Damage number floats up from NPC
  - NPC flashes white briefly
  - Impact particle effect (stars, dust)
  - Health bar shakes
- Miss:
  - "MISS" text appears
  - Whoosh particle effect
  - No damage number

**Audio Feedback:**
- Hit: Punch impact sound (thud)
- Miss: Whoosh/swish sound
- Critical hit: Stronger impact sound

**Haptic Feedback (if available):**
- Hit: Brief vibration
- Miss: No vibration

#### C5: Damage Amount Unclear
- **Issue**: Health bar updates but player doesn't know exact damage
- **Impact**: Can't strategize effectively
- **Severity**: Medium

**Recommendation:**
Add floating damage numbers:
```
      -20
       ↑
    [NPC]
   ▓▓▓▓▓░░ 70/100
```

Design:
- White for normal damage
- Red for critical hits
- Larger font for bigger damage
- Floats up and fades out over 1 second

#### C6: Player Taking Damage Unclear
- **Issue**: Hearts update but no immediate feedback
- **Impact**: Player doesn't notice they're being hurt
- **Severity**: High

**Recommendation:**
Add strong damage feedback:

**Visual:**
- Red screen flash (outer edges)
- Player sprite red tint (200ms)
- Screen shake (subtle, 2-3 pixels)
- Vignette effect (red edges pulse)

**Audio:**
- Grunt/pain sound
- Heartbeat sound at low HP

**UI:**
- Hearts shake when damaged
- Damaged hearts glow red briefly
- Screen edge pulsing red at <30% HP

Intensity scales with damage:
- Small damage (5-10): Subtle flash
- Medium damage (10-20): Flash + shake
- Large damage (20+): Strong flash + shake + sound

## 3. Health System Clarity

### Current Design
- Hearts hidden at full HP
- Appear when damaged
- 5 hearts, 20 HP each
- Half hearts at 10 HP increments

### UX Analysis

#### C7: Hearts Hidden Initially
- **Issue**: Player doesn't know they have health until hit
- **Impact**: First damage is surprising
- **Severity**: Medium

**Recommendation:**

**Option A:** Always show hearts
- Pro: Player always knows their status
- Pro: Standard in most games
- Con: Clutters UI slightly

**Option B:** Show semi-transparent
- Pro: Clean UI when healthy
- Pro: Player can see hearts exist
- Con: Might not be noticed

**Option C:** Show briefly at start
- Show for 3 seconds when entering combat-capable area
- Hide after no combat
- Reveal when damaged
- Pro: Best of both worlds
- Con: More complex logic

**Recommendation: Option C**

#### C8: Heart Calculation Confusing
- **Issue**: 100 HP to 5 hearts math not intuitive
- **Impact**: Player doesn't know exact HP
- **Severity**: Low

**Recommendation:**
Add HP number option (in settings):
```
❤️❤️❤️💔🖤  70/100 HP
```

Or tooltip on hover:
```
❤️❤️❤️💔🖤
    ↓
 70/100 HP
```

#### C9: No Health Regeneration
- **Issue**: No way to recover health (as designed)
- **Impact**: One mistake = permanent consequence
- **Severity**: Medium (depends on game design intent)

**Recommendation:**

If this is intentional (high stakes):
- Make it very clear to player
- Add tutorial explaining permanent damage
- Consider checkpoints or save points

If health regen desired:
- Add med kits as items
- Slow regeneration out of combat
- Safe rooms that restore health
- Pay for healing (game currency)

## 4. Combat Flow

### Current Design
- Player can punch when near hostile NPC
- Cooldown prevents spam
- NPC attacks when in range
- No dodge/block mechanics

### UX Analysis

#### C10: Combat Feels Stiff
- **Issue**: Stand and trade hits, no mobility options
- **Impact**: Combat is repetitive
- **Severity**: Medium

**Recommendation:**

Add mobility to combat:
- **Dodge roll**: Quick dash with i-frames
- **Backstep**: Small backward movement
- **Sprint**: Hold Shift to run faster (drains stamina?)

Adds skill expression:
- Good players can dodge attacks
- Positioning matters
- Not just DPS race

#### C11: No Defensive Options
- **Issue**: Can only attack or run
- **Impact**: Limited tactical options
- **Severity**: Medium

**Recommendation:**

Add one defensive option:

**Option A: Block**
- Hold key to block (e.g., Shift)
- Reduces damage by 50%
- Can't move while blocking
- Good for new players

**Option B: Dodge**
- Tap key for quick dodge (e.g., Space)
- Brief invulnerability (200ms)
- Small cooldown (2 seconds)
- Skill-based defense

**Option C: Counter**
- Block just before hit = counterattack
- High skill, high reward
- Might be too complex for this game

**Recommendation: Option A (block) for accessibility**

#### C12: Single Attack Type
- **Issue**: Only one punch attack
- **Impact**: Combat is one-dimensional
- **Severity**: Low (acceptable for MVP)

**Future Enhancement:**
- Light attack (fast, low damage)
- Heavy attack (slow, high damage)
- Special attack (costs resource)

## 5. NPC Behavior Clarity

### Current Design
- Hostile NPC chases player
- Attacks when in range
- No warning before attacking

### UX Analysis

#### C13: No Attack Telegraph
- **Issue**: NPC attacks without warning
- **Impact**: Feels unfair, hard to react
- **Severity**: High

**Recommendation:**

Add attack wind-up:
```
NPC in range → Wind-up (500ms) → Attack → Cooldown
                    ↓
              Player can react
              (dodge, block, retreat)
```

Visual telegraph:
- NPC sprite flashes red
- Fist raises (different animation)
- Exclamation mark appears
- Attack indicator (red circle expanding)

Audio telegraph:
- Grunt sound before punch
- Whoosh sound during wind-up

Gives player 500ms to react = fair combat

#### C14: Chase Behavior Unclear
- **Issue**: Player doesn't know NPC is chasing
- **Impact**: Unexpected attacks
- **Severity**: Medium

**Recommendation:**

Add chase indicators:
- Angry emoji above NPC head
- Red name plate when hostile
- Footstep sounds getting closer
- Warning when NPC is approaching from off-screen

Alert levels:
- 🔴 Alert: "Security Guard is pursuing!"
- 🟡 Warning: "Security Guard nearby"
- 🟢 Clear: "Area secure"

#### C15: Lost Sight Behavior Confusing
- **Issue**: What happens when player escapes?
- **Impact**: Player doesn't know if safe
- **Severity**: Medium

**Recommendation:**

Clear state communication:
```
Hostile + In Sight: 🔴 "CHASING"
Hostile + Lost Sight: 🟡 "SEARCHING"  (30 seconds)
Hostile + Timeout: 🟢 "CALMED DOWN"  (returns to patrol)
```

Visual feedback:
- Question mark above head when searching
- Search animation (looking around)
- Return to normal color when calmed

## 6. Win/Loss Conditions

### Current Design
- Player at 0 HP = KO = Game Over
- NPC at 0 HP = KO = Replaced with sprite

### UX Analysis

#### C16: Instant Game Over Too Harsh
- **Issue**: 0 HP = immediately lose
- **Impact**: Frustrating, no comeback chance
- **Severity**: Medium

**Recommendation:**

Add grace period:
```
0 HP → Player KO'd → 5 second countdown → Game Over
              ↓
         Can be revived?
         (if item/mechanic exists)
```

Or second chance system:
- First KO: Warning, restored to 10 HP
- Second KO: Game Over

Makes failure less punishing, encourages learning

#### C17: No Victory Celebration
- **Issue**: NPC KO'd, no fanfare
- **Impact**: Victory feels hollow
- **Severity**: Low-Medium

**Recommendation:**

Add victory feedback:
- Victory sound effect
- XP/points gained display
- Brief slow-motion on KO hit
- Item drop from NPC (optional)
- Achievement toast: "Defeated Security Guard!"

Makes combat feel rewarding

#### C18: Game Over Screen Too Simple
- **Issue**: Just "GAME OVER" and restart
- **Impact**: No context, stats, or learning
- **Severity**: Low-Medium

**Recommendation:**

Enhanced game over screen:
```
┌──────────────────────────────────┐
│         KNOCKED OUT              │
├──────────────────────────────────┤
│  Defeated by: Security Guard     │
│  Damage dealt: 45                │
│  Damage taken: 100               │
│  Time survived: 2:34             │
├──────────────────────────────────┤
│  [Restart Level]  [Main Menu]    │
│  [Load Save]      [Quit]         │
└──────────────────────────────────┘
```

Shows what went wrong, gives options

## 7. Tutorial and Onboarding

### Current Design (Not Specified)
- No tutorial in plan
- Player must discover combat

### UX Analysis

#### C19: No Combat Tutorial
- **Issue**: Player doesn't know how to fight
- **Impact**: Frustrating first encounter
- **Severity**: High

**Recommendation:**

Add first combat tutorial:

**Approach A: Popup Tips**
When first hostile encounter:
```
┌────────────────────────────────┐
│ ⚠️ NPC has become hostile!     │
│                                │
│ Press SPACE to punch           │
│ Stay in range to hit           │
│ Watch your health (top right)  │
│                                │
│ [Got it!]                      │
└────────────────────────────────┘
```

**Approach B: Safe Training**
- Add training dummy in safe area
- Optional tutorial before first combat
- Practice punching without risk

**Approach C: Contextual Hints**
- "Press SPACE to punch" appears near hostile NPC
- "Out of range!" when punch misses
- "Low health!" when HP < 30%

**Recommendation: Combination of A and C**

#### C20: Control Scheme Not Intuitive
- **Issue**: SPACE for punch might conflict with other actions
- **Impact**: Accidental punches or missed punches
- **Severity**: Medium

**Recommendation:**

Consider alternative control schemes:
- **Option 1:** SPACE for punch (current)
  - Pro: Common key
  - Con: Often used for jump/interact in games
- **Option 2:** Left Mouse Click
  - Pro: Very intuitive for attacking
  - Con: Might conflict with movement if click-to-move
- **Option 3:** F key
  - Pro: Dedicated action key
  - Con: Less discoverable

**Recommendation: Support multiple inputs**
- SPACE, F, or Left Click all work
- Show all options in tutorial
- Player can rebind in settings

## 8. Accessibility

### Current Design
- Visual and audio feedback
- No accessibility features specified

### UX Analysis

#### C21: No Colorblind Support
- **Issue**: Red/green health indicators
- **Impact**: Colorblind players can't distinguish
- **Severity**: Medium

**Recommendation:**
- Use shapes in addition to colors
  - Full heart: ❤️
  - Half heart: 💔
  - Empty heart: 🖤
- Add colorblind mode in settings
  - Replace red with blue/yellow
- Use text labels when possible

#### C22: No Difficulty Options
- **Issue**: Combat might be too hard/easy for some
- **Impact**: Not accessible to all skill levels
- **Severity**: Medium

**Recommendation:**

Add difficulty settings:
- **Easy:**
  - Player HP: 150
  - NPC damage: 5
  - Longer attack telegraphs (750ms)
  - Slower NPC movement
- **Normal:**
  - Current values
- **Hard:**
  - Player HP: 75
  - NPC damage: 15
  - Shorter telegraphs (250ms)
  - Faster NPCs

Allow changing mid-game

#### C23: No Visual/Audio Toggles
- **Issue**: Some players sensitive to screen shake, flashes
- **Impact**: Accessibility issues
- **Severity**: Low-Medium

**Recommendation:**

Add settings toggles:
- [ ] Screen shake
- [ ] Screen flash effects
- [ ] Combat sounds
- [ ] Damage numbers
- [ ] Motion blur (if added)

Labeled: "Reduce visual effects"

## 9. Pacing and Encounter Design

### Current Design
- Combat triggered by dialogue choices
- No specified encounter pacing

### UX Analysis

#### C24: No Safe Zones
- **Issue**: Player might not have break from combat
- **Impact**: Stress, no recovery time
- **Severity**: Medium

**Recommendation:**
- Designate safe rooms (no hostile NPCs)
- Save points in safe rooms
- Healing/rest areas
- Clear visual distinction (blue vs red lighting)

#### C25: No Escalation Curve
- **Issue**: First combat same difficulty as last
- **Impact**: No sense of progression
- **Severity**: Low-Medium

**Recommendation:**

Design difficulty curve:
1. **First encounter:** Weak guard (50 HP, 5 damage)
   - Tutorial fight
2. **Mid-game:** Normal guards (100 HP, 10 damage)
   - Standard combat
3. **Late-game:** Tough guards (150 HP, 15 damage)
   - Challenges player mastery

Communicate difficulty:
- Guard title: "Junior Guard" vs "Elite Guard"
- Visual difference: Different sprites/colors
- Health bar color indicates difficulty

## 10. Overall Game Feel

### Assessment

**Strengths:**
- Clear cause and effect (dialogue → combat)
- Simple mechanics (easy to learn)
- Immediate consequences (stakes)

**Weaknesses:**
- Feedback could be much stronger
- Limited tactical options
- Fairness concerns (telegraphing)
- No tutorial or onboarding
- Potentially too punishing

### Recommended Priority Improvements

**Must Have (MVP):**
1. Attack telegraphing for NPCs
2. Strong damage feedback (visual/audio)
3. Hit/miss indicators
4. Combat tutorial/hints
5. Warning before hostile state

**Should Have:**
6. Floating damage numbers
7. Better game over screen
8. Safe zones
9. Victory celebration
10. Health display improvements

**Nice to Have:**
11. Block/dodge mechanics
12. Difficulty settings
13. Accessibility options
14. Escalation curve
15. Visual polish

## Summary

The core hostile NPC system is solid, but the player experience needs significant feedback and clarity improvements. The biggest UX gaps are:

1. **Feedback Intensity** - Players need stronger visual/audio feedback
2. **Attack Telegraphing** - NPCs need wind-up animations for fairness
3. **Combat Tutorial** - First encounter needs guidance
4. **Clarity** - All states and transitions need clear communication

With these improvements, the feature will feel responsive, fair, and fun rather than confusing and frustrating.

## UX Testing Checklist

When implementing, test these scenarios:

- [ ] Player doesn't realize NPC is hostile
- [ ] Player doesn't notice taking damage
- [ ] Player can't tell if punch hit
- [ ] Player doesn't know how much damage dealt
- [ ] Player surprised by NPC attack
- [ ] Player doesn't understand heart system
- [ ] Player lost in combat, no clear objective
- [ ] Player doesn't know controls
- [ ] Player feels combat is unfair
- [ ] Player finds combat too easy/hard
- [ ] Player KO'd without understanding why
- [ ] Player defeats NPC, feels no satisfaction
- [ ] Colorblind player can't read health
- [ ] Player sensitive to screen effects

Each "doesn't" above should become "clearly understands" after improvements.