Fixed issue where unlocked doors/containers couldn't be opened because
the server wasn't being notified to add them to unlockedRooms/unlockedObjects.
Server changes (game.rb):
- Updated validate_unlock to accept method='unlocked' for unlocked targets
- Added logic to grant access for unlocked doors/objects without validation
Client changes (doors.js):
- Updated handleDoorInteraction to notify server for unlocked doors
- Calls notifyServerUnlock with method='unlocked' before opening
Client changes (interactions.js):
- Added notifyServerForUnlockedContainer helper function
- Updated container interaction to notify server before launching minigame
This ensures that all room/container access is properly authorized on the
server side, preventing 403 Forbidden errors when loading room/container data.
Updated validate_unlock to use two-tier validation model:
- Server trusts client validation for item-based locks (key, lockpick, biometric, bluetooth, rfid)
- Server validates knowledge-based locks (pin, password)
This fixes 422 errors when unlocking with keys/lockpicking where attempt is nil,
since these methods don't require server-side answer validation.
- Created notifyServerUnlock helper function to DRY up code
- Updated lockpicking, key, biometric, bluetooth, and RFID unlocks to call server API
- All unlock methods now:
1. Validate unlock client-side (minigame/item check)
2. Notify server to update player_state
3. Receive room/container data in response
4. Pass serverResponse to unlockTarget
This ensures:
- Server tracks all unlocks in player_state (unlockedRooms/unlockedObjects)
- Room endpoint can validate access (403 if not unlocked)
- Single API call returns data needed (roomData for doors, contents for containers)
- Consistent behavior across all lock types
Server-side changes:
- Unlock endpoint already returns roomData for doors
Client-side changes:
- Pass serverResponse through minigame callback chain
- Store serverResponse in minigame gameResult (password & PIN)
- Update minigame-starters to pass result to callbacks
- Update unlock-system callbacks to accept and pass serverResponse
- Pass roomData to unlockDoor for doors
- Cache roomData in roomDataCache before loadRoom is called
- loadRoom checks cache before making API call
Benefits:
- Doors: Unlock + room load = 1 API call instead of 2
- Containers: Unlock + contents = 1 API call instead of 2
- More efficient, faster user experience
- Consistent pattern for both doors and containers
- Add find_object_in_scenario helper to locate objects by ID or name
- Include hasContents and contents fields in unlock response for containers
- Update password and PIN minigames to populate scenarioData.contents from server response
- This allows the container minigame to launch after successful server-side unlock
Without this, the contents field was filtered for security, preventing the container UI from launching.
- Import ApiClient in game.js to ensure window.ApiClient is set early
- Use window.breakEscapeConfig?.gameId instead of window.gameId in minigames
- Consistent with the rest of the codebase
Without importing ApiClient in the main game flow, window.ApiClient wasn't available when minigames needed it.
- Use correct ApiClient casing (window.ApiClient not window.APIClient)
- Check for both null and empty string to trigger server validation
- Add fallback to support both naming conventions
- Add debug logging to show which validation method is used
The ApiClient is exported as window.ApiClient but code was checking for window.APIClient.
- Make submit button always visible (not just when hints are enabled)
- Add console logging to track validation flow
- Debug why server validation isn't being triggered
This ensures users can submit passwords and helps diagnose validation issues.
- Add detailed logging to validate_unlock method to debug validation issues
- Check both object 'id' and 'name' fields when searching for objects
- Log password comparison details for debugging
This helps diagnose why correct passwords might not be accepted.
- Update password minigame to call server API when correctPassword is null
- Update PIN minigame to call server API when correctPin is null
- Pass lockable and type parameters to minigames for server validation
- Maintain backwards compatibility with client-side validation
- Handle network errors gracefully without counting failed attempts
This allows minigames to validate attempts server-side for security, preventing client-side answer spoofing.
- Update unlock-system.js to check 'locked' field instead of 'requires' for lock detection
- Pass null for key/pin/password required values (server validates)
- Preserve 'requires' field for biometric/bluetooth locks (contains item identifiers, not answers)
- Update both Game model and controller filtering methods
Fixes issue where locked objects didn't prompt for unlock after server-side filtering was implemented.
Changes:
- Add player_state type checking before accessing encounteredNPCs
- Reset player_state to empty hash if not a Hash type
- Add comprehensive logging for type mismatches
- Change from concat to array addition (+) to avoid in-place mutation issues
- Wrap entire method in try-catch to prevent NPC tracking from breaking room loading
- Add detailed error logging with stack traces
Fixes:
- TypeError: no implicit conversion of Array into String
- Handles legacy data where player_state might be malformed
- Room loading continues even if NPC tracking fails
Changes:
- Fix track_npc_encounters to handle case where encounteredNPCs is not an array
- Add type checking to ensure encounteredNPCs is always an array before operations
- Add comprehensive error handling and logging to room endpoint
- Add scenario_data presence check before processing room request
- Wrap room endpoint in try-catch to catch and log all errors
Fixes:
- TypeError: no implicit conversion of String into Array on line 312
- Prevents 500 errors when player_state has malformed data
- Provides clear error messages and stack traces for debugging
- Add try-catch blocks to prevent 500 errors
- Add logging to help diagnose issues
- Add nil checks for scenario_data and rooms
- Skip individual rooms that fail to process
- Return descriptive error messages for debugging
Server-side changes:
- Game model: Initialize starting items in player inventory from scenario
- Game model: Add filter_requires_and_contents_recursive to hide solutions and locked contents
- Game model: Fix filtered_room_data to preserve lockType while removing requires
- GamesController: Add scenario_map endpoint for minimal layout metadata
- GamesController: Update room endpoint with access control and NPC encounter tracking
- GamesController: Add container endpoint for lazy-loading locked container contents
- GamesController: Update inventory endpoint with comprehensive validation
- Validates item exists in scenario
- Checks item is takeable
- Verifies container is unlocked if item is in container
- Verifies room is unlocked if room is locked
- Checks NPC is encountered if item held by NPC
- GamesController: Update unlock endpoint with transaction safety
- GamesController: Update sync_state to verify room accessibility
- Routes: Add scenario_map and container routes
Client-side changes:
- inventory.js: Make addToInventory async and add server validation before local updates
- container-minigame.js: Add lazy-loading of container contents from server
- game.js: Update to use scenario_map endpoint for reduced initial payload
- api-client.js: Add getScenarioMap method alongside getScenario
Security improvements:
- Prevents client-side cheating by validating all actions server-side
- Hides solution fields (requires) from client responses
- Hides locked container contents until unlocked
- Enforces room and container access controls
- Tracks NPC encounters automatically
- All validation failures return clear error messages
Implements plans from:
- planning_notes/validate_client_actions/GOALS_AND_DECISIONS.md
- planning_notes/validate_client_actions/IMPLEMENTATION_PLAN.md
- Added server-side validation for inventory actions, ensuring items are validated before being added to the player's inventory.
- Updated client-side `addToInventory()` function to include server validation and error handling for inventory actions.
- Implemented container loading logic to fetch contents from the server, handling locked containers appropriately.
- Enhanced player state initialization to ensure starting items are correctly added to the inventory.
- Clarified NPC `itemsHeld` structure and updated validation logic to match the expected item format.
- Improved error handling for room access and container interactions, including transaction safety for state mutations.
- Introduced new endpoints for scenario mapping and bulk inventory synchronization.
- Added performance optimizations, including caching filtered room data and implementing JSON schema validation for item structures.
- Established a detailed implementation plan with phased priorities and testing gaps identified for future work.
- Implement RoomLazyLoadTest to verify room data retrieval and error handling for non-existent rooms.
- Create FilteredScenarioTest to ensure scenario data is filtered correctly for game initialization, preserving navigation structure while removing unnecessary details like objects and NPCs.
- Add tests for lock requirements and ensure original scenario data remains unmodified after filtering.
- Added tests to verify serving of door tile image and key-operations minigame module.
- Created new NPCInkLoadingTest to check various scenarios for NPC story file loading:
- Return 404 for NPCs without story files and for non-existent NPCs.
- Validate handling of missing NPC parameter.
- Ensure correct API endpoint construction in npc-lazy-loader.
- Verify person-chat and phone-chat minigames use the correct story loading endpoint.
- Confirm npc-manager loads stories via API endpoint without direct fetch of storyPath.
- Check asset path resolution in person-chat-portraits and phone-chat-ui.
- Ensure ink endpoint returns correct MIME type and handles special characters in NPC IDs.
- Created `AssetLoadingIntegrationTest` to verify the loading of game assets in the correct order, including JavaScript, CSS, and sound files.
- Implemented tests to ensure proper handling of asset paths, security constraints, and response headers.
- Added `StaticFilesControllerUnitTest` to test the content type determination logic for various file extensions, ensuring case insensitivity and handling of multiple dots in filenames.
- Implement StaticFilesController to serve CSS, JS, and asset files for the BreakEscape engine.
- Update routes to include static file paths for CSS, JS, and assets.
- Refactor game show view to load multiple CSS files and include Google Fonts.
- Remove application stylesheet link from the layout.
- Modify various CSS files to improve layout and styling, including HUD and inventory.
- Update JavaScript files to ensure asset paths are correctly prefixed with /break_escape/.
- Enhance minigame UI components, including notifications, modals, and overlays.
- Adjust game-over screen and health UI to use correct asset paths.
- Update constants and crypto workstation utility to reflect new asset paths.
- Change stylesheet_link_tag to plain <link> tag
- Change javascript_include_tag to plain <script> tag
- Fix CSS file path from styles.css to main.css
- This prevents Rails from trying to process static files through asset pipeline
- Add HTML response tests for missions index (checks mission cards rendered)
- Add game page tests (checks game container and config injection)
- Add API endpoint tests:
* scenario endpoint returns JSON scenario data
* bootstrap endpoint returns complete game state
* sync_state endpoint updates player position
* unlock endpoint validates and rejects invalid attempts
* inventory endpoint adds items to player inventory
- Fix inventory API to use action_type instead of reserved 'action' param
All 23 tests passing with 64 assertions verifying server returns correct data!
- Add root route that redirects to missions list
- Fix ApplicationController to fallback to demo user when current_user unavailable
- Configure dummy app to load engine migrations in application.rb
- Create test/dummy/db/migrate directory
- Successfully migrated and seeded database with 26 missions
Now visiting http://localhost:3000 will show the missions selection page!
- 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
