Skip to content

SayeemX/game

BranchesTags

Repository files navigation

🎮 GameX - Ultimate Gaming & Reward Arena

A high-performance, provably fair gaming platform featuring advanced 3D hunting simulations, fortune games, and integrated wallet ecosystem. Built with React, Three.js, Node.js, and MongoDB.

Status: ✅ Production-Ready | Last Updated: February 2026

📋 Table of Contents

  1. Quick Start
  2. Architecture Overview
  3. Project Structure
  4. Core Features
  5. Technology Stack
  6. Installation & Setup
  7. Running the Application
  8. Environment Configuration
  9. Deployment
  10. Documentation

🚀 Quick Start

Prerequisites

  • Node.js v18+
  • MongoDB (Local or Atlas)
  • npm or yarn

Installation

# Clone and install all dependencies
git clone <repository-url>
cd game
npm run install-all

# Setup environment variables (see Environment Configuration section)
cp server/.env.example server/.env
cp client/.env.example client/.env

# Start development servers
npm run dev

# Build for production
npm run build

# Start production server
npm start

🏗️ Architecture Overview

High-Level System Design

┌─────────────────────────────────────────────────┐
│     Frontend (React + Vite + Three.js)          │
│  - Game Rendering (WebGL)                       │
│  - Real-time UI State (Redux)                   │
│  - Socket.IO Client (Real-time Events)          │
└────────────────────┬────────────────────────────┘
                     │ WebSocket + REST API
┌────────────────────▼────────────────────────────┐
│     Backend (Node.js + Express 5)               │
│  - Game Logic (BirdShootingEngine, SpinEngine)  │
│  - Authentication (JWT)                         │
│  - Financial System (Transaction Ledger)        │
│  - Real-time Multiplayer (Socket.IO)            │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│     Database (MongoDB + Mongoose)               │
│  - User Profiles & Wallets                      │
│  - Game Sessions & Matches                      │
│  - Transaction History                          │
│  - Provably Fair Seeds                          │
└─────────────────────────────────────────────────┘

Core Systems

  • Provably Fair Engine - HMAC-SHA256 verification
  • Physics Engine - Cannon-es for ballistics
  • 3D Rendering - Three.js with dynamic environments
  • Real-time Communication - Socket.IO for live updates
  • State Management - Redux Toolkit for UI state
  • Authentication - JWT with role-based access control

📂 Project Structure

game/
├── client/                          # React Frontend (Vite)
│   ├── src/
│   │   ├── components/
│   │   │   ├── games/               # Game Components
│   │   │   │   ├── BirdShooting.jsx # 3D Hunting Game
│   │   │   │   └── SpinWheel.jsx    # Fortune Spin
│   │   │   ├── layout/              # Navigation & Layout
│   │   │   │   └── Navbar.jsx
│   │   │   ├── AuthForm.jsx         # Login/Register
│   │   │   ├── CurrencyConfigManager.jsx
│   │   │   ├── ProvablyFairSettings.jsx
│   │   │   └── RedeemCodeSection.jsx
│   │   ├── pages/
│   │   │   ├── Home.jsx             # Landing Page
│   │   │   ├── GameRoom.jsx         # Game Selection
│   │   │   ├── AdminDashboard.jsx   # Admin Panel
│   │   │   ├── Profile.jsx          # User Profile
│   │   │   ├── Store.jsx            # Item Shop
│   │   │   └── Wallet.jsx           # Wallet Management
│   │   ├── entities/
│   │   │   └── Arrow.js             # Projectile Physics
│   │   ├── context/
│   │   │   └── AuthContext.jsx      # Auth Provider
│   │   ├── redux/
│   │   │   ├── store.js
│   │   │   └── slices/
│   │   │       └── userSlice.js
│   │   ├── services/
│   │   │   └── api.js               # Axios Setup
│   │   ├── assets/
│   │   │   └── birds/               # Bird Sprites
│   │   │       ├── eagle/
│   │   │       ├── falcon/
│   │   │       ├── owl/
│   │   │       ├── parrot/
│   │   │       ├── pigeon/
│   │   │       └── sparrow/
│   │   ├── App.jsx
│   │   ├── index.css
│   │   └── main.jsx
│   ├── public/
│   │   ├── 404.html
│   │   └── assets/
│   │       ├── birds/
│   │       ├── effects/
│   │       ├── environment/
│   │       ├── projectiles/
│   │       ├── ui/
│   │       └── weapons/
│   ├── vite.config.js
│   ├── tailwind.config.js
│   └── package.json
│
├── server/                          # Node.js Backend (Express)
│   ├── models/
│   │   ├── User.js                 # User Schema
│   │   ├── Game.js                 # Game Sessions
│   │   ├── BirdMatch.js            # Hunting Sessions
│   │   ├── BirdWeapon.js           # Weapon Inventory
│   │   ├── CurrencyConfig.js       # Dynamic Settings
│   │   ├── Transaction.js          # Ledger
│   │   └── RedeemCode.js           # Redeem Codes
│   ├── routes/
│   │   ├── auth.js                 # Auth Endpoints
│   │   ├── user.js                 # User Profile
│   │   ├── game.js                 # Game Endpoints
│   │   ├── games.js                # Game List
│   │   ├── admin.js                # Admin Panel
│   │   ├── spin.js                 # Fortune Spin
│   │   ├── payment.js              # Payment Processing
│   │   ├── redeem.js               # Code Redemption
│   │   └── shop.js                 # Item Shop
│   ├── services/
│   │   ├── BirdShootingEngine.js   # Game Logic
│   │   ├── SpinEngine.js           # Spin Logic
│   │   └── rngService.js           # RNG & Fairness
│   ├── middleware/
│   │   ├── auth.js                 # JWT Verification
│   │   ├── admin.js                # Admin Check
│   │   └── authorize.js            # Permissions
│   ├── scripts/
│   ├── index.js                    # Server Entry Point
│   └── package.json
│
├── GEMINI.md                        # Technical Specification
├── README.md                        # This File
├── SCOPE_AND_MOBILE_GUIDE.md       # Scope System Guide
├── package.json                     # Root Package Config
└── render.yaml                      # Render Deployment Config

