Documentation - Web API Guide

• At a glance
• Quick start
  • List the servers
  • See who is playing on one, through the relay
  • Watch a match live
  • Keep a server list up to date
• Reaching a server
  • Direct connections
  • The relay
• Conventions
  • JSON and text
  • Text markup
  • Errors
  • CORS
  • Caching
• Signing in
  • Privileges
  • Getting a Privilege
  • Encryption is required
  • Sessions from an account
  • Remembered sign-ins
    • Sessions from a remembered sign-in
  • Failed attempts
• Game server routes
  • GET /api/v1
  • GET /status
  • GET /players
  • GET /mapshot
  • GET /matches
  • GET /objectives
  • GET /teams
  • GET /controls
  • POST /controls
  • DELETE /controls/<id>
  • POST /map
  • POST /say
    • Bridging chat
• The Event feed
  • Choosing events
  • Signing in on the feed
  • Chatting on the feed
  • Events
• The master server
  • GET /api/v1/servers
    • Polled status
  • GET /api/v1/servers/<address>/<port>/history
  • GET /api/v1/history
  • WebSocket /api/v1/servers/live
  • Join links and bounce links
  • The Matchmaking Queue
    • GET /api/v1/queue
    • Queuing over the live list
    • Queuing Discord members
• Accounts
  • Registering
  • Lost keys
  • The game collects its key
  • The owner’s own account
  • Linking Steam and Discord
  • Administration
• Limits
• Reference
  • Privileges
  • Teams
  • Player states
  • Game states
  • Master modes
  • Modes and mutators
  • Weapons
  • Leave reasons
• Versions

Red Eclipse game servers and the master server answer HTTP and WebSocket requests with JSON. You can use this to build server lists, live scoreboards, match trackers, Discord bots and moderation tools.

This guide covers what you can call and what comes back. How it is built inside the engine is in src/doc/web-api.md in the base repository.

At a glance

• The master server is play.redeclipse.net, port 28888, for HTTP and HTTPS alike. It lists every public server, pushes changes to that list live, and relays requests to game servers.
• Game servers each run their own copy of the API on a port of their own. The master’s list tells you which port (webport).
• Every route is below /api/v1. The rest of each server’s address space is left for web pages, such as the master’s bounce links.
• Most sites only need the master. A browser page on https can’t reach a game server that has no CA-signed certificate, and most don’t have one. The master’s relay reaches every server holding a link to it, over https, with one code path.
• Reading is open to everyone. Anything above that, such as moderation, needs a token and an encrypted connection.
• The master holds the Matchmaking Queue, where people with an account wait for enough others to play with, and sends them to a server together. See The Matchmaking Queue.
• People can stay signed in for weeks through a remembered sign-in on the master, which gets them a session on any server that takes one, without your site keeping their private key. See Remembered sign-ins.
• The master registers accounts, from the game or a website, and lets their owners reset a lost key, change their email, link Steam and Discord and pick a display name. See Accounts.

Quick start

All of these work from a browser page on any site (see CORS).

List the servers

const res = await fetch("https://play.redeclipse.net:28888/api/v1/servers");
const list = await res.json();
for(const s of list.servers)
    console.log(s.description, s.host, s.port, s.status ? s.status.map : "(no status)");

See who is playing on one, through the relay

The relay address uses the server’s game port (port), not its webport.

const s = list.servers[0];
const base = `https://play.redeclipse.net:28888/relay/${encodeURIComponent(s.host)}/${s.port}/api/v1`;
const players = await (await fetch(`${base}/players`)).json();

s.relay says what the relay will carry for that server: 0 means nothing, 1 means public routes and the Event feed, and 2 means everything.

Watch a match live

const ws = new WebSocket(`wss://play.redeclipse.net:28888/relay/${encodeURIComponent(s.host)}/${s.port}/api/v1/events`);
ws.onmessage = (e) =>
{
    const ev = JSON.parse(e.data);
    if(ev.event === "frag") console.log(`${ev.killer.name} fragged ${ev.victim.name} with the ${ev.weaponname || ev.weapon}`);
};

Keep a server list up to date

const live = new WebSocket("wss://play.redeclipse.net:28888/api/v1/servers/live");
live.onmessage = (e) =>
{
    const ev = JSON.parse(e.data);
    switch(ev.event)
    {
        case "snapshot": /* ev.servers is the whole list */ break;
        case "add": case "update": /* ev.server is one entry */ break;
        case "remove": /* ev.host and ev.port name it */ break;
    }
};

Reaching a server

Direct connections

A game server’s entry in the master’s list has a webport when its API is on, and a fingerprint when it serves HTTPS. Most servers use a self-signed certificate:

• Browsers will refuse a self-signed certificate. They also block plain http:// requests from an https page, so a browser page should use the relay.
• Tools can trust a self-signed certificate by its fingerprint. The fingerprint is the SHA-256 of the server’s DER certificate in lowercase hex, the same as openssl x509 -noout -fingerprint -sha256 prints without the colons. Only trust a fingerprint you fetched from the master over https. Note that curl’s --pinnedpubkey hashes the public key instead, which gives a different value.
• Plain http:// works too, but tokens are ignored over it (see Signing in).

The relay

/relay/<host>/<port>/<path> asks that server for /<path> exactly as given, query string included. <host> is the host from the list and <port> is its game port. They are separate path segments because an IPv6 address has colons of its own. Requests and the Event feed both work.

What the relay passes on:

