Introduction to Matchmaking

Last updated on August 3, 2026

info

AGS Matchmaking service has been upgraded. To see what's changed, refer to the table that compares the two versions.

Overview

AccelByte Gaming Services (AGS) Matchmaking provides a set of features developers can use to coordinate players into groups. The groups are based on selected preferences -- such as game mode and language -- and attributes stored for players -- such as Matchmaking Rating (MMR) -- to provide a well-balanced gameplay experience. Matchmaking will generate a match ticket based on these preferences and queue that ticket into a match pool to be evaluated.

Choose a session hosting model

Matchmaking creates a game session after it finds a match. How the game clients connect after joining that session depends on the session template and hosting model you choose.

Hosting model	Use when	Matchmaking owns	Your game owns
AMS dedicated server	You need a server-authoritative match hosted by AccelByte Multiplayer Servers (AMS).	Ticket creation, match evaluation, game session creation, and session invitation delivery.	Waiting for DS readiness, resolving the connection string, and connecting the client to the dedicated server.
P2P	One matched player can host the game session as a listen server or peer host.	Ticket creation, match evaluation, game session creation, and session invitation delivery.	Enabling P2P transport, determining whether the local player is the P2P host, and connecting clients to the host.

Use the engine-specific matchmaking guides for the shared game-code flow. When you reach the step for connecting to the game host, choose the tab that matches your hosting model:

• Integrate matchmaking (Unreal)
• Integrate matchmaking (Unity)

First implementation path

Use this path for your first end-to-end matchmaking implementation:

1. Choose the session hosting model: AMS dedicated server or P2P.
2. Configure a session template for that hosting model.
   • For P2P, set the session template type to P2P. See Configure P2P.
   • For AMS, configure the session template to request a dedicated server from AMS.
3. Configure a match ruleset for your game mode.
4. Configure a match pool that uses the session template and ruleset.
5. Integrate matchmaking in your game client:
   • Integrate matchmaking (Unreal)
   • Integrate matchmaking (Unity)
6. In the Connect to the game host section of the game-code guide, choose the tab that matches your hosting model.

Key concepts

It is important to understand the key concepts used in the design of AGS Matchmaking.

Matchmaking types

AGS Matchmaking supports three primary types of matchmaking by default, but can also be configured to handle complex scenarios where two or more types are combined. The primary types are:

• Team-based Matchmaking: matching players into teams to compete against each other. Team size and minimum player requirements can be defined as part of the ruleset.
• Skill-based Matchmaking: matching players based on skill level by comparing defined attributes to determine a good match. Attributes and the criteria to compare them by can be defined as part of the ruleset.
• Role-based Matchmaking: matching players based on an in-game role they have selected to play during a game session (e.g., tank, healer, or damage) often as part of a team. Role requirements for the game session and teams can be defined as part of the ruleset.

Additionally, the Matchmaking can be extended using our gRPC plugin, which allows developers to customize the implementation according to their needs.

Game mode

A game mode provides a distinct gameplay experience for players such as team deathmatch, free for all, co-op, and others. AGS Matchmaking supports multiple game mode definitions, including separate matchmaking logic for each mode. This allows unique criteria to be defined -- such as skill ranking or team composition -- for grouping players together. To learn more about defining a game mode, refer to Session.

Game session

A game session is an instance of a game mode where matched players are connected to interact with each other. Game sessions can be deployed to a dedicated servers or hosted locally on a game client computer for peer-to-peer play.

Team composition

For team-based game modes, team composition refers to the number of players that can participate as part of a team and any role-specific requirements needed to balance out a game session. Additionally, the number of teams required to participate, including the minimum number of players per team, are configurable as part of the match ruleset.

Match ticket

A match ticket represents a player or party during matchmaking. It contains the attributes and parameters necessary for the match ruleset to determine the best possible match.

Match pool

Also referred to as a queue, a match pool defines a segment of players and parties, represented as tickets, based on selected preferences such as game mode, region, language, etc. Once in a pool, tickets will be evaluated and paired together and connected to a game session based on the match ruleset defined for the game mode.

Match ruleset

A match ruleset defines the logic used to compare tickets during matchmaking to ensure they are optimally grouped based on the experience desired per game mode. AGS Matchmaking reviews the tickets queued in the corresponding pool to determine the best possible match.

Match function

A match function defines the behavior that AGS Matchmaking will use to evaluate tickets waiting in the queue. By default, it will use the logic defined in match the rulesets, but through the use of a gRPC Plugin, new functions can be implemented that extend how the service works.

Backfilling

During gameplay, it may become necessary for a game session to request new players to be added. Backfilling is the process by which the game session can submit a ticket to AGS Matchmaking to receive proposals for new players, which can then be accepted or rejected. Game sessions can be configured to auto-backfill through the Session Template, or it can be left up to the game server to manage directly.

Matchmaking flow

This section reviews the flow experienced by players that match into a game session either as a solo player or as part of a party. Here are the high level steps involved:

1. If the game supports parties, a player may create a party and invite friends to participate. The party leader selects the desired game mode and sets any preferences available. Any invited party members must join before matchmaking can begin.
2. The solo player or the party leader initiates matchmaking, which creates a match ticket and queues it into a match pool. If a party leader initiates matchmaking, one match ticket is submitted with all the players in the party attached.
3. The service evaluates the ticket based on the logic defined in the associated match ruleset in order to find optimal matches.
4. When a match is found, the service requests a game session from AGS Session and attaches the ticket information, match results information, and suggested teams to the session.
5. The service creates a backfill ticket for the game session if auto-backfill is enabled in the match ruleset (by setting auto_backfill to true) so additional matches can continue to be found until the max player setting is satisfied for that ruleset.
6. Players receive an invite to join the game session once they are selected as a match and can be connected.

This simplified flow diagram illustrates the interactions between the client and relevant services during the matchmaking process:

A few notes on the flow:

• if multiple Players in a party were matching together, the party leader would have created a single ticket on behalf of the party, and all party members would receive relevant notifications and take actions like joining the session and connecting to the Host.
• the order of OnMatchFound and OnSessionInvited is not guaranteed
• the Player may not receive OnDSStatusChanged if they join after the host was initialized. As a result, they must check the DSInformation.ip field after joining the session to see if there is an existing host.
• this flow shows the dedicated server path. If your session template uses P2P, the match ticket, match result, and session invitation steps are the same, but the game host connection step changes.