🎮 Core Features

1. 🎯 Bird Shooting Game (GameX Sniper)

Advanced 3D hunting simulation with realistic physics and procedural AI.

Mechanics:

  • Bow & Arrow Physics - Realistic ballistic trajectory with wind effects
  • Dynamic Bird AI - 8+ bird types with distinct flight patterns (Sparrow, Pigeon, Crow, Eagle, Falcon, Owl, Parrot, Phoenix)
  • Procedural Environments - Multi-themed levels (Meadows, Hills, Night, Rainbow)
  • Scope System - Professional 2x-8x zoom reticle with 4 magnification levels
  • Mobile Controls - Touch-based aiming and charging
  • Physiological Simulation - Breathing and heart rate affect camera stability
  • Session Billing - Automated credit deduction every 3 minutes

Key Technologies:

  • Three.js for 3D rendering
  • Cannon-es for physics
  • Real-time Socket.IO for server synchronization
  • Server-authoritative hit validation

2. 🎡 Fortune Spin Game

Provably fair wheel with configurable rewards and bonus segments.

Features:

  • Tiered Wheel System - Multiple wheel configurations
  • HMAC-SHA256 Verification - Cryptographically proven fairness
  • Dynamic Rewards - Custom prize configuration
  • Bonus Segments - Special GameX GIFT rewards
  • Inventory Integration - Direct item rewards (arrows, weapons)

3. 💰 Unified Wallet System

Comprehensive financial management with multiple balance types.

Components:

  • Main Balance - Primary currency
  • Bonus Balance - Promotional credits
  • GameX Credits - Per-session gaming currency
  • Transaction Ledger - Immutable history
  • Withdrawal System - Secure payout processing

4. 🔐 Provably Fair System

Cryptographically verified game results using HMAC-SHA256.

How It Works:

  1. Server generates a secret seed
  2. User creates a client seed
  3. Combined with nonce, seeds generate deterministic results
  4. Post-game verification: User can hash seeds to confirm fairness

5. 🛒 Admin Dashboard

Comprehensive management panel for operators.

Capabilities:

  • User management (balance adjustments, restrictions)
  • Currency configuration (entry fees, rewards)
  • Wheel management (segment editing, probability tuning)
  • Transaction approval/rejection
  • Payment gateway settings (bKash, Nagad, TRX addresses)
  • Leaderboards and statistics

6. 📱 Mobile Responsiveness

Full mobile optimization with touch-based controls.

Features:

  • Responsive UI (mobile breakpoint: 768px)
  • Two-finger tap for scope toggle
  • Touch-based aiming (right side swipe)
  • Touch-based charging (left side drag)
  • Reduced sensitivity during charge
  • Device-aware HUD hints

🛠️ Technology Stack

Frontend

Technology Purpose Version
React UI Framework 18.2.0
Vite Build Tool 5.0.0
Three.js 3D Rendering 0.182.0
Cannon-es Physics Engine 0.20.0
Redux Toolkit State Management 2.11.2
Socket.io Client Real-time Events 4.7.2
Tailwind CSS Styling 3.3.5
Framer Motion Animations 10.16.4
React Router Navigation 6.18.0

Backend

Technology Purpose Version
Node.js Runtime 18+
Express.js Web Framework 5.2.1
MongoDB Database Latest
Mongoose ODM 9.1.5
Socket.io Real-time Comms 4.8.3
JWT Authentication 9.0.3
bcryptjs Password Hashing 3.0.3
Helmet Security Headers 8.1.0

📦 Installation & Setup

Step 1: Clone Repository

git clone <repository-url>
cd game

Step 2: Install Dependencies

npm run install-all

Step 3: Setup Environment Variables

Create server/.env:

PORT=10000
MONGODB_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/<database>
JWT_SECRET=your_jwt_secret_key
SOCKET_URL=http://localhost:10000
CLIENT_URL=http://localhost:4173

Create client/.env:

