VisionGame: Precision Image Finding Challenge

VisionGame is a modern, full-stack web application designed to test players' observational skills and speed. Players are presented with a challenging visual puzzle: finding the exact location of a small, cropped image snippet within a set of massive, highly detailed gigapixel-style images.

The project features both a serene Single-Player training mode and a highly competitive, real-time Multiplayer (PvP) mode synchronized via WebSockets.

Architecture and Technology Stack

The application relies on a decoupled Client-Server architecture and employs modern real-time event-driven design.

Frontend (Client)

• Framework: React.js with Vite
• Real-time Communication: Socket.io-client
• UI/UX: Custom CSS featuring Glassmorphism, Pop-in Modals, and responsive layouts
• Interaction: React Zoom Pan Pinch for seamless deep-zooming and panning on high-resolution targets

Backend (Server)

• Environment: Node.js
• Framework: Express.js API
• Real-time Engine: Socket.io for managing PvP lobbies, synchronized countdowns, and instant penalty distributions
• Image Processing: Sharp for dynamic, high-performance image manipulation and on-the-fly coordinate validation

Key Features

• Real-Time PvP Battles: Players can join private rooms using generated access codes. The server maintains strict state synchronization, managing timers, round transitions, and determining the winner based on speed and precision.
• Dynamic Penalty System: Incorrect guesses in PvP mode dynamically subtract time from the individual player's clock, creating an intense, risk-reward gameplay loop.
• Precision Validation: The server mathematically calculates the distance and intersection between the player's guessed bounding box and the true origin coordinates of the crop.
• Refined UX/UI: The interface is built with absolute focus. Instead of scroll-heavy pages, the game uses floating glass-morphic modals that pin the target image to the viewport while allowing the user to deeply inspect the master images.

Project Structure

The repository is divided into two main environments:

• /backend: Contains the Express server, Socket.io handlers, gameplay logic controllers, and image processing services.
• /frontend: Contains the React application, React Router configurations, and component logic.

Getting Started

Follow the instructions below to run the application locally on your machine.

Prerequisites

• Node.js (v18 or higher recommended)
• npm or yarn

Installation Steps

1. Clone the repository to your local machine.

2. Install Backend Dependencies: Navigate to the /backend directory and run:

   npm install

3. Install Frontend Dependencies: Navigate to the /frontend directory and run:

   npm install

Running the Application

For the application to function correctly, both the backend and frontend servers must run simultaneously.

1. Start the Backend Server: From the root directory or /backend, start the Express/Socket server:

   npm run dev

   The server will typically start on port 3000.

2. Start the Frontend Development Server: From the /frontend directory, spin up the Vite environment:

   npm run dev

   Vite will provide a local URL (usually http://localhost:5173).

3. Access the Game: Open the provided local URL in your web browser. You can immediately play the Single Player mode or open multiple browser tabs to simulate and test the PvP mode locally.

Design Philosophy

The user interface was built prioritizing clarity and speed. By removing unnecessary UI clutter and avoiding layout shifts (such as forcing the user to scroll up and down between the target crop and the master image), players can maintain unbroken visual concentration. Interactions are enhanced with subtle micro-animations and a unified dark theme to reduce eye strain during intensive search sessions.