mirror of https://github.com/cliffe/BreakEscape.git synced 2026-02-20 13:50:46 +00:00

Files

Z. Cliffe Schreuders 660105421a 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:47:54 +00:00

7.5 KiB

Raw Blame History

Implementation Validation Checklist

✅ Code Changes Completed

Cooldown Bug Fix (npc-manager.js:359)

Changed from config.cooldown || 5000 to explicit null/undefined check
Verified cooldown: 0 now evaluates correctly
No compilation errors
Verified change in file

Event Start Knot Fix (person-chat-minigame.js)

Added this.startKnot = params.startKnot to constructor (line 53)
Added startKnot check before state restoration (lines 315-340)
Added console log: ⚡ Event-triggered conversation: jumping directly to knot:
No compilation errors
Verified changes in file

npc-manager.js line 465 already passes startKnot: config.knot
NPCManager event triggering system unchanged (working correctly)
InkEngine and PhoneChatConversation goToKnot() methods working

✅ Documentation Completed

Comprehensive Guides

docs/EVENT_START_KNOT_FIX.md - Detailed explanation
docs/EVENT_FLOW_COMPLETE.md - Complete flow with code examples
docs/EVENT_TRIGGERED_QUICK_REF.md - One-page reference
docs/VISUAL_PROBLEM_SOLUTION.md - Visual before/after
docs/SESSION_COMPLETE_SUMMARY.md - Complete session summary

Previous Documentation (Reference)

docs/COOLDOWN_ZERO_BUG_FIX.md - From previous fix
docs/EVENT_JUMP_TO_KNOT.md - From previous implementation
docs/EVENT_JUMP_TO_KNOT_QUICK_REF.md - From previous implementation
docs/JUMP_TO_KNOT_DEBUGGING.md - From previous implementation

✅ Testing Requirements

Scenario Setup

Scenario file exists: scenarios/npc-patrol-lockpick.json
NPCs have event mappings with cooldown: 0
NPCs have event mappings with targetKnot: "on_lockpick_used"
Security guard has hostile Ink story: scenarios/ink/security-guard.json
Security guard story compiled successfully

Code Verification

No JavaScript errors in modified files
Parameter passing chain verified: npc-manager → minigame-manager → minigame
StartKnot stored in constructor
StartKnot checked before state restoration
Console logging in place for debugging

📋 Pre-Test Validation

File Integrity

js/systems/npc-manager.js - Line 359 fixed
js/minigames/person-chat/person-chat-minigame.js - Lines 53, 315-340 fixed
scenarios/ink/security-guard.ink - Hostile tags added
No unintended changes to other files

Parameter Flow Verification

Parameter: startKnot = 'on_lockpick_used'
Location: npc-manager.js line 465
    ↓
Passed to: MinigameFramework.startMinigame('person-chat', null, { startKnot })
    ↓
Received by: PersonChatMinigame constructor (params.startKnot)
    ↓
Stored as: this.startKnot = params.startKnot
    ↓
Used in: startConversation() line 317
    ↓
Effect: this.conversation.goToKnot(this.startKnot)
    ✅ Verified chain is complete

🧪 Manual Test Checklist

Before Testing

Open scenario_select.html in browser
Open browser console (F12)
Make console visible

Test Procedure

Select scenario: npc-patrol-lockpick.json
Game loads, player appears in patrol_corridor
Verify both NPCs are present (patrol_with_face, security_guard)
Navigate player to find the lockable object
Position player so security_guard is in view (~120 pixels)
Start lockpicking action
Expected: Lockpicking interrupted immediately
Expected: Person-chat window opens
Expected: Console shows event-triggered logs

Console Verification

Look for: 🎯 Event triggered: lockpick_used_in_view
Look for: ✅ Event conditions passed (NOT ⏸️ on cooldown)
Look for: ⚡ Event-triggered conversation: jumping directly to knot:
Look for: 📝 showDialogue called with character: security_guard
NOT seeing: 🔄 Continuing previous conversation (would mean state restored)

Dialogue Verification

Person-chat displays
NPC speaking name appears
Dialogue text appears (response to lockpicking)
Not showing old conversation dialogue

Expected Dialogue

The first dialogue should be the event response knot content, something like:

"What brings you to this corridor?"
or
"Hey! What do you think you're doing with that lock?"

🐛 Troubleshooting Guide

Issue: Console shows "on cooldown"

Cause: Cooldown bug not fixed or browser cache not cleared Fix:

Hard refresh (Ctrl+Shift+R)
Check line 359 in npc-manager.js for the fix
Verify no || 5000 fallback operator

Issue: Person-chat opens but shows old dialogue

Cause: startKnot not being used (parameter ignored) Fix:

Check line 53 in person-chat-minigame.js has this.startKnot = params.startKnot
Check lines 315-340 have the startKnot check BEFORE state restoration
Hard refresh browser cache

Issue: No person-chat window opens at all

Cause: Event not triggering or NPCManager error Fix:

Check console for error messages
Verify security_guard is in LOS (within ~120px, facing ~200°)
Verify cooldown: 0 in scenario JSON event mapping
Check npc-manager.js has all console logs

Issue: Person-chat opens but nothing shows

Cause: Ink story not loading or goToKnot failed Fix:

Check console for ❌ Failed to load conversation story
Verify scenarios/ink/security-guard.json exists
Check browser network tab for 404 errors
Verify on_lockpick_used knot exists in security-guard.ink

📊 Success Criteria

Minimum Success

Code compiles without errors
No JavaScript runtime errors
Event triggers and event-chat minigame starts

Full Success

Lockpicking interrupts when NPC in view
Person-chat window opens immediately
Event response dialogue appears
Console shows ⚡ Event-triggered conversation
No console errors

Excellent Success

All above plus:
Multiple events fire at cooldown: 0 with no delay
Different NPCs all respond to events correctly
Conversation history restored when not event-triggered
All console logs help with debugging

📈 Metrics to Track

After successful testing:

Cooldown Fix Validation: Events with cooldown: 0 fire immediately (0ms delay)
StartKnot Fix Validation: Event response knots displayed (not old state)
User Experience: Clear visual feedback of NPC reaction to player action

🎯 Next Steps After Validation

If all tests pass:
- Deploy to production
- Update player-facing documentation if needed
- Consider implementing same-NPC jump-to-knot feature
If any test fails:
- Check troubleshooting section above
- Review console output carefully
- Compare console output to expected logs
- Check file changes match documented changes
For future enhancement:
- Implement jump-to-knot while already in conversation with same NPC
- Extend to phone-chat minigame
- Add support for event interruption in other minigames

📝 Documentation References

For debugging, consult:

docs/VISUAL_PROBLEM_SOLUTION.md - Quick visual reference
docs/EVENT_TRIGGERED_QUICK_REF.md - Console indicators
docs/EVENT_FLOW_COMPLETE.md - Complete code flow
docs/SESSION_COMPLETE_SUMMARY.md - Full context

✅ Sign-Off

When all tests pass:

Mark this checklist as complete
Event-triggered conversation system is production-ready
All documentation is in place for future maintenance
Console logging helps with ongoing debugging

7.5 KiB Raw Blame History