Matchmaker In-Depth

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

See Getting Started for your first steps with Matchmaker, game integration, and detailed examples.

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

✔️ Introduction

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.

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

Learn about matchmaking process to customize, troubleshoot, or optimize your game integration.

See Getting Started for your first steps with Matchmaker, game integration, and detailed examples.

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.

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

• Unreal Engine ⚡ Integration Kit:

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

  • import simple example blueprint and customize to your needs.

• Unity ⭐ Matchmaking SDK by Edgegap:

  • install package using Unity Package Manager for free,

  • import simple example script and customize for your needs,

Authenticate

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

In addition to your existing game client authentication using your Game Backend, all requests for the Matchmaker must send an Authorization HTTP header with your secret Auth Token:

Authorization: 

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

Example Game Client Ping Measurements in milliseconds

{
  "Chicago": 224.4,
  "Frankfurt": 23.2,
  "Tokyo": 167.4
}

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. In such case your server 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 5s) to detect when the matchmaking starts, and to communicate matchmaking progress through in-game UI.

Players should save their membership and group IDs persistently, so that in case of game client crash they can restart and resume the matchmaking progress.

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.

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

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

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

If players experience any issues, or a long queue time, they may attempt deleting their current ticket before a match is found and restart the process by creating a new ticket.

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

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

Unreal Engine

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.

Unity

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 Getting Started 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.

Use Matchmaker In-Depth 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 Matchmaker In-Depth for each team separately, using values from:

   • Real assignment data retrieved from Injected Environment 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 ,

2. Game clients create new Matchmaker In-Depth with backfill_group_size array with values:

   • "1" if the player is matchmaking alone.

   • .

   • "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)