• Request headers: only Content-Type, Accept, Origin and If-None-Match. Authorization is passed on only when the server’s relay level is 2 and you reached the master over https. A token sent to the master over plain http is dropped, and the server sees an anonymous request.
• Request bodies: text only, such as JSON or a form.
• Response headers: only Content-Type, ETag, Cache-Control, Allow, WWW-Authenticate and Retry-After. The master adds X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox allow-scripts allow-forms allow-popups, so anything a server returns is sandboxed away from the master’s origin.
• Caching: anonymous GETs that succeed are cached for 2 seconds per server, path and query string. Polling more often than that gets the same answer back.

Errors that come from the relay itself rather than from the server:

Conventions

JSON and text

• Request and response bodies are UTF-8 JSON. POST routes also accept application/x-www-form-urlencoded, and a few fields can go in the query string.
• Numbers that are counts, ids and scores are integers. time, ends and stateends are unix times in seconds.
• Names of things (privileges, teams, states, weapons) are plain strings, listed under Reference.

Text markup

Strings are plain text, with one exception: a server’s description in the master’s list is stored as the server sent it, and may carry Red Eclipse’s colour codes. Each code starts with a form feed (\f, U+000C). This strips them:

const plain = (s) => s.replace(/\f(?:z..|\[[^\]]*\]|\([^)]*\)|\{[^}]*\}|.)/g, "");

Player names and chat are plain everywhere: in the master’s list, in /status and /players, and on the Event feed. Where the game shows a player with colours and icons, the list gives you the parts as fields of their own (see GET /api/v1/servers).

Errors

Every error has a JSON body of the form {"error": "what went wrong"}, with a matching status:

CORS

Browsers may call the API from other origins:

• Responses carry Access-Control-Allow-Origin.
• Preflight OPTIONS requests are answered for the methods GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS, and the headers Authorization and Content-Type. They are cached for a day.
• No cookies are used, so don’t send credentials. Tokens go in Authorization. The one exception is the master’s remembered sign-ins, below /api/v1/signin, whose cookie only pages from the master’s own list of origins may send.

The official master, play.redeclipse.net, allows every origin. Any site can use its list, live list and relay from the browser, which is what the Web API is for.

Game servers allow every origin by default too. An operator can limit their own server with httpalloworigin, and then only the origins listed can read its responses from a browser or open its WebSockets. That affects direct connections only, since the relay and the live list follow the master’s setting.

Caching

• GET /servers on the master has an ETag and Cache-Control: public, max-age=5. Send If-None-Match to get 304 Not Modified when nothing changed.
• Relayed anonymous GETs are cached for 2 seconds, or as long as the server’s Cache-Control says, up to an hour, as for /mapshot asked for by crc.

Compressed responses are sent when you accept gzip, which browsers do by default.

Signing in

Privileges

Every request has a Privilege, from lowest to highest: none, player, supporter, moderator, administrator, developer, founder. An anonymous request is none, as an unauthenticated player is in the game. player means a signed in account with no higher standing.

Each route needs at least a set Privilege. GET /api/v1 lists the routes your Privilege allows, and what each needs.

A Privilege can be local: standing the server’s operator gives of their own, rather than the master’s, as for players in the game. Local Privileges go no higher than administrator, and wherever a Privilege is given, a local one comes with "local": true, so it can be drawn with the game’s local icon.

Getting a Privilege

There are two ways:

• API tokens are set by a server’s operator in its config, each with a fixed Privilege, which is local. Ask the operator for one. A token works only on the server that issued it.
• Signing in with a Red Eclipse account gives a session token at that account’s standing on the server, through a challenge the master checks (below): what the master grants it, or what the server’s operator gives it locally when that is higher.

Send a token as Authorization: Bearer <token>. On the Event feed, where browsers can’t set headers, use ?token=<token> on the URL or a message (see Signing in on the feed).

Encryption is required

Tokens and sign-ins only count over an encrypted connection. That means one of:

• https or wss directly to the server,
• the relay over https or wss, when the server’s link to the master is itself encrypted (it is by default),
• or localhost, or a reverse proxy the operator trusts.

Over plain http a token is ignored: the request is answered as anonymous, and routes that need an account return 403. This keeps tokens and the addresses moderators can see from crossing the network in the clear.

Sessions from an account

A server’s session comes from the master, which vouches for the account to that server:

1. Sign in on the master, as in Remembered sign-ins.
2. POST /api/v1/signin/session/<address>/<port> on the master, with that sign-in, as in Sessions from a remembered sign-in. The answer is:

{"token": "4f3a...", "name": "someone", "privilege": "moderator", "local": true, "expires": 1800}

About the session:

• expires is the session’s idle lifetime in seconds. Each use renews it, and a server restart ends it. A route that needs an account answers an ended session’s token with 401 unknown or expired token, so get another then.
• The Privilege is what the master grants the account, raised by any local standing the server’s operator gives it.

Servers take no challenges themselves. An answer given to one server could be passed on by it to sign in somewhere else as you, so only the master asks for one, and its answer is made so that it counts nowhere else.

Remembered sign-ins

A session lasts half an hour unused and ends when its server restarts, and a site that talks to many servers would need one on each. A remembered sign-in lasts weeks instead. It lives on the master, which gets you a session on whichever server you need, so neither your site nor the person’s browser has to keep their private key.

Signing in on the master is a challenge and response:

1. POST /api/v1/signin with {"name": "<account name>"} gives {"id": <number>, "challenge": "<string>"}.
2. Compute the answer to the challenge with the account’s private key, as below.
3. POST /api/v1/signin with {"id": <number>, "answer": "<string>", "remember": true}, from the same address as step 1 and within a minute, gives:

{"id": "5cbf5ba653fbe075", "name": "someone", "flags": "u", "expires": 1810350612}

Computing the answer:

