mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 11:18:08 +00:00
660105421a
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
Break Escape: Cyber-Physical Security Learning Framework
Break Escape is an escape room-inspired games-based learning framework that simulates cyber-physical security challenges. Break Escape creates immersive experiences where learners engage with both physical and digital security mechanisms within narrative-driven scenarios explicitly mapped to the Cyber Security Body of Knowledge (CyBOK). The game is inspired by retro top-down games, dungeon crawlers, escape rooms, and cyber security challenges.
Note: Break Escape is currently in development. Please report any issues or feedback via GitHub.
Live Demo -- Early Beta Playtesting
You can try Break Escape directly from your browser by visiting: https://hacktivity.co.uk/break-escape-beta/scenario_select.html
You’ll choose from scenarios, each offering its own set of puzzles and challenges, ranging from cryptography to physical security.
After playing, please fill out a short survey. Your insights will be instrumental in improving the game and understanding the benefits. https://forms.gle/kiVgNUBSHu2KjcJt8
Features
- Immersive Learning Environment: Top-down 2D game environment accessible through web browsers
- Cyber-Physical Security Challenges: Simulations of various security mechanisms:
- Key-based locks (with physical keys and lockpicking mini-game)
- PIN code systems
- Password-protected interfaces
- Biometric authentication (fingerprints that can be dusted and spoofed)
- Bluetooth proximity detection
- CyberChef Integration: Embedded cryptographic tools for encryption and data analysis
- CyBOK Mapping: Each scenario is explicitly mapped to relevant Cyber Security Body of Knowledge areas
- Multiple Scenarios: Various pre-built scenarios focusing on different security aspects:
- "CEO Exfil Investigation" - Corporate espionage and data exfiltration
- "Captain Meow's Disappearance" - Encoding and cryptography
- "Encoding and Encryption Lab" - Basic cryptographic principles
- "Asymmetric Encryption with RSA" - Public key cryptography
- "Symmetric Encryption with AES" - Block ciphers and encryption modes
- "Biometric Security Breach" - Fingerprint authentication
Technical Implementation
Break Escape is implemented using:
- Phaser.js: Core game engine
- JavaScript/HTML5: Front-end implementation
- JSON: Scenario specification format
Installation
Break Escape is a web-based application and requires a web server to run. You can:
Option 1: Use the hosted version
Visit the live demo at https://hacktivity.co.uk/break-escape-beta/scenario_select.html
Option 2: Use Python's built-in HTTP server
-
Clone the repository:
git clone https://github.com/yourusername/break-escape.git cd break-escape -
Start a local web server:
python3 -m http.server -
Open your web browser and navigate to:
http://localhost:8000
Option 3: Deploy to a web server
- Upload all files to your web server directory
- Access through your domain
Usage
Start Break Escape:
- Open Break Escape in your web browser
- Choose a scenario based on your learning objectives or difficulty preference
Play the game:
- When you start a scenario, you will be given a brief of the scenario.
- You can navigate through the virtual environment using mouse clicks.
- Interact with objects by clicking on them.
- Collect items into your inventory to use later.
- Solve puzzles and progress through rooms to complete the scenario.
After playing, please fill out a short survey. https://forms.gle/kiVgNUBSHu2KjcJt8
Game Controls
- Mouse Click: Move character, interact with objects
- Inventory: Click collected items to use them
- Notes Panel: Access important information you've discovered
- Bluetooth Scanner: Detect nearby Bluetooth devices (when available)
- Biometrics Panel: View collected fingerprint samples (when available)
Scenario Design
Break Escape features a flexible JSON-based scenario specification format that enables educators to create custom scenarios without programming knowledge. The scenario structure includes:
- Rooms with connections, objects, and optional locks
- Objects with properties like takeable, readable, observations, and lock requirements
- Special object types for fingerprint collection, cryptographic analysis, and more
For detailed information on creating your own scenarios, refer to README_scenario_design.md.
License
Break Escape is dual licensed:
- AGPL (GNU Affero General Public License)
- Open Government Licence
Acknowledgements
Break Escape was developed as an educational tool to address the "reflection gap" identified in many existing cyber security games by requiring players to actively apply security knowledge rather than merely encountering security terminology during gameplay.
The project integrates CyberChef, an open-source web application for encryption and data analysis, allowing learners to interact with genuine cryptographic tools within the game environment.
Special thanks to the Cyber Security Body of Knowledge (CyBOK) for providing the knowledge framework that Break Escape scenarios are mapped to.
This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.1 grant (2024-2025).
For questions, contributions, or more information, please open an issue on the project repository.