{
  "profile": "backfill-example",
  "attributes": {
    "assignment": {
      "request_id": "cd28e6c66554",
      "fqdn": "cd28e6c66554.pr.edgegap.net",
      "public_ip": "192.168.2.14",
      "ports": {
        "game": {
          "internal": 7777,
          "external": 56890,
          "link": "cd28e6c66554.pr.edgegap.net:56890",
          "protocol": "UDP"
        },
        "web": {
          "internal": 22,
          "external": 57440,
          "link": "cd28e6c66554.pr.edgegap.net:57440",
          "protocol": "TCP"
        },
        "server": {
          "internal": 80,
          "external": 50110,
          "link": "cd28e6c66554.pr.edgegap.net:50110",
          "protocol": "TCP"
        }
      },
      "location": {
        "city": "Montreal",
        "country": "Canada",
        "continent": "North America",
        "administrative_division": "Quebec",
        "timezone": "America/Toronto"
      }
    }
  },
  "tickets": {
    "c3d057h5h6f7j889fk43": {
      "player_ip": "174.25.48.238",
      "attributes": {
        "beacons": {
          "New York": 12.2,
          "Los Angeles": 45.3,
          "Paris": 78.3
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "192bb97e-7fd6-4d86-8ce4-61c53c9fef16",
      "id": "c3d057h5h6f7j889fk43",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    },
    "cqg0bg9583s738h9dkf6": {
      "player_ip": "217.34.85.142",
      "attributes": {
        "beacons": {
          "New York": 21.0,
          "Los Angeles": 30.2,
          "Paris": 101.1
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "aea7df3c-d391-4ea3-a3ec-dded422fe7c8",
      "id": "cqg0bg9583s738h9dkf6",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    }
  },
  "assigned_ticket": null
}

🥛 Backfill Assignment Example (Backfill Showcase)

{
  "profile": "backfill-example",
  "attributes": {
    "assignment": {
      "request_id": "cd28e6c66554",
      "fqdn": "cd28e6c66554.pr.edgegap.net",
      "public_ip": "192.168.2.14",
      "ports": {
        "game": {
          "internal": 7777,
          "external": 56890,
          "link": "cd28e6c66554.pr.edgegap.net:56890",
          "protocol": "UDP"
        },
        "web": {
          "internal": 22,
          "external": 57440,
          "link": "cd28e6c66554.pr.edgegap.net:57440",
          "protocol": "TCP"
        },
        "server": {
          "internal": 80,
          "external": 50110,
          "link": "cd28e6c66554.pr.edgegap.net:50110",
          "protocol": "TCP"
        }
      },
      "location": {
        "city": "Montreal",
        "country": "Canada",
        "continent": "North America",
        "administrative_division": "Quebec",
        "timezone": "America/Toronto"
      }
    }
  },
  "tickets": {
    "c3d057h5h6f7j889fk43": {
      "player_ip": "174.25.48.238",
      "attributes": {
        "beacons": {
          "New York": 12.2,
          "Los Angeles": 45.3,
          "Paris": 78.3
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "192bb97e-7fd6-4d86-8ce4-61c53c9fef16",
      "id": "c3d057h5h6f7j889fk43",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    },
    "cqg0bg9583s738h9dkf6": {
      "player_ip": "217.34.85.142",
      "attributes": {
        "beacons": {
          "New York": 21.0,
          "Los Angeles": 30.2,
          "Paris": 101.1
        },
        "backfill_group_size": [
          "2",
          "1"
        ]
      },
      "group_id": "aea7df3c-d391-4ea3-a3ec-dded422fe7c8",
      "id": "cqg0bg9583s738h9dkf6",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    }
  },
  "assigned_ticket": {
    "profile": "backfill-example",
    "player_ip": "244.13.201.244",
    "attributes": {
      "beacons": {
        "New York": 30.2,
        "Los Angeles": 10.5,
        "Paris": 123.9
      },
      "backfill_group_size": [
        "new",
        "1"
      ]
    },
    "id": "cqg0bg550h7uujd77khg",
    "group_id": "e0cf41c0-f88f-456e-a032-03b1d6821a9a",
    "created_at": "2024-08-20T13:38:08.251393+00:00",
    "status": "HOST_ASSIGNED"
  }
}

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:

  • Unity - OnApplicationQuit callback or custom game end callback,

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

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

Every matchmaker is based on JSON configuration, validated automatically during restarts.

See Getting Started for our SDKs and detailed example scenarios.

🍀 Simple Example (Minimal Recommended Configuration)

{
  "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": {}
      }
    }
  }
}

🏁 Advanced Example (Complete Example Configuration)

{
  "version": "3.2.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "allowed_cors_origins": [
    "https://*.my-game-server.com"
  ],
  "profiles": {
    "advanced-example": {
      "ticket_expiration_period": "5m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m"
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 125
            }
          },
          "elo_rating": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 50
            }
          },
          "selected_game_mode": {
            "type": "string_equality"
          },
          "selected_map": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "elo_rating": {
              "max_difference": 150
            },
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          },
          "60": {
            "elo_rating": {
              "max_difference": 200
            }
          },
          "180": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 4
            },
            "beacons": {
              "difference": 99999,
              "max_latency": 99999
            }
          }
        }
      }
    }
  }
}

🎾 Custom Lobby Example

{
  "version": "3.2.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "profiles": {
    "custom-lobby-example": {
      "ticket_expiration_period": "3m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m"
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "lobby_id": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "10": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 4
            }
          }
        }
      }
    }
  }
}

🥛 Backfill Configuration Example

{
  "version": "3.2.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "profiles": {
    "backfill-example": {
      "ticket_expiration_period": "5m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m",
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 100,
              "max_latency": 200
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {}
      }
    }
  }
}

⚔️ Competitive Game Example

{
  "version": "3.2.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "profiles": {
    "casual-example": {
      "ticket_expiration_period": "5m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m",
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "min_team_size": 5,
              "max_team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "selected_maps": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          },
          "180": {
            "beacons": {
              "difference": 99999,
              "max_latency": 99999
            }
          }
        }
      }
    },
    "competitive-example": {
      "ticket_expiration_period": "5m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m"
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "min_team_size": 5,
              "max_team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "versus_ranks": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "120": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          }
        }
      }
    },
    "challenger-example": {
      "ticket_expiration_period": "5m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m"
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 2,
              "min_team_size": 5,
              "max_team_size": 5
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "elo_rating": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 50
            }
          }
        },
        "expansions": {
          "120": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            }
          }
        }
      }
    }
  }
}

