Skip to main content

Gen2 Matchmaker

🌟 Introduction​

Our Matchmaker Gen2 is a managed service that uses your own rules to find the optimal group of teammates and opponents in seconds, for any player. Get started within 5 minutes, and test the entire feature set for free. Upgrade when you're ready to a private dedicated cluster with enhanced security. Native integration with Edgegap Deployments delivers best-in-class ping no matter where your players are located.

tip

Try out Gen2 now! Free Tier allows up to 3 hours of runtime on our shared test cluster. Need more time? Simply restart your matchmaker and continue your integration test.

info

Legacy Managed matchmaker will be deprecated on Nov 27th 2024, but it’s still available here. We’ll post an updated offering for our Advanced and Legacy Managed matchmakers soon.

warning

Disclaimer: As this is an Early Access release, some details are subject to change. We will employ our best efforts to follow your needs, and to minimize breaking changes.

This tutorial will help you learn how to:

  • create a free/dedicated, customizable Gen2 matchmaker,
  • deploy a low-latency Edgegap server using tickets,
  • integrate ticket APIs in your game project,
  • speed-up matchmaking and improve match quality,
  • debug and troubleshoot common issues.

Before we get started, this tutorial assumes you have already:

  1. understood Edgegap’s “just in time” deployment model,
  2. uploaded and configured your server application on Edgegap,
  3. successfully connected from a game client to your server on Edgegap.
tip

If you need help with any of the above, please reach out to us over Discord. For urgent matters related to live games, we provide 24/7 support through our “Request Help” feature (lifesaver icon).

There are three main components to each matchmaker:

  1. ☁️ Hosting Cluster - underlying server infrastructure, fully managed and operated by Edgegap.
  2. 📏 Configuration - set of rules and settings that define how the matchmaker will operate. Each matchmaker version may require a different configuration definition.
  3. 🌐 Service Instance - the 24/7 live matchmaking service running on the Cluster, using Configuration to match players together and produce deployment assignments.

☁️ Hosting Cluster​

During this tutorial we will only use our Free Tier, which allows up to 3 hours of runtime on our shared test cluster. Need more time? Simply restart your matchmaker and continue your integration test.

tip

If you wish to upgrade to a private cluster later, you may duplicate your matchmaker in 1 click. Your estimated monthly cluster price will be displayed before you deploy your private matchmaker.

info

If you’re unsure what cluster size you need, contact us for help over email or Discord.

📏 Configuration​

The basis for every matchmaker is a JSON Configuration. To make testing new rules easier, our dashboard UI will validate the config upon upload.

🍀 Simple Example​

If you prefer building from scratch, you may try extending our minimal configuration required to start your matchmaker:

{
  "version": "0.2.3",
  "max_deployment_retry_count": 3,
  "profiles": {
    "simple-example": {
      "application": {
        "name": "myapp",
        "version": "demo-app-2460c4"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 50,
              "max_latency": 250
            }
          }
        },
        "expansions": {}
      }
    }
  }
}
info

Please input your own name and version in the application parameter of your config. Find the latest matchmaker version here.

🏁 Advanced Example​

To get you started faster, we’ve also prepared an advanced example demonstrating all of the matchmaker’s rules and capabilities:

Advanced Matchmaker Example
{
  "version": "0.2.3",
  "max_deployment_retry_count": 3,
  "profiles": {
    "advanced-example": {
      "application": {
        "name": "myapp",
        "version": "demo-app-2460c4"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 4
            }
          },
          "elo_rating": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 50
            }
          },
          "selected_game_mode": {
            "type": "string_equality"
          },
          "selected_map": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_region": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 50,
              "max_latency": 80
            }
          }
        },
        "expansions": {
          "5": {
            "elo_rating": {
              "max_difference": 100
            }
          },
          "10": {
            "elo_rating": {
              "max_difference": 200
            },
            "beacons": {
              "difference": 100,
              "max_latency": 250
            }
          },
          "20": {
            "match_size": {
              "team_count": 1,
              "team_size": 3
            }
          },
          "30": {
            "match_size": {
              "team_count": 1,
              "team_size": 2
            }
          },
          "60": {
            "match_size": {
              "team_count": 1,
              "team_size": 1
            }
          }
        }
      }
    }
  }
}
info

