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
17 KiB
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
#hostiletag - 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:
- First encounter: Weak guard (50 HP, 5 damage)
- Tutorial fight
- Mid-game: Normal guards (100 HP, 10 damage)
- Standard combat
- 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):
- Attack telegraphing for NPCs
- Strong damage feedback (visual/audio)
- Hit/miss indicators
- Combat tutorial/hints
- 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:
- Feedback Intensity - Players need stronger visual/audio feedback
- Attack Telegraphing - NPCs need wind-up animations for fairness
- Combat Tutorial - First encounter needs guidance
- 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.