In-Depth Look

Learn more about Edgegap’s no-code matchmaker concepts in-depth and customize to your needs.

✔️ Introduction

Matchmaking in match-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.

Get started within 5 minutes and test the all features for free, no credit card required.

Upgrade when you're ready for a more powerful, private (dedicated) cluster. Native integration with Edgegap Deployments delivers best-in-class ping no matter where your players are located.

There are three essential concepts to each Matchmaker:

• ☁️ Hosting Cluster - underlying server infrastructure, fully managed and operated by Edgegap.

• ⚙️ Configuration - set of rules and settings which define how the matchmaker operates.

• 🌐 Service Instance - live matchmaking service running 24/7 on the Cluster, using Configuration to match players together and produce deployment (server) assignments.

▶️ Start Matchmaking

Get started quickly - add our SDK to your game:

• Unreal Engine ⚡ Integration Kit:

  • read the documentation by Betide Studios,

  • install from Fab Marketplace (free for Personal use).

• Unity ⭐ Software Development Kit:

  • install package using Unity Package Manager for free,

  • explore our getting started guide and complete examples.

Learn about matchmaking process to customize, troubleshoot, and optimize your game integration:

1. Authenticate Player - prevents pirated copies from playing online,

2. Create Lobby - join up with your friends and share player/match preferences,

3. Group Up - register your Lobby as a Matchmaking Group,

4. Find Match - get ready and start looking for a match (new or existing),

   1. Assign Server & Inject Tickets - server is automatically assigned after a few seconds,

5. Connect and Authenticate - attempt secure connection to game server,

   1. Confirm Identity - server verifies identity of game client using third party tokens,

   2. Accept Player or Kick Player - server decides if the player is allowed to join.

Authenticate

All requests must send an Authorization HTTP header with your secret Auth Token:

Individual players can be identified using their ticket ID, available on clients and server. Optionally, add custom authentication or limits with a custom proxy using Server to Server API.

Group Up

Creating a Group ensures players join the same team and server with their friends.

Lobby and Group

Lobby and Group are similar but slightly different terms relating to Player Sessions.

Use a Lobby service if your game design requires setting player-controlled matchmaking preferences (e.g. character choice, difficulty, map, etc.). As players join and leave the Lobby, they also update the matchmaking Group to prepare for finding a match later.

Our cross-platform matchmaker supports all commercial and custom Lobby services:

Lobby owner (the player sending invites) must also create the matchmaking group.

Store your group's ID in your shared lobby data, so other lobby members can easily find and join a matchmaking group associated with the third party lobby. Players invited to the group use the group ID to create their memberships (join), and to securely store their matchmaking attributes.

Ping Optimization

If ⚙️ Configuration includes latencies rule all group members send their Ping Beacons measurements to prevent matching players in distant regions or much higher/lower ping (latency).

Abandon Queue

Group owner may delete the group, automatically deleting all group memberships. Deleting the group after matchmaking started will cancel all memberships, and delete them shortly after.

Group members (besides owner) may delete their memberships (leave group) at any time before Find Match. Deleting a membership afterwards will cancel matchmaking for the whole group.

Once cancelled, if the group wishes to restart matchmaking, the group owner must re-create the group, share the new group ID to members, and have them re-create their memberships.

Once a match is found, group can't be deleted (409 Conflict), and will be removed automatically. Your server should allow some time (e.g. 60s) for players to connect before assuming a player abandoned.

If your server flags a player as abandoned, you may:

• replace the leaver with an AI character to immediately start the match,

• or create a backfill to find a new player to replace the leaver,

• or proceed without replacing the leaver, if your game design permits variable player count.

Find Match

To start looking for a match, all members and the owner must mark themselves ready.

All players must poll their membership in regular intervals (recommended 3-5s) to detect when matchmaking starts, and to communicate matchmaking progress through in-game UI.

Players should save their membership and group IDs persistently, allowing them to restart the game and resume without losing matchmaking progress in case of game client crash.

Deleting a membership at this stage will result in all group memberships being cancelled and all other groups' assigned to the same team returning to status:SEARCHING .

Players search for matches using the overlapping values across their groups (or average in case of number_difference ) until enough players and teams are assembled. Memberships indicate this with response status:MATCH_FOUND , which means your deployment is being started.

Partial Matches