• The private key is in the player’s auth.cfg, as the second word after authkey <name>. It is a secret, so it must never leave the player’s machine.
• The key’s answer: the challenge is a point on NIST P-192 in compressed form: a sign (+ or -, for the parity of y), then x in hex. Multiply that point by the private key and take its x coordinate in lowercase hex, without leading zeros. See answerchallenge in src/shared/crypto.cpp. From tools, genkey answer <private key> <challenge> prints it.
• What the master takes is the SHA-256 of Red Eclipse master sign-in (with its trailing space) followed by that hex, as 64 lowercase hex digits. This is what makes the answer count only on the master: the game answers a server’s challenge with the key’s answer alone, so a server can’t turn one into a sign-in. See signinanswer in src/engine/http.cpp.
• A browser does the maths itself, with crypto.subtle.digest("SHA-256", ...) for the hash, which needs a secure page.

Options on the last step:

• remember keeps the sign-in for weeks. Without it, it ends after a day unused, and a browser’s cookie ends when the browser closes.
• label names the device in the person’s list, up to 64 characters. Without one, it’s the browser’s User-Agent.
• cookie: see below.

How long it lasts:

Each account holds at most 10; signing in an 11th time ends the one used longest ago. The master’s operator can change these, or turn remembered sign-ins off for moderators and above, who then get 403 and can’t sign in through the Web API. expires is when it ends at the latest, as a Unix time.

Where the token goes:

