Module online 

Matchmaking

For online matchmaking, we use a centralized matchmaking server to connect peers to each-other and to forward the peers’ network traffic. All connections utilize UDP and the QUIC protocol.

The matchmaking server is implemented in the bones_matchmaker crate. It binds to a single UDP port and listens for client connections. QUIC’s multiplexing capabilities allow the server to handle any number of clients on this single port.

Once a match starts, client traffic is proxied through the matchmaking server. While not true peer-to-peer networking, clients logically send messages to each other, with the server acting as an intermediary.

Pros of this approach:

• Reduced connections per peer (one connection to the matchmaker only)
• Client IP addresses are hidden from each other
• Easier to bypass firewalls and NATs
• Simplified connection process

Cons:

• Increased server bandwidth usage
• Additional network hop between peers, potentially increasing latency

This design doesn’t preclude future support for true peer-to-peer connections or LAN games without a matchmaker.

Matchmaking Protocol

Initial Connection

1. The client connects to the matchmaking server.
2. The client sends a RequestMatchmaking message over a reliable channel.
3. This message contains MatchInfo with:
   • The desired number of players
   • A game_id to identify the game
   • match_data (arbitrary bytes for game mode, parameters, etc.)
   • player_idx_assignment to specify how player ids should be assigned (ie. randomly assign a side for a pvp match)

Players must specify identical MatchInfo to be matched together. The match_data ensures players are connected for the same game mode and version.

Waiting for Players

1. The server responds with an Accepted message.
2. While waiting, the server may send MatchmakingUpdate messages with the current player count.
3. When the desired number of players is reached, the server sends a Success message containing:
   • A random_seed for deterministic random number generation
   • The client’s player_idx
   • The total player_count
   • A list of player_ids with their network addresses

In the Match

Once all players have received the Success message, the matchmaker enters proxy mode:

1. Clients send SendProxyMessages to the server, specifying a target client (or all clients) and the message data.
2. The server forwards these as RecvProxyMessages to the target client(s), including the sender’s player index.

The matchmaker supports both reliable and unreliable message forwarding, allowing the game to implement its preferred synchronization protocol.

Structs

LobbyId

A unique identifier for a lobby

LobbyInfo

Information about a lobby

LobbyListItem

Information about a lobby for the lobby list

MatchInfo

Information about a match that is being requested

MatchmakerConnectionState

Internal struct used to keep track of the connection with the matchmaker

OnlineMatchmaker

Struct that holds a channel which exchange messages with the matchmaking server.

Enums

OnlineMatchmakerRequest

Online matchmaker request

OnlineMatchmakerResponse

Online matchmaker response

PlayerIdxAssignment

Choose how player_idx should be assigned to each player who joins a match/lobby.

Constants

MATCH_ALPN

ALPN used for the matchmaking protocol.

READ_TO_END_BYTE_COUNT

The number of bytes to use for read_to_end()

Statics

ONLINE_MATCHMAKER

Online matchmaker channel

Type Aliases

GameID

A unique identifier for a game