🤝 Cooperative Game Example

{
  "version": "3.2.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "profiles": {
    "cooperative-example": {
      "ticket_expiration_period": "3m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m",
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "min_team_size": 4,
              "max_team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 125,
              "max_latency": 150
            }
          },
          "selected_difficulty": {
            "type": "string_equality"
          },
          "selected_map": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "player_level": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 10
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "moderation_flags": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "30": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            },
            "player_level": {
              "max_difference": 20
            }
          },
          "60": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 2,
              "max_team_size": 4
            }
          },
          "150": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 4
            }
          }
        }
      }
    }
  }
}

🎈 Social Game Example

{
  "version": "3.2.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "profiles": {
    "social-example": {
      "ticket_expiration_period": "3m",
      "ticket_removal_period": "1m",
      "group_inactivity_removal_period": "5m",
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "attributes": {
              "team_count": 1,
              "min_team_size": 50,
              "max_team_size": 50
            },
            "type": "player_count"
          },
          "beacons": {
            "attributes": {
              "difference": 125,
              "max_latency": 150
            },
            "type": "latencies"
          },
          "selected_mode": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "backfill_group_size": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "moderation_flags": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          }
        },
        "expansions": {
          "15": {
            "beacons": {
              "difference": 125,
              "max_latency": 250
            },
            "match_size": {
              "team_count": 1,
              "min_team_size": 20,
              "max_team_size": 50
            }
          },
          "30": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 10,
              "max_team_size": 50
            }
          },
          "150": {
            "match_size": {
              "team_count": 1,
              "min_team_size": 1,
              "max_team_size": 50
            }
          }
        }
      }
    }
  }
}

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.

• We couldn’t find your Apps and Versions, please verify application values.

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	❌	❌	145.6	32.4
Tokyo	n/a	n/a	❌	❌

❌ 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	❌
Los Angeles	n/a	n/a	145.6	❌
Tokyo	n/a	n/a	❌	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 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 Getting Started 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

Fine-Tuning Expansions

Predicting player preferences is similar to shooting at a moving target. Start with a less restrictive rule set at release and optimize afterwards in iterations with 👀 Analytics.

These questions may help frame your thinking process:

• How long is my play session?

  • 5 min play session means each player rejoins queue every 5 min, which will indirectly reduce queue time due to more players queueing at any given time.

• What is my and my ?

  • If there's high variance (more than 60%) between low/high, you may need a separate profile for low tide to wait longer in each expansion, to accumulate more players.

• What is my players' geographic distribution?

  • Even spread across multiple time zones means the peak and low tide have lower variance, but doesn't improve match speed since players in different regions shouldn't match if your Ping Optimization is configured correctly (would result in high ping).

• What is my skill rating distribution (per region)?

  • Skill distribution typically follows Bell curve (natural distribution), so with each standard deviation from average, you find less players further away from average. Players with average values will be matched fast, in first expansion, but extremes are a problem.

  • We recommend to increase the expanded difference amount with each expansion, e.g. 25 -> 50 -> 100, so you account for having less players on the curve extremes.

  • If you have any challenger tier (pro players) we recommend a separate profile with custom skill setup, since the sample is smaller and often doesn't follow the macro trend across the entire player base. (leaning towards extremes, inverted bell curve)

• How can I improve matchmaking speed and match fill rate with small player base?

  • Learn as much about your players and their preferences as possible!

  • Consider removing some rules or relaxing restrictions initially.

  • Relax team size or team count over time - partial match is better than no match.

  • Increase duration between expansions to accumulate more players.

  • Contact us for more tips and tricks, specifically for your game design.

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

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