VITE_API_URL=http://localhost:10000
VITE_API_WS=ws://localhost:10000

Step 4: Verify Installation

# Check MongoDB connection
npm run test-connection

# Build verification
npm run build

▶️ Running the Application

Development Mode

# Terminal 1: Start backend
npm run dev-server

# Terminal 2: Start frontend
npm run dev-client

# Or use concurrently (single command)
npm run dev

Access Points:

Production Mode

# Build optimized bundles
npm run build

# Start production server
npm start

# Set environment
NODE_ENV=production npm start

Preview Build

# Build and preview locally
cd client
npm run build
npm run preview

🔧 Environment Configuration

Server Environment Variables

Variable Description Default Required
PORT Server port 10000 No
MONGODB_URI MongoDB connection string N/A Yes
JWT_SECRET JWT signing key N/A Yes
NODE_ENV Environment (dev/production) development No
CLIENT_URL Frontend URL (CORS) http://localhost:5173 No
SOCKET_URL Socket.IO server URL http://localhost:10000 No

Client Environment Variables

Variable Description Example
VITE_API_URL Backend API URL http://localhost:10000
VITE_API_WS WebSocket URL ws://localhost:10000

🚀 Deployment

Render Deployment (Recommended)

# render.yaml (Pre-configured)
services:
  - type: web
    name: gamex-api
    env: node
    buildCommand: npm run install-all && npm run build
    startCommand: npm start

Steps:

  1. Push to GitHub
  2. Connect repository to Render
  3. Configure environment variables
  4. Deploy

GitHub Pages (Frontend Only)

# Build for GitHub Pages
npm run build
# Push dist/ to gh-pages branch

Environment-Specific URLs

📚 Documentation

Main Documentation Files

Quick Reference

  • Architecture: See GEMINI.md → System Architecture
  • Bird Shooting: See GEMINI.md → Bird Shooting Game
  • Scope System: See SCOPE_AND_MOBILE_GUIDE.md → User Guide
  • API Endpoints: See GEMINI.md → Backend Structure
  • Database Schema: See GEMINI.md → Database Models

🧪 Testing

Smoke Test

# Run backend smoke test
cd /home/sym/Desktop/game
node smoke-test-backend.js

Coverage:

  • Server health check
  • User registration & authentication
  • Token validation
  • Database connectivity
  • Socket.IO readiness

Manual Testing Checklist

  • Login/Registration
  • Bird Shooting game entry
  • Scope toggle (Desktop: Right-Click, Mobile: 2-Finger Tap)
  • Zoom levels (Scroll wheel / Swipe)
  • Arrow charging and firing
  • Hit detection and scoring
  • Wallet balance updates
  • Session billing (every 3 minutes)
  • Fortune Spin gameplay
  • Admin Dashboard functions

🐛 Known Issues & Fixes

Recent Fixes (Latest Session)

  • Fix72: Resolved "ReferenceError: user is not defined" in chargeUserSession
  • Fix73: Implemented automatic scope behavior (auto-zoom on nock, unscope on fire)
  • Fix74: Configured desktop mouse controls (right-click scope toggle)

Previous Notable Fixes

  • Fix70: Backward flying bug fixed, smart sprite system upgraded
  • Fix71: Bird animation system optimized for 1x5 vertical sprite sheets
  • Fix69: API and Socket.io services refactored for environment variables
  • Fix68: Hardened system-wide logic with atomic Mongoose operations

📈 Performance Metrics

Client-Side

  • Initial Load: < 3 seconds
  • Game FPS: 60 FPS maintained (scoped and unscoped)
  • Memory Usage: ~150-200 MB (normal gameplay)
  • Bundle Size: 1.2 MB JavaScript (gzipped: 331.82 KB)

Server-Side

  • Requests per Second: 100+ RPS
  • Database Latency: < 50ms (MongoDB Atlas)
  • Socket.IO Latency: < 100ms (average)
  • Concurrent Connections: 500+ users

🔐 Security Features

Authentication

  • JWT-based token authentication
  • Secure password hashing (bcryptjs)
  • Role-based access control (Admin, User)

Game Integrity

  • Server-authoritative hit validation
  • Trajectory simulation verification
  • Rate limiting on high-frequency endpoints
  • Provably fair cryptographic verification

Data Protection

  • HTTPS/TLS encryption in production
  • Environment-based configuration (no hardcoded secrets)
  • CORS policy enforcement
  • Helmet.js security headers
  • Rate limiting (express-rate-limit)

🤝 Contributing

Development Workflow

  1. Create feature branch: git checkout -b feature/your-feature
  2. Make changes and test locally
  3. Commit: git commit -m "Add your feature"
  4. Push: git push origin feature/your-feature
  5. Create Pull Request

Code Standards

  • ES6+ JavaScript
  • React functional components with hooks
  • Proper error handling
  • Environment variable usage

📞 Support & Contact

📄 License

Private / GameX Dev - All rights reserved

Maintained by: GameX Development Team
Version: 1.0.0
Last Build: February 4, 2026

About

gaming site

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages