mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 19:28:03 +00:00
b3156bf125
Added remaining sections to SOLUTION_GUIDE.md: - Complete Item List (starting inventory, key items, optional items) - LORE Items (all 3 fragments with locations) - Environmental Clues (founding plaque, sticky notes, emails) - VM-Related Items (all 4 flags with rewards) - Speedrun Optimization Guide (minimal 60% + perfect 100% routes) - Achievement Guide (story, ethical, combat, stealth, speedrun) - Common Mistakes & Solutions (7 troubleshooting scenarios) - Educational Learning Outcomes (CyBOK mapping for 8 knowledge areas) - Conclusion (key takeaways, Season 1 connection, final statistics) Guide Contents Summary: ✅ Mission Overview (47 patients, 12-hour crisis, 2.5 BTC ransom) ✅ Complete Objectives List (5 constant aims, ~17 tasks) ✅ ASCII Room Layout Diagram (8 rooms with guard patrol route) ✅ 3 Step-by-Step Walkthroughs (Optimal/Combat/Social paths) ✅ NPC Interaction Guide (5 NPCs with influence systems) ✅ Puzzle Solutions (PIN 1987, Base64, ROT13) ✅ VM Challenge Solutions (all 4 flags with commands) ✅ LORE Fragment Locations (3 fragments with narrative significance) ✅ Moral Choices & Consequences (3 choices with decision matrices) ✅ Complete Item List (40+ items categorized) ✅ Speedrun Routes (35-min minimal, 65-min perfect) ✅ Achievement Guide (20+ achievements) ✅ Common Mistakes (7 issues with solutions) ✅ Educational Outcomes (8 CyBOK knowledge areas) Perfect Run Statistics: - Rooms: 8/8 - NPCs: 5/5 (Dr. Kim, Marcus, Guard, Agent 0x99, Ghost) - VM Flags: 4/4 - LORE: 3/3 - Moral Choices: 3/3 - Time: 65-75 minutes - Score: 100% Educational Focus: - MAT: Ransomware, ProFTPD CVE-2010-4652 - IR: Recovery procedures, backup importance - NSS: SSH weaknesses, FTP vulnerabilities - ACS: Encoding vs encryption, Base64, ROT13 - SS: Linux navigation, file permissions - HF: Social engineering, scapegoating dynamics - AB: Threat actor motivations, ransomware economics - SOC: Physical security, investigation techniques Narrative Impact: - LORE 3 (ZDS Invoice) sets up Mission 3: "Ghost in the Machine" - First evidence of ENTROPY cell coordination under "The Architect" - Connects Ransomware Inc → Zero Day Syndicate → Crypto Anarchists - Transforms Season 1 from isolated missions to connected campaign Document is now complete and ready for playtesting reference.
BreakEscape Rails Engine
Cybersecurity training escape room game as a mountable Rails Engine.
Features
- 24+ cybersecurity escape room scenarios
- Server-side progress tracking with 2-table schema
- Randomized passwords per game instance via ERB
- JIT Ink script compilation for NPC dialogue
- Polymorphic player support (User/DemoUser)
- Pundit authorization
- RESTful API for game state management
- Session-based state persistence
Installation
In your Gemfile:
gem 'break_escape', path: 'path/to/break_escape'
Then:
bundle install
rails break_escape:install:migrations
rails db:migrate
rails db:seed # Optional: creates missions from scenarios
Mounting in Host App
In your config/routes.rb:
mount BreakEscape::Engine => "/break_escape"
Usage
Standalone Mode (Development)
export BREAK_ESCAPE_STANDALONE=true
rails server
# Visit http://localhost:3000/break_escape/
Mounted Mode (Production)
Mount in Hacktivity or another Rails app. The engine will use the host app's current_user via Devise.
Configuration
# config/initializers/break_escape.rb
BreakEscape.configure do |config|
config.standalone_mode = false # true for development
config.demo_user_handle = 'demo_player'
end
Database Schema
break_escape_missions- Scenario metadata (name, display_name, published, difficulty)break_escape_games- Player state + scenario snapshot (JSONB)break_escape_demo_users- Standalone mode only (optional)
API Endpoints
GET /games/:id/scenario- Scenario JSON (ERB-generated)GET /games/:id/ink?npc=X- NPC script (JIT compiled from .ink)GET /games/:id/bootstrap- Initial game dataPUT /games/:id/sync_state- Sync player statePOST /games/:id/unlock- Validate unlock attemptPOST /games/:id/inventory- Update inventory
Architecture
ERB Scenario Generation
Scenarios are stored as .json.erb templates and rendered on-demand with randomized values:
<%= random_password %>- Generates unique password per game<%= random_pin %>- Generates unique 4-digit PIN<%= random_code %>- Generates unique hex code
JIT Ink Compilation
NPC dialogue scripts compile on first request (~300ms):
- Check if
.jsonexists and is newer than.ink - If needed, run
inklecateto compile - Cache compiled JSON for subsequent requests
State Management
Player state stored in JSONB column:
- Current room and unlocked rooms
- Inventory and collected items
- NPC encounters
- Global variables (synced with client)
- Health and minigame state
Testing
rails test
License
AGPL v3 - See LICENSE file for details
Documentation
See HACKTIVITY_INTEGRATION.md for integration guide.