Multiversal Rush | Real-Time 3D Multiplayer Racing

A high-performance WebGL multiplayer racing game featuring real-time synchronization, voice communication, and dynamic obstacle courses across multiple dimensions.

---

Overview

Multiversal Rush is an immersive 3D multiplayer racing game where players compete in real-time obstacle courses across different dimensions. Built with React Three Fiber for stunning WebGL graphics and Socket.io for seamless multiplayer synchronization, the game offers competitive racing with friends, voice chat, character customization, and a comprehensive progression system.

---

Core Features

Real-Time Multiplayer

• Socket.io-powered synchronization with sub-50ms latency
• Room-based matchmaking supporting up to 5 players per match
• Server-authoritative game state preventing cheating
• Dynamic obstacles: wind mechanics, avalanche events, snow cannons, laser grids
• Automatic elimination detection and winner determination

Progression System

• XP and leveling with dynamic requirements (100 XP base, +200 per level)
• Trophy-based global leaderboard with top 20 rankings
• 10 unique achievements with bronze/silver/gold tiers
• Match rewards: 1st place (200 XP, 15 trophies), 2nd (175 XP, 10 trophies), 3rd (150 XP, 5 trophies)

Social Features

• Friends system with real-time online status
• Direct messaging with persistent chat history
• Room invitations for private matches
• LiveKit-powered voice chat with low latency (<100ms)

In-Game Economy

• Gem currency system (earn through leveling and achievements)
• Character shop with 8+ unique 3D avatars
• Payment integration via Razorpay (India) and Stripe (Global)
• Secure transactions with HMAC-SHA256 verification

Game Modes

• Solo Race: Compete individually in fast-paced obstacle courses
• Team Relay: Coordinate with teammates in relay-style races
• Private Lobbies: Create custom rooms with friends
• World Test: Practice mode for skill improvement

Admin Dashboard

• Live game monitoring with real-time room state
• User management (ban/unban, gem gifting, XP adjustments)
• Analytics dashboard (revenue, player retention, match history)
• Match history tracking and moderation tools

---

Tech Stack

Layer	Technologies
Frontend	React 18, Vite 5, React Three Fiber, React Three Drei
3D Graphics	Three.js 0.160, WebGL, GLTF models
Backend	Node.js, Express 4, Socket.io 4
Database	MongoDB 8, Mongoose ODM
Voice	LiveKit Cloud (WebRTC)
Auth	JWT, bcryptjs
Payments	Razorpay, Stripe
State	Zustand 4
Routing	React Router DOM 6

---

Quick Start

Prerequisites

• Node.js 16+
• MongoDB (local or Atlas)
• LiveKit Cloud account
• Razorpay/Stripe account (for payments)

Installation

# Clone repository
git clone https://github.com/yourusername/multiversal-rush.git
cd multiversal-rush

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install

Environment Setup

Server .env (multiversal-rush/server/.env)

PORT=5000
MONGODB_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret_key
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
LIVEKIT_URL=wss://your-project.livekit.cloud
RAZORPAY_KEY_ID=your_razorpay_key_id
RAZORPAY_KEY_SECRET=your_razorpay_key_secret
STRIPE_SECRET_KEY=your_stripe_secret_key
CLIENT_URL=http://localhost:5173

Client .env (multiversal-rush/client/.env)

VITE_API_URL=http://localhost:5000
VITE_SOCKET_URL=http://localhost:5000

Get your credentials from:

• MongoDB Atlas - Database
• LiveKit Cloud - Voice chat
• Razorpay - Payments (India)
• Stripe - Payments (Global)

Running the Project

# Start server (from server directory)
npm run dev

# Start client (from client directory, new terminal)
npm run dev

Open http://localhost:5173 to play the game.

---

Project Structure

multiversal-rush/
├── client/                     # React frontend
│   ├── public/
│   │   ├── assets/             # Images and static files
│   │   └── models/             # 3D character models (GLTF)
│   ├── src/
│   │   ├── components/         # React components
│   │   │   ├── Environment/    # 3D scene elements
│   │   │   ├── Obstacles/      # Game obstacles
│   │   │   ├── Player/         # Player controller
│   │   │   ├── UI/             # HUD and overlays
│   │   │   └── Worlds/         # Map arenas
│   │   ├── pages/              # Route pages
│   │   ├── socket/             # Socket.io client
│   │   ├── store/              # Zustand state
│   │   ├── utils/              # Helper functions
│   │   └── voice/              # LiveKit integration
│   └── package.json
│
└── server/                     # Node.js backend
    ├── config/                 # Database config
    ├── controllers/            # Route handlers
    ├── middleware/             # Auth middleware
    ├── models/                 # MongoDB schemas
    ├── routes/                 # API routes
    ├── services/               # Business logic
    ├── socket/                 # Socket.io events
    ├── server.js               # Entry point
    └── package.json

---

Key API Endpoints

Authentication

• POST /api/auth/register - Create account
• POST /api/auth/login - User login

Game

• GET /api/leaderboard - Top 20 players
• GET /api/achievements/:username - User achievements
• POST /api/voice/token - LiveKit access token

Social

• GET /api/friends - Friend list
• POST /api/friends/request - Send friend request
• POST /api/friends/accept/:id - Accept request

Shop & Payments

• GET /api/shop/items - Available items
• POST /api/shop/purchase - Buy with gems
• POST /api/payments/razorpay/order - Create payment
• POST /api/payments/razorpay/verify - Verify payment

Admin

• POST /api/admin/login - Admin auth
• GET /api/admin/users - User management
• GET /api/admin/analytics - Dashboard stats

---

Socket.io Events

Client → Server

• joinRoom - Join multiplayer lobby
• playerReady - Toggle ready state
• playerMove - Broadcast position
• playerFinished - Complete race
• dm:send - Send direct message

Server → Client

• roomJoined - Confirm room join
• playerJoined - New player entered
• gameStarting - Race begins
• playerMoved - Position update
• matchResults - Post-match rewards
• achievementUnlocked - Achievement notification

---

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'feat: add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

---

License

This project is private and proprietary.

---

Built with ❤️ by the Multiversal Rush Team