Lobbies and matchmaking
Steam-compatible lobbies with data, search filters and chat, the game-server browser with master-server filters, party beacons and networking helpers.
0x implements Steam's matchmaking model: lobbies that players create, search and join; a server browser of dedicated servers; and party beacons for joining friends. There is no automatic matchmaker that sorts players into matches. Your game picks a lobby or a server with the filters below.
Lobby state changes reach members over the push stream (lobby events), so clients don't
poll.
#Lobbies
| Route | Does |
|---|---|
POST /v1/apps/{appid}/lobbies {max_members?, type?} | create a lobby (the caller owns it and is its first member) |
POST /v1/apps/{appid}/lobbies/search {filters} | find public, joinable lobbies |
GET /v1/lobbies/{id} | the lobby's state |
POST /v1/lobbies/{id}/join | join → {response: EChatRoomEnterResponse, lobby} |
POST /v1/lobbies/{id}/leave | leave |
PUT /v1/lobbies/{id}/data | owner: set key/values (null deletes a key) |
PUT /v1/lobbies/{id}/member_data | a member: set their own key/values |
PUT /v1/lobbies/{id}/settings | owner: max_members, type, joinable, owner, game_server, linked |
POST /v1/lobbies/{id}/chat {data: hex} | send a chat message to every member → {chat_id} |
POST /v1/lobbies/{id}/invite {user} | invite someone (they get lobby_invite) |
max_membersis 1 to 250 (default 4).typeis Steam'sELobbyType:0private,1friends only,2public (the default),3invisible. Only public, joinable lobbies show up in search.- A lobby's state looks like
{id, appid, owner, members, member_data, data, max_members, type, joinable, game_server, personas}.personasgives members' display names. Lobby IDs and SteamIDs are strings. - A member whose last connection to the push stream closes drops out of their lobbies, as on Steam.
API=https://api.0x.limo; H="Authorization: Bearer $TOKEN"
LOBBY=$(curl -s $API/v1/apps/480/lobbies -H "$H" -H 'Content-Type: application/json' \
-d '{"max_members": 8, "type": 2}' | jq -r .id)
curl -s -X PUT $API/v1/lobbies/$LOBBY/data -H "$H" -H 'Content-Type: application/json' \
-d '{"mode": "ctf", "map": "dust", "skill": "1450"}'const api = "https://api.0x.limo", h = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
const lobby = await fetch(`${api}/v1/apps/480/lobbies`, { method: "POST", headers: h, body: JSON.stringify({ max_members: 8, type: 2 }) }).then(r => r.json());
await fetch(`${api}/v1/lobbies/${lobby.id}/data`, { method: "PUT", headers: h, body: JSON.stringify({ mode: "ctf", map: "dust", skill: "1450" }) });#Search filters
filters is a list. Every filter must match:
kind | Fields | Matches |
|---|---|---|
string | key, value, cmp | the lobby's data[key] compared as text |
numerical | key, value, cmp | data[key] parsed as an integer |
slots | value | at least value free slots |
near | key, value | no filtering; results sort by distance of data[key] to value |
count | value | at most value results (default 50) |
compatible | lobby | no member of the result blocked or ignored, or is blocked or ignored by, a member of lobby (or the lobbies linked to either) |
cmp is Steam's ELobbyComparison, read as "lobby value cmp filter value": -2 ≤, -1 <,
0 = (default), 1 >, 2 ≥, 3 ≠.
curl -s https://api.0x.limo/v1/apps/480/lobbies/search -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"filters": [
{"kind": "string", "key": "mode", "value": "ctf", "cmp": 0},
{"kind": "slots", "value": 2},
{"kind": "near", "key": "skill", "value": 1500},
{"kind": "count", "value": 10}
]}'The answer is a list of lobby states, closest first.
#Game-server browser
Dedicated servers log on (game servers) and send a heartbeat with their state at least every 90 seconds:
curl -s -X PUT https://api.0x.limo/v1/gameservers/me -H "Authorization: Bearer $GS_SESSION" \
-H 'Content-Type: application/json' \
-d '{"advertise": true, "port": 27015, "query_port": 27016, "name": "EU #1", "map": "dust",
"game_dir": "mygame", "players": 7, "max_players": 16, "tags": "ctf,eu", "dedicated": true, "secure": true, "password": false}'Only servers that send advertise: true are listed. Leave out ip (or send 0) and the service lists
the address the heartbeat came from.
Players list servers with GET /v1/apps/{appid}/gameservers. It takes the master-server filters
map, gamedir, gametagsand, gametagsnor, notfull, hasplayers, noplayers, dedicated,
secure, password and name_match. Each entry carries updated, the time of its last heartbeat.
DELETE /v1/gameservers/me unlists a server at once.
Players' favourite and history servers are kept with GET|PUT /v1/me/server_favorites (at most 1000).
#Party beacons
A beacon advertises open slots in a party to the members of one of the host's clans:
| Route | Does |
|---|---|
GET /v1/apps/{appid}/party/locations | where a beacon can go: the caller's clans |
POST /v1/apps/{appid}/party/beacons {open_slots, location, connect, metadata} | create one (1 to 250 slots) |
GET /v1/apps/{appid}/party/beacons | active beacons in the caller's clans |
POST /v1/party/beacons/{id}/join | reserve a slot for 5 minutes → {owner, connect} |
POST /v1/party/beacons/{id}/reservation {user, completed} | host: the player arrived, or the slot opens again |
PUT / DELETE /v1/party/beacons/{id} | host: change the slots / turn it off |
#Networking helpers
| Route | For |
|---|---|
GET /v1/net/config | the networking CA, the relay list and whether direct connections are allowed |
POST /v1/net/cert {spki} | a 24-hour certificate for the caller's key (peer-to-peer identity) |
POST /v1/apps/{appid}/fakeip {ports} | a stable FakeIP (169.254.128.0/17) and up to 4 fake ports for the caller in this app |
POST /v1/apps/{appid}/net/relay_ticket | publishers: a signed relay auth ticket for a game coordinator |
See the generated lobbies reference, the game servers reference and the lobbies reference.
