🧠 How Eaglercraft Multiplayer Works (Simple Version)

The Problem

Eaglercraft cannot connect directly to a Minecraft server because browsers cannot open TCP sockets. They can only use HTTP/HTTPS and WebSocket.

The Solution

Browser (WebSocket) → Proxy/Translator → Minecraft Server (TCP)

Codespaces runs all three pieces inside one Docker container:

Browser — You playing Eaglercraft in your web browser
WebSocket — Secure connection from browser to Codespaces (wss://)
Proxy — Converts WebSocket packets to Minecraft protocol
Minecraft Server — Spigot or Paper in offline mode

Why Codespaces?

Feature	Codespaces	VPS	Your Computer
Cost	Free (120 hours/month)	$5-20/month	Free (but running 24/7)
HTTPS	Automatic ✅	Certbot required	Difficult
WSS (Secure WebSocket)	Automatic ✅	Requires Nginx	Difficult
Docker	Built-in ✅	Must install	Must install
Port Forwarding	Automatic ✅	Manual config	Manual config

Server Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     GITHUB CODESPACES                            │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │          Docker Container                                │  │
│  │                                                           │  │
│  │  ┌────────────────────────────────────────────────────┐ │  │
│  │  │  EaglercraftX Server (Port 5200/5201)           │ │  │
│  │  │  ├─ WebSocket Receiver (wss://)                │ │  │
│  │  │  ├─ Packet Translator                          │ │  │
│  │  │  └─ Minecraft Protocol Handler                 │ │  │
│  │  │                                                 │ │  │
│  │  │  ┌────────────────────────────────────────┐   │ │  │
│  │  │  │  Spigot/Paper Server (Port 25565)    │   │ │  │
│  │  │  │  ├─ World files: /world, etc.        │   │ │  │
│  │  │  │  ├─ Plugins                          │   │ │  │
│  │  │  └─ └─ Server config                    │   │ │  │
│  │  └────────────────────────────────────────────────────┘ │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  HTTPS + WSS = ✅ Automatic                                    │
│  Persist files = ✅ Volume mounts                              │
└─────────────────────────────────────────────────────────────────┘

         ↓ Public URL ↓

    ┌─────────────────────┐
    │   Your Browser      │
    │  (Eaglercraft)      │
    │                     │
    │  wss://connection   │
    └─────────────────────┘

What Happens When You Connect

You open Eaglercraft in your browser
You add your Codespaces URL: wss://PORT-CODESPACE.github.dev
Browser opens WebSocket connection (automatically secure, wss://)
EaglercraftX server receives connection
Translator converts browser packets → Minecraft packets
Spigot/Paper server processes them normally
You play Minecraft in your browser, connected to your server

File Persistence

Codespaces stores files on GitHub servers. Your world data is saved in Docker volumes:

./world — Main world and player data
./world_nether — Nether dimension
./world_the_end — End dimension

These persist as long as your Codespace exists (even if you close the browser).

Networking Flow

Internet
    ↓
GitHub.dev DNS
    ↓
Codespaces Public Port (5200/5201)
    ↓
Docker Container
    ↓
EaglercraftX Server (Port 5200/5201 inside container)
    ↓
Spigot/Paper Backend (Port 25565 inside container)
    ↓
Player connects ✅

Why This Is Better Than Old Methods

No reverse proxy needed — Codespaces handles it
No SSL certificates — GitHub manages it
No domain registration — You get *.github.dev free
No VPS cost — Free tier includes 120 hours/month
Everything in one container — No juggling multiple services