If your matchmaker config allows dynamic team size (different min and max setting), some players may end up with a partial match - including less players than the defined maximum.

Matchmaker will not produce matches with less than the defined team size minimum.

The only scenarios in which partial matches are allowed are:

1. one or more players in queue reach a Rule Expansion (if defined),

2. one or more players in queue reach the ticket expiration time.

Partial match is attempted exactly once. Unmatched players receive status:CANCELLED.

Every player receives a unique Ticket ID, which can be used to Authenticate with game servers.

If the player has been matched and assigned to a game server, their ticket is deleted automatically. Players who abandon queue after status:HOST_ASSIGNED can be replaced with backfill.

Once players receive status:HOST_ASSIGNED they proceed to Connect to Server.

Connect to Server

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 FQDN (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:

Game clients 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.

Backfill Match

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.

The steps to complete a successful backfill are:

1. Server should create one Backfill per team missing players, using values from:

   • Real assignment data retrieved from Injected Variables (deployment).

   • Currently connected players' tickets:

     • from 📌 Injected Variables (matchmaker), previous backfills' assigned_ticket response, or mock data manipulated to match specific players,

     • replace backfill_group_size values with possible group sizes up to available capacity,

2. Game clients create new tickets (memberships) and include backfill_group_size values:

   • "1" if the player is matchmaking alone.

   • "2" if the player is a part of a matchmaking group with 2x members total.

   • "new" if players enabled starting new games in addition to joining in-progress games.

3. Game clients proceed to Find Match and pair players with the matching backfill.

4. 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.

Once game server initialization concludes, your server should:

• Start abandonment timer for each new player. We recommend indicating loading progress to connected players with a loading scene/level - either a full fledged 3D scene, a lobby-like social UI, or a loading screen with a progress bar.

• Keep track of new player connections or existing players leaving over time:

  1. New players must announce ticket ID to the server for authentication and to map their connection to matchmaker 📌 Injected Variables or assigned_ticket (if backfilled).

  2. Create new Backfills for unused player capacity (leavers) throughout server lifespan.

  3. Renew expired Backfills, which are deleted after ticket_expiration_period.

• Clean up (delete) any leftover Backfills once the 5. Deployment Stopped:

  • Unity - OnApplicationQuit callback or custom game end callback,

  • Unreal Engine - OnWorldDestroyed , PreExit , or a custom game end callback.

Any profile can be used for Backfill as long as valid server assignment and at least one ticket is provided. See 🥛 Backfill Showcase for a minimal example.

⚙️ Configuration

Matchmaker API is generated from a JSON configuration specified when you create a new (or quick-restart) Matchmaker. You may specify any number of profiles with varying rules and expansions:

Profiles (Queues)

Profiles represent entirely separated matchmaking queues, sharing the same matchmaker version. You can configure any number of profiles for each matchmaker. Splitting up your player base in multiple profiles may result in longer queue times for your players.

Each matchmaker profile uses an App Version as a template to start new deployments (servers).

Rules

Every player and group joins matchmaking queue and finds matches using initial rules at first.

Each entry in profile at path .rules.initial represents a rule, where:

• key is a string value to name the rule however you prefer; e.g. match_size , and

• value is an object defining the type and attributes of the rule, adhering to our standard ruleset.

Operators (Rule Type)

player_count is a special rule defining how many players need to match to initiate assignment.

Matchmaker always strives to maximize match fill rate, up to specified max_team_size :

1. if max team size is reached the match is made immediately,

2. otherwise, players wait in queue to fill match until expansion (or expiration) is about to elapse,

3. shortly before expanding (or expiring), if partial match is possible (≥ min and < max team size), this match will be made with all players in same expansion stage (assuming other rules pass).

Team count may be configured to compose multiple balanced teams for competitive games:

• group attributes are calculated as average/overlap of the group's player attributes,

• team attributes are calculated as average/overlap of the team's group attributes.

Assuming a fixed team size of 4 players:

string_equality matches players with the exact same string value.

number_difference matches players within the absolute numerical difference from each other.

Rule Example: elo_rating

elo_rating rule above with "max_difference": 50 initially:

✅ Alice + Bob may match, or Bob + Charlie may match,

❌ Alice + Bob + Charlie will never match.

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).