Please input your own name and version in the application parameter of your config. Find the latest matchmaker version here.

🚪 Matchmaking Profiles​

Profiles represent entirely separated matchmaking queues, only sharing the same matchmaker version. You can configure any number of profiles for your matchmakers, though splitting up your player base will result in longer queue times for your players.

info

Some game modes may require higher vCPU / RAM, especially if they support a higher number of players. To account for the increase, you may define a separate profile for such game mode, linked to an app version with a higher resource allocation.

📦 Application and Versions​

Each matchmaker profile points to an exact version of an application in your Edgegap organization. Make sure to clearly distinguish between development, testing, and production environments in matchmaker profiles to prevent accidentally releasing a version which is not production ready.

info

You may create multiple matchmaker profiles with different app versions to test in a bigger team.

warning

Gen2 only supports Default session type at the moment. Stay tuned for updates on support of Seat and Match session types.

⚖️ Matchmaking Rules​

Every ticket joins matchmaking queue based on initial rules defined for their chosen profile.

📑 Rules​

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.
info
  • Rule names (e.g. match_size) are unique identifiers.
  • Operators player_count and latencies may only be used once per profile.
  • See 🎟️ Create a Ticket for an example of mapping ticket attributes to rules.

✅ Operators (rule type)​

All rules have to be met simultaneously to initiate assignment. You may match using operators:

  • player_count is a special rule defining how many players need to match to initiate assignment,
warning

This operator is required and may only be defined once in your initial configuration rule set.

tip

To support multiple teams, increase team_count value. Total number of players is calculated as product of team size and team count, e.g. for "team_count": 2 and "team_size": 5, a total of 10 players is required to initiate assignment.

  • string_equality only matches players with the exact same value, case sensitively.
info

Our example selected_game_mode rule:

  • Alice (”Free For All”) and Bob (”Free For All”) will match; A=B,
  • Charlie (”Capture The Flag”) and Dave (”Free For All”) will not match; A≠B,
  • Erin (”Capture The Flag”) and Frank (”capture the flag”) will not match; A≠B.
  • number_difference matches players within the absolute numerical difference from each other,
info

Our example elo_rating rule above with "max_difference": 50 initially:

  • Alice (42) and Bob (90) will match; | A-B |=48 elo_rating points,
  • Charlie (40) and Dave (91) will not match; | C-D |=51 elo_rating points.
  • intersection matches tickets if a given minimum of values from arrays supplied by both players match, case sensitively,
info

Our example selected_region rule above with "overlap": 1 :

  • Alice [”NA”,”EU”] and Bob [”EU”,”APAC”] will match; A ∩ B = {“EU”},
  • Charlie [”NA”] and Dave [”EU”] will not match; C ∩ D = {}.
  • latencies is a special rule matching players within an absolute difference in ping values, from nearest Location Beacons,
    • this presents a “soft” solution to splitting your player base, enabling matching with neighboring regions, especially improving match speed for less populated regions,
    • max_latency should be specified to discard locations above a given threshold,
info

Our example beacons rule above with "difference": 50, "max_latency": 250 initially:

  • Alice and Bob will match, since Beijing is discarded (>250) and the rest is within | A-B | < 50:
    • Alice {Montreal: 12.3, Newark: 45.6, Dallas: 59.9, Beijing: 264.4}; and
    • Bob {Montreal: 27.3, Newark: 32.4, Dallas: 23.1, Beijing: 252.2}.
  • Charlie and Dave will not match, since | C-D | > 50 for Dallas Beacon:
    • Alice {Montreal: 5.7 Newark: 44.2, Dallas: 59.5, Beijing: 263.2}; and
    • Bob {Montreal: 57.8, Newark: 32.0, Dallas: 24.2, Beijing: 272.3}.
info

Learn more about how to compute and supply latency values in section 🗼 Latency Measurement.

tip

An example ticket + Beacons API specification are generated after releasing your matchmaker, see 📗 Matchmaking API.

⏩ Rule Expansion​

