BreakEscape/.github/copilot-instructions.md

Break Escape: AI Coding Agent Instructions

Project Overview

Break Escape is a web-based educational game framework combining escape room mechanics with cyber-physical security learning. Players navigate 2D top-down environments (powered by Phaser.js), collect items, and solve security-themed mini-games aligned to the Cyber Security Body of Knowledge (CyBOK).

Architecture

Core Systems (Sequential Initialization)

1. Game Engine (js/core/game.js): Phaser.js initialization, scene management (preload → create → update)
2. Rooms (js/core/rooms.js): Dynamic room loading from JSON scenarios, depth layering by Y-position + layer offset
3. Player (js/core/player.js): Character sprite with pathfinding, keyboard/mouse controls, animation system
4. Systems (js/systems/): Modular subsystems (interactions, inventory, doors, collisions, biometrics)
5. Mini-games (js/minigames/): Framework-based educational challenges (lockpicking, password, biometrics, etc.)

Data Flow

• Scenarios (JSON) → loaded into window.gameScenario → populate rooms/objects → create interactive environment
• Player Actions → interaction system checks proximity → triggers object interactions or mini-games
• Game State stored in window.gameState: { biometricSamples, bluetoothDevices, notes, startTime }

Global Window Object

Break Escape attaches critical runtime objects to window for cross-module access (no complex bundling):

window.game              // Phaser game instance
window.gameScenario      // Current scenario JSON
window.player            // Player sprite
window.rooms             // Object of room data
window.gameState         // Persistent game state
window.inventory         // Player's collected items

Key Patterns & Conventions

Room System & Depth Calculation

Every object's depth = worldY + layerOffset (not Z-index). This ensures correct perspective in top-down view:

• Walls: roomY + 0.2
• Interactive Objects: objectBottomY + 0.5
• Player: playerBottomY + 0.5
• Doors: doorY + 0.45

See js/core/rooms.js (lines 1-40) for detailed depth hierarchy documentation.

Object Interactions

1. Objects must have interactable: true and active: true in scenario JSON
2. Interaction distance: INTERACTION_RANGE = 64px (checked every 100ms)
3. Interaction handlers in js/systems/interactions.js dispatch to specialized systems:
   • Locks: unlock-system.js (key-based, password, PIN, biometric)
   • Doors: doors.js (movement triggers)
   • Inventory: inventory.js (item collection)
   • Biometrics: biometrics.js (fingerprint collection/scanning)

Mini-game Framework

All mini-games extend MinigameScene (js/minigames/framework/base-minigame.js):

// Registration in js/minigames/index.js
MinigameFramework.registerScene('game-name', GameClass);

// Usage
window.MinigameFramework.startMinigame('game-name', { data });

Mini-games handle modal display, pause/resume, and return callbacks automatically.

Inventory System

• Items stored as objects with id, name, texture properties
• Item identifiers created via createItemIdentifier() for UI display
• Starting items defined in startItemsInInventory array at scenario root level
• Starting items automatically added to inventory on game initialization

Scenario JSON Structure

{
  "scenario_brief": "Mission description",
  "endGoal": "What player must accomplish",
  "startRoom": "room_id",
  "startItemsInInventory": [
    {
      "type": "object_type",
      "name": "Display name",
      "takeable": true,
      "observations": "Item description"
    }
  ],
  "rooms": {
    "room_id": {
      "type": "room_type",
      "connections": { "north": "next_room" },
      "objects": [
        {
          "type": "object_type",
          "name": "Display name",
          "takeable": false,
          "interactable": true,
          "scenarioData": { /* unlock conditions */ }
        }
      ]
    }
  }
}

Essential Development Workflows

Adding a New Security Challenge

1. Create mini-game class in js/minigames/{challenge-name}/
2. Extend MinigameScene base class (see js/minigames/framework/base-minigame.js)
3. Register in js/minigames/index.js and export
4. Trigger from interactions via window.MinigameFramework.startMinigame()

Adding Scenario Content

1. Create scenarios/{name}.json with room/object definitions
2. Use existing room types from assets/rooms/*.json Tiled files
3. Objects must match registered texture names (loaded in game.js preload)
4. Reference scenarios from scenario_select.html

Debugging Game Issues

• Player stuck/pathfinding: Check STUCK_THRESHOLD (1px) and PATH_UPDATE_INTERVAL (500ms) in constants.js
• Object not interactive: Verify interactable: true, active: true, and INTERACTION_RANGE distance in scenario JSON
• Depth/layering wrong: Recalculate depth = worldY + layerOffset in rooms.js hierarchy
• Mini-game not loading: Verify registered in minigames/index.js and exported from minigame class

Project-Specific Patterns

Tiled Map Integration

Rooms use Tiled editor JSON format (assets/rooms/*.tmj). Key workflow:

• Objects stored in map.getObjectLayer() collections
• Tiled object GID → texture lookup via tileset registry
• TiledItemPool class manages available objects to prevent duplicates

External Dependencies

• Phaser.js v3.60: Game engine (graphics, physics, input)
• EasyStar.js v0.4.4: Pathfinding (A* algorithm for player movement)
• CyberChef v10.19.4: Embedded crypto tools (iframe-based in laptop minigame)

URL Versioning Convention

Assets use query string versioning: import { x } from 'file.js?v=7' to bust browser cache during development.

CSS Styling Conventions

Maintain pixel-art aesthetic consistency:

• Avoid border-radius - All UI elements use sharp, 90-degree corners
• Borders must be exactly 2px - This matches the pixel-art tile size (32px tiles = 2px scale factor)
• Examples: buttons, panels, modals, and input fields in css/*.css

Quick Command Reference

Local Development

python3 -m http.server  # Start local web server (root dir)
# Access: http://localhost:8000/scenario_select.html

Scenario Testing

• Edit scenario JSON directly
• Reload browser (hard refresh if using version queries)
• Test from scenario_select.html dropdown

Files to Read First When Onboarding

1. README.md - Project overview and feature list
2. js/main.js - Game initialization and global state setup
3. js/core/game.js - Phaser scene lifecycle and asset loading
4. js/core/rooms.js - Room management and depth layering documentation
5. scenarios/biometric_breach.json - Full example scenario structure
6. js/minigames/framework/minigame-manager.js - Mini-game architecture