MM_MATCH_PROFILE=advanced-example
MM_EXPANSION=initial
MM_TICKET_IDS=["cusfn10msflc73beiik0","cusfn18msflc73beiil0"]
MM_TICKET_cusfn10msflc73beiik0={"id":"cusfn10msflc73beiik0","player_ip":"174.93.233.25","group_id":"b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1","team_id":"cusfn1gmsflc73beiim0","attributes":{"beacons":{"Chicago":12.3,"LosAngeles":145.6,"Tokyo":233.2},"elo_rating":1337,"selected_game_mode":"quickplay","selected_map":["DustII","Airport","BankVault"],"backfill_group_size":["new","1"]}}
MM_TICKET_cusfn18msflc73beiil0={"id":"cusfn18msflc73beiil0","player_ip":"174.93.233.23","group_id":"015d4dc8-6c79-4b5c-bbc6-f309b9787c8f","team_id":"cusfn1gmsflc73beiim0","attributes":{"beacons":{"Chicago":87.3,"LosAngeles":32.4,"Tokyo":253.2},"elo_rating":1339,"selected_game_mode":"quickplay","selected_map":["Island","Airport"],"backfill_group_size":["new","1"]}}
MM_GROUPS={"b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1":["cusfn10msflc73beiik0"],"015d4dc8-6c79-4b5c-bbc6-f309b9787c8f":["cusfn18msflc73beiil0"]}
MM_TEAMS={"cusfn1gmsflc73beiim0":["b2080c27-19c9-4fb0-8fe7-4bf1e5d285d1","015d4dc8-6c79-4b5c-bbc6-f309b9787c8f"]}
MM_MATCH_ID=advanced-example_initial-2025-02-21T22:17:43.3886970Z
MM_INTERSECTION={"selected_map":["Airport"],"backfill_group_size":["new","1"]}
MM_EQUALITY={"selected_game_mode":"quickplay"}

Environment variables are stored as stringified JSONs, parse them using an 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

To make things easy, we host and manage matchmaking entirely for you 24/7. You can use our

• 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 ⭐ Matchmaking SDK 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.

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 you game clients do not retry requests upon receiving response 429 Too Many Requests your deployments may be missing players who stop reading their assignments due to high load.

Load Testing

Matchmaking and assignments require CPU and memory usage, requiring a hosting cost with each private matchmaker. See resources and prices associated with each tier on our pricing page.

Always use private clusters for stress testing. Free matchmakers are strictly limited for dev testing only.

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

Realistic Scenario	Unrealistic Traffic Pattern
✅ Players join matchmaking gradually, increasing req/s over several hours.	❌ All players coordinate and create their tickets 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 matchmaking anew.	❌ All players restart matchmaking anew immediately after receiving their assignment.
✅ Peak traffic is sustained for 6-8 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.

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.

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

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

Swagger Web UI: deploying a matchmaker 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.

🍀 Simple Example

106KB

mm-conf-simple-example.json

Open

🏁 Advanced Example

🎾 Custom Lobby

🥛 Backfill Showcase

⚔️ Competitive Games

🤝 Cooperative Games

🎈 Social Games

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

Server to Server

Add enhanced or customized controls over matchmaking flow - implement a custom proxy using our Managed Clusters or any cloud 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 1. Server Score Strategy (Best Practice).

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

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)

{
  "version": "3.2.0",
  "allowed_cors_origins": [
    "https://dev.my-game-server.com",
    "https://prod.my-game-server.com"
  ],
  "profiles": {
      ...
  }
}

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

🍀 Simple Example (Wildcard Domain Example)

{
  "version": "3.2.0",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
      ...
  }
}

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

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

• We couldn’t find your Apps and Versions, please verify application values.

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 matchmaker uses official Semantic Versioning guidelines. Each configuration JSON is tied to a specific version of the matchmaker. Matchmaker version dictates which rules and settings are available in your configuration and API. Once a version is released, it will never change.

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.0. All examples on this page are up to date. Keep an eye out for end of support notices for your matchmaker version. See also ⏩ Rolling Updates.

3.2.0 (Oct 31, 2025)

This is the latest matchmaker service version, recommended for production use.

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

🩹 Bugfixes:

• Various smaller specification fixes and documentation consistency updates.

• Various stability and self-healing fixes across matchmaker infrastructure.

✨ Improvements and new features:

• Introducing Group Up feature - managing groups is now easy and doesn't require 3rd party!

  • No more sharing complex ticket attributes amongst group members. You only need Group ID.

  • Start matching as a group once all of your players mark themselves as ready.

  • Validate group member attributes against the group leader upon joining, preventing unmatchable groups (attributes of group players wouldn't match with under profile's rules).

  • Validate group size and block new memberships once maximum team size is reached.

  • Read our updated documentation with the new user flow, SDK updates coming soon!

• Tickets (memberships) now include your match ID - track players and add UI elements to share your team or opponent teams nicknames, skill rating, or other properties stored in third parties.

• Major Rate Limits overhaul based on internal stress testing, better handling of short bursts.

• Improved match fill rate due to delaying partial matches size until end of expansion.

  • If maximum team size reached, match immediately.

  • Otherwise match at the end of current expansion, if minimum team size reached.

• Set expiration and removal periods per profile and optimize for best player experience.

To update your Configuration, increase version, and copy expiration and removal fields to each profile.

3.1.0 (June 10, 2025)

🩹 Bugfixes:

• Matchmakers now correctly validate tickets with multiple profiles including different rules.

✨ Improvements and new features:

• More optimizations to maximize match fill rate with player_count rule. Tickets will now wait until end of expansion (or expiration) if only partial match is possible (>min and <max team size).

  • Full matches (max team size reached) are made immediately (no change).

• Upgrade to Enterprise ☁️ Hosting Cluster to unlock matchmaking 👀 Analytics! Gain insights into matchmaker load and performance, no code or configuration required. Metrics at launch include:

  • total tickets, backfills, assignments, and deployments made over custom period of time,

  • per minute rates for the above metrics over custom period of time,

  • totals and time series insights into expired tickets, expanded matches, match fill rate,

  • API usage metrics, and more.

• Improved Rules documentation with better examples and visuals.

3.0.0 (May 20, 2025)

⚠️ Breaking changes:

• Use min/max team size to fill teams efficiently (replaces player count expansions):

  • in your configuration player_count rule, replace team_size with min_team_size and max_team_size to achieve "best effort" matching attempting to maximize match fill rate,

  • to require a specific number of players per team, set both min and max to the same value,

  • backfills bypass player_count rule and always match with 1 ticket (unchanged).

• Tickets, group tickets, and backfills with all latencies above the highest max_latency in a given profile will be immediately rejected with 400 Bad Request response to ticket create request, instead of expiring:

  • only applies if latency rule is configured,

  • to bypass this behavior, create an expansion with max_latency: 99999 (any value higher than your client latency measurement timeout).

• Injected environment variables containing ticket data now include field id (ticket ID) so they can be reused more easily when creating Matchmaker In-Depth.

🩹 Bugfixes:

• Matchmaker In-Depth now uses configured deletion and expiration period (like tickets and group tickets).

• Matchmaker In-Depth now correctly matches using configured intersection rules.

• Fixed openAPI specification for POST Matchmaker In-Depth request (requires public_ip) and GET /tickets response (team_id is optional), including examples.

✨ Improvements and new features:

• Up to 3x more potential matches are considered now, producing more optimal groups and maximizing match fill rate.

• Up to 200% faster matching speed due to concurrency optimizations.

• Up to 40% increased match fill rate due to optimization of expansions algorithm.

• Improved service stability and increased speed of quick restarts.

Benchmarks were produced with chaos-generated data using Advanced Example configuration.

2.1.0 (Feb 24, 2025)

⚠️ Breaking changes:

• Separated game profile and expansion stage information in the Matchmaker In-Depth:

  • MM_MATCH_PROFILE will now only include the profile name as it appears in the configuration.

  • Introduced MM_EXPANSION_STAGE which will contain the expansion stage as a string (e.g. "initial", "15", "30").

• Ticket assignments now include the group ID when Matchmaker In-Depth. Group ID is also included as an Matchmaker In-Depth, as a mapping of group ID to a list of the group's player IDs.