Some players with high ping to all beacons due to ISP issues or slow connection (e.g. wireless/mobile) may cause lags and degrade game experience for others. To mitigate this issue:

• Gradually expand allowed latency maximum and difference (see Advanced Example Config),

  • players with high ping may have to wait longer than usual to find a match.

• Alternatively, allow players to override measurement with manual region selection, only sending fake ping values for the player-selected regions only (e.g. 25ms for fast match),

  • this may negatively impact player experience of the players' teammates and opponents.

intersection matches players with one or more overlapping string values, case sensitively.

Rule Example: selected_map

selected_map rule above with "overlap": 1 will match:

✅ Alice + Bob + Charlie may match, or Alice + Bob + Dave may match,

❌ Alice + Bob + Charlie + Dave will never match.

Rule Expansion

Optionally, expansions modify rule attributes after a period of time spent in queue to relax limitations and expand the pool of players which can be matched, resulting in faster matches.

In configuration, expansions are keyed using seconds relative to each player's ticket creation. Each expansion must be lower than ticket expiration in order to activate.

📌 Injected Variables

Your server might need to know details about it’s players. Player attributes, resolved match values, and other values are injected to your deployment alongside the usual Injected Variables.

Preview unformatted 🏁 Advanced Example Variables:

🧵 Player Tracing

If your players experience any issues, tracing their path to server logs can be helpful. Each Matchmaker deployment will be tagged with assigned player ticket IDs so you can easily Filter Deployments and find Container Logs to help you troubleshoot.

👀 Analytics

Gain insights into your matchmaker load and performance, no code or configuration required.

🌟 Upgrade Matchmaker to Enterprise Tier to unlock matchmaking metrics and insights:

☁️ Hosting Cluster

Matchmaker is conveniently hosted and managed 24/7 around the clock by Edgegap.

Choose a hosting option best suited for your goal:

• Free Cluster (shared) to test all features and explore synergies with your design,

  • shuts down after 3 hours automatically, requiring restart to continue testing.

• Private Cluster (dedicated) to ensure a stable environment for your production needs,

  • pick your region and get 24/7 support for live games to release with confidence.

Private Cluster Tiers

We currently offer 3 private cluster tiers to cater to everybody’s needs:

Upgrade to a private cluster with one click. Changing Private Cluster Tiers after launch, without any player downtime, is also possible with ⏩ Rolling Updates. Managed clusters provide high-availability service hosting maintained by Edgegap with 24/7 live support for publicly released games.

Resource requirements for your instance will depend on factors:

• number of players - more players result in more tickets and API requests,

• number of requests per player - faster retries increase service load and consume resources,

• configuration complexity - intersection rules and expansions are particularly demanding,

• average match duration - shorter sessions make players rejoin matchmaking more often,

• expiration and removal periods - stale tickets stockpile over time and consume resources,

• client retry fallback logic - retrying with jittered backoff helps spread traffic burst peaks.

⏩ Rolling Updates

Keeping track of compatibility between server and client versions can get complicated. Follow our tips for reliable releases, updates, and preventing downtime or compatibility issues.

Your Matchmaker URL and Auth token will always remain the same after restarting.

⚠️ Before Going Live

We recommend creating multiple copies of your matchmaker ahead of time: green, blue and orange. You can rotate which matchmaker is in use as you release updates (blue/green strategy).

Choose different regions for each instance to prevent downtime during localized outages.

🔃 Client + Server Update

Prerequisites: This section assumes you’ve completed ⚠️ Before Going Live.

In order to release game client + server updates, you may:

1. Prepare new server app version v1.2.0-rc on Edgegap:

   1. push a new image tag to your container registry t1.2.0,

   2. create new app version v1.2.0-rc,

2. Perform any dev tests by deploying your new app version v1.2.0-rc:

   1. connect your game engine’s Editor to the provided URL + external port,

3. Update unused matchmaker blue to link to your new image tag t1.2.0,

   1. enable caching for new app version v1.2.0-rc , enabling cache for this version will ensure the image is also cached for version v-blue since they reference the same tag,

   2. wait for caching indicator in version v1.2.0-rc to reach 🟢 green,

4. Update your new game client c2 to use the new version v-blue when creating tickets:

   1. update your base URL and Authorization token in game client,

