System Overview

This page provides a high-level overview of MafiaNet’s architecture.

Core Components

┌─────────────────────────────────────────────────────────┐
│                    Your Application                     │
├─────────────────────────────────────────────────────────┤
│                    Plugin Layer                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │Replica   │ │NAT Punch │ │File      │ │ RPC4     │   │
│  │Manager3  │ │through   │ │Transfer  │ │          │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘   │
├─────────────────────────────────────────────────────────┤
│                  RakPeerInterface                       │
│  ┌──────────────────────────────────────────────────┐  │
│  │ Connection Management | Reliability Layer        │  │
│  │ BitStream            | Security                  │  │
│  └──────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│                    Socket Layer                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │              UDP Sockets                         │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

RakPeerInterface

The main entry point for all networking. Handles:

  • Socket creation and management

  • Connection establishment and maintenance

  • Packet sending and receiving

  • Plugin management

  • Statistics tracking

Reliability Layer

Provides reliable delivery over UDP:

  • Sequencing: Packets arrive in order

  • Acknowledgments: Confirms packet delivery

  • Retransmission: Resends lost packets

  • Congestion control: Adapts to network conditions

BitStream

Binary serialization utility:

  • Write any data type

  • Bit-level precision

  • Endian handling

  • Compression helpers

Plugin System

Modular extensions that hook into the network layer:

  • Process packets before/after your application

  • Add features without modifying core code

  • Enable/disable as needed

Data Flow

Sending

Your App → BitStream → RakPeerInterface → Reliability Layer → Socket → Network

  1. Create data with BitStream

  2. Call Send() with priority and reliability

  3. Reliability layer queues and manages delivery

  4. Socket sends UDP packets

Receiving

Network → Socket → Reliability Layer → Plugins → RakPeerInterface → Your App

  1. Socket receives UDP packets

  2. Reliability layer reassembles and orders

  3. Plugins process (optional)

  4. Receive() returns packet to your app

Threading Model

MafiaNet uses a background thread for:

  • Socket I/O

  • Reliability processing

  • Keep-alive pings

Your application:

  • Calls Receive() from any thread

  • Calls Send() from any thread

  • Both are thread-safe

Memory Management

  • Packets: Allocated by MafiaNet, freed with DeallocatePacket()

  • BitStream: You manage (stack or heap)

  • Plugins: You manage lifetime

  • RakPeerInterface: Create with GetInstance(), destroy with DestroyInstance()

Namespaces

  • MafiaNet:: - Primary namespace for all classes

  • MNet - Preprocessor macro shorthand that expands to MafiaNet (defined in mafianet/defines.h)

  • DataStructures:: - Container classes (DS_List, DS_Queue, etc.)

Common Patterns

Client-Server

One authoritative server, multiple clients:

Client A ─────┐
              │
Client B ─────┼───── Server
              │
Client C ─────┘

Peer-to-Peer

All peers connect to each other:

Peer A ◄────► Peer B
   │  ╲      ╱  │
   │   ╲    ╱   │
   │    ╲  ╱    │
   │     ╲╱     │
   │     ╱╲     │
   │    ╱  ╲    │
   │   ╱    ╲   │
   ▼  ╱      ╲  ▼
Peer C ◄────► Peer D

Hybrid

Central server for matchmaking, P2P for gameplay:

Phase 1: Matchmaking          Phase 2: Gameplay

Client A ──┐                  Client A ◄──► Client B
           │
Client B ──┼── Lobby Server   (direct connection)
           │
Client C ──┘

See Also