Every term these documents use. Grouped by subject rather than alphabetised, because most
of them only make sense next to their neighbours.
| Term | Meaning |
|---|
| Ticket | One player or one party waiting to be matched, and the unit of matchmaking. The game backend creates it, and it carries everything the engine needs to know about those players. It leaves the pool when it is matched, cancelled, or expires. The ID is a UUID chosen by the caller. |
| Party | Several players who queued together and have to land in the same match on the same team. A party is one ticket with several players in it, never several tickets. The engine will not split a ticket across teams. |
| Pool | Every ticket currently waiting in a queue, and the engine’s working set. Pool size drives match quality more than any other number: more waiting players means more candidates to choose between. |
| Match | The engine’s output: a set of tickets, divided into teams, with a chosen host to run on. Its UUID makes a natural session key. |
| Backfill request | A request to find more players for a match that is already running, because someone left or it started under-full. The game backend posts it on behalf of a live game server. |
| Host | A place a match can be played: a region, a datacenter, a specific machine. IVK Match never interprets host identifiers. Whatever strings you send in Player.latencies come back as the match’s chosen host, so pick strings your provisioning layer already understands. |
| Skill rating | The number you assign to a player to say how good they are, sent as Player.mmr. The engine does not compute, store, or update it; that is the game backend’s job. It is unitless, and the queue’s parameters have to use the same scale you send. See Nemesis § The skill rating scale. |
| Attribute | A named property of a ticket that affects who it may be matched with: playlist, platform, language, input device. Each attribute carries what a ticket is (values) and what it will accept (accepts). Between them, that pair is how you express opt-in crossplay. |
| Term | Meaning |
|---|
| Queue | A group of players who want the same kind of match, and the unit of configuration. One YAML document describes one queue completely. Tickets are always created into a specific queue. |
| Queue ID | A queue’s stable identity, declared as queue_id. May be dot-separated (acme.ranked.solo), which groups related queues together. |
| Ruleset | A named matching configuration inside a queue. One queue can run several side by side (different team sizes, playlists, or skill brackets) and each ticket picks which rulesets it competes in. Each ruleset runs its own engine instance over the queue’s pool. |
Engine parameters (params) | The settings on a ruleset that control matching: team shape, latency budgets, scoring weights. Documented in full in Nemesis. |
engine_defaults | Parameters declared once at the queue level and merged into every ruleset, so a multi-mode queue does not repeat twenty settings five times. Objects merge recursively; arrays are replaced wholesale. |
| Live reload | Configuration changes take effect without a restart or a deploy on your side, within seconds of being saved. An invalid edit is rejected and the queue keeps running its last known-good configuration. |
| Retirement | The deliberate shutdown of a queue, via retired: true. It clears the pool rather than draining it, so every waiting player is removed. |
| Quarantine | A queue taken out of service after an internal state error. Unlike a configuration error it does not resolve itself, and submissions to that queue fail until it is recovered. |
| Term | Meaning |
|---|
| Nemesis | The match engine. Stateful and iterative: it keeps working on the matches it is assembling and improves them tick by tick, rather than solving the pool from scratch each time. |
| Tick | One round of engine work, run every tick_rate_secs (normally once per second). Several parameters, wait_time among them, are measured in ticks rather than seconds. |
| Hard filter | A rule that decides whether two tickets may share a match at all: latency budgets, attribute compatibility, match size. Failing a hard filter removes a candidate entirely, however good the fit would otherwise be. |
| Scoring | How the engine ranks the options the hard filters left it. Skill closeness, connection quality, and team balance are weighted against each other. The weights only mean anything relative to one another. |
| Origin | The host a ticket’s players are collectively best served from. Used by max_latency_by_origin to give different regions different latency budgets. |
| Host coverage | The share of the current pool a ticket can reach, given the hosts it finds acceptable. Low coverage is what makes a pool stop matching: strict latency budgets leave each ticket accepting one host, and no two tickets accept the same one. The min_host_coverage_* parameters exist to prevent that. |
| Term | Meaning |
|---|
| Outcome | Anything IVK Match needs to tell the game backend about asynchronously: a match was formed, a backfill was filled, tickets expired or were removed. The message shape is the same regardless of how it is delivered. |
| Sink | How outcomes reach your backend: webhook or WebSocket. Chosen per queue. See Outcome Delivery. |
| At-least-once delivery | The guarantee every sink offers. An outcome will arrive, and may arrive more than once. Consumers have to be idempotent; key on Outcome.id or Match.id. |
metadata | An opaque blob you attach to a ticket. IVK Match never looks inside it and hands it back verbatim on every outcome about that ticket. The place for your session IDs, party IDs, and anything else you want returned without a side lookup table. |
engine_input | The structured payload the engine does read: players, skill ratings, measured latencies, attributes. Validated at submission; a malformed payload is rejected. |
engine_output | The engine’s structured result on a match: teams and host selection. The counterpart to engine_input. |
| Reactivation | Putting already-resolved tickets back into the pool. The compensating action for a match the backend cannot honour, most often because provisioning failed. Reactivated tickets keep their original queue position. |
| Term | Meaning |
|---|
| Organisation | The ownership and billing boundary. Holds your team members, your billing relationship, and one or more games. |
| Game | The unit of tenancy for the service, sometimes called an app. Holds your queues, your credentials, and your usage records. Isolation is per game; nothing is shared between two games. |
| Portal | The web console for an organisation and its games: credentials, queue configuration, and usage. |
| Checkpoint | A periodic snapshot of a queue’s pool, so players waiting in a queue survive a restart of the service rather than being dropped. |
| Backend-driven provisioning | The integration shape available today: you receive the formed match and provision the game server yourself. |
| Matchmaker-driven provisioning | The planned alternative: IVK Match requests the server itself and hands you a match that is ready to join. See Availability & Roadmap. |
| Term | Who it means |
|---|
| Player | The game client. Never talks to IVK Match directly. |
| Game backend | Your service. Owns identity, skill ratings, and session state, and is the only thing that calls IVK Match. |
| IVK Match | The matchmaker. Holds the pool, forms matches, emits outcomes. |
| Orchestrator | Whatever provisions your game servers, whether your own service or a hosting provider’s API. |
| Game server | The dedicated server process a match is played on. |
