How mahender-reddy85/escape-room works
What this project is (type + purpose)
C-ESCAPE is a frontend-only web application: a 3D escape-room game built with React + TypeScript, rendered via Three.js / React Three Fiber, bundled with Vite, and deployed to Vercel or GitHub Pages.
• A browser client containing all gameplay + rendering logic
• Static hosting (Vercel/GH Pages) delivering the app bundle
“anti-cheat protection” is implemented at the client layer (the README explicitly references index.html).
How to read the file structure (what maps to components)
Top-level files imply a typical Vite React app:
• index.html
• index.tsx
React bootstrap (mount <App />).
• App.tsx
Main React composition / routing between screens (likely StartScreen -> GameScene) and global state wiring.
• components/
• StartScreen.tsx: initial UI / start flow
• GameScene.tsx: the core 3D scene (React Three Fiber canvas, lights, physics-ish, level loading)
• Room.tsx: room geometry / level layout
• InteractiveObject.tsx: interaction wrapper (click/hover/proximity triggers)
• UIOverlay.tsx: HUD/lives/questions/instructions overlay atop 3D canvas
• constants.ts
Level definitions/config: the “5 progressive levels” and tuning knobs should be modeled as “Level Config Data”.
• types.ts
Shared domain types (Level, Question, Object interactions). Useful to infer domain boundaries: “Game State”, “Level State”, “Question Model”.
• metadata.json
Likely asset/config metadata. Treat it as “Static game data”.
• vite.config.ts, tsconfig.json, package.json
Use names that align with the project’s actual structure:
React App Shell
• index.tsx, App.tsx
Start / Navigation
• StartScreen.tsx (Start → Begin Level 1)
3D Rendering + Scene Graph
• GameScene.tsx (Canvas, camera, lighting)
• Room.tsx (room meshes/layout)
Interaction System
• InteractiveObject.tsx
• Inputs: mouse/keyboard/pointer lock (if used)
• Outputs: triggers to game state (open drawer, collect cube, attempt terminal)
Game State / Rules
• Lives (3), restart logic
• Level progression (1..5)
• Inventory: cube/key/tools
• Gate conditions: “cube powers terminal”, “key unlocks exit”, etc.
Question/Challenge Subsystem
• Gemini API call to generate/validate questions (based on README)
• Model: “Question”, “Answer”, “Attempts”, “Lives decrement”
UI Overlay / HUD
• UIOverlay.tsx
• Displays: lives, prompts, question modal, hints, success/fail
Anti-cheat Controls
• index.html scripts/event listeners
• Tab visibility change, right-click/copy prevention, refresh on suspicious activity
Google Gemini API
• Authentication via GEMINI_API_KEY (environment variable at build/deploy time)
• It as “External SaaS”
Hosting
• Vercel or GitHub Pages (Static site)
Player → Browser App
• “Pointer/keyboard input”
React App Shell ↔ Game State
• “State updates: lives, inventory, level”
GameScene → InteractiveObject
• “Registers objects / hit testing / onClick handlers”
InteractiveObject → Game State
• “Emit interaction event: open drawer / pick up cube / use terminal”
Game State → UIOverlay
• “Render HUD; show question; show lives”
Terminal Interaction → Gemini Client → Gemini API
• “HTTPS request: generate C question (topic=level)”
• “Response: question text + options/expected answer”
Answer Submission → Game State
• “Validate answer; decrement lives; progress gating”
Anti-cheat Guard → App Runtime
• “On blur/visibility change/copy: block or refresh”
• It as a cross-cutting concern attached to the browser container
Hosting/CDN → Browser
• “Serves index.html + JS bundle + assets”
Architectural patterns/design principles evident here
• Client-heavy SPA: Nearly all logic runs in the browser.
• Component composition (React): UI and 3D scene are built from modular components.
• Scene/Entity interaction abstraction: InteractiveObject.tsx suggests a reusable wrapper for click/inspect/use behavior (like a lightweight entity-component pattern).
• Configuration-driven levels: constants.ts + metadata.json implies levels and objects are driven by data rather than hardcoded logic.
• Cross-cutting security/anti-cheat: implemented at the document level (index.html) and affects all UI/scene flows.
• External dependency for content: Gemini API is a runtime dependency for generating challenges.