- Move scenarios from app/assets/scenarios/ to scenarios/
- Update Mission model to use BreakEscape::Engine.root instead of Rails.root
- Update seeds.rb to use engine root for scenario discovery
- Update tests to use engine root for path assertions
This ensures scenarios are found correctly in both mounted (Hacktivity)
and standalone (test) environments.
All 12 tests now passing with 19 assertions!
- Update migration to support both PostgreSQL (jsonb) and SQLite (json)
- Fix Rails 8 compatibility (remove config.assets)
- Configure Pundit to use current_player instead of current_user
- Add explicit fixture class mappings for engine fixtures
- Configure standalone mode for tests
- Update test fixtures with proper timestamps and structure
- Improve game test to create data programmatically
Tests now run with 10/12 assertions passing. Remaining errors are due to
missing test scenario files, which can be addressed separately.
- Update README with complete feature list and usage
- Add architecture documentation (ERB, JIT, state management)
- Create HACKTIVITY_INTEGRATION.md guide
- Include installation, configuration, and troubleshooting
- Document API endpoints and security considerations
- Add monitoring and performance notes
Rails Engine Migration Complete! 🎉
- Create DemoUser migration for standalone development
- Add DemoUser model with polymorphic games association
- Add configuration system (standalone vs mounted)
- Use ENV variables for configuration
- current_player method supports both modes (ApplicationController)
- Can run without Hacktivity for development
- Add fixtures for missions, demo_users, games
- Add model tests for Mission and Game
- Add controller tests for MissionsController
- Test validations, scopes, and methods
- Test state management and health clamping
- Ready for integration testing in host app
- Add config.js for API configuration and CSRF token handling
- Add api-client.js wrapper for server communication
- Add state-sync.js for periodic state synchronization
- Support multiple CSRF token sources (config object and meta tag)
- Provide detailed error messages for configuration issues
- Enable GET/POST/PUT requests with proper auth headers
- Expose ApiClient globally for game code integration
- Add missions index view with grid layout
- Add game show view with Phaser container
- Include CSP nonces for inline scripts
- Bootstrap game configuration in window object
- Load game CSS and JavaScript
- Add ApplicationPolicy base class
- Add GamePolicy (owner or admin can access)
- Add MissionPolicy (published visible to all)
- Implement Scope for filtering records
- Support admin and account_manager roles
- Add MissionsController for scenario selection
- Add GamesController with scenario/ink endpoints
- Add JIT Ink compilation logic
- Add API::GamesController for game state management
- Configure routes with REST + API endpoints
- Add authorization hooks (Pundit)
- Add polymorphic player support (current_player helper)
- Create missions from scenario directories
- Auto-discover scenarios in app/assets/scenarios/
- Simple metadata only (no scenario data in DB)
- Scenario data generated on-demand via ERB
- Create break_escape_missions table (metadata only)
- Create break_escape_games table (state + scenario snapshot)
- Add Mission model with ERB scenario generation
- Add Game model with state management methods
- Use JSONB for flexible state storage
- Polymorphic player association (User/DemoUser)
- Move scenario JSON files to app/assets/scenarios/
- Rename to .erb extension (24 scenarios converted)
- Keep .ink files in scenarios/ink/ for JIT compilation
- Each scenario now in own directory
- Add conversion script for future use
- Move js/ to public/break_escape/js/
- Move css/ to public/break_escape/css/
- Move assets/ to public/break_escape/assets/
- Preserve git history with mv command
- Keep index.html.reference for reference
- Create mountable engine with isolated namespace
- Configure Pundit authorization
- Set up gemspec with dependencies
- Configure generators for test_unit with fixtures
User correctly pointed out the loading UI was over-engineered.
## Simplifications:
### Before (over-complicated):
- Complex timeline management
- Success/failure flash effects (green/red)
- Spinner alternatives
- Stored references on sprites
- Timeline cleanup logic
- ~150 lines of code
### After (simple):
- startThrob(sprite) - Blue tint + pulsing alpha
- stopThrob(sprite) - Kill tweens, reset
- ~20 lines of code
## Why This Works:
1. **Door sprites get removed anyway** when they open
2. **Container items transition** to next state automatically
3. **Game already shows alerts** for success/error
4. **Only need feedback** during the ~100-300ms API call
## API Changes:
- showUnlockLoading() → startThrob()
- clearUnlockLoading() → stopThrob()
- No success/failure parameter needed
- No stored references to clean up
## Result:
From 150+ lines down to ~30 lines total.
Same UX, much simpler implementation.
User feedback: "Just set the door or item to throb, and remove when
the loading finishes (the door sprite is removed anyway), and if it's
a container, just follow the unlock with a removal of the animation."
User correctly noted that Hacktivity's application layout already includes
csrf_meta_tags, so we don't need to add them again.
## Changes:
### Section 9.3.1: Layout Strategy
- Split into Option A (Hacktivity layout - recommended) and Option B (standalone)
- **Option A (Recommended):** Read from existing meta tag
- Uses Hacktivity's csrf_meta_tags (already present in layout)
- No duplicate meta tags needed
- Reads via: document.querySelector('meta[name="csrf-token"]')?.content
- **Option B:** Standalone layout
- For when engine needs separate layout
- Must add <%= csrf_meta_tags %> to engine layout
- Can use <%= form_authenticity_token %> directly
### Section 9.3.3: Token Reading Logic
- Updated config.js to try multiple sources:
1. window.breakEscapeConfig.csrfToken (if explicitly set)
2. meta[name="csrf-token"] tag (from Hacktivity layout)
- Better error messages showing all sources checked
- Logs which source provided the token
### Section 9.3.5: Issue #2 Solution
- Updated to reference the fallback logic in 9.3.3
- Added debugging console commands
- Shows how to check all meta tags
## Key Points:
- ✅ Hacktivity layout csrf_meta_tags are reused (don't duplicate)
- ✅ Fallback chain ensures token found from either source
- ✅ Clear guidance for both integration scenarios
- ✅ Better debugging when token is missing
This aligns with Rails best practices and Hacktivity's existing setup.
Based on comprehensive codebase review, enhanced implementation plans with:
## Phase 3 Updates (Scenario Conversion):
- Complete bash script to convert all 26 scenarios to ERB structure
- Explicit list of 3 main scenarios (ceo_exfil, cybok_heist, biometric_breach)
- List of 23 test/demo scenarios for development
- Instructions to rename .json to .erb (actual ERB code added later in Phase 4)
- Preserves git history with mv commands
- Both automated script and manual alternatives provided
## Phase 9 Updates (CSRF Token Handling):
NEW Section 9.3: "Setup CSRF Token Injection"
- Critical security implementation for Rails CSRF protection
- Complete view template with <%= form_authenticity_token %>
- JavaScript config injection via window.breakEscapeConfig
- CSRF token validation and error handling
- Browser console testing procedures
- 5 common CSRF issues with solutions
- Fallback to meta tag if config missing
- Development vs production considerations
## Phase 9 Updates (Async Unlock with Loading UI):
ENHANCED Section 9.5: "Update Unlock Validation with Loading UI"
- New file: unlock-loading-ui.js with Phaser.js throbbing tint effect
- showUnlockLoading(): Blue pulsing animation during server validation
- clearUnlockLoading(): Green flash on success, red flash on failure
- Alternative spinner implementation provided
- Complete unlockTarget() rewrite with async/await server validation
- Loading UI shows during API call (~100-300ms)
- Graceful error handling with user feedback
- Updates for ALL lock types: pin, password, key, lockpick, biometric, bluetooth, RFID
- Minigame callback updates to pass attempt and method to server
- Testing mode fallback (DISABLE_SERVER_VALIDATION)
- Preserves all existing unlock logic after server validation
## Key Features:
- Addresses 2 critical risks from review (CSRF tokens, async validation)
- Solves scenario conversion gap (26 files → ERB structure)
- Maintains backward compatibility during migration
- Comprehensive troubleshooting guidance
- Production-ready security implementation
Total additions: ~600 lines of detailed implementation guidance
Complete documentation for:
- 04_API_REFERENCE.md: All 9 API endpoints with examples
- 05_TESTING_GUIDE.md: Minitest strategy with fixtures and tests
These complete the documentation set along with the Hacktivity integration guide.
Major simplification to migration plan:
- Remove NpcScript model entirely
- Reduce to 2 tables: missions (metadata) + games (state + scenario snapshot)
- Serve ink files directly from filesystem via game endpoints
- Move scenario_data to game instances (enables per-instance randomization)
- Eliminates Issue #2 (NPC schema complexity)
- Reduces P0 fixes from 10 hours to 2-3 hours
- Much simpler seed process (metadata only)
- Identify 5 critical issues requiring fixes before implementation
- Validate architecture decisions (mostly solid)
- Provide corrected database schema for shared NPCs
- Document P0 fixes needed: Ink compilation, file structure, NPC schema
- Recommend 1.5 days of prep work to save 3-5 days of rework
- Total review: 6 documents covering issues, architecture, and solutions
Generated by automated codebase analysis.
Provides detailed breakdown of project structure, systems, and components.
Referenced by updated migration plans.
Updated migration plans to reflect significant codebase evolution:
NEW SYSTEMS DOCUMENTED:
- NPC system (fully implemented with NPCManager, conversation state, events)
- Event system (80+ events across codebase)
- Global game state management (window.gameState.globalVariables)
- Multiple scenarios (24 total, up from 1 originally planned)
KEY UPDATES:
- UPDATED_MIGRATION_STATUS.md: Comprehensive status of what's changed
- What's implemented vs what still needs server-side integration
- Updated timeline: 22 weeks (was 18 weeks)
- New database schema requirements
- Updated risk assessment
- CLIENT_SERVER_SEPARATION_PLAN.md: Added 3 new systems
- System 5: NPC System (hybrid approach confirmed)
- System 6: Event System (selective logging)
- System 7: Global Game State (server as source of truth)
- Updated migration checklist: 9 phases (was 7)
- Updated timeline: 18-22 weeks
- README_UPDATED.md: New master index document
- Quick start guide
- Document index
- What's changed summary
- Timeline breakdown
- Architecture decisions
- Success metrics
MIGRATION APPROACH:
- Hybrid NPC approach: Scripts client-side, validation server-side
- Selective event logging: Critical events only
- State sync: Server as source of truth, client cache for performance
- Incremental rollout with dual-mode support
TIMELINE: 22 weeks (~5.5 months)
- Added 4 weeks for NPC, Event, State integration
- Original: 18 weeks → Updated: 22 weeks (+22%)
All plans are complete, self-contained, actionable, and feature-focused.
Ready for team review and implementation.
Create comprehensive Ink dialogue files for five security tools:
- Kali Linux: Overview and getting started guide
- nmap: Port scanning and network discovery
- Metasploit: Finding and running exploits
- chmod: File permissions and usage
- nikto: Web vulnerability scanning
Each file provides interactive educational content with:
- Multiple topic branches for different aspects
- Practical examples and use cases
- Step-by-step instructions
- Security and ethical usage reminders
- Navigation between related topics
These files can be included in game scenarios to provide
contextual help to players learning security tools.
- Remove ready_for_practice and challenge_tips sections
- Update encoding_encryption.ink header and start section
- Clean exploitation.ink and post_exploitation.ink references
- Ensure all files use consistent game narrative format
- exploitation.ink
- post_exploitation.ink
- phishing_social_engineering.ink
- encoding_encryption.ink
- feeling_blu_ctf.ink
All files now use consistent Haxolottle character and conversational tone
- Add nmap_basics.ink, metasploit_basics.ink, netcat_basics.ink as reusable tools
- Completely rewrite intro_linux.ink:
- Remove all unnecessary tracking variables
- Change from 'Tech Instructor' to 'Haxolottle'
- Remove lab/training/exercise language
- Convert to helpful NPC offering to explain concepts
- Keep all technical content but make conversational
- Link to reusable tool files where appropriate
- Use proper ink patterns (hub structure, #exit_conversation)
- Copy all lab sheets to game_scenarios/ for narrative conversion
- Add dead_drop_system.ink explaining ENTROPY's flag-based communication
- Prepare for converting educational labs into game challenges