Optionally, expansions can be defined to modify each rule’s attributes at time intervals since ticket creation, effectively expanding the pool of players which can be matched, speeding up queue times.

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

  • 5 seconds spent in queue:
    • elo_rating difference of 100 points is now accepted,
  • 10 seconds spent in queue:
    • elo_rating difference of 200 points is now accepted,
    • latency difference of 100 points is now accepted,
    • latency maximum of 250 points is now accepted,
  • 20 seconds spent in queue:
    • match_size of 3 players is now accepted,
  • 30 seconds spent in queue:
    • match_size of 2 players is now accepted,
  • 60 seconds spent in queue:
    • match_size of 1 players is now accepted
    • the match starts automatically.
info

Updates of the same rule’s attribute will overwrite previous values during expansion.

⏫ Semantic Versioning​

Our matchmaker uses the 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.

info

The latest version of Gen2 matchmaker as of 8th October 2024 is 0.2.3. 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 & AB Tests.

warning

Early Access - Gen2 is in Early Access as stated by semantic versioning guidelines, and indicated by version 0.x.x. Gen2 is not production ready yet and may receive breaking changes before 1.0.0. Please update your Matchmaker version frequently.

🎫 Player Tickets​

Each player creates tickets to join the matchmaking queue. Tickets are compared and if criteria defined in the 📏 Configuration is met, a deployment will be assigned, and players may establish connection with game server.

👞 Matchmaking Process​

The matchmaking process can be summarized in 3 simple steps:

  1. Player creates a ticket,
  2. Player repeatedly reads their ticket every second; looking for matches,
    1. Ticket has been matched (no visible change for player yet),
      1. A game server is assigned to each matched ticket,
      2. Players read the assignment (URL & port) from their tickets,
      3. Players initiate connection to game server (end of sequence).
  3. Player leaves the queue / exits the game
    1. Player deletes their ticket,
    2. Player stops reading their ticket status (end of sequence).

If players experiences any issues, or a long queue time, they may attempt deleting their current ticket and restarting the process by creating a new ticket.

tip

If the player has been matched and assigned a game server, their ticket will be deleted automatically.

📗 Matchmaking API​

Send HTTP requests from your game client to your newly created matchmaker to manage player tickets. See our examples for each 📏 Configuration below.

tip

Swagger Web UI: deploying a matchmaker will generate an openapi specification and a convenient web UI. Open the URL in your browser to view all API paths and request/response examples.

🎟️ Create a Ticket​

Each ticket represents one player in matchmaking queue, and each rule requires a corresponding value (depending on operator) to be included when creating the ticket.

info

  • Server-to-Server: when calling from your backend service instead of game client, add request header Player-Ip with player’s public IP address to take full advantage of our latency optimization. Find out player’s public IP using ipify service, free of charge.

  • Auth Token: to authenticate, clients should send HTTP header Authorization: ee427fe4-e458-4592-b607-c2c28afd8b62, find your secret token on your matchmaker page. Do not share plain text secret tokens with users outside your organization!

warning

Caution when copy-pasting request constructor code. Specification may differ depending on your configuration and matchmaker version.

🍀 Simple Ticket​

To create a valid ticket with the 🍀 Simple Example, your request body may look like this:

{
  "profile": "simple-example",
  "attributes": {
    "beacons": {
      "Montreal": 12.3,
      "Newark": 45.6,
      "Dallas": 59.9
    }
  }
}

🏁 Advanced Ticket​

To create a valid ticket with the 🏁 Advanced Example, the request body may look like this:

{
  "profile": "advanced-example",
  "attributes": {
    "elo_rating": 1337,
    "beacons": {
      "Montreal": 12.3,
      "Newark": 45.6,
      "Dallas": 59.9
    },
    "selected_game_mode": "quickplay",
    "selected_map": ["Dust II", "Airport", "Bank Vault"],
    "selected_region": ["North America", "Europe"]
  }
}

🧾 Ticket Receipt and ID​

Once the ticket is created, you will receive a ticket ID as a receipt, used to check the status of your ticket and connect your players once they’ve been matched and the server is assigned:

{
  "id": "cqg0bg550h7uujd77khg",
  "profile": "example",
  "assignment": null,
  "created_at": "2024-08-20T13:38:08.251393+00:00"
}
info

The ticket receipt has the same exact structure for both Simple and Advanced Configuration.

🗼 Latency Measurement​

To compute values for your latencies operator (beacons rule in our example) your client should:

  1. fetch a list of all Location Beacons from your matchmakers Beacons API,
  2. send a TCP or a UDP ping 3x to each of the beacons (typically ~ 10 beacons),
  3. submit the average (mean) value for each beacon.