• Ticket assignments now include the team ID when Matchmaker In-Depth. The team ID is also included in every ticket data Matchmaker In-Depth.

• Matchmaker In-Depth now returns 409 Conflict HTTP code instead of 204 No Content to indicate the ticket can't be deleted since the deployment is starting. To replace leavers, use a Matchmaker In-Depth issued by the server after a pre-specified timeout period.

• Matchmaker In-Depth request body parameter attributes.deployment_request_id has been moved to attributes.assignment.request_id.

• Matchmaker In-Depth request body now requires full assignment details as part of attributes parameter in addition to the request_id.

🩹 Bugfixes:

• Resolved intersection rule values are now Matchmaker In-Depth in the MM_INTERSECTION environment variable.

• Quick restart feature now reliably regenerates API endpoints and openAPI specification when configuration is changed.

• Fixed several bugs during matchmaker (re)start causing prolonged startup time or getting matchmaker stuck.

✨ Improvements and new features:

• Increased rate limits and scalability of all API endpoints, across all matchmaker tiers.

• When assigning a player to a Matchmaker In-Depth, the new player's ticket ID will be added as a tag to the Backfill's Deployments.

• Added swagger UI authentication feature to test API directly in web UI without needing postman.

• Improved openAPI examples to reflect realistic requests and responses more closely.

• Added new Matchmaker In-Depth meant for development and debugging purposes.

  • Allows listing all current player tickets in a paginated list.

  • Allows listing all current matches in a paginated list.

1.0.0 (Dec 9, 2024)

• Matchmaker In-Depth: Upon (popular) request, we’re adding backfill with automated ticket assignment, which allows you to reuse server seats when players leave the session.

  • Ideal for filling empty player seats after a match has begun, or for replacing players that have left during a match.

• Matchmaker In-Depth: We’re adding the ability to join as a group to the already available ability to fill multiple teams with players.

  • Ideal for joining up in a matchmaking queue with a group of friends or coming from a common lobby.

• ⭐ Matchmaking SDK and Developer Tools matchmaking SDKs:

  • To make integration easier, we’re now offering Software Development Kits for the most popular game engines.

• Fixed a bug where the Matchmaker In-Depth was not applied correctly.

• Tickets will now be automatically canceled after a Matchmaker In-Depth if they haven't been assigned to a deployment.

• You can now Matchmaker In-Depth to enhance the flow of your matchmaking process.

• Deployments made by the matchmaker are now tagged with ticket IDs.

• You can now edit your configuration while the matchmaker is running. This triggers a quick reload of your configuration without requiring a full on/off cycle for your matchmaker. Note: This feature is not recommended for production environments, as it deletes all current tickets and temporarily makes the API unresponsive.

• Fixed Matchmaker In-Depth to use the correct primitive types instead of arrays.

• Fixed Matchmaker In-Depth JSON values, which previously contained escaped characters.

0.2.3 (Oct 8, 2024)

This version is no longer supported, please use a newer version for your matchmaker.

• Fixed a bug where certain headers were not accepted by the matchmaker when requests were made from a WebGL application (CORS policies).

0.2.2 (Oct 3, 2024)

This version is no longer supported, please use a newer version for your matchmaker.

• Fixed issue with TLS/SSL certificate validation preventing matchmaker from launching.

0.2.1 (Sep 30, 2024)

This version is no longer supported, please use a newer version for your matchmaker.

• Fixed a bug causing the beacons endpoint to return a 500 error.

0.2.0 (Sep 25, 2024)

This version is no longer supported, please use a newer version for your matchmaker.

• Basic authentication is now mandatory for all endpoints.

• Added the ability to configure the number of retries on server assignment failure.

• Team-based matchmaking is now the default for all matchmaking configurations.

• Both application and version are now required fields in all profiles.

• Introduced a new endpoint to monitor the matchmaker's status.

• Updated the format of the tickets environment variable in the deployment.

• Added a configuration option to allow hosts to communicate with the matchmaker.

• The debug API is now only available when explicitly enabled in the configuration (it is currently disabled for rework).

• The game_profile key in the GET ticket response has been replaced by profile.