5. Perform QA tests and final verifications of your new game client c2:

   1. if you find and resolve any issues, repeat process from the beginning,

   2. wait 3-7 days to propagate matchmaker DNS changes to ISPs globally, after the matchmaker has been stopped (quick restart doesn't require DNS updates or waiting period),

6. Release your new game client update c2 on game distribution platforms,

7. Allow time for new game client c2 to distribute to player devices (typically up to 3-7 days):

   1. monitor outdated game clients c1 using deployment Analytics,

8. Clean up unused resources in your Edgegap account:

   1. delete image tag t1.0.0 to free up Container Registry capacity,

   2. delete image tag t1.1.0 to free up Container Registry capacity,

   3. turn off your green matchmaker to pause billing until your next update.

⚡ Server Hotfix

Prerequisites: This section assumes you’ve completed ⚠️ Before Going Live.

To release a server patch without requiring a game client update, you may:

1. Prepare new server app version v1.2.0-rc on Edgegap:

   1. push a new image tag to your container registry t1.2.0,

   2. create new app version v1.2.0-rc,

2. Perform tests and verifications by deploying your new app version v1.2.0-rc:

   1. connect your game engine’s Editor to the provided URL + external port,

   2. if you find and resolve any issues, repeat process from the beginning,

   3. enable caching for new app version v1.2.0-rc , enabling cache for this version will ensure the image is also cached for version v-green later since they will reference the same tag,

   4. wait for caching indicator in version v1.2.0-rc to reach 🟢 green,

3. Update version v-green to link to your new image tag t1.2.0,

   1. new matches will automatically initiate assignment with the updated tag t1.2.0,

   2. monitor outdated game clients c1 using deployment Analytics,

4. Clean up of unused resources in your Edgegap account:

   1. delete image tag t1.1.0 to free up Container Registry capacity.

📗 API

Clients and servers may call API directly or with game engine SDKs, see also Matchmaking.

Import API specification to Scalar API Web Client or Swagger Editor to inspect details.

Rate Limits

To protect your cluster from exceeding it's burst capacity and crashing, we limit the number of requests per second based on our internal load tests using 🏁 Advanced Example configuration.

Rate limits are expressed in combined requests per second to the specified set of API endpoints.

Load Testing

Load testing in production-like environment comes with a deployment hosting cost. See resources and prices associated with each tier on our pricing page.

When designing your load test, please consider realistic player patterns:

Behavior Under Load

If a matchmaker is experiencing high load:

• if CPU is throttling, matchmaking could be slowed down,

• if matchmaker runs out of memory, it will restart without losing ticket information, hoping that clients will implement exponential backoff and the burst is spread over longer period of time.

Cross-Origin Resource Sharing (CORS)

For webGL games hosted on third party distribution platforms (e.g. itch.io), sending any requests to Matchmaker from game client may result in Cross-Origin Resource Sharing policy violations. Most modern web browsers send a pre-flight request to verify that a backend service (the Matchmaker) understands and accepts communication from your game client.

Failing pre-flight check (default for security reasons) can result in one of several possible CORS-related errors, most commonly CORS header 'Access-Control-Allow-Origin' missing .

To resolve this error, add allowed_cors_origin parameter to your configuration to either:

• whitelist your exact client hosting domains:

• or whitelist a wildcard domain (including all subdomains):

Server to Server

Add enhanced or customized controls over matchmaking flow - implement a custom proxy using our Managed Clusters or any cloud FaaS compute platform, to achieve any of:

• attach sensitive player attributes - such as cheater flags, skill ratings, or similar,

• provide team and match context in-game - list my teammates and opponents during loading,

• restrict specific edge cases - e.g. allow only 1 group per player at any time,

• add caching or API rate limiting - reduce number of requests and load on matchmaker,

• customize lobby-group integration - create asymmetric/role-based lobbies before matchmaking.

🚨 Troubleshooting

Your success is our priority. If you'd like to send custom requests, ask for missing critical features, or express any thoughts, please reach out in our Community Discord.

🔖 Changelog

Please see Release Notes for up to date changelog of this service.

Semantic Versioning

Our developer tools and managed services use official Semantic Versioning, indicating which updates are ✅ safe (minor, patch) and which may contain ⚠️ breaking changes (major).

Once a version is released, it will never be modified/changed.

Your configuration file will be validated depending on matchmaker version used, make sure your rules are matching the matchmaker version’s capabilities.