Getting Started
Last updated
Was this helpful?
Last updated
Was this helpful?
Get started with Matchmaking quickly and explore example scenarios for various genres.
See Matchmaker In-Depth for detailed explanations and more tips on customization.
Our matchmaking philosophy is driven by player perspective, with core principles of matchmaking:
social integration (such as friends and lobbies),
balance between match speed (time to play) and match quality (balanced player attributes),
high availability, process observability, and user-friendly error handling.
Testing our Matchmaker is entirely free, no credit card required.
Free Tier allows up to 3 hours of runtime on our shared test cluster, after each restart.
This tutorial assumes you have already:
,
uploaded and configured your server application on Edgegap,
Getting Started - Servers (Unity),
Getting Started - Servers (Unreal Engine),
successfully connected from a game client to your server on Edgegap.
For now, we’ll give you a quick tour of core Matchmaker features using , free for individuals.
Understanding matchmaking architecture is easy:
Our matchmaker reference architecture involves several flows of data:
Deployments API is used to deploy, scale, and manage your Dedicated Servers by Matchmaker,
This guide will focus on Matchmaking API and Backfill API.
Start with a simple example and test the core matchmaking player flow:
☑️ Click on Create Matchmaker first, then input:
matchmaker name - for your own reference, e.g. quickstart-dev ,
upload our Simple Example JSON configuration.
🍀 Simple Example (Minimal Recommended Configuration):
Make sure to change the application name and version to match your Apps and Versions.
☑️ If no validation errors appear, hit Create and Start and wait for the process to complete. This will result in a new free cluster starting, with your Simple Example matchmaker.
✅ You may now proceed to the next step.
🔥 major versions include breaking changes and require integration review,
🌟 minor versions include substantial backwards-compatible improvements,
🩹 patch versions include bug fixes and minor improvements.
To ensure that unexpected client crashes or abandoned tickets do not linger and take up your matchmaker resources, tickets will be cancelled after ticket_expiration_period causing their status to change to CANCELLED and then permanently deleted after ticket_removal_period .
name of your choosing, e.g. - match size,
rule type, also known as operator, e.g. - player_count,
and lastly operator attributes, e.g. team_count or team_size.
Player Count Rule
This is a special rule defining how many players need to match to initiate assignment:
team_count refers to number of teams, 1 team may be used for cooperative or free-for-all modes,
team_size refers to the number of players per team.
Our simple example demonstrates a cooperative game with 2 players.
Player Count rule is required and may only be defined once in your initial configuration rules.
Latencies Rule
Use this rule to provide the lowest possible ping for all players. Once clients measure and submit their round-trip time (ping) against all available beacons, matchmaking will only consider matches within a specific difference in ping values, measured against Ping Beacons. This presents a “soft” solution to splitting your player base, enabling matching with neighboring regions, especially improving match speed for less populated regions.
Use max_latency to prevent matching against players located far away.
Latencies rule may only be defined once in your initial configuration rules.
✅ You may now proceed to the next step.
Our example beacons rule above with "difference": 50, "max_latency": 200 initially:
Alice and Bob will match, since Beijing is discarded (>200) and the rest is within | A-B | < 50:
Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4}; and
Bob {Montreal: 27.3, Newark: 32.4, Dallas: 23.1, Beijing: 252.2}.
Charlie and Dave will not match, since | C-D | > 50 for Dallas Beacon:
Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2}; and
Bob {Montreal: 57.8, Newark: 32.0, Dallas: 24.2, Beijing: 272.3}.
☑️ Review details of your new matchmaker in our dashboard once it’s initialized:
Status indicates service health, may be ONLINE, OFFLINE, or ERROR.
Identifier helps Edgegap staff find your matchmaker quickly if you need help troubleshooting.
Started at can be useful to track down the latest update time.
API URL will be used by Game Clients and Game Servers to communicate with your matchmaker.
Swagger URL is a handy openAPI specification GUI we provide to explore API schema.
Auth Token is a unique secret token used by Game Clients and Game Server for authentication.
Edgegap staff will never ask for your tokens. Regenerate your token if you suspect a security breach.
To test your new matchmaker using the API, you will need the Swagger URL, API URL and Auth Token.
✅ You may now proceed to the next step.
☑️ First, open your Swagger URL to inspect your openAPI schema in the swagger GUI:
☑️ Click on Authorize 🔒, paste your Auth Token, and confirm by clicking on Authorize.
☑️ Scroll down to Ticket API - POST /tickets, expand and click Try it out.
attributes include values for your matchmaker rules, in this case for the latencies rule,
rule player_count is the only rule which doesn’t require any attributes in player tickets.
☑️ Click Execute and review the response to your player ticket request:
id is your unique matchmaking ticket ID, save this to check on your ticket later,
group_id is a unique group ID issued to every ticket, a solo player is represented as a group of 1,
each team can contain multiple groups, not exceeding the configured team size,
player_ip is the resolved public IP address of the player, regardless of the identification method,
assignment is set to null to indicate the ticket has not been matched or assigned to a server,
created_at provides information about when the player ticket was created for game UI usage,
☑️ Create a second ticket by hitting Execute again, so our two players match and a server is started.
☑️ Collapse POST /tickets and open GET /tickets/{ticketId}, then click Try it out.
☑️ Input ticket ID from the response in previous step and click Execute.
☑️ Review the updated assignment for your player ticket:
status changed to MATCH_FOUND first, while keeping assignment set to null to indicate players have matched and a server is being assigned,
☑️ Click Execute again to check on your ticket, and review the updated assignment for your ticket:
status changed to HOST_ASSIGNED with assignment containing details of the assigned server.
notice each deployment is tagged with all ticket IDs and profile for added traceability.
☑️ Try connecting from your game client to the assigned server.
☑️ Once you verify you’re able to connect to your Deployment without issues and are done testing, Stop your Deployment to free up capacity in your account for the next build.
✅ You may now proceed to the next step.
As indicated by Matchmaking Architecture above, Matchmaker integrates:
with Dedicated Server, to:
process player preferences passed through their tickets,
☑️ In Game Client, ensure you’re handling non-retryable errors:
HTTP 404 Not Found - ticket has been deleted,
HTTP 500 Internal Server Error - temporary service outage.
☑️ In Game Server, process player preferences and initial server context. API usage is not required:
☑️ Once players connect, Game Server and Game Clients start a loading scene to perform synchronization steps (e.g. selecting and loading a map/scene/level). We recommend a full fledged 3D scene, a lobby-like social UI, or a loading screen with a progress bar, to indicate initialization is progressing.
☑️ Once Game Clients fully loaded, players load/travel to the main gameplay scene.
no players join the match,
all players have left the match,
match concludes correctly.
🙌 Congratulations, you’ve completed Matchmaking integration! To learn more, keep reading.
Add custom-lobby-example profile in addition to your other profiles to support custom lobbies.
Competitive games focus on players competing against each other to achieve victory, whether as individuals (free for all) or teams. Matchmaking is crucial to ensure fair and balanced matches by pairing players or teams of similar skill levels. Maintain the pace of the game by quickly finding opponents with low latency to ensure fair competition.
You may define multiple teams with 1 or more players each, e.g.:
1v1 fighting game, with team count of 2 and team size of 1, require 2 players per game.
5v5 FPS, with team count of 2 and team size of 5, require 10 players per game.
5v5 MOBA, with team count of 2 and team size of 5, require 10 players per game.
10 player free-for-all, with team count of 1 and team size of 10, require 10 players per game.
20x3 battle royale, with team count of 20 and team size of 3, require 60 players per game.
restrict rank within a difference between two players for more casual games,
restrict rank difference to only allow opponents with the same rank for ranked games,
let players provide their map preferences and choose a map suitable for everyone,
slowly relax latency restrictions over time to find more players,
slowly increase allowed rank difference to find more players,
increase time between expansions for the highest ranks (challengers), as less players are available.
Create tickets with a higher rank for promotion matches, to match with tougher opponents.
Define separate cheater profiles to ensure that flagged cheaters or players with high amount of moderation reports do not negatively impact experience of healthy player segments.
With team count 1 and team size 4, require 4 players per game (all players are on the same team).
let players provide their map preferences and choose a map suitable for everyone,
let players choose a particular game difficulty to suit everybody’s skill level,
restrict player level difference to align players with a similar degree of game progression,
allow higher latency to prefer faster matches with better granular player preferences,
relax latency restrictions over time to find more players,
slowly decrease team size to require less players and start the game sooner,
optionally, you may have the server fill empty slots with AI teammates,
slowly increase allowed player level difference to find more players,
Using multiple profiles to separate casual game modes, competitive game modes, and top-tier challenger players allows you to customize rules and expansions for each type of player separately.
With team count 1 and team size 50, require 50 players per game (all players are on the same team).
let players provide their game mode preferences and choose a mode suitable for everyone,
allow higher latency to prefer faster matches with more players,
quickly relax latency restrictions to find more players,
slowly decrease team size to require less players and start the game sooner,
optionally, you may have the server fill empty slots with AI players,
this will allow players to join existing matches over new ones to maximize social interaction.
is used by Game Clients to communicate with Matchmaker,
to check on matchmaking service status,
and to manage ,
optionally to retrieve Ping Beacons,
are used to communicate between Game Clients and Dedicated Servers (Edgegap is not involved),
Optionally, is used by Dedicated Servers to replace or add more players.
creating the matchmaker instance on the shared ,
defining rules and settings in your matchmaker ,
testing player flow and managing with .
☑️ Once you’ve navigate to the .
As we release updates to Matchmaker, each new version uses to clearly communicate the impact of changes by interpreting format major.minor.patch:
Use to better understand and debug possible matchmaking flows while in development. We recommend disabling inspect API for your live matchmaker.
Some . We attempt to resolve this by retrying deployment up to max_deployment_retry_count times automatically (without client confirmation).
The core of our matchmaking logic is configured in . Each profile is a completely isolated matchmaking queue, pointing to with pre-defined amount of required CPU and memory (RAM) resources.
in the initial rule set must be met for players to be grouped together, each defined by three properties:
Size corresponds to one of our .
See for live games and zero-downtime updates.
☑️ Preview your request:
notice player_ip set to null - this will cause Matchmaker to use the IP address automatically added to your request (see for alternatives),
profile refers to your ,
profile confirming the choice of ,
see for matchmaking with your friends or lobbies,
team_id is a unique team ID issued to every ticket once reaches TEAM_FOUND status,
see for grouping up players in multiple teams,
status indicates the current status of the ticket, all tickets start in SEARCHING (see for details).
☑️ :
If you’re experiencing high latency, your netcode integration may be configured to simulate network latency. Disable VPN when testing for more realistic conditions and receive a .
with Game Client, to manage ,
optionally to support to add or replace players after starting.
☑️ In Game Client, we recommend providing ticket status updates throughout to players using in-game UI for best player experience. See:
See for additional information regarding Matchmaker service health.
Read to retrieve initial players’ matchmaking data.
Read for version parameters, settings, and secrets.
Read for deployment information, IP, location, etc...
Get variable values using or .
☑️ Optionally, Game Server may create and manage and player capacity (add or replace players who leave).
☑️ Ensure your properly using , if:
A full fledged configuration utilizing all matchmaking features including , , with may look like this:
Custom lobbies (private lobbies, sandbox levels) are a very popular option for couch multiplayer but also testing new features in competitive or cooperative games before they enter main game modes. These games typically require the least amount of restrictions, but aim to ensure that players can .
may use Custom Lobby profiles to support inviting friends reliably.
Define multiple for game modes specific rules and settings:
add to restrict opponents to specified Ping Beacons,
restrict to a maximum threshold to prevent matching players far away,
restrict to a maximum difference to maximize ping fairness,
allocate more CPU or memory using different when more players are allowed,
for pre-made lobbies or to fill teams without exceeding team sizes.
Start with the ideal conditions, and to ensure quick matches:
Cooperative games require players to work together as a team towards a common goal. Efficient matchmaking helps align players with similar preferences, gameplay habits, replaces players who leave, and improves to provide a responsive player experience.
Define multiple for game modes specific rules and settings:
for pre-made lobbies or to fill teams without exceeding team sizes,
allocate more CPU or memory using different when more players are allowed.
Start with the ideal conditions, and to ensure quick matches:
if no teammates are found, launch the game solo and use to add players later on.
Social games focus on building connections and relationships between players. These games emphasize collaboration, communication, and shared experience in a collaborative or competitive setting. Number of players per game may be very high. Efficient matchmaking ensures player preferences and gameplay habits are aligned, replaces players who leave, maximizes player capacity usage per server, and improves to provide a responsive player experience.
Define for game modes specific rules and settings:
for pre-made lobbies or to fill teams without exceeding team sizes,
add to restrict opponents to specified regions,
allocate more CPU or memory using different when more players are allowed.
to ensure quick matches:
if no teammates are found, launch the game solo and use to add players later on,