• Browsers on the master’s own list of origins (on play.redeclipse.net, https://www.redeclipse.net) get it as an HttpOnly cookie, which page scripts can never read, so a script injected into the page can’t take it away. Send every request below /api/v1/signin with credentials: "include". The answer has no token, unless you send "cookie": false.
• Everyone else, such as tools and bots, gets token in the answer, and sends it as Authorization: Bearer <token> to the routes below. Keep it secret: it is the account, until it ends.
• The cookie only counts from those origins. Sent from anywhere else, it’s ignored.
• Safari keeps a cookie at most 7 days when the server that set it has a different address from the page’s, which is the case for the website and the master. So in Safari, people who don’t come back within 7 days sign in again.

Routes, all below /api/v1/signin, each needing the sign-in:

Each DELETE answers {"ok": true, "ended": <count>}. A sign-in also ends when the account’s key or standing changes on the master.

Sessions from a remembered sign-in

POST /api/v1/signin/session/<address>/<port>, with the address and port as the master’s list gives them, answers as signing in on that server would:

{"token": "4f3a...", "name": "someone", "privilege": "moderator", "local": true, "expires": 1800}

• The master vouches for the account over that server’s link, so the server never sees the sign-in token. The session is an ordinary one: use it on the server directly or through the relay, and get another when it answers 401.
• It ends with the remembered sign-in that made it, at once. It also ends when the server’s link to the master closes, as when either restarts.
• The standing is the account’s, raised by any local standing the server’s operator gives it, as for any session.

Errors:

POST /api/v1/signin/session, with no server named, gives a session on the master’s own Web API, in the same form without local. Open the live list with it to queue as the account in the Matchmaking Queue. It ends with the remembered sign-in that made it, and lapses unused like any other session. | 502, 504 | The server’s link closed, or it didn’t answer within 10 seconds |

Failed attempts

Each unknown token, wrong answer or expired session counts as a failure, even on public routes. So drop a token once it stops working rather than resending it.

• An address with 10 failures within a minute gets 429 for the rest of that minute.
• An address that hits that limit 3 times within an hour is banned from the server, game included, for the server’s usual ban time (4 hours by default).
• Through the relay, this counts your visitor’s address, not the master’s.
• On the master’s /api/v1/signin, an unknown token or cookie and a wrong answer count the same way and give 429 for the rest of the minute, but never a ban.

Game server routes

The paths below leave out /api/v1. All GET routes also answer HEAD.

The Privileges listed are the minimum to reach the route. Each action then checks the server’s own in-game minimum for it, the same as a player in the game would face. For example, banning needs at least the server’s banlock.

Operators can add routes of their own outside /api, and those appear in the index.

GET /api/v1

{
    "name": "Red Eclipse",
    "version": "Red Eclipse 2.0.9 ...",
    "type": "server",
    "routes": [
        {"path": "/api/v1/status", "methods": {"GET": "none"}},
        {"path": "/api/v1/events", "methods": {"WS": "none"}},
        {"path": "/api/v1/controls", "methods": {"GET": "player", "POST": "player"}}
    ]
}

• type is server or master.
• Each route maps its methods to the Privilege they need. WS is a WebSocket.
• Only the routes your Privilege reaches are listed.

GET /status

{
    "description": "My Server",
    "version": "Red Eclipse 2.0.9 ...",
    "url": "https://example.org/",
    "motd": "Welcome! Match nights are on Saturdays.",
    "map": "bloodlust",
    "mode": "Deathmatch",
    "modeid": 2,
    "mutators": 0,
    "players": 6,
    "spectators": 1,
    "bots": 4,
    "maxplayers": 16,
    "playerslots": 16,
    "reserved": 0,
    "connections": 4,
    "mastermode": "open",
    "state": "Playing",
    "timeleft": 412,
    "relay": 1,
    "bridge": 1
}

GET /players

An array with one entry for each player, bot and spectator. The map’s own enemies and hazards are left out here and on the Event feed:

[
    {
        "cn": 0, "name": "someone", "team": "alpha", "state": "Alive", "bot": false,
        "privilege": "player", "colour": 3368703, "handle": "someone", "points": 12, "frags": 10, "deaths": 4, "ping": 38
    }
]

GET /mapshot

The current map’s preview, as a PNG. Add ?crc= with the mapcrc from /status or the master’s list: the answer is then cached for a day by browsers and the master’s relay, and is 404 once the map has changed. Without it the answer is no-cache with an ETag, so send If-None-Match to get 304 Not Modified.

It’s 404 when the server doesn’t have the map’s files, which is the case in editing, or until a player has sent a map the server didn’t have. The previews of the official maps are on the website too, so try those first.

const img = new Image();
img.src = `https://play.redeclipse.net:28888/relay/${encodeURIComponent(s.host)}/${s.port}/api/v1/mapshot?crc=${s.status.mapcrc}`;

GET /matches

The results of the last matches played there, newest first, kept until the server stops (httpmatches of them, 10 by default). A match is kept when play ends with a winner, by the time or score limit, and only when a human player was playing at the end; demos and editing aren’t matches.

[
    {
        "ended": 1762201234, "duration": 600, "map": "bloodlust", "maptitle": "Bloodlust", "modeid": 2, "mutators": 0,
        "teams": [{"team": "alpha", "score": 5}, {"team": "omega", "score": 3}],
        "players": [
            {"name": "someone", "handle": "someone", "team": "alpha", "points": 12, "frags": 9, "deaths": 4},
            {"name": "Ken", "team": "omega", "points": 7, "frags": 6, "deaths": 8, "bot": true}
        ]
    }
]

GET /objectives

What every player in the match already sees of its objectives: who carries each flag or ball, and who holds each point and who is taking it. It’s {} in modes without objectives and outside play, and only the mode’s own list is present.

{
    "flags": [
        {"team": "alpha", "state": "taken", "carrier": {"cn": 3, "name": "someone", "team": "omega"}},
        {"team": "omega", "state": "home"}
    ],
    "points": [
        {"id": "A", "name": "Point", "owner": "alpha", "progress": 100},
        {"id": "B", "name": "Courtyard", "owner": "neutral", "enemy": "omega", "progress": 45}
    ],
    "balls": [{"state": "dropped"}]
}

The Event feed sends an objectives event with the same fields whenever any of this changes, at most once a second.

GET /teams

[{"team": "alpha", "score": 3}, {"team": "omega", "score": 5}]

The array is empty in modes without teams. A team only appears once it has a score.

GET /controls

The Control entries your Privilege may see:

[
    {"id": 7, "type": "ban", "scope": "local", "source": "player", "name": "someone", "by": "admin", "reason": "cheating", "ip": "1.2.3.4"}
]

POST /controls

{"cn": 3, "type": "ban", "reason": "cheating"}

• type is kick, allow, ban, mute, limit or except. reason is optional.
• Success is 201 with {"ok": true}.
• You can’t act on a player whose Privilege is higher than yours. A player protected by an except entry can only be acted on by an Administrator.

DELETE /controls/<id>

Removes the entry. The answer is {"ok": true}, or 404 when there is no such entry.

POST /map

{"map": "bloodlust", "mode": 2, "mutators": 0}

• mode and mutators are optional and default to what is playing now.
• They are checked as an in-game vote would be: mutators the server forces are added, combinations that can’t go together are fixed, and demo playback is refused.
• The map changes straight away, with no vote, so it needs the server’s httpmaplock (moderator by default).
• The server’s vote, mode and map locks still apply, as they do to a forced vote in the game: a recently played map, a locked mode, or a map outside the rotation, gets 403 unless your Privilege meets the lock.

POST /say

{"text": "Server restarting in 5 minutes"}

The message is shown in game under your account’s name, marked as from the web. It needs the server’s httpsaylock (player by default) and follows the server’s rules for chat: muted addresses and Privileges below messagelock get 403, text is censored and cut to fit messagelength (256 by default) ending with ..., in which case the answer is {"ok": true, "cut": <characters kept>} so you can tell whoever wrote it, and sending more than the server’s flood limit (5 messages in 10 seconds by default) gets 429. Repeated flooding mutes your address, as it would in the game. Add "action": true to send it as an action, as /me does in the game.

Bridging chat

A bridge carries chat between a server and somewhere outside the game, such as a Discord channel, so a message can name the person who wrote it there rather than your account:

{"text": "anyone up for a duel?", "from": "Someone", "via": "discord"}

• from is the sender’s name, filtered as a player’s name is. via is where they are, up to 32 lowercase letters, digits, - or _; players see its icon when their game knows it, and the web’s icon when it doesn’t. Without via it is web, and without from the name is your account’s.
• Sending either needs the server’s httpbridgelock (developer by default, and never lower), and the server’s bridge in GET /status or the master’s list to be 1; a server with it at 0 refuses them with 403.
• Bridged chat skips the flood rule, as everyone you carry would otherwise share your address’s limit. Keep your own senders in check.
• The Event feed’s chat carries your account’s handle along with from as its name, so drop events with your own handle to keep your messages from coming back to you.
• account is the bridged sender’s own Red Eclipse account, when they’ve linked one where they are (see Linking Steam and Discord). Players see it after their name as Someone (handle), drawn by the game so no name can pass for one, and the Event feed’s chat carries it as account. Send it with privilege set to the account’s own standing, which the bot’s lookup gives. It is refused without from or via.
• privilege is the standing a bridged sender has where they are, such as a Discord moderator, as one of none, player, supporter, moderator, administrator, developer or founder. It only chooses the icon players and websites see by their name and gives them nothing; without it they show none, as a bridged sender never wears your account’s. It is refused without from or via.
• A bridged sender can’t be muted or banned in the game, as they have no player or address there; players can hide them with ignorebridge <via> <name>. Moderate them where they are.

The Event feed

Open a WebSocket to /api/v1/events, directly or through the relay. Each message is a JSON object with an event name and a time.

• No snapshot comes first. Fetch /status and /players when you connect, then apply events as they arrive.
• Choose your events with ?events= on the URL, such as ?events=chat,action,join,leave. See Choosing events.
• The server sends a WebSocket ping every 30 seconds. Browsers answer it by themselves. A connection that stays silent for about a minute is closed.
• Your messages must be text frames, and on the relay at most 4 KB.

Choosing events

?events= takes event names separated by commas, and default, which stands for every event except ping. The game’s broadcast messages are chosen by their own names, such as servmsg or capture.

• Without ?events= a feed gets default. Pings come only to feeds that name ping, so a scoreboard asks for ?events=default,ping.
• The answers to your own messages (auth, challenge and said) always come, whatever you chose.
• A name the server doesn’t know is ignored, so you can ask for an event a server doesn’t have yet.
• Choose once, when the feed opens. To change your mind, open another.

The server works out an event only when some feed asked for it, so asking only for what you use spares the server and the relay.

Signing in on the feed

A feed starts as none. To see more, such as Control changes, sign in with one of:

• ?token=<token> on the URL,
• or a message {"token": "<token>"},

with a session on that server, which the master vouches for (see Sessions from an account). A message with a name or answer instead is refused, as servers take no challenges.

The answer is one of:

{"event": "auth", "privilege": "moderator", "local": true, "name": "someone"}
{"event": "auth", "error": "unknown token"}

How long it lasts:

• A feed drops back to none when its token is removed or its session expires. You get another auth event when that happens.
• Signing in needs wss:// (see Encryption is required). Through the relay it also needs the server’s relay level to be 2.

Chatting on the feed

A feed signed in as an account can chat, under the same rules as POST /say: httpsaylock, messagelock, mutes, censoring, cutting and the flood limit. Send:

{"say": "anyone for a duel?", "id": 7}

Add "action": true to send it as an action. id is optional, and comes back so you can match the answer:

{"event": "said", "ok": true, "id": 7}
{"event": "said", "ok": true, "cut": 255}
{"event": "said", "status": 429, "error": "too many messages, slow down"}

status and error are what POST /say would have answered. The message itself comes back as a chat or action event, as everyone’s does. The game’s server browser and the website chat this way.

Events

Players in events are described the same way throughout:

{"cn": 3, "name": "someone", "team": "alpha", "bot": false, "handle": "someone", "privilege": "player"}

• weapon is a weapon name, and missing when none applies, and weaponname the name the server gives it to players, such as Sidearm Pistol, which a game mod can change; show that one, and the weapon from servers too old to send it. flags is the game’s own hit flags; treat it as opaque.
• score comes at most once a second. teams lists every team’s score, in team modes only. players lists only the players whose points, frags or deaths changed, as {"cn", "points", "frags", "deaths"}. The first score after you connect lists everyone.
• ping comes at most every 30 seconds. players lists only the players whose ping changed, as {"cn", "ping"}, which is nearly everyone each time, as pings shift a little all the time. The first ping after a feed that asks for it connects lists everyone. A bot has its owner’s ping, as in /players.
• control: action is add or remove. These go only to feeds whose Privilege may see that type of entry, and ip and mask only to those at the server’s iphostlock and above (moderator by default).
• client, victim, killer and a flag’s or ball’s carrier are players as in GET /players, with cn, name, team, bot, handle, privilege, local and colour. So are a match result’s players, without cn.
• chat and action from POST /say have a client with cn -1, the sender’s name (from when it was bridged), the bridged sender’s own account when it was sent, the account’s handle, the sender’s privilege and local (the account’s own, or for someone bridged the privilege sent for them), "web": true and via (see Bridging chat).
• A server’s operator can turn chat events off.
• join and leave come for bots too, with bot true in client, so a scoreboard kept from the feed has everyone /players lists. The game and the website keep them off their match feeds.
• identify takes the place of the game’s servmsg line saying the same, and comes only for a player already on the server. One who signs in as they connect has no identify, and their join carries the handle. On joins and leaves, show a player’s standing and handle after their name as the game’s own join line does, such as (global moderator: someone), (player account: someone), or (local administrator) for a standing without an account, so nobody can pass for someone with an account.

The feed also passes on the game’s broadcast messages, the ones every player sees in their console. These are named for their kind, such as match, balance, duel, capture, defend, bomber, speedrun and servmsg. Each has:

• a text field with the console line, markup removed,
• fields that vary by kind,
• and arrays of the players involved, each with cn, name, team, actortype and privilege (a number here).

Use text for display, and the events above for anything you compute.

Positions, health, loadouts and anything else a player couldn’t already see in the match are never sent.

The master server

The master also answers the game server routes above for itself, and its /api/v1 index says "type": "master".

GET /api/v1/servers

{
    "time": 1762201000,
    "version": {"main": 209, "game": 289},
    "servers": [
        {
            "host": "1.2.3.4", "port": 28801, "priority": 0,
            "description": "My Server", "handle": "someone", "flags": "s", "branch": "stable",
            "version": 209, "webport": 28888, "relay": 1, "bridge": 1, "fingerprint": "9f86d0...",
            "status": { ... }
        }
    ]
}

For servers linked to the master, status is what the server reports about its match:

{
    "gameversion": 289, "map": "bloodlust", "maptitle": "Bloodlust", "mapauthor": "someone", "mapcrc": 1324137294,
    "modeid": 2, "mutators": 0,
    "ends": 1762201234, "maxplayers": 16, "playerslots": 16, "reserved": 0, "connections": 4, "mastermode": 0, "gamevars": 0, "gamemods": 0,
    "build": [2, 0, 9, 0, 1], "state": 5, "stateends": 1762201234,
    "spectators": 1, "bots": 4,
    "lastmatch": {"ended": 1762200634, "duration": 600, "map": "bloodlust", "maptitle": "Bloodlust", "modeid": 2, "mutators": 0,
        "teams": [{"team": "alpha", "score": 5}, {"team": "omega", "score": 3}], "players": [{"name": "someone", "team": "alpha", "points": 12, "frags": 9, "deaths": 4}]},
    "players": [
        {"cn": 0, "name": "someone", "handle": "someone", "team": "alpha", "privilege": "moderator", "local": true, "colour": 3368703},
        {"cn": 1, "name": "watcher", "team": "neutral", "privilege": "none", "spectator": true, "colour": 0}
    ]
}

Differences from /status on the server itself:

• mastermode and state are numbers here: the index into the master modes and game states.
• url and motd are as in GET /status.
• lastmatch is the newest of GET /matches, present once a match has ended there, with only the best httpmatchstatus players (3 by default). Show it when nobody is on, such as “Alpha won 5-3 in Deathmatch on Bloodlust, 20 minutes ago”.
• Times are end times, not times left, by the master’s clock. ends is when the match ends (-1 with no time limit), stateends when the current state does, and lastmatch’s ended when it ended. The master moves them off each server’s clock onto its own, and neither need agree with your visitor’s, so count down from the list’s time: work out how far your clock is ahead of it as the list arrives, and take that off your clock from then on. A list your browser revalidated with If-None-Match comes back with its old time and its old end times together, so keep the smallest difference you’ve seen rather than the latest.
• Players are every human player, spectators included; bots are left out. There are fewer fields than in /players:

Polled status

Servers that aren’t linked, including older versions of the game, don’t report anything. The master asks them itself every 30 seconds, the way the game’s server browser does, and lists what they answer as a status with "polled": true:

{
    "polled": true, "gameversion": 230, "map": "enyo", "modeid": 2, "mutators": 2,
    "ends": 1762201234, "maxplayers": 16, "mastermode": 0, "gamevars": 0, "gamemods": 0,
    "build": [1, 6, 0, 2, 64], "state": 5, "stateends": 1762201234,
    "players": [
        {"name": "someone", "handle": "someone", "privilege": "moderator", "local": true, "colour": 6316287, "teamcolour": 6252287},
        {"name": "watcher", "privilege": "none", "colour": 16731972, "teamcolour": 9478288}
    ]
}

• Fewer fields. There is no spectators or bots, and players have no cn, team or spectator. Spectators are listed as players, as the server doesn’t say who is spectating. Players come best score first.
• Players carry what the game’s server browser shows. That is name, handle (when signed in), privilege and local, and two colours as 0xRRGGBB in a number:

Any of these is left out when the server’s answer doesn’t have it.

• Numbers follow the server’s gameversion. modeid, mutators, mastermode and state are passed on exactly as the server sent them. Modes, master modes and game states are numbered the same in every version, but the mutator bits moved: v1.6 (game version 230) and 2.0.0 (245) number them differently from the current list. Check gameversion before naming them.
• Up to a poll old. ends and stateends are worked out from the times left when the master asked. A server that misses three polls in a row loses its status but stays listed, and one that starts reporting over the link replaces it with its own.

A server that has never answered has no status, and you only have what the list gives.

GET /api/v1/servers/<address>/<port>/history

How busy a server has been: the most players it had in each 15 minutes, oldest first, over the last days (default 7, up to a year).

{"bucket": 900, "start": 1762128000, "peaks": [0, 0, null, 3, 8, 12]}

• start is the unix time the first peak’s 15 minutes begin, and each one after is bucket seconds later; the last is the 15 minutes in progress.
• null is a time the master knew nothing: the server wasn’t listed, or didn’t say how many were on.
• Players are human players, spectators included and bots left out, as in status.
• A server the master has never listed gets all null. The answer may be a minute old.

GET /api/v1/history

The same for the whole game: every listed server’s players added together, then the most in each 15 minutes. That’s more than adding up each server’s peaks would say, as their busiest moments needn’t be at the same time. null is a time no listed server said how many were on.

To show when people usually play, average the peaks for each weekday and hour, in the viewer’s own time zone. A small game is quiet on weekdays, so eight weeks give each weekday enough to go on:

const res = await fetch("https://play.redeclipse.net:28888/api/v1/history?days=56");
const h = await res.json();
const sums = [...Array(7)].map(() => new Array(24).fill(0)), counts = [...Array(7)].map(() => new Array(24).fill(0));
h.peaks.forEach((p, i) => {
    if(p === null) return;
    const t = new Date((h.start + i * h.bucket) * 1000), day = (t.getDay() + 6) % 7; // Monday first
    sums[day][t.getHours()] += p; counts[day][t.getHours()]++;
});
const usual = sums.map((row, d) => row.map((s, hr) => counts[d][hr] ? s / counts[d][hr] : null));

WebSocket /api/v1/servers/live

The live list sends these messages:

• On connect: a snapshot with the same fields as GET /servers, its time included, then a queue event (see The Matchmaking Queue).
• When a server appears or changes: {"event": "add" | "update", "time": ..., "server": {...}}, with one entry as in the list.
• When a server goes: {"event": "remove", "host": "...", "port": ...}.

Changes are checked once a second. All you can say to it is about the Matchmaking Queue, below; anything else is ignored. A token, as ?token= on the URL, is read as the socket opens and sets, for as long as it stays open, which account the socket queues as and what it sees of the queue. A session on the master, from a remembered sign-in, is one.

If your visitors’ networks block port 28888, fall back to polling GET /servers with If-None-Match, no more often than every 5 seconds.

Join links and bounce links

A join link, redeclipse://<host>:<port>, opens the game and joins that server, or hands the server to the game that’s already open. The game registers the scheme itself whenever it starts. Join links never carry a password. Anything after the port is ignored, so later links can carry more. Link a listed server’s host and port from GET /servers straight to its join link when your page is in a browser.

Some places, such as Discord, only make https links clickable. For those, link the master’s bounce link instead:

https://play.redeclipse.net:28888/join/<host>/<port>

It’s a web page, not part of /api/v1. For a server on the list it shows the server’s description, sends the browser on to the join link, and offers a download link for anyone without the game. For anything else it answers 404 with a page that says so, so the master’s address can’t be used to send people to an unlisted server.

The Matchmaking Queue

The Matchmaking Queue is for people who’d play if enough others turned up. It has a channel for each version the master’s operator names, devel with masterverdevel and release with masterverrelease, and a channel set to "" doesn’t exist. A channel’s servers are the linked ones on its version that run the newest protocol any of them does, which is what an up to date game of that version plays, and each lists that channel. Everything below happens within one channel. Each entry has a Threshold: the fewest people it will play with, 2, 4, 6 or 8, counting everyone already on the server it would be sent to, spectators included. Once some group’s Thresholds are all met, the master pops them: it sends them all to one server and takes them out of the queue.

• Who goes: the largest group, lowest Thresholds first, whose Thresholds are all met by the group and those already on the server.
• Where: a listed server linked to the master, on the current game version, open, and with a player slot for each of them. Spectators don’t take a player slot, but slots kept for an earlier pop do, and spectators still take one of the server’s connections; a server too old to report its playerslots counts everyone on it against maxplayers instead. Of those, the one taking the largest group, then the one with the most people on, then the highest priority.
• When: whenever the queue changes, and once a second as the list does.
• On their way: popped entries count as on their server for 5 minutes (the master’s masterqueuetravel), or until they arrive, so the next pop doesn’t fill the same slots. The server is told who’s coming and keeps a player slot for each of them for that long (at most its own serverqueuereserve, 10 minutes by default), or until they’re playing there, so someone joining by themselves can watch but not take it; the slots it keeps are its reserved.

Every entry belongs to an account, and queuing needs one: there is one entry for each account, however many places it joined from. Linked servers report the handle of each player the master signed in there, which is how the master knows:

• Arrived: a popped entry’s account turns up on its server, and the entry ends.
• Held: an entry’s account is on a server without having been popped there. A held entry doesn’t count again, isn’t popped, and picks up again when they leave. It ends once its server has as many on as its Threshold.

So a player who joins without signing in to the server isn’t seen there. The game signs in by itself once its auth.cfg holds the account’s key.

Every entry lasts 60 minutes from when it last joined or was renewed, wherever from, whether or not any socket stays open. A renewal adds 30 minutes, up to 90 from now. An entry also ends when its account is deleted.

GET /api/v1/queue

{"time": 1762201000, "queue": {
    "channels": [{"name": "devel", "version": "2.0.9", "servers": 2, "ready": 3, "held": 1, "travelling": 0, "next": {"threshold": 4, "needed": 1}}],
    "ready": 3, "held": 1, "travelling": 0, "thresholds": [2, 4, 6, 8], "next": {"threshold": 4, "needed": 1},
    "entries": [{"handle": "someone", "displayname": "Some One", "privilege": "player", "channel": "devel", "threshold": 4,
        "state": "ready", "added": 1762200400, "expires": 1762204000}]}}

channels gives each channel’s counts, its version and how many servers it has; the fields beside it add every channel up, with the next closest to a pop of them all. A page or bot shows each channel, as a player can only join the servers of their own version.

Show it as the game does: “3 waiting, 1 more needed for a 4+ match”.

Each entry has its account’s handle, displayname ("" for none) and privilege (a name from the privilege table), its channel, threshold, state (ready, held or travelling), added and expires, and when they apply held or popped (host, port and, for popped, time). Show a player as the game does: the privilege’s icon, then the display name, or the handle when there’s none. At masterqueuelock and above (moderator by default) each also has sources (web, game, discord) and a game’s protocol, and at masterqueuediscordlock (developer) the account’s linked discord ID.

Queuing over the live list

Open the live list with a session on the master as ?token=, from a remembered sign-in, and send text messages on it for that account:

A socket may send one queue message every 250 ms. Without an account, offer the buttons greyed out with a way to register one, as the master answers sign in with an account to queue.

What comes back:

The account’s events go to every socket signed in as it. On a pop that’s mine, open redeclipse://<host>:<port> when the visitor asks, never by itself.

Queuing Discord members

A viewer signed in at masterqueuediscordlock (developer, the Discord bot’s) queues members by their Discord ID, with no source, into the account that ID is linked to:

Each is answered with queued and the member’s discord, the account’s handle, threshold, channel and expires, or queued with their discord and an error: no account when no account is linked to that ID, so tell them how to register one and link it, or not queued. A leave that takes them out is answered by its unqueued. Those viewers also hear unqueued with handle, the linked discord when there is one, and reason whenever any entry ends.

The queue is saved to masterqueuefile (masterqueue.dat) as it changes, so it outlives a restart.

Accounts

The master holds every account. Anyone can register one, from the game or the website, with a handle and an email address. The master mails a link to activate it, and only an activated account works. All of these routes are on the master and need https (or localhost), like signing in.

Registering

GET /api/v1/accounts says whether registration is open:

{"register": true, "website": true, "days": 7}

website is false when the master has no captcha set up, so only the game can register. days is how long a registration has to be activated.

POST /api/v1/accounts registers one:

It answers 202 with {"handle": "<handle>", "expires": <Unix time>}, and from the game, also pickup, a secret the game keeps (see The game collects its key).

The registration is now pending. It holds its handle and email so nobody else can take them, but it can’t sign in. The email has two links to the website’s account page:

• /account/activate#<token> activates it. The page posts the token to POST /api/v1/accounts/activate with {"token": "<token>"}, which makes the account’s key pair and answers once with:

  {"handle": "someone", "privkey": "1f3a...", "pubkey": "+8c2d...", "authkey": "authkey someone 1f3a..."}
  

  The master keeps only the public key. The private key is in this answer and nowhere else, so show it to the person straight away with how to save it: the authkey line typed in the game’s console, or saved as auth.cfg in their Red Eclipse home folder. The same token again gets 410.

• /account/cancel#<token>, “this wasn’t me”, posts to POST /api/v1/accounts/cancel and removes the registration at once (204).

A registration not activated within days is removed. Registering again with the same handle and email replaces it with a fresh one and a new email, in case the first never arrived; its earlier links stop working. The tokens are after # so they never reach a server’s logs, and a mail scanner fetching the links does nothing, as only the page’s script posts them.

Errors:

Lost keys

POST /api/v1/accounts/reset with {"handle": "<handle>"} or {"email": "<address>"}, and a captcha or "game": true as above, asks for a new key. It always answers 202 the same way, so it never says whether an account exists. If one does and has an email address, that address gets a link to /account/reset#<token>, lasting 24 hours. Only the newest link works.

The page posts the token to POST /api/v1/accounts/reset/confirm, which answers like activation, with the new key. The old key stops working, and the account’s remembered sign-ins end.

The game collects its key

A registration or reset from the game gets a pickup secret. The game posts it to POST /api/v1/accounts/pickup as {"pickup": "<secret>"} every few seconds:

• {"ready": false, "expires": <Unix time>} while the link hasn’t been followed. A registration’s answer also has its handle.
• {"ready": true, "handle", "privkey", "pubkey", "authkey"} once it has, which the game saves to auth.cfg. This works once.
• 404 once it ran out or was collected.

The page that followed the link still shows the key too, in case the game was closed.

The owner’s own account

These are below /api/v1/signin, so they take a remembered sign-in, as a cookie or a Bearer token.

The email links post their token to POST /api/v1/accounts/email/confirm, which answers {"handle", "email"}, or POST /api/v1/accounts/email/cancel (204).

Display names are what the website shows for an account, always with its handle beside it, as Display Name (handle). They’re free-form and not unique: up to 32 characters, filtered as names in game are, without colour codes or any of (){}<>:. An account that hasn’t chosen one takes the first name it’s seen playing under on a server the master signed it in on, or failing that its Discord name. In game, players are known by their in-game names, and on Discord by their Discord names.

Linking Steam and Discord

An account can link one Steam account and one Discord account, each proven through its own sign-in. A Steam or Discord account links to one account at most (409 otherwise). Links are only shown to the owner, administrators and the Discord bot.

Steam, through Steam’s OpenID:

1. GET /api/v1/signin/account/steam gives {"url", "state"}. Send the person to url.
2. Steam sends them back to /account/steam?state=<state> with openid.* fields in the query. Post them all, as they came, to POST /api/v1/signin/account/steam as {"openid": {"openid.ns": "...", ...}}.
3. The master asks Steam whether it made that answer, and answers with the account as GET /api/v1/signin/account does. The state works once, within 10 minutes.

DELETE /api/v1/signin/account/steam unlinks it.

Discord, two ways:

• Through Discord’s sign-in: GET /api/v1/signin/account/discord gives {"url", "state"}. Discord sends the person back to /account/discord?code=<code>&state=<state>; post both to POST /api/v1/signin/account/discord. 503 when the master has no Discord application set up.
• With a code: POST /api/v1/signin/account/discord/code gives {"code": "H6SEHTCQ", "expires": <Unix time>}, good once for 10 minutes. The person types /link <code> to the Discord bot.

DELETE /api/v1/signin/account/discord unlinks it.

The bot’s routes need a session at the master’s masterdiscordlock (developer by default), as the bot’s account has:

Administration

The master has no console, so its administrators manage it here, signed in with a remembered sign-in at the master’s masteradminlock (administrator by default). Nobody can change an account at or above their own standing, or give one, except a founder.

Flags are letters: u player, s supporter, m or o moderator, a administrator, d developer, c founder.

Limits

These are defaults. Operators can change them, except on the master’s own sockets and the Event feed.

Reference

Privileges

none, player, supporter, moderator, administrator, developer, founder, lowest to highest.

Teams

neutral (no team), alpha, omega, enemy (non-player enemies), environment.

Player states

Alive, Dead, Editing, Spectator, Waiting.

Game states

Numbers are for state in the master’s status, and strings are for /status.

Master modes

Modes and mutators

mutators is a bit field: bit n set means mutator n is on, including any the mode implies (Editing implies Free for All and Arena).

The game-specific mutators mean something different in each mode:

Weapons

claw, pistol, sword, shotgun, smg, flamer, plasma, zapper, rifle, corroder, trident, grenade, mine, rocket, minigun, jetsaw, eclipse, melee.

Leave reasons

End of packet, Invalid client number, Kicked from server, Communication error, Address is banned, Server is in private mode, Incorrect password, AI client removed, Server is at maximum capacity, Server and client are incompatible, Connection timed out, Packet overflow, Server shutting down, Hostname lookup failure, Client with same handle authenticated.

A player who simply quits leaves with no reason.

Versions

Everything here is version 1 of the API, below /api/v1. A future change that breaks clients will move to a new prefix, with /api/v1 kept alongside it for a while. New fields and events may appear in version 1 at any time, so ignore anything you don’t recognise.