tip

Consider using Edgegap Integration Kit by Betide Studio to simplify integration with Unreal Engine Blueprints. Automation for Unity and C# is coming soon!

info

Ticket keys for your latencies object are fully customizable, you may provide city, continent, administrative_division from Beacons API or even your own custom values if needed.

🔍 Get Ticket Status​

Once a ticket is created, the player will need to check it’s status every second. As soon as a match is made and the server is assigned by Edgegap, your ticket response will change to include:

{
  "id": "cqg0bg550h7uujd77khg",
  "profile": "example",
  "assignment": {
    "fqdn": "cd28e6c66554.pr.edgegap.net",
    "public_ip": "192.168.2.14",
    "ports": {
      "game": {
        "internal": 7777,
        "external": 51123,
        "link": "cd28e6c66554.pr.edgegap.net:51123",
        "protocol": "UDP"
      },
      "web": {
        "internal": 8888,
        "external": 51456,
        "link": "cd28e6c66554.pr.edgegap.net:51456",
        "protocol": "TCP"
      }
    },
    "location": {
      "city": "Montreal",
      "country": "Canada",
      "continent": "North America",
      "administrative_division": "Quebec",
      "timezone": "America/Toronto"
    }
  },
  "created_at": "2024-08-20T13:38:08.251393+00:00"
}
info

Your port values may differ, find details in your App version or Deployment pages on dashboard.

tip

Either one of fqdn or public_ip values (+external port) may be used to establish connection.

💉 Injected Environment Variables​

Your server might need to know some details about the connecting players. Attributes of all tickets, resolved equality, intersection values, and more values are injected as environment variables to your Deployment.

🏁 Advanced Example
{
  "MM_MATCH_PROFILE": "advanced-example",
  "MM_MATCH_ID": "advanced-example-2024-09-28T19:40:15.5060333Z-0",
  "MM_EQUALITY": {
    "selected_game_mode": ["quickplay"]
  },
  "MM_INTERSECTION": {
    "selected_map": ["Airport"],
    "selected_region": ["North America"]
  },
  "MM_TICKET_IDS": ["crs5n05becfc73ar62ag"],
  "MM_TICKET_crs5n05becfc73ar62ag": {
    "public_ip": "142.170.86.173",
    "attributes": {
      "beacons": [{
        "Montreal": 12.3,
        "Toronto": 45.6,
        "Quebec": 59.9
      }],
      "elo_rating": ["1337"],
      "profile": ["advanced-example"],
      "player_ip": ["142.170.86.173"],
      "selected_game_mode": ["quickplay"],
      "selected_map": ["Dust II", "Airport", "Bank Vault"],
      "selected_region": ["North America", "Europe"]
    }
  }
}
tip

Map players to tickets - players should send their ticket ID via a Remote Procedure Call (RPC) to server when they connect.

warning

Known bug - profile key in injected variables is using outdated naming game_profile, we're working on a fix!

🕵️ Inspect API (Coming Soon)​

Our matchmaker offers a vast set of capabilities, adding complexity to the matchmaking process. The changes you make to your configuration and the impact on your players will be more predictable if you run tests on your matchmaker, using our Inspect API:

  • Pause and Resume ticket assignments to preview the match suggestions step by step. While Paused, you may use all ticket APIs fully, they simply won’t start new deployments, so you will no longer need to remove deployments spawned during your testing sessions.
  • List and Delete all tickets to understand and reset your matchmaker state reliably anytime.
  • List match proposals for live tickets to fine tune your ruleset and gain more control.
info

Inspect API has been temporarily disabled due to a bug. We’re working on a patch and will post an announcement in our Community Discord, and in our web changelog when access is restored.

🥛 Backfill - Replace Leavers (Coming Soon)​

Inform the matchmaker that players left a deployment, and we'll try to find new players to replacem them and join the game in progress. Stay tuned for updates!

➕ Join as Group (Coming Soon)​

Bring your whole group/party to the matchmaking process, we'll make sure to balance the teams (if enabled). Stay tuned for updates!

🚌 Rolling Updates & AB Tests​

Keeping track of compatibility between server and client versions can get confusing. Here are our recommendations for reliable releases for new updates, preventing downtime or compatibility issues.

