mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 19:28:03 +00:00
26a5d6fafa
Created OBJECTIVES_VERIFICATION.md to confirm objectives are clear and constant: ✅ Verification Status: PASS - 5 well-defined objectives with descriptive titles - 15 specific tasks with explicit completion criteria - Consistent across all files (scenario.json.erb, SOLUTION_GUIDE.md, Ink scripts) - Progressive unlock structure ensures linear story flow - Multiple solution paths documented for flexibility Objectives Summary: 1. Infiltrate Hospital (3 tasks) - Active at start 2. Access IT Systems (3 tasks) - Unlocks after Objective 1 3. Exploit ENTROPY's Backdoor (4 tasks) - Unlocks after server room access 4. Recover Offline Backup Keys (3 tasks) - Unlocks after database flag 5. Make Critical Decisions (2 tasks) - Unlocks after Objectives 3 & 4 Cross-File Verification: ✅ scenario.json.erb: 5 objectives, 15 tasks ✅ SOLUTION_GUIDE.md: 5 objectives, 15 tasks (documented) ✅ Ink scripts: Reference tasks via #complete_task tags ✅ Global variables: Track objective states Progression Flow: Start → Obj 1 → Obj 2 → Obj 3 + Obj 4 → Obj 5 → Complete Completion Requirements: - Minimum (60%): 2+ VM flags, offline keys, both moral choices - Perfect (100%): All 15 tasks, 4 VM flags, 3 LORE fragments, Marcus protected Player-Facing Clarity: - Clear task titles guide player actions - Progressive unlocking prevents confusion - Multiple solution paths (social, stealth, combat) - No ambiguity in completion criteria Optional Content (not required for completion): - Marcus Protection Choice (moral decision) - LORE Fragment Collection (3 fragments for narrative depth) Result: Mission 2 objectives are clear, constant, and suitable for: - Player guidance during gameplay - Completion tracking for mission scoring - Educational assessment of learning outcomes - Narrative pacing and tension building
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.