Quickstart

This guide goes from a new game to a formed match. It assumes an existing sign-up; the free tier is enough for everything here.

1. Get a token

In the portal, create an API credential for the game. It is shown once. Store it in a secret manager immediately, because it cannot be retrieved again, only replaced.

2. Create a queue

Create a queue with this configuration. It is the smallest configuration that forms matches:

version: 1
queue_id: acme.smoketest
name: Smoke Test
rulesets:
  - ruleset_id: default
    engine_id: nemesis
    params:
      team_size: { start: 5, end: 5 }
      team_count: { start: 2, end: 2 }

Ten players, two teams of five. Everything else takes a default: skill matching is on, latency scoring is off, and no attribute filtering happens. Change queue_id to an ID in the game’s own namespace. Dot-separated IDs are the convention, and they keep related queues grouped together.

3. Submit a ticket

One ticket is one player or one party. This is a single player:

grpcurl -H 'Authorization: Bearer <token>' -d '{
  "ticket": {
    "id": "3f2b8c1e-9a4d-4f7b-8e11-2c5d6a7b8c90",
    "queue_id": "acme.smoketest",
    "ruleset_ids": ["default"],
    "engine_input": "<base64 nemesis EngineInput>"
  }
}' match.ivk.dev:443 matchmaker.core.v1.MatchmakerService/CreateTicket

engine_input is a serialized matchmaker.engines.nemesis.v1.EngineInput, base64-encoded. That is the least convenient part of calling the API by hand, and the .NET SDK handles it by packing the payload:

EngineInput = Nemesis.PackInput(new EngineInput
{
    Players = { new Player { PlayerId = "alice", Mmr = 0.55 } },
})

The call returns as soon as the ticket is durably queued. It does not return a match.

4. Submit nine more

A 5v5 ruleset needs ten players, and the engine will not form a match until it has them. Submit nine more tickets with different UUIDs and varying mmr values.

Reusing an ID is not an error, since that is how retries stay safe, but it will not add a second player to the pool. Ten calls with the same ID result in one ticket and no match.

5. Watch the match form

Within a tick or two of the tenth ticket, the engine forms a match and emits a match.created outcome carrying the match ID, every ticket, and the teams the engine chose.

What a full integration adds

These steps submit tickets and let the engine match them. A production integration adds four things:

Next	Why
Core Concepts	The model behind these steps: pools, ticks, commitments
Integration Flow	The full sequence, including provisioning and notifying players
Queue Configuration	Latency budgets, skill tolerance, crossplay rules
Production Checklist	The failure cases this quickstart does not handle

A formed match is a commitment. Those ten players have left the pool, and the game backend is responsible for putting them in a game. The integration flow covers what that requires.