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

CI

Tests run automatically on GitHub Actions. The committed Gemfile.lock pins the exact gem versions used.

Locally with network access

bundle install
bundle exec rails db:create db:migrate RAILS_ENV=test
bundle exec rails test

Locally without network access

The engine ships with a bin/setup script that bootstraps the bundle from a sibling Hacktivity checkout (which already has all the required gems vendored):

# From the BreakEscape root — Hacktivity must be at ../Hacktivity
bin/setup
bundle exec rails test

# If Hacktivity is elsewhere, set HACKTIVITY_DIR:
HACKTIVITY_DIR=/path/to/Hacktivity bin/setup

bin/setup copies the resolved .gem files into vendor/cache/ and runs bundle install --local. The vendor/cache/ and vendor/bundle/ directories are gitignored; only Gemfile.lock is committed.

Documentation

See HACKTIVITY_INTEGRATION.md for integration guide.

Acknowledgments

Many thanks to everyone who has contributed to the project. Please refer to the GitHub history.

• This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.1 grant (2023-2024).
• This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.1 grant (2024-2025).
• This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around Security-Informed Safety grant (2025-2026).