mirror of https://github.com/cliffe/BreakEscape.git synced 2026-02-20 13:50:46 +00:00

Files

Z. Cliffe Schreuders bca619aeac Add Lock Scenario and System Architecture Documentation

- Introduced `LOCK_SCENARIO_GUIDE.md` to provide a comprehensive reference for implementing locks in scenarios, detailing room and object lock configurations, lock types, and quick examples.
- Added `LOCK_SYSTEM_ARCHITECTURE.md` to outline the data flow from scenario definition to server validation, including steps for scenario definition, server bootstrap filtering, client lock checks, and server validation processes.
- Included security notes and references for various lockable object types and items related to the locking system.

2025-11-29 23:46:39 +00:00

1.8 KiB

Raw Blame History

Lock System Architecture

How locks flow from scenario definition to server validation.

Data Flow

scenario.json.erb → Server Bootstrap → Client Game → Unlock Attempt → Server Validation

1. Scenario Definition

Locks are defined on rooms (for doors) or objects (for containers):

{
  "room_id": {
    "locked": true,
    "lockType": "pin",
    "requires": "1234"
  }
}

2. Server Bootstrap Filtering

When game starts, filtered_scenario_for_bootstrap sends room metadata to client:

Kept: locked, lockType, keyPins, difficulty
Removed: requires (for pin/password/key - the "answer")
Kept: requires (for rfid/biometric/bluetooth - references collectible items)

3. Client Lock Check

When player interacts with a locked door/object:

handleUnlock() gets lock requirements from sprite properties
Checks lockRequirements.locked - if false, asks server to verify
If locked, launches appropriate minigame based on lockType

4. Server Validation

validate_unlock(target_type, target_id, attempt, method):

Method	Server Validates
`key`	Player has matching `key_id` in inventory
`lockpick`	Player has lockpick in inventory
`pin`/`password`	`attempt` matches room's `requires`
`rfid`/`biometric`/`bluetooth`	Trusted (client validated item possession)
`npc`	NPC encountered + has unlock permission
`unlocked`	Room has `locked: false` in scenario

5. Unlock Success

On success:

Server adds room to player_state['unlockedRooms']
Server returns roomData for the connected room
Client opens door and loads room

Security Notes

PINs/passwords validated server-side only
Keys validated against server inventory
requires field stripped for exploitable locks
Already-unlocked rooms bypass validation

1.8 KiB Raw Blame History