2D Metaverse

A lightweight multiplayer 2D metaverse built with Node.js, Express, Socket.IO, Redis, MongoDB and a React + Vite front-end using Phaser for the game layer.

Table of Contents

• Project: Short description and goals
• Features: What this repo includes
• Architecture: Folder overview with links
• Tech Stack: Key libraries and versions
• Quick Start: Install and run instructions
• Environment: Required env variables
• Development: Useful scripts and tips
• Contributing: How to help
• License

Project

This repository contains the backend server and frontend client for a small-scale 2D metaverse. The backend exposes REST APIs for authentication, rooms, users and admin functionality and runs a Socket.IO server for realtime player movement, chat and media. The frontend is a React + Vite app that integrates a Phaser scene for the in-browser 2D experience.

What this project is

2D Metaverse is a prototype and minimal foundation for building lightweight, browser-based social spaces. It combines a server-authoritative backend for persistence and realtime state syncing with a small React + Phaser client that renders a 2D world and UI. The codebase focuses on being easy to extend: add new room types, gameplay mechanics, avatar customizations, or richer media features.

Real-world use

This project is intended as a starting point for practical, real-world scenarios including:

• Social hangouts & virtual events — small gatherings, meetups, networking rooms, and casual social spaces.
• Remote collaboration & co-working — lightweight shared spaces for teams to meet, pair-program, or brainstorm.
• Education & training — interactive lessons, guided simulations, and gamified learning environments.
• Marketing & virtual storefronts — promotional spaces where visitors can explore and interact with brand content.
• Prototyping multiplayer mechanics — experiment with real-time movement, syncing, and simple game rules before committing to larger systems.

The project is intentionally opinionated but minimal: for production usage you would add hardened authentication, media servers or TURN/STUN for robust WebRTC, horizontal scaling (Redis + multiple Node instances), monitoring, and proper security/hardening.

Features

• Realtime multiplayer via Socket.IO with optional Redis adapter for scale
• Authentication with JWTs
• Room management and player state syncing
• Chat & media channels (WebRTC/simple-peer + socket signaling)
• Session cleanup utilities and rate limiting for safety

Architecture

• Backend: Backend — Node.js + Express server, Socket.IO handlers, MongoDB models and REST routes. Entry: Backend/app.js
• Frontend: Frontend/client — React + Vite client, Phaser scenes under game/scenes and UI pages under pages.
• Sockets: Server-side socket code lives in Backend/sockets
• Routes & Controllers: See Backend/routes and Backend/controllers

Tech Stack

• Backend: Node.js, Express, Socket.IO, Mongoose, Redis
• Frontend: React, Vite, Phaser, Tailwind, Zustand
• Realtime/media: socket.io-client, simple-peer

Quick Start

Prerequisites:

• Node.js 18+ (or compatible)
• MongoDB instance (local or hosted)
• (Optional) Redis for multi-instance Socket.IO support

Install backend dependencies and run server:

cd Backend
npm install
npm run dev

Install client dependencies and run frontend (dev):

cd Frontend/client
npm install
npm run dev

Open the client app in your browser at the Vite dev URL (usually http://localhost:5173) and the backend runs by default on port 4000.

Environment

Create a .env file in Backend/ or set environment variables in your shell. Important variables:

• MONGO_URI: MongoDB connection string used by Backend/config/db.js
• REDIS_URL: Redis connection URI (optional) used by Backend/config/redis.js. Defaults to redis://localhost:6379.
• JWT_SECRET: Secret used to sign JWT tokens (required for production). See Backend/app.js for runtime checks.
• PORT: Backend port (defaults to 4000)

Example .env (do NOT commit to git):

MONGO_URI=mongodb://localhost:27017/metaverse
REDIS_URL=redis://localhost:6379
JWT_SECRET=your_secret_here
PORT=4000
NODE_ENV=development

Development Notes

• API routes are under Backend/routes and controllers under Backend/controllers.
• Socket handlers are registered from Backend/sockets/index.js.
• The server will attempt to connect to Redis and enable the Socket.IO Redis adapter when REDIS_URL is reachable; otherwise it falls back to the in-memory adapter (not recommended for production with multiple instances).
• Sessions are periodically cleaned by Backend/utils/sessionCleanup.js.
• Use the rate limiter middleware to protect auth and API endpoints: Backend/middlewares/rateLimiter.middleware.js.

Scripts

• Backend: npm run dev or npm start from the Backend folder (node app.js)
• Frontend: npm run dev, npm run build from Frontend/client

Contributing

• Fork the repo, create a feature branch, add tests where applicable, and open a PR.
• Describe changes concisely and reference any related issues.

Troubleshooting

• If Socket.IO messages don't cross instances, ensure Redis is running and REDIS_URL is set.
• If auth fails, ensure JWT_SECRET is defined (required in production).
• If Mongo fails to connect, verify MONGO_URI and network access.

License

This project is provided as-is. Add an open-source license file (for example, MIT) if you intend to make it public.