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 data
• PUT /games/:id/sync_state - Sync player state
• POST /games/:id/unlock - Validate unlock attempt
• POST /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):

1. Check if .json exists and is newer than .ink
2. If needed, run inklecate to compile
3. 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.