mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 11:18:08 +00:00
d25ad88e2a
Major design revision to accommodate single floor plan constraint while maintaining branching narrative and player choice. Key Changes to README.md: LOCATION CHANGE: - Changed from 4 separate physical facilities to single SAFETYNET Emergency Operations Center (EOC) - Player remains in SAFETYNET HQ throughout mission - 4 crisis response zones within same facility - Player chooses which crisis terminal to directly control - Other SAFETYNET teams (Alpha/Bravo/Charlie/Delta) visible working in adjacent zones FLOOR PLAN DESIGN: - 6 shared rooms (all branches visit these): 1. Emergency Briefing Room (choice presentation) 2. Main Operations Floor (central hub with all 4 crisis zones visible) 3. Server Room (VM challenges) 4. Communications Center (The Architect's taunts) 5. Intelligence Archive (Tomb Gamma discovery) 6. Debrief Room (outcomes revealed) - 1 branch-specific crisis terminal (player's choice determines which): 7A. Infrastructure Crisis Terminal (power grid remote control) 7B. Election Security Terminal (voter database protection) 7C. Supply Chain Terminal (software distribution security) 7D. Corporate Defense Terminal (corporate zero-day defense) NPC INTERACTION MODEL: - ENTROPY antagonists appear via video feeds/screens (not physically present in EOC) - Maintains distinct antagonists per branch without violating single-location constraint - Player interacts with remote operatives through crisis terminal displays FILE STRUCTURE SIMPLIFICATION: - Changed from 4 separate scenario files to 1 scenario.json.erb with ERB branching logic - Uses globalVariable "crisis_choice" to conditionally render crisis terminal content - Dramatically reduces development complexity while preserving 4 distinct narratives TECHNICAL APPROACH: - ERB conditionals switch crisis terminal NPCs/objects based on player choice - Shared rooms identical for all players (easier testing/maintenance) - VM challenges reusable across all branches - LORE reveals centralized in Intelligence Archive - Timer mechanic consistent regardless of choice BRANCHING PRESERVATION: - ✅ Still 4 distinct story paths (Infrastructure/Data/Supply Chain/Corporate) - ✅ Still meaningful choice with permanent consequences - ✅ Still deterministic outcomes matrix for unchosen operations - ✅ Still unique antagonists per branch (via video feeds) - ✅ Still branch-specific technical challenges at crisis terminals BENEFITS: - Drastically reduces development time (1 scenario vs 4) - Easier to maintain consistency across branches - Simpler testing (test shared rooms once, then 4 crisis terminal variations) - Cleaner file structure - More realistic (command center coordination vs field deployment) Next Steps: - Update stage 0 planning documents to reflect single-location design - Begin scenario.json.erb implementation with shared rooms - Implement choice mechanism in Emergency Briefing Room - Build crisis terminal templates
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.