Every term these documents use. Grouped by subject rather than alphabetised, since 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). That pair is how opt-in crossplay gets expressed. |
| Term | Meaning |
|---|
| Queue | A group of players who want the same kind of match, and the unit of configuration. One YAML file describes one queue completely. Tickets are always created into a specific queue. |
| Queue ID | A queue’s stable identity, taken from the file’s queue_id field and never from its filename. May be dot-separated (acme.ranked.solo), which groups a customer’s queues and lets outcome consumers subscribe by namespace. |
| 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. |
| Hot reload | Configuration changes take effect without a restart. The container watches the config directory and applies valid edits within a second. 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 in its file. Deleting the file does not retire a queue. |
| Quarantine | A queue taken out of service by the runtime after a state error. Unlike a config error, it does not resolve itself; it needs an operator. |
| 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 how a pool stops being matchable: 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 the game backend: webhook, WebSocket, or NATS JetStream. Chosen per queue in that queue’s config. See Outcomes. |
| 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 |
|---|
| Container | One IVK Match process, serving one customer, holding all of that customer’s queues. The unit of tenancy: isolation between customers comes from running separate containers, not from anything inside the application. |
| Queue-config directory | The read-only mount holding one YAML file per queue. The source of truth for configuration; there is no registration API and no database. |
| State directory | The read-write, durable mount holding pool checkpoints and undelivered outcomes. Not optional: with ephemeral storage, every player waiting in queue is dropped on restart. |
| Checkpoint | A periodic snapshot of a queue’s pool to the state directory, so queued players survive a container restart. |
| Dashboard | The embedded operator UI on port 3002. A live view of queues, the pool, and recent matches. Unauthenticated, so never expose it outside the platform’s own network. |
| Model A / Model B | The two integration shapes. In Model A the game backend receives the match and provisions the server itself; this is what works today. In Model B IVK Match provisions the server and returns a match that is ready to join. See Integration Flow. |
| Term | Who it means |
|---|
| Player | The game client. Never talks to IVK Match directly. |
| Game backend | The customer’s service. Owns identity, skill ratings, and session state; the only thing that calls IVK Match. |
| IVK Match | The matchmaker — the managed service, or a self-hosted container at a later stage. Holds the pool, forms matches, emits outcomes. |
| Orchestrator | The platform’s gameserver provisioning API. |
| Game server | The dedicated server process a match is played on. |
| Platform / reseller | The gameserver-orchestration company offering IVK Match to its own customers. |
| Game team / customer | The studio authoring queue configs and integrating the API. |
