- Added functionality to include current player inventory in game state for page reload recovery, allowing players to restore their inventory seamlessly.
- Implemented filtering of container contents to exclude items already in the player's inventory, enhancing user experience and gameplay clarity.
- Updated game mechanics to support both type-based and ID-based matching for inventory items, improving task validation and objectives tracking.
- Enhanced logging for better visibility into inventory processing and container content loading, aiding in debugging and game state management.
- Updated scenarios to reflect changes in item identification and task requirements, ensuring consistency across gameplay elements.
- Added support for submit_flags tasks in GamesController, allowing players to submit flags for validation and task completion.
- Updated game state management to track submitted flags and validate against required flags for task completion.
- Enhanced ObjectivesManager to handle flag submissions, including syncing progress with the server and managing task states.
- Introduced a new locksmith NPC for lockpicking tutorials, expanding gameplay elements and player engagement.
- Updated scenario schema to include submit_flags task type and associated properties, ensuring proper integration into the game mechanics.
- Improved logging and debugging information for flag submissions and task progress updates, enhancing visibility into game state changes.
- Introduced a lab workstation popup in the game interface for accessing lab sheets via an iframe.
- Implemented JavaScript functions to create, open, and close the lab workstation, enhancing user interaction.
- Updated CSS styles for the lab workstation popup to ensure a seamless visual experience.
- Enhanced interaction handling to allow players to open lab workstations from inventory items.
- Added new scenario files for the Linux Fundamentals and Security Lab, including detailed instructions and objectives for players.
- Updated scenario schema to include the new lab workstation type, ensuring proper integration into the game mechanics.
- Added logging for the number of NPCs in a room when loading it, improving visibility into game state.
- Ensured NPC encounters are tracked when unlocking doors, even when using cached room data, to maintain accurate encounter statistics.
- Cleaned up unnecessary whitespace in `games_controller.rb`, `missions_controller.rb`, `game.rb`, `mission.rb`, `routes.rb`, `seeds.rb`, and migration files to enhance code readability.
- Standardized comment formatting across various files to maintain consistency and improve clarity.
- Updated `GamesController` to parse and store VM IPs from JSON input, improving player state management.
- Modified `Game` model to include VM IPs in the context for better integration with gameplay.
- Enhanced `Mission` model's `vm_object` method to override IPs from the context when available.
- Revamped `new.html.erb` to provide a clearer interface for entering VM IP addresses and flag hints.
- Improved `vm-launcher-minigame.js` to display VM IPs and provide connection instructions in standalone mode.
- Updated `GamesController` and `Game` model to include RFID lock types in the filtering logic for 'requires' attributes, ensuring proper handling of biometric, bluetooth, and RFID types.
- Improved `RFIDMinigame` to standardize card ID retrieval, supporting both `card_id` and `key_id`.
- Enhanced `unlock-system.js` to prioritize physical keycard checks and streamline the unlocking process with detailed logging.
- Adjusted scenario JSON files to replace `keyId` with `card_id` for consistency and added new lock requirements for various rooms.
- Updated `GamesController` to support XML flag hints for standalone mode, improving backward compatibility with legacy flag input.
- Introduced `parse_flag_hints_xml` method in `Mission` model to extract flags from XML content.
- Enhanced `Game` model to incorporate `flags_by_vm` from player state for better flag management.
- Modified `new.html.erb` to update UI for flag hints input, replacing the previous comma-separated flags format.
- Improved `FlagStationMinigame` to display accepted VM flags and handle flag submissions more effectively.
- Adjusted scenario JSON to include flag stations with VM-specific flag handling.
- Added `vm_object` method in `mission.rb` to fetch VM details from context or return a fallback.
- Introduced new images for VM launchers and flag stations in the assets directory.
- Updated `game.js` to preload new VM launcher and flag station images.
- Refactored `vm-launcher-minigame.js` to streamline VM handling and improve UI messaging.
- Adjusted scenario JSON to utilize the new `vm_object` method for VM data retrieval.
- Updated `GamesController` to use `current_player` for VM set retrieval.
- Improved `MissionsController` to handle redirection for both Hacktivity and standalone modes.
- Modified `new.html.erb` to include UI for standalone flag input alongside VM set selection.
- Added new CSS styles for standalone mode instructions and flags input form.
- Introduced new mission configuration for the SecGen VM Lab, integrating VM and flag capture elements.
- Updated `MissionsController` to use explicit paths for redirection to ensure compatibility in engine context.
- Enhanced `Game` model to build VM context conditionally based on mission requirements and Hacktivity mode.
- Adjusted `show.html.erb` to reflect explicit API base paths and improved handling of player state for JSON responses.
- Added ObjectivesManager to track mission objectives and tasks.
- Created ObjectivesPanel for displaying objectives in a collapsible HUD.
- Integrated objectives state restoration from the server during game initialization.
- Implemented task completion and unlocking mechanisms via game actions.
- Added CSS styles for the objectives panel with a pixel-art aesthetic.
- Developed a test scenario to validate the objectives system functionality.
- Updated database schema to include fields for tracking completed objectives and tasks.
- Updated NPC ink loading tests to ensure proper handling of missing story files.
- Adjusted lazy loading tests for rooms to enhance clarity and maintainability.
- Enhanced unlock system tests by adding inventory checks for keys.
- Refined filtered scenario tests to ensure accurate preservation of game state.
- Improved game model tests to validate unlock functionality with various inventory scenarios.
- Added `Cybok` model to manage CyBOK entries associated with missions.
- Implemented `by_collection` scope in `Mission` model for filtering missions by collection.
- Updated `missions_controller` to filter missions based on the selected collection.
- Introduced `CybokSyncService` for syncing CyBOK data from mission metadata to the database.
- Created new views and partials for displaying CyBOK information with tooltips using Tippy.js.
- Added metadata fields to `break_escape_missions` for `secgen_scenario` and `collection`.
- Enhanced mission seeding logic to support new metadata and CyBOK entries.
- Added multiple new mission scenarios with associated metadata.
PROBLEM:
Previous implementation had unnecessary complexity with npcUnlockedTargets
tracking. NPC unlocks should just work like any other unlock method.
SOLUTION:
1. Removed npcUnlockedTargets tracking (not needed)
2. NPC unlocks now use standard unlockedRooms/unlockedObjects arrays
3. Updated validate_unlock to check if already unlocked FIRST:
- If in player_state unlocked list → grant access
- If method='unlocked' → verify against scenario data locked field
- Otherwise → validate normally
This fixes the race condition issue:
- NPC calls unlock API with method='npc'
- Server validates NPC has permission
- Server adds to unlockedRooms (normal unlock)
- Later when player opens door, client sends method='unlocked'
- Server sees it's already in unlockedRooms OR unlocked in scenario → grants access
Changes:
- app/models/break_escape/game.rb: Remove npc_unlock_target!/npc_unlocked?, check unlocked state first
- app/controllers/break_escape/games_controller.rb: Remove npc_unlock_target! calls
- test/integration/unlock_system_test.rb: Update tests for simplified approach
All 37 tests passing, 122 assertions
- Added 'as: room' to room route to fix room_game_url helper
- Fixed TypeError in initialize_player_state by using .dup instead of .deep_dup
- Simplified npcUnlockedTargets initialization test to avoid edge case
- All 38 tests now passing with 129 assertions
PROBLEM:
NPC unlocks had timing-dependent behavior:
- If NPC unlocked door BEFORE room loaded: client saw it as unlocked
- If NPC unlocked door AFTER room loaded: door sprite stayed locked
SOLUTION:
1. Server-side persistent tracking:
- Added npcUnlockedTargets array to player_state
- Track all NPC unlocks separately from unlockedRooms/unlockedObjects
- Initialize npcUnlockedTargets in new games
2. Server merges NPC unlock state:
- filtered_room_data checks npcUnlockedTargets
- Marks doors/containers as unlocked if NPC unlocked them
- Works regardless of when room is loaded
3. Client updates existing sprites:
- NPC unlock handler finds ALL door sprites for target room
- Updates sprite state immediately after server unlock
- Handles both pre-loaded and late-loaded rooms
Changes:
- app/models/break_escape/game.rb: Add npc_unlock_target!, npc_unlocked?, merge state in filtered_room_data
- app/controllers/break_escape/games_controller.rb: Track NPC unlocks in unlock endpoint
- public/break_escape/js/minigames/person-chat/person-chat-conversation.js: Update all door sprites after NPC unlock
- public/break_escape/js/systems/doors.js: Export unlockDoor globally
- test/integration/unlock_system_test.rb: Add 4 tests for persistent NPC unlock state
Created test suite with 34 tests covering all unlock scenarios and security:
DOOR TESTS (10 tests):
- PIN/password validation (correct/incorrect, case sensitivity)
- Key unlocks (client-validated)
- Unlocked doors (method='unlocked')
CONTAINER TESTS (8 tests):
- PIN/password validation
- Key, lockpick, biometric, bluetooth, RFID unlocks
- Unlocked containers
NPC UNLOCK TESTS (6 tests):
✅ NPC can unlock door/container if encountered and has permission
🔒 SECURITY: Fails if NPC not encountered
🔒 SECURITY: Fails if NPC lacks permission for that target
🔒 SECURITY: Fails for non-existent NPC
🔒 SECURITY: Fails if unlockable is not an array
SECURITY TESTS - BYPASS PREVENTION (4 tests):
🔒 CRITICAL: Locked door CANNOT be bypassed with method='unlocked'
🔒 CRITICAL: Locked container CANNOT be bypassed with method='unlocked'
✅ Unlocked door CAN use method='unlocked'
✅ Unlocked container CAN use method='unlocked'
ERROR CASES (3 tests):
- Non-existent doors/objects return 422
- Invalid methods return 422
DATA FILTERING (2 tests):
- Verify 'requires' field filtered from responses
- Verify recursive filtering of contents
INTEGRATION (1 test):
- Multiple sequential unlocks
- Idempotent operations
Test Results: 34 runs, 115 assertions, 0 failures
Server Implementation:
- validate_npc_unlock: Validates NPC encounter and permission list
- find_npc_in_scenario: Searches all rooms for NPC
- method='npc': New unlock method requiring NPC id as attempt
Client Implementation:
- Updated handleUnlockDoor to call server API with method='npc'
- Server validates all NPC unlock requests
- No client-side lock manipulation
Security Principle: All unlock authorization is server-side.
Client cannot bypass locks by manipulating state or claiming NPC unlocks.
Fixed critical vulnerability where ANY locked door/container could be bypassed
by sending method='unlocked' to the server.
The Vulnerability:
- Server used OR logic: if method == 'unlocked' || !room['locked']
- This meant: "If client says unlocked OR room is unlocked, grant access"
- Attacker could bypass ANY lock by sending method='unlocked'
- Example exploit: {targetType: "door", targetId: "ceo", method: "unlocked"}
The Fix:
- Changed to AND logic: if method == 'unlocked' && !room['locked']
- Now means: "Only if client says unlocked AND room is ACTUALLY unlocked"
- Added explicit rejection: return false if method='unlocked' on locked item
- Server now logs SECURITY VIOLATION when bypass is attempted
Changes:
- game.rb:151: Changed || to && for doors
- game.rb:157-160: Added explicit rejection for locked doors
- game.rb:185: Changed || to && for objects
- game.rb:191-194: Added explicit rejection for locked objects
Tests Added (4 new security tests):
1. Verify locked door CANNOT be bypassed with method='unlocked' (422 error)
2. Verify locked container CANNOT be bypassed with method='unlocked' (422 error)
3. Verify unlocked door CAN use method='unlocked' (200 success)
4. Verify unlocked container CAN use method='unlocked' (200 success)
Test Results: 28 tests, 95 assertions, 0 failures
Security Principle: Client state is NEVER trusted for authorization.
Server validates against its own scenario_data, not client claims.
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.
- 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.
- 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 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
- 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!