danger

We strongly recommend creating a separate matchmaker instance for your dev & production environments.

tip

To run an AB test or a Multivariate test, follow procedures below. Once your test concludes, disable any variants that you found underperforming, keeping the winner. 🏆

info
  • Your matchmaker URL will always remain the same after restarting, to make testing easier.
  • We recommend the blue/green strategy for update releases. Learn more below.

🟠 Before Going Live​

To prepare for zero-downtime updates we recommend creating at least 3x copies of your matchmaking profile ahead of time, for example green, blue and orange. Each game client version will create tickets for one of these, rotating after each update.

tip

Each profile can point to a different app version. App versions serve as aliases for specific server image tags, removing the need to restart your matchmaker when rolling out a new server version.

🔃 Client + Server Update​

This section assumes you’ve completed 🟠 Before Going Live. Let’s assume that live game clients (c1) are currently connecting to profile green, pointing to app version green linked with image tag v1.1.0. We also assume you’ve previously created profile blue pointing to app version blue linked with an older image tag which is no longer used (e.g. v1.0.2).

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

  1. Prepare new server app version (v1.2.0) on Edgegap:
    1. push a new image tag to your container registry (v1.2.0),
    2. create new app version (v1.2.0),
    3. optionally enable caching for new app version (v1.2.0) in preparation,
    4. wait for cache percentage to get to 80% or higher,
  2. Perform any dev tests by deploying your new app version (v1.2.0) through our dashboard
    1. connect your game engine’s Editor to the provided URL + external port,
  3. Update unused profile blue to link to your new image tag (v1.2.0),
  4. Update your new game client (c2) to use the new profile (blue) when creating tickets,
    1. change the base URL and Authorization token to production matchmaker values,
  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,
  6. Release your new game client update (c2) on 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) by filtering deployments with app version (green) in our dashboard,
  8. Perform cleanup of unused resources in your Edgegap account:
    1. delete app version v1.2.0 as it’s no longer used for dev tests,
    2. delete image tag v1.1.0 to free up Container Registry capacity since update is completed.
tip

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

⚡ Server Hotfix​

This section assumes you’ve completed 🟠 Before Going Live Let’s assume that live game clients (c1) are currently connecting to profile green, pointing to app version green linked with image tag v1.1.0.

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

  1. Prepare new server app version (v1.2.0) on Edgegap:
    1. push a new image tag to your container registry (v1.2.0),
    2. create new app version (v1.2.0),
    3. optionally enable caching for new app version (v1.2.0) in preparation,
    4. wait for cache percentage to get to 80% or higher,
  2. Perform tests and verifications by deploying your new app version (v1.2.0) through our dashboard
    1. connect your game engine’s Editor to the provided URL + external port,
    2. if you find and resolve any issues, repeat process from step 1,
  3. Update currently used profile green to link to your new image tag (v1.2.0),
    1. new matches will automatically initiate assignment with the updated tag (v1.2.0),
  4. Perform cleanup of unused resources in your Edgegap account:
    1. delete app version v1.2.0 as it’s no longer used for dev tests,
    2. delete image tag v1.1.0 to free up Container Registry capacity since update is completed.

🗣️ Support and Future Updates​

Our priority is your success. If you feel strongly that some features need to be adjusted, some critical features are missing for you, or would express any thoughts, please reach out in our Community Discord.

⌛ Legacy Managed and Advanced Matchmakers​

warning

Legacy Managed and Advanced matchmakers will be deprecated on November 27th 2024. If you’re using either one and need help upgrading, please reach out to us at your earliest convenience.

tip

Using our Managed matchmaker? Consider upgrading to Gen2 before end of support (deprecation).

info

Using our Advanced matchmaker? Consider upgrading to Gen2. Missing features? There might be a custom solution, please contact us.

🚨 Troubleshooting​

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 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 simply restart your matchmaker from our dashboard. Please consider upgrading to paid tier for unliminted runtime.

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 use Inspect API to delete all tickets and reset your matchmaker’s state, or restart your matchmaker entirely using our dashboard.

Why am I getting errors when trying to create a new matchmaker using my configuration file?

  • 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. 🙏

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 or in case of urgency create a support request through our dashboard page (lifesaver icon in the bottom right corner, “Request Help”).