Game Modes

A game mode is a matchmaking configuration for your game, referenced when a client starts a search. Game modes are created and managed from the Config page in the dashboard, not through the API described in the rest of this guide.

Fields

Match Shape

Match Shape describes a match's team composition as an array of team sizes — one entry per team, each the number of players on that team:

• [5, 5] — 5v5
• [3, 3] — 3v3
• [2, 2, 2, 2] — four teams of two
• [1, 3] — an asymmetric 1-vs-3 mode
• [5] — a single team of 5 with no opposing side, for grouped/co-op modes
• [1, 1, 1, 1, 1, 1, 1, 1, 1, 1] — a 10-player free-for-all, where every player is their own team

The total number of players a match needs is the sum of the shape (e.g. [5, 5] needs 10) — that total is what counts against your tier's match size limit, not the number of teams.

Once enough players are found for a match, they're split into teams according to the shape. For MMR and Ping game modes, players are balanced across teams so each side's average skill/ping is comparable. FIFO game modes have no skill or ping signal to balance on, so the split is random — see the Game Mode Config Reference for exactly how each algorithm forms and splits a group. Each player's resulting team is a zero-based index included in both the client's MATCH_FOUND message and the backend notification webhook — see Match Made.

Matching algorithm

Every game mode is MMR-based, Ping-based, or FIFO.

MMR-based game modes match players by skill rating, with two settings:

• Base Tolerance — the initial MMR range around a player's own rating that counts as a match. A smaller value gives tighter, more even matches; a larger value matches faster but more loosely.
• Expansion Multiplier — how much that range widens for every second a player keeps waiting (not once per matchmaking cycle), trading match quality for faster matches over time.

See the Game Mode Config Reference for the exact formula and how groups larger than 2 players are formed.

Every player must have an mmr attribute set on their ticket to queue for an MMR-based game mode — see Generate a Ticket.

Ping-based game modes match players by network latency instead, with one setting:

• Max Delta — the maximum difference (in milliseconds) between two players' measured ping that still counts as a match. Unlike MMR's tolerance, this does not widen the longer a player waits — it's a flat threshold. See the Game Mode Config Reference for more detail.

Unlike mmr, ping is never supplied via the ticket's attrs — it can't be known in advance. Pairiquium measures it live, per search attempt, directly against the player's connection. See Start a Search for what your client integration needs to handle.

FIFO game modes match players strictly in the order they joined the queue — the longest-waiting players are grouped together first, no config settings needed. Match Shape still applies: once enough players have accumulated at the front of the queue to fill the shape's total player count, they're grouped together as one match and randomly split into teams. See the Game Mode Config Reference for more detail.

Notification webhook

When a match is made for a game mode, Pairiquium sends a POST request to that game mode's Notification Webhook — separate from the MATCH_FOUND message sent to the game client over the WebSocket connection. See Match Made for the payload shape and response requirements, and Verifying webhook signatures for the per-game-mode signing secret.

Enabling, disabling, and limits

Each tier allows a limited number of enabled game modes at once. Creating a new game mode beyond your tier's limit, or downgrading to a tier with a lower limit, disables the excess modes rather than deleting them — their configuration is kept, and they can be re-enabled later (e.g. after upgrading) as long as you're back within the limit.

A game mode can only be deleted while it isn't actively processing searches. If players are currently queued in it, wait for searches to clear before deleting.