Browser-Based MOBA Game

A real-time multiplayer online battle arena (MOBA) game built with MapLibre GL, Phaser.js, Django, and MQTT for state synchronization.

Features

• Real-time Multiplayer: MQTT-based networking for instant state synchronization
• Geospatial Gameplay: Maps based on real-world GeoJSON data with isometric view
• Multiple Hero Types: Warriors, Rangers, Mages, and Support classes
• Django Admin Interface: Manage all game aspects (maps, heroes, sessions) via admin panel
• Interactive Gameplay: Click-to-move controls, real-time combat, objectives
• Team-based: Red vs Blue team battles with bases, towers, and objectives

Technology Stack

Frontend

• MapLibre GL JS: Rendering geospatial maps with isometric perspective
• Phaser 3: Game entities, sprites, animations, and physics
• MQTT.js: Real-time message synchronization
• Vanilla JavaScript: Lightweight client-side logic

Backend

• Django 4.2+: Web framework and ORM
• Django REST Framework: RESTful API endpoints
• Paho MQTT: Python MQTT client
• SQLite: Database (easily swappable to PostgreSQL)

Architecture

┌─────────────────────────────────────────────────────┐
│                  Browser Client                      │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │  MapLibre GL │  │   Phaser.js  │  │  MQTT.js  │ │
│  │  (Map Layer) │  │  (Entities)  │  │  (Sync)   │ │
│  └──────────────┘  └──────────────┘  └───────────┘ │
└─────────────────────────────────────────────────────┘
                         ↕ WebSocket
┌─────────────────────────────────────────────────────┐
│                   MQTT Broker                        │
│              (Mosquitto / EMQX)                      │
└─────────────────────────────────────────────────────┘
                         ↕ MQTT
┌─────────────────────────────────────────────────────┐
│                  Django Backend                      │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │  REST API    │  │  Game Logic  │  │  Admin UI │ │
│  │  (DRF)       │  │  (Models)    │  │           │ │
│  └──────────────┘  └──────────────┘  └───────────┘ │
└─────────────────────────────────────────────────────┘

Installation

Prerequisites

• Python 3.9+
• Node.js (optional, for development)
• MQTT Broker (Mosquitto recommended)

1. Install MQTT Broker

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install mosquitto mosquitto-clients
sudo systemctl enable mosquitto
sudo systemctl start mosquitto

macOS:

brew install mosquitto
brew services start mosquitto

Docker:

docker run -d -p 1883:1883 -p 9001:9001 eclipse-mosquitto

2. Clone and Setup

# Clone repository
git clone <repository-url>
cd browser-moba

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp .env.example .env
# Edit .env with your settings

# Run migrations
python manage.py migrate

# Load sample data
python manage.py loaddata game/fixtures/sample_data.json

# Create superuser
python manage.py createsuperuser

# Collect static files
python manage.py collectstatic --noinput

3. Run the Server

python manage.py runserver

Visit:

• Game: http://localhost:8000/
• Admin: http://localhost:8000/admin/
• API: http://localhost:8000/api/

Configuration

MQTT Settings (.env)

MQTT_BROKER=localhost
MQTT_PORT=1883
MQTT_USERNAME=
MQTT_PASSWORD=
MQTT_KEEPALIVE=60

Game Settings

Edit moba_game/settings.py:

# Game tick rate (updates per second)
GAME_TICK_RATE = 30

# Map boundaries
GAME_MAP_BOUNDS = {
    'min_lat': 37.7,
    'max_lat': 37.8,
    'min_lng': -122.5,
    'max_lng': -122.4,
}

Game Management

Django Admin Interface

Access the admin interface at /admin/ to manage:

1. Game Maps: Create and edit GeoJSON-based maps
2. Hero Types: Define hero classes with stats
3. Game Sessions: Create and manage active game sessions
4. Players: View player stats and positions
5. Buildings: Place towers, bases, and structures
6. Objectives: Add map objectives and rewards
7. Game Events: View game history and analytics

Creating a New Map

1. Go to Admin → Game Maps → Add Game Map
2. Enter map details (name, description, center coordinates)
3. Add GeoJSON data with features:
   • Bases: Points with type: "base", team: "red|blue"
   • Lanes: LineStrings with type: "lane"
   • Jungle: Polygons with type: "jungle"
   • Objectives: Points with reward data

Example GeoJSON:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "Red Base",
        "type": "base",
        "team": "red"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-122.430, 37.780]
      }
    }
  ]
}

Gameplay

Controls

• Left Click: Move hero to location
• Right Click: Attack/Interact (planned)
• Q/W/E/R: Use abilities (planned)
• Enter: Open chat
• Tab: View scoreboard (planned)

Game Flow

1. Lobby: Players join a game session and select heroes
2. Selection: Choose hero type and team
3. Battle: Fight enemy players and destroy objectives
4. Victory: Destroy enemy base to win

MQTT Topics

• moba/session/{session_id}/state - Full game state updates
• moba/session/{session_id}/player/{player_id} - Player-specific updates
• moba/session/{session_id}/events - Game events (kills, objectives)
• moba/session/{session_id}/chat - Chat messages

API Endpoints

Game Maps

• GET /api/maps/ - List all maps
• GET /api/maps/{id}/ - Get map details

Hero Types

• GET /api/hero-types/ - List all hero types
• GET /api/hero-types/{id}/ - Get hero details

Game Sessions

• GET /api/sessions/ - List active sessions
• GET /api/sessions/{id}/ - Get session details
• POST /api/sessions/{id}/join/ - Join a session
• POST /api/sessions/{id}/start/ - Start a session

Players

• GET /api/players/ - List players
• POST /api/players/{id}/move/ - Update player position

Development

Project Structure

browser-moba/
├── moba_game/          # Django project settings
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── game/               # Main game app
│   ├── models.py       # Data models
│   ├── admin.py        # Admin interface
│   ├── views.py        # API views
│   ├── serializers.py  # DRF serializers
│   ├── mqtt_client.py  # MQTT client
│   └── fixtures/       # Sample data
├── templates/          # HTML templates
│   └── index.html
├── static/             # Static files
│   └── js/
│       └── game.js     # Main game client
├── requirements.txt
└── README.md

Adding New Features

1. New Hero Type: Admin → Hero Types → Add
2. New Ability: Extend HeroType model and add logic
3. New Building Type: Add to Building.BUILDING_TYPES
4. New Event Type: Add to GameEvent.EVENT_TYPES

Testing

# Run Django tests
python manage.py test

# Check MQTT connection
mosquitto_sub -t "moba/#" -v

Deployment

Production Settings

1. Set DEBUG=False in .env
2. Configure ALLOWED_HOSTS
3. Use PostgreSQL instead of SQLite
4. Set up proper MQTT broker (not test.mosquitto.org)
5. Use Nginx/Apache for static files
6. Use Gunicorn/uWSGI for Django

Docker Deployment

# Build image
docker build -t moba-game .

# Run with Docker Compose
docker-compose up -d

Roadmap

• Player abilities and cooldowns
• Combat system with damage calculations
• AI-controlled minions
• Experience and leveling system
• Item shop and inventory
• Match replay system
• Ranked matchmaking
• Mobile responsive design
• WebRTC voice chat

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - See LICENSE file for details

Credits

• MapLibre GL JS: https://maplibre.org/
• Phaser 3: https://phaser.io/
• Django: https://www.djangoproject.com/
• MQTT: https://mqtt.org/

Support

For issues and questions:

• GitHub Issues: [Create an issue]
• Documentation: [Wiki]
• Community: [Discord/Forum]