From baceea6dabbf57905a1c1fa6dddee8eca8d5647b Mon Sep 17 00:00:00 2001 From: "Z. Cliffe Schreuders" Date: Wed, 22 Oct 2025 13:29:16 +0100 Subject: [PATCH] Add AI Coding Agent Instructions: Introduce comprehensive documentation for the Break Escape project, detailing architecture, data flow, key patterns, and essential development workflows to enhance onboarding and developer understanding. --- .github/copilot-instructions.md | 152 ++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..660921a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,152 @@ +# 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): +```javascript +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`): +```javascript +// 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 +- Special handling: "inInventory" flag in scenario JSON auto-adds items on load + +### Scenario JSON Structure +```json +{ + "scenario_brief": "Mission description", + "endGoal": "What player must accomplish", + "startRoom": "room_id", + "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 +```bash +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