0xDocs 0x.limo

Docs / REST API

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

RouteDoes
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}/joinjoin → {response: EChatRoomEnterResponse, lobby}
POST /v1/lobbies/{id}/leaveleave
PUT /v1/lobbies/{id}/dataowner: set key/values (null deletes a key)
PUT /v1/lobbies/{id}/member_dataa member: set their own key/values
PUT /v1/lobbies/{id}/settingsowner: 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_members is 1 to 250 (default 4).
  • type is Steam's ELobbyType: 0 private, 1 friends only, 2 public (the default), 3 invisible. 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}. personas gives 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.
bash
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"}'

filters is a list. Every filter must match:

kindFieldsMatches
stringkey, value, cmpthe lobby's data[key] compared as text
numericalkey, value, cmpdata[key] parsed as an integer
slotsvalueat least value free slots
nearkey, valueno filtering; results sort by distance of data[key] to value
countvalueat most value results (default 50)
compatiblelobbyno 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 ≠.

bash
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:

bash
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:

RouteDoes
GET /v1/apps/{appid}/party/locationswhere 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/beaconsactive beacons in the caller's clans
POST /v1/party/beacons/{id}/joinreserve 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

RouteFor
GET /v1/net/configthe 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_ticketpublishers: a signed relay auth ticket for a game coordinator

See the generated lobbies reference, the game servers reference and the lobbies reference.