mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 11:18:08 +00:00
111 lines
2.7 KiB
Markdown
111 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
```ruby
|
|
gem 'break_escape', path: 'path/to/break_escape'
|
|
```
|
|
|
|
Then:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```ruby
|
|
mount BreakEscape::Engine => "/break_escape"
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Standalone Mode (Development)
|
|
|
|
```bash
|
|
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
|
|
|
|
```ruby
|
|
# 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
|
|
|
|
```bash
|
|
rails test
|
|
```
|
|
|
|
## Documentation
|
|
|
|
See `HACKTIVITY_INTEGRATION.md` for integration guide.
|