Getting Started
Get started with Matchmaking quickly and explore example scenarios for various genres.
Matchmaking in session-based games generally aims to:
find other players based on criteria like region, latency, skill, or game parameters;
search for servers to join based on available capacity [or ping, region, skill, map, mode];
start new server if existing servers are full or don't satisfy player criteria.
Player experience comes first, defining our core objectives:
high match fill rate and social feature integration (play with friends in groups),
fast matches with controlled match quality (low latency, shared preferences),
reliable and predictable matchmaking process with global availability.
Follow along this video to get started with our Matchmaker service:
✔️ Preparation
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 (Unreal Engine),
Getting Started - Servers (Unity),
successfully connected from a game client to your server on Edgegap.
Matchmaking Architecture
This guide will focus on Matchmaking API and Backfill API.
There are four (4) important flows of data when matchmaking is involved:
Matchmaking API is used by Game Clients to communicate with Matchmaker:
for group management, server assignment, and monitoring,
for ping measurement with Ping Beacons.
Deployments API is used to deploy, scale, and manage your Dedicated Servers by Matchmaker.
Netcode Transports are used to communicate between Game Clients and Dedicated Servers:
Backfill Match to replace or add more players from Server.
🍀 Simple Example
Start with a simple example and test the basic matchmaking player flow:
creating the matchmaker instance on the shared ☁️ Hosting Cluster,
defining rules and settings in your matchmaker 📏 Configuration,
testing player flow and managing tickets with 📗 API.
1. Set Up on Free Tier
☑️ Register for your free Edgegap account and open the Matchmaker dashboard page.
☑️ 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.
{
"version": "3.2.0",
"inspect": true,
"max_deployment_retry_count": 3,
"profiles": {
"simple-example": {
"ticket_expiration_period": "5m",
"ticket_removal_period": "1m",
"group_inactivity_removal_period": "5m",
"application": {
"name": "",
"version": ""
},
"rules": {
"initial": {
"match_size": {
"type": "player_count",
"attributes": {
"team_count": 1,
"min_team_size": 2,
"max_team_size": 2
}
},
"beacons": {
"type": "latencies",
"attributes": {
"difference": 100,
"max_latency": 200
}
}
},
"expansions": {}
}
}
}
}Troubleshooting and FAQ:
☑️ 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.
2. Explore Configuration
As we release updates to Matchmaker, each new version uses Semantic Versioning to clearly communicate the impact of changes by interpreting format major.minor.patch:
🔥
majorversions include breaking changes and require integration review,🌟
minorversions include substantial backwards-compatible improvements,🩹
patchversions include bug fixes and minor improvements.
Use Matchmaker In-Depth to better understand and debug possible matchmaking flows while in development. We recommend disabling inspect API for your live matchmaker.
Some deployments may result in Errors. We attempt to resolve this by retrying deployment up to max_deployment_retry_count times automatically (without client confirmation).
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 .
The core of our matchmaking logic is configured in Profiles (Queues). Each profile is a completely isolated matchmaking queue, pointing to 🏷️ App Versions with pre-defined amount of required CPU and memory (RAM) resources.
Rules in the initial rule set must be met for players to be grouped together, each defined by three properties:
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_countormax_team_size.
Player Count Rule
This is a special rule defining how many players need to match to initiate assignment:
team_countrefers to number of teams, 1 team may be used for cooperative or free-for-all modes,min_team_sizerefers to the minimum number of players per team.max_team_sizerefers to the maximum 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
latencies is a special rule optimizing the ping of player matches:
reduce client-server latency by removing regions with high latency (above threshold),
improve match fairness by grouping players with similar latency (below difference).
Rule latencies is optional and may only be defined once in your initial configuration rules.
✅ You may now proceed to the next step.
3. Review Instance Details
☑️ 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.
Size corresponds to one of our Pricing Tiers.
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, you will need the Swagger URL, API URL and Auth Token.
✅ You may now proceed to the next step.
See ⏩ Rolling Updates for live games and zero-downtime updates.
4. Test Tickets API
☑️ 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.
☑️ Preview your request:
notice
player_ipset tonull- this will cause Matchmaker to use the IP address automatically added to your request (see Matchmaker In-Depth for alternatives),profilerefers to your Profiles (Queues),attributesinclude values for your matchmaker rules, in this case for thelatenciesrule,rule
player_countis the only rule which doesn’t require any attributes in player tickets.
☑️ Click Execute and review the response to your player ticket request:
idis your unique matchmaking ticket ID, save this to check on your ticket later,profileconfirming the choice of Profiles (Queues),group_idis a unique group ID issued to every ticket, a solo player is represented as a group of 1,team_idis a unique team ID issued to every player onceTEAM_FOUNDstatus is reached,player_ipis the resolved public IP address of the player, regardless of the identification method,assignmentis set tonullto indicate the ticket has not been matched or assigned to a server,created_atprovides information about when the player ticket was created for game UI usage,statusindicates the current status of the ticket, all tickets start inSEARCHING.
☑️ 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_FOUNDfirst, while keepingassignmentset tonullto 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_ASSIGNEDwithassignmentcontaining details of the assigned server.
☑️ Inspect your new deployment in our dashboard:
notice each deployment is tagged with all ticket IDs and profile for added traceability.
A few seconds after finding a match, memberships proceed to status:HOST_ASSIGNED indicating that your deployment is now ready and your game server is initializing.
Each player reads their ticket_id and assignment and attempt connection using the (deployment URL) and the External Port. Your game server may be still initializing at this time, so players must retry connection several times, until exceeding your usual server initialization time:
To connect from PIE (Editor) during development and testing, press the tilde key ~ and type open {URL}:{port} and wait for your editor to load the map.
To connect from a game client build (and in live production environment) try
Unreal Engine ⚡ Integration Kit:
install from Fab Marketplace (free for Personal use),
import simple example blueprint and customize to your needs.
In case of failed connections or dark screen consult our troubleshooting guide.
To connect your Unity Editor or game client to your cloud deployment, input:
Deployment URL pointing to the server's IP, usually in
NetworkManagercomponent.External port mapping to the server's internal listen port, usually in a Transport component.
In case of connection timeout or other issues consult our troubleshooting guide.
Players should save their assignment ID persistently between game restarts, so that in case of game client crash they can retrieve the connection details and attempt reconnecting.
See Getting Started and our SDKs with automatic reconnect function and more.
☑️ Try connecting from your game client to the assigned server.
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 low-latency deployment.
☑️ 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.
5. Game Integration
Matchmaker integrates with:
Game Client, to manage groups, memberships, assignments, and tickets,
Dedicated Server, to Backfill Match after a player leaves.
☑️ In Game Client, we recommend providing ticket status updates to players using in-game UI for best player experience. See:
Unity ⭐ Matchmaking SDK by Edgegap:
import simple example script and customize for your needs,
Unreal Engine ⚡ Integration Kit:
install from Fab Marketplace (free for Personal use),
import simple example blueprint and customize to your needs.
☑️ 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, read player preferences and initial server context:
Injected Variables (Matchmaker) to retrieve initial players’ matchmaking data.
Injected Variables (App Versions) for version parameters, settings, and secrets.
Injected Variables (Deployment) for deployment information, IP, location, etc...
☑️ Once players connect, Game Server and Game Clients start a loading scene - 3D scene, a lobby-like social UI, or a loading screen with a progress bar, to indicate initialization is progressing.
☑️ Ensure your deployment will be stopped properly once the match concluded.
🙌 Congratulations, you’ve completed Matchmaking integration! To learn more, keep reading.
🏁 Advanced Example
A full fledged configuration utilizing all matchmaking features including Profiles (Queues), Rules, and Rule Expansion may look like this:
🎾 Custom Lobby
Custom lobbies (private lobbies, sandbox levels) are a very popular option for couch multiplayer and testing new features in games before they enter main game modes. Typically require the least amount of restrictions, but aim to ensure that players can Group Up.
Add custom-lobby-example profile in your existing matchmaker to support custom lobbies.
🥛 Backfill Showcase
Building on 🍀 Simple Example, this configuration showcases Matchmaker In-Depth with Matchmaker In-Depth.
Optionally, some games may have special matchmaking needs, such as:
allow new players to join games in progress (friends or "randoms"),
replace players who abandon (leavers) after server starts to avoid restarting match,
allow spectators to join and observe tournament or friends’ matches (e-sports),
centralize players in larger servers to provide more social interactions (MMOs).
Backfill is a server-owned ticket representing players currently connected to the server. This ensures newly added players will respect your matchmaking rules when matched with current players.
Use Matchmaker In-Depth to replace Seat/Match sessions. Matchmaker only supports Default session.
Backfills ignore player_count rule, and always match exactly one group. backfill_group_size controls team capacity with round-robin strategy, filling teams evenly in a controlled manner.
The steps to complete a successful backfill are:
Server creates Matchmaker In-Depth for each team separately, using values from:
Real
assignmentdata retrieved from Injected Environment Variables (deployment).Currently connected players'
tickets:from 📌 Injected Variables (matchmaker), previous backfills'
assigned_ticketresponse, or mock data manipulated to match specific players,replace
backfill_group_sizevalues with possible group sizes ,
Game clients create new Matchmaker In-Depth with
backfill_group_sizearray with values:"1"if the player is matchmaking alone..
"new"if players enabled starting new games in addition to joining in-progress games.
Game clients proceed to Find Match and pair players with the matching backfill.
If the backfilled group didn't completely fill the team, the server may repeat this process with the newly backfilled players' tickets, to add more players and reach desired team sizes.
⚔️ Competitive Games
Competitive games focus on players competing against each other to achieve victory, whether as individuals (free for all) or teams. Ensure fair and balanced matches by pairing players or teams of similar skill levels, and maintain game pace by quickly finding fair competition.
You may define multiple teams with 1 or more players each, for example:
5v5 FPS
2
5
10
5v5 MOBA
2
5
10
20x3 Battle Royale
20
3
60
10p Free For All
1
10
10
Define multiple Profiles (Queues) for game mode specific rules and settings, and expand as needed.
For all matches:
restrict matchmaking latency to prevent matching players far away,
Group Up for pre-made parties and prevent exceeding team sizes,
slowly relax latency restrictions over time to find more players,
allocate more CPU or memory with different 🏷️ App Versions for specific profiles,
For casual matches:
omit rank restrictions to maximize match speed and match fill rate,
let players provide their map preferences to find a map suitable for everyone,
specify backfill group size to replace leavers without exceeding team sizes,
remove latency limitations to guarantee a match after 3 minutes (180s) of queue time.
For competitive matches:
restrict rank to only allow opponents with similar skill level,
use rank-up or rank-down ranks to match players at the league's rank extremes.
For the top 1% of high skill matches (challengers):
use numerical skill ratings (ELO) to gain fine control over skill distribution in matches,
wait longer before relaxing latency requirements due to lower amount of 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.
🤝 Cooperative Games
Cooperative games require players to work together as a team towards a common goal, or AI opponent. Align players with similar preferences and gameplay habits. Replace players who leave, and improve 🟢 Connection Quality to provide a responsive player experience.
With team count 1 and maximum team size of 4, require up to 4 players per match.
Define multiple Profiles (Queues) for game modes specific rules and settings:
start with minimum of 4 players to keep players in queue and maximize match fill rate,
restrict matchmaking latency to prevent matching players far away,
let players choose a particular game difficulty to suit everybody’s skill level,
let players provide their map preferences to find a map suitable for everyone,
restrict player level difference to require similar degree of game progression,
specify backfill group size to replace leavers without exceeding server capacity,
use moderation flags to separate low-karma players and cheaters from general population,
Group Up for pre-made parties and to fill teams without exceeding server capacity,
allocate more CPU or memory using different 🏷️ App Versions for other profiles.
Start with the ideal conditions, and expand restrictions to ensure quick matches:
relax latency restrictions over time to find more players,
increase allowed player level difference to find more players,
decrease minimum team size to require less players and start the game sooner,
server may fill empty slots with AI teammates,
or Backfill Match to add players later,
set minimum team size to 1 to launch the game solo after 150s of queue time
🎈 Social Games
Social games focus on building connections and relationships between players through collaboration, communication, and shared experience. Support high number of players, maximize match fill rate, and align player preferences and gameplay habits. Replace players who leave, and ensure high 🟢 Connection Quality to provide a responsive player experience.
With team count 1 (free for all) and maximum team size of 50, require up to 50 players per match.
Define Profiles (Queues) for game modes specific rules and settings:
restrict matchmaking latency to prevent matching players far away,
let players provide their game mode preferences and find a mode suitable for everyone,
specify backfill group size to replace leavers without exceeding server capacity,
use moderation flags to separate low-karma players and cheaters from general population,
Group Up for pre-made lobbies or to fill teams without exceeding server capacity,
allocate more CPU or memory using different 🏷️ App Versions for other profiles.
Start with the ideal conditions, and expand restrictions to ensure quick matches:
relax latency restrictions over time to find more players,
slowly decrease minimum team size to require less players and start the game sooner,
server may fill empty slots with AI players,
or Backfill Match to add players later,
set minimum team size to 1 to launch the game solo after 150s of queue time.
Last updated
Was this helpful?
🎈 Social Game Example