Ctrlk
edgegap.comDashboard
discordlinkedin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

In-Depth Look

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

If you need help, please reach out to us over Discord. For live games support see our ticketing system.

✔️ 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.

Alternatively, let players pick a persistent (always online) server from a list with Server Browser.

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.

Free Tier allows 3 hours of runtime after each restart. Your matchmaker will run on shared infrastructure with limited resources, suitable for testing. After your public release, matchmaker needs to run 24/7.

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.

Update your matchmaker version frequently to take advantage of new features and bug fixes.

▶️ Start Matchmaking

Get started quickly - add our SDK starter sample to your game:

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

Matchmaking Sequence

  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:

Keep your tokens secret and safe! Edgegap staff will never ask you for your tokens.

This token may be included in your game client safely, as it doesn't grant access to Edgegap API.

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 (party) ensures players join the same team and server with their friends.

Create a group marked ready to Find Match quickly as a solo player without group members.

Group Lifecycle Activity Diagram

Lobby and Group

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.

Don't have time for a Lobby service? Guide players to share group IDs through Discord or DMs.

Game Design - Feature / Requirement
Pre-Match Lobby
Matchmaker Group

invite friends to play with me

✅

✅

modify my player/match preferences

✅

❌

view other lobby member preferences

✅

❌

store and manage custom key-value data

✅

❌

notify group members that I'm ready to play

❌

✅

show matchmaking progress and find match

❌

✅

get team assignment for a player/group

❌

✅

retrieve game server connection details

❌

✅

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

Lobby Service (Third Party)
Unreal Engine
Unity
PC
Consoles
VR/XR
Mobile

Epic Online Services Lobby (Epic Games)

Steamworks Lobby (Valve Corporation)

Nakama Group (Heroic Labs)

Playfab Lobby (Microsoft)

brainCloud Lobby (bitHeads)

Gamekit Friends (Apple)

Custom Lobby (your company)

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.

Once a group starts matchmaking, it can't be joined. Abandon Queue and create a new one.

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 matchmaking is cancelled, members are removed from matchmaking automatically and notified through membership status:CANCELLED in their next status polling response.

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.

To let the group owner start matchmaking immediately, mark memberships ready at creation. Once the owner marks themselves ready the matchmaking will start, since everyone is ready.

For best experience, provide status updates to players using in-game UI.

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.

Once we find enough players to put into the same team adhering to your Rules, players will be notified in their membership response with status:TEAM_FOUND.

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 .

Teams continue matchmaking with other teams using the overlapping values across their groups (or average in case of number_difference ) until enough teams are assembled. Memberships indicate this with response status:MATCH_FOUND , which means your deployment is being started.

Matchmaker aims to maximize match fill rate, and will not proceed to MATCH_FOUND until either:

  1. enough teams are matched with the configured maximum team size,

  2. or if Rule Expansion defined AND expansion time reached, AND enough teams are matched with the configured minimum team size,

  3. or the configured ticket expiration time elapsed AND enough teams are matched with the configured minimum team size.

If neither scenario succeeds before configured ticket expiration, group and tickets are cancelled.

Experiencing long queue times during testing, or with players in less popular regions? Set a lower ticket expiration period (e.g. 30s) and re-create group (or tickets) on client side upon expiration.

Ticket expiration automatically resets whenever a group (or a player) is matched to a team.

Store team_id and match_id in your game backend to display team members information in-game.

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:

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

In case of failed connections or dark screen consult our troubleshooting guide.

We do not ask players to confirm the match, as we aim to provide shortest possible time to gameplay, high match fill rate, and minimize queue dodging and match cancellations.

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 Matchmaking and our SDKs with automatic reconnect function and more.

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.

Backfill Match to replace Seat/Match sessions. Matchmaker only supports Default session.

Backfill Scenarios Visualized

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:

  1. Server creates 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.

To create a Backfill-only profile, set min_team_size to 999,999 and disable ticket + ticket matches.

🥛 Backfill Example (Backfill Showcase)
🥛 Backfill Assignment Example (Backfill Showcase)

See Mirror Seat Management and FishNet Seat Management for player connection monitoring.

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:

Use GetEnvironmentVariable in C# or GetEnvironmentVariable in C++ to get variable values.

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:

See Matchmaking for our SDKs and detailed example scenarios.

🍀 Simple Example (Minimal Recommended Configuration)
🏁 Advanced Example (Complete Example Configuration)
🥛 Backfill Configuration Example
⚔️ Competitive Game Example
🤝 Cooperative Game Example
🎈 Social Game Example

Editing a running matchmaker will trigger a quick reload, deleting all tickets and causing short downtime.

The application configuration is not valid for profile XYZ.
Docker image for '2024.01.30-16.23.00-UTC' is not cached.

