Dynamic Lobbies

What is Dynamic Lobbies?

Dynamic Lobbies is a system that dynamically registers servers/lobbies to your Velocity proxy. It also supports creating a server switcher item with a GUI on your Bukkit/Paper servers.

How does it work?

Dynamic Lobbies follows a simple workflow:

1. Each server sends a heartbeat to the API.
2. The API stores the server info and exposes it at /api/servers
3. Your proxy/server fetches /api/servers to dynamically register the server.

Installation

1. Clone the backend repo. https://forge.techtransthai.org/mrrpmeowfurry/dynamic-lobbies-backend/
2. Copying .env.example to .env and change your API_SECRET.
3. Install all the dependencies with npm i
4. Start the express server with node main.js
5. Config a reverse proxy with Caddy, Nginx or Cloudflare Tunnel (Optional)

API GET/POST

GET /api/servers will return a JSON list of all active servers (last seen in the last 10 seconds)

[
  {
    "name": "test-server",
    "fancyName": "Testing Server",
    "host": "124.121.177.234",
    "port": 9980,
    "players": 0,
    "maxPlayers": 20,
    "lastSeen": 1763250491083
  },
  {
    "name": "lobby-1",
    "fancyName": "Lobby #1",
    "host": "124.121.177.234",
    "port": 6971,
    "players": 0,
    "maxPlayers": 200,
    "lastSeen": 1763250490669
  }
]

POST /api/heartbeat registers or updates a server entry.

JSON body requires: name, fancyName, host, port, players, maxPlayers

See Java/CURL example down below.

Example

Sending the POST Request to /api/heartbeat using Java using Bukkit API

JSONObject json = new JSONObject();
json.put("name", "server-1");
json.put("fancyName", "1st Server!");
json.put("host", "0.0.0.0"); // use your own method to get server's ip
json.put("port", Bukkit.getPort());
json.put("players", Bukkit.getOnlinePlayers().size());
json.put("maxPlayers", Bukkit.getMaxPlayers());

URL url = new URL("http://localhost:3000/api/heartbeat");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();

conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("X-API-Key", "API_SECRET");
conn.setDoOutput(true);

try (OutputStream os = conn.getOutputStream()) {
    os.write(json.toString().getBytes());
}

int responseCode = conn.getResponseCode();
if (responseCode != 200) {
    System.out.println("Heartbeat failed (" + responseCode + ")");
} else {
    System.out.println("Heartbeat success! (" + responseCode + ")");
}

Sending the POST Request to /api/heartbeat using CURL

curl -X POST "http://localhost:3000/api/heartbeat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: API_SECRET" \
  -d '{
    "name": "test-server",
    "fancyName": "Testing Server!",
    "host": "192.168.1.100",
    "port": 25565,
    "players": 5,
    "maxPlayers": 100
  }'