🌟 Upgrade to Pay as You Go tier to unlock instant deployments with Caching.

  • 4GB+ uncached images may take longer to deploy, resulting in 4. Deployment Error. Consider optimizing your server image size (Unreal Engine / Unity).

  • You may proceed anyway, though we recommend testing your deployment time.

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

Some game modes may require more vCPU / RAM, especially if they support a higher number of players. Each matchmaker may include multiple profiles, each linked to an app version with adjusted resources.

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.

All rules have to be met simultaneously to initiate host assignment and start or find a deployment.

Operators (Rule Type)

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

Rule player_count is required and may only be defined once in your initial configuration rules.

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

For cooperative, free-for-all, or asymmetric team size game modes, set your "team_count": 1 .

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:

Example Match Scenarios

Groups match in teams without overfilling, only if a team has sufficient capacity to fit the whole group.

string_equality matches players with the exact same string value.

Rule Example: selected_game_mode

selected_game_mode rule will match players case sensitively:

✅ Alice + Bob + Dave may match,

❌ Alice + Erin, or Charlie + Frank will never match.

"Free For All"
"Capture The Flag"
"capture the flag"

Alice

Erin

Frank

Bob

Charlie

Dave

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

Rule Example: beacons

beacons rule configured with "difference": 100, "max_latency": 200 will match:

✅ Alice and Bob may match:

  • Tokyo is discarded (>200 ms),

  • latency for Chicago within 100 ms absolute difference.

Beacon City
Match
abs(A - B) [ms]
Alice [ms]
Bob [ms]

Chicago

✅

75.0

12.3

87.3

Los Angeles

❌

113.2 ❌

145.6

32.4

Tokyo

n/a

n/a

233.2 ❌

253.2 ❌

❌ Alice and Charlie will never match:

  • no beacons have < 200 ms latency for both players,

  • Alice lives in North America - Illinois,

  • Charlie lives in Asia - Japan.

Beacon City
Match
abs(A - B) [ms]
Alice [ms]
Charlie [ms]

Chicago

n/a

n/a

12.3

215.6 ❌

Los Angeles

n/a

n/a

145.6

238.3 ❌

Tokyo

n/a

n/a

233.2 ❌

24.2

Rule latencies is optional and may only be defined once in your initial configuration rules.

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.

High beacon ping doesn’t always result in high server ping. Deployments are available in more locations than beacons. Beacons are orchestrated in real time to prioritize global coverage and reliability.

See Matchmaking for automated ping measurement using our SDKs.

Beacons are automatically rescaled in real time - adding/removing/replacing existing beacons. Your clients and backend should account for this and reload list of beacons before each matchmaking round.

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 a rule’s 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.

Example Scenario: Expansions

Initially, we require 1 team composed of exactly 4 players (possibly split in groups) with:

  • maximum of 125 ms latency against the same (any one) beacon,

  • latency difference of 125 ms or less between lowest/highest value for the same beacon,

  • skill rating difference of 50 points or less between lowest and highest ranking player,

  • the exact same (case sensitive) selected game mode,

  • at least one matching map selection (case sensitive) amongst players,

  • at least one matching backfill group size value amongst players.

In the example above, we expand the search by modifying attributes after:

30 seconds:

  • 4 players

  • 150 skill rating range

  • max 250 ms latency

60 seconds:

  • 4 players

  • 200 skill rating range

  • max 250ms latency

3 minutes (180s):

  • 1-4 players

  • 200 skill rating range

  • any latency

Expansions of any rule’s attribute will overwrite previous values of that attribute.

Learn about common pitfalls of matchmaking, and optimize your match fill rate with our guide.

📌 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:

Environment variables are stored as stringified JSONs, parse them using our SDK or a custom method.

Servers can map player connections to groups and attributes after player sends their ticket ID to server.

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

Display ticket IDs and deployment IDs in client match history UI to trace players when troubleshooting.

See 🟢 Connection Quality to learn about deployment troubleshooting.

👀 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:

Tier
Hobbyist Tier
Studio Tier
Enterprise Tier

Best Suited For

enthusiasts, solo developers

commercial releases

high-traffic launches

Resources

1 vCPU + 2GB RAM

6 vCPU + 12GB RAM

18 vCPU + 48GB RAM

Redundancy

1x virtual node

3x virtual nodes

3x virtual nodes

Rate Limit (req/s)

200

750

2,000

Price, hourly

$0.0312

$0.146

$0.548

Price, 30 days (nonstop usage)

$22.464

$105.12

$394.56

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.

Prepare for success and optimize after launch, so you don’t block your players on release day. Use Developer Tools or implement exponential jittered backoff to recover from high load.

Our clusters use cloud machines featuring AMD/Intel CPUs with clock speed 2.4 - 3.2 GHz.

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

Create separate matchmakers for dev & production environments to experiment safely.

⚠️ 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.

Blue/Green DevOps Environment Example

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

For your next update, increase version numbers and swap green and blue keywords in the guide.

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

Unity/Android - consider using raw string interpolation to prevent code stripping of hardcoded JSONs.

Swagger Web UI: deploying your service will generate an openAPI specification and a convenient web UI. Open the URL in your browser to view and test all API endpoints, and to review payload examples.

106KB
mm-conf-simple-example.json
Open

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.

API endpoint
Free Tier
Hobbyist Tier
Studio Tier
Enterprise Tier

Overall Limit

100

200

750

2,000

Create Deployment

5

10

30

30

List Beacons

10

20

75

200

Create Group + Create Ticket + Create Group Ticket

10

20

75

200

Read Membership + Read Group + Read Ticket

10

120

450

1,300

Create Backfill

5

10

37

100

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

If your game clients do not retry requests upon receiving response 429 Too Many Requests your deployments may be missing players during short bursts and peak traffic periods.

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.

Use private clusters for stress testing. Free instances are strictly limited for dev testing only.

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

Realistic Scenario
Unrealistic Traffic Pattern

✅ Players join game gradually, increasing req/s over several hours.

❌ All players coordinate and hit the API in the exact same second.

✅ Players wait an increasing amount of time between their retries (e.g. 1s-5s-10s-10s).

❌ All players retry immediately upon receiving 429 Too Many Requests response.

✅ Most players will receive their assignments within a short time (10-60s) and stop polling.

❌ All players continue polling for a set amount of time even after receiving assignment.

✅ Most players finish their game (taking time) before restarting a new session.

❌ All players restart their session anew immediately after receiving server assignment.

✅ Peak traffic is sustained for ~6 hours a day, after which some time zones drop off.

❌ Peak traffic is sustained 24 hours a day, with all players playing night and day.

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:

🍀 Simple Example (Specific Domains Example)

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

🍀 Simple Example (Wildcard Domain Example)

No credentials are required for Matchmaker pre-flight requests, if domains are configured correctly.

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.

Include parameter player_ip with member's public IP address to ensure lowest possible player latency and take advantage of Deployments.

Game clients may use ipify.org free service to find their public IPs. VPNs may mask public IP address.

Server to Server Matchmaking Activity Diagram

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

The application configuration is not valid for profile XYZ.
Docker image for '2024.01.30-16.23.00-UTC' is not cached.

🌟 Upgrade to Pay as You Go tier to unlock instant deployments with Caching.

  • 4GB+ uncached images may take longer to deploy, resulting in 4. Deployment Error. Consider optimizing your server image size (Unreal Engine / Unity).

  • You may proceed anyway, though we recommend testing your deployment time.

Why am I getting errors when trying to create a new matchmaker?

  • Please read the error, it’s possible you’ve misspelled an identifier, rule, or an operator. - Use JSONLint to validate your JSON formatting, you may have missed a comma or a bracket. - Reach out over our Community Discord for help, we’ll be happy to assist. 🙏

Why did my matchmaker turned off automatically after 3 hours?

  • Matchmakers in Free Tier are intended for initial tests and are automatically turned off after 3 hours. To continue testing you may restart your matchmaker.

  • Consider upgrading to paid tier for unliminted runtime.

Why can’t I start a second deployment on my account?

  • You may only run 1 concurrent deployment in Free Tier.

  • Please consider upgrading to paid tier for unlimited deployments.

Why am I getting assignment/deployment at random times, disregarding player_count?

  • You or another team member may have created tickets during a previous testing session which were not assigned. Please restart your matchmaker.

My ticket is stuck in SEARCHING .

  • Please verify you’ve created enough matching tickets adhering to your configuration.

My ticket is stuck switching between MATCH_FOUND and TEAM_FOUND repeatedly.

  • Free Tier accounts are limited to 1 deployment at a time.

  • Please consider upgrading or stop your current deployment to start a new one.

My ticket goes straight to CANCELLED.

  • Your ticket reached it’s expiration. Create a new ticket or increase the expiration period in your configuration for testing purposes.

I receive HTTP 404 Not Found when checking on my ticket.

  • Your ticket was removed either by a DELETE request, or by reaching it’s removal period (starts after ticket is expired, defined in your configuration). Recreate a new ticket or increase the expiration/removal periods in your configuration for testing purposes.

My matchmaker shows an error, what should I do?

  • If this is a development or a testing instance, try restarting your matchmaker first. - Please report any issues through our Community Discord.

  • In case this issue is impacting a live game, create an urgent support request.

🔖 Changelog

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.

The latest version of matchmaker is 3.2.2. All examples on this page are up to date.

Keep an eye out for updates and announcements. See also ⏩ Rolling Updates.

To upgrade your matchmaker version - Stop, Edit, Restart. Quick Restart won't apply version changes.

PreviousMatchmakingNextServer Browser

Last updated

Was this helpful?