Matchmaker In-Depth

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

✔️ Introduction

Edgegap Matchmaker is a managed service using your own rules to find the optimal group of teammates and opponents in seconds. Get started in 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.

Our matchmaking philosophy is driven by player perspective, with core principles of matchmaking:

• maximizing match fill rate and social integration (friends and lobbies),

• fast matches and high match quality controls (low latency, similar preferences),

• high service availability, observability, analytics, and user-friendly error handling.

To deliver on our core principles, we prioritize first and foremost:

• real world examples, game engine SDKs, and step by step guides,

• modular and configurable features, focused on player experience,

• no-code configuration and support for zero downtime service updates.

⭐ Essentials

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 that define how the matchmaker will operate.

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

☁️ 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,

  • matchmakers on free cluster shut down after 3 hours automatically, requiring restart,

• Private Cluster to ensure stable and dedicated environment for your production needs.

Private Cluster Tiers

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

Upgrading to a private cluster only takes one click. Changing Private Cluster Tiers after launch, without any player downtime, is also possible with ⏩ Rolling Updates. Managed clusters provide you high-availability service hosting maintained by Edgegap.

Prepare for success and optimize after launch, so you don’t block your players on release day.

📏 Configuration

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

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "simple-example": {
      "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": 2,
              "max_team_size": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 100,
              "max_latency": 200
            }
          }
        },
        "expansions": {}
      }
    }
  }
}

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
    "advanced-example": {
      "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
            }
          }
        }
      }
    }
  }
}

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "3m",
  "ticket_removal_period": "1m",
  "profiles": {
    "custom-lobby-example": {
      "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
            }
          }
        }
      }
    }
  }
}

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "backfill-example": {
      "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": {}
      }
    }
  }
}

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "casual-example": {
      "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": {
      "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": {
      "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
            }
          }
        }
      }
    }
  }
}

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "3m",
  "ticket_removal_period": "1m",
  "profiles": {
    "cooperative-example": {
      "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
            }
          }
        }
      }
    }
  }
}

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "3m",
  "ticket_removal_period": "1m",
  "profiles": {
    "social-example": {
      "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
            }
          }
        }
      }
    }
  }
}

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.

Application and Versions

Each matchmaker profile points to Apps and Versions in your Edgegap organization. Separating development and production environments with separate matchmaker may help prevent accidentally releasing a version which is not production ready.

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.

Operators (rule type)

To demonstrate various operators, we will refer to our example configuration:

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
    "advanced-example": {
      "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
            }
          }
        }
      }
    }
  }
}

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,

• example defaults to 1 team (no team split), see Teams for more details,

• 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 a partial match is possible (>min and <max team size), this match will be made with all players in same expansion stage and any preceding expansion stages with matching rules (other than player count).

string_equality matches players with the exact same string value, for example:

• example selected_game_mode rule will match players case sensitively:

  ✅ Alice + Bob + Dave may match,

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

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

• example 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 matching players within a specific difference range in ping values:

• 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,

Our example beacons rule above with "difference": 100, "max_latency": 200 initially:

✅ Alice and Bob will match:

• Tokyo is discarded (>200 ms),

• latency for Chicago within 100 ms absolute difference.

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

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

• example selected_map rule above with "overlap": 1 :

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

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

Rule Expansion

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

{
  "version": "3.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
    "advanced-example": {
      "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
            }
          }
        }
      }
    }
  }
}

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 and highest player value for that 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 - see Backfill.

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

Teams

To support multiple teams, increase team_count value. Get total number of players by multiplying team size and team count:

• for "team_count": 2 and "max_team_size": 5, a total of 10 players is allowed for a match,

• for cooperative and free-for-all game modes, set "team_count": 1 .

🎫 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 a few steps:

• Player creates a ticket status="SEARCHING" ,

• Player repeatedly reads their ticket every second; looking for matches:

  1. Team has been found status="TEAM_FOUND" (see Teams and Join as Group),

     1. Optionally team disbanded status="SEARCHING" , shuffling groups.

     2. Optionally team disbanded status="SEARCHING" , teammate abandoned.

     3. Optionally group disbanded status="CANCELLED" , group member abandoned.

  2. Match has been found status="MATCH_FOUND" ,

     1. Deployment started, waiting while Assignment is null,

     2. Deployment may be retried several times if 4. Deployment Erroroccurs,

  3. Host has been assigned status="HOST_ASSIGNED" ,

     1. Deployment is Ready, server process starts initializing,

     2. Players read the assignment (URL & external port) from their tickets,

     3. Players retry connection to game server until ready.

• Matchmaking may stop before "MATCH_FOUND" due to either:

  1. Player abandoning (deleting) their ticket,

     1. Ticket is immediately deleted and reading it will return 404 Not Found.

  2. Ticket expiration period reached status="CANCELLED" ,

     1. Ticket can be read until removal period is reached, then it’s deleted (returns 404).

  3. Maximum deployment retries exhausted status="CANCELLED" ,

     1. Ticket can be read until removal period is reached, then it’s deleted (returns 404).

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

Latency Optimization

To provide best possible latency, 🎫 Player Tickets may include game clients’ latency for one or more Ping Beacons. Once clients perform a “best effort” measurement, they construct an object with all beacon-specific latency values:

{
  "Los Angeles": 224.4,
  "Manama": 23.2,
  "Tokyo": 167.4
}

Beacon latency values are used to prevent matching with players in a vastly different region.

Join as Group

Joining matchmaking with your friends relies on a third party identity system. Most games will use Epic Online Services, Nakama, Steamworks, brainCloud, Lootlocker, Playfab, Apple Identity, Google Play, or others… These systems usually expose a platform-dependent friend system and a lobby/party system which can be used to communicate across the group.

To join matchmaking with a group, once the group is assembled:

• Group leader requests ticket attributes from other members,

• Group members provide requested information to leader,

• Group leader creates a Group Ticket using our SDKs or the API,

  1. upon receiving assignments, Group leader sends each member one assignment,

• Group members follow regular Matchmaking Process as if they joined alone.

In case a group member decides to abandon their ticket prior to HOST_ASSIGNED, all tickets of group members immediately update to status="CANCELLED" pending removal after the configured period. Afterwards, this matchmaking process may be repeated from scratch with a new group ticket, disregarding the previous tickets.

If a group member decides to abandon match after HOST_ASSIGNED , game server is responsible for waiting for a pre-defined period of time and finally issuing new Backfill tickets to replace the player.

If a group member’s game client crashes, they may reconnect as long as they have saved their assignment ID persistently (on drive) between game restarts.

Backfill

Optionally, some games may have special matchmaking needs, such as:

• allow new players to join games in progress (friends or strangers),

• replace players who leave (leavers) after game 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),

• let players choose a server to join through a server browser (custom).

See 🥛 Backfill Showcase for a minimal example of a backfill-enabled configuration.

To initiate successful backfill:

1. Server creates /backfills for each team separately, with values:

   • real assignment data retrieved from Injected Environment Variables (deployment).

   • adding backfill_group_size to tickets, listing group sizes up to available team capacity.

   • real tickets data retrieved from Injected Environment Variables (matchmaker),

   • or mock tickets data fabricated to match specific (real) player tickets,

2. Clients create /tickets or /group-tickets with backfill_group_size array:

   • including value "1" if the player is matchmaking alone, or number of group members,

   • additionally including value "new" if players wish to allow starting new games,

   • or omitting value "new" if players only wish to join a game in progress (backfill).

3. Matchmaking Process proceeds to assignment and clients connect to the server.

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

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

Once game server initialization concludes, your server should continually:

• Start idle disconnect countdown for each new player (recommend up to 3 min):

  1. Start a loading scene/level while players connect - a full fledged 3D scene, a lobby-like social UI, or a loading screen with a progress bar, to indicate initialization is progressing.

  2. Trigger loading for new players on server initialization.

  3. Trigger loading for players replacing leavers (joining via Backfills).

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

  1. Listen to custom client RPCs containing new player ticket IDs (initial or backfilled), to pair tickets to netcode entities/actors.

  2. Read and verify assigned_ticket player data retrieved from /backfills.

  3. Create new Backfills for unused player capacity (leavers).

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

• Delete any leftover Backfills once the 5. Deployment Stopped:

  • Unity - OnApplicationQuit callback,

  • Unreal Engine - OnWorldDestroyed or PreExit callback.

Any profile can be used for Backfill as long as attributes of backfill are valid.

🔎 Server Browser

This feature is in development, scheduled for late 2025, stay tuned for updates! 🚀

Some games may want to let players join servers with open capacity. We're working on additional matchmaking features allowing this in addition or as a replacement of classic matchmaking.

Reach out to let us know about your server browser requirements and needs!

👀 Observability

To pass information to game servers and provide operational insights, we provide additional features.

Injected Environment Variables

Your server might need to know details about it’s players. Ticket attributes, resolved rule values, and other values are injected to your deployment, in addition to default Injected Environment 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"}

Load Testing

Instances use CPU and memory to perform matchmaking and assignments, associating a hosting cost with each private matchmaker. See resources and prices associated with each tier on our pricing page.

The resource requirements for your instance will depend on factors:

• number of players - more players make more tickets,

• number of requests - polling for status more often creates more load on matchmaker,

• configuration complexity - number of profiles, rules, and expansions,

• average match duration - shorter duration means more matches, tickets, and higher load,

• ticket expiration and removal periods - keeping stale tickets for longer consumes more memory,

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

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 retried over longer period of time.

Player Traceability

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

Analytics

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

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

⏩ Rolling Updates

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

Your Matchmaker URL will always remain the same after restarting.

🟠 Before Going Live

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

We strongly recommend implementing blue/green strategy for update releases.

🔃 Client + Server Update

Prerequisites:

• This section assumes you’ve completed 🟠 Before Going Live.

• Live game clients c1 are currently connecting to matchmaker green, pointing to app version v-green linked with image tag t1.1.0.

• You’ve previously created matchmaker blue pointing to app version v-blue linked with an older image tag which is no longer used t1.0.0.

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

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

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

   2. create new app version v1.2.0,

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

   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 , 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 to reach 🟢 green,

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

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

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

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

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

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

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

   1. monitor outdated game clients c1 using deployment Analytics,

8. Clean up unused resources in your Edgegap account:

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

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

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

⚡ Server Hotfix

Prerequisites:

• This section assumes you’ve completed 🟠 Before Going Live.

• Live game clients c1 are currently connecting to matchmaker green, pointing to app version v-green linked with image tag t1.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 t1.2.0,

   2. create new app version v1.2.0,

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

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

Authentication

Game clients and servers authenticate with Matchmaker using Authorization HTTP header containing your secret token (Auth Token):

Authorization: xxxxxxxx-e458-4592-b607-c2c28afd8b62

Authorization (S2S)

Matchmaking API token provides unrestricted access to all matchmaking API endpoints.

Individual players can be identified using the ticket ID shared between clients and server:

Enhance security and integrate custom authorization with Server to Server (below).

Server to Server

Include parameter player_ip in player ticket with the player’s public IP address to take advantage of 1. Server Score Strategy (Best Practice) and ensure lowest possible player latency:

• to authenticate players with your own third party service acting as a proxy,

• or when creating tickets from a custom lobby/party service (e.g. 📦 Nakama by Heroic Labs).

Player API

These endpoints can be used directly by game clients or with Server to Server integration.

/monitor

Monitoring endpoint provides a convenient way to verify uptime of your Matchmaker Service from game clients or backend services, so you can reach out for assistance in case of urgent issues. You may integrate redundant (multiple) monitoring systems checking this endpoint for your own visibility.

{
  "status": "HEALTHY",
  "message": "All systems operational.",
  "healthy_components": 5,
  "unhealthy_components": 0
}

/locations/beacons

Ping Beacons provide a simple yet effective way to approximate connection quality to major networking nodes and prevent high latency matches. See Matchmaker In-Depth for more.

{
  "count": 5,
  "beacons": [
    {
      "fqdn": "b-1b67036359bc.pr.edgegap.net",
      "public_ip": "172.233.26.222",
      "tcp_port": 31709,
      "udp_port": 32126,
      "location": {
        "city": "Sao Paulo",
        "country": "Brazil",
        "continent": "South America",
        "administrative_division": "Sao Paulo",
        "timezone": "Brasília Time"
      }
    },
    {
      "fqdn": "b-7ef05f5f25f7.pr.edgegap.net",
      "public_ip": "172.104.9.206",
      "tcp_port": 30775,
      "udp_port": 31490,
      "location": {
        "city": "Newark",
        "country": "United States of America",
        "continent": "North America",
        "administrative_division": "New Jersey",
        "timezone": "Eastern Time"
      }
    },
    {
      "fqdn": "b-4c07a9a8369b.pr.edgegap.net",
      "public_ip": "157.175.50.63",
      "tcp_port": 30857,
      "udp_port": 32711,
      "location": {
        "city": "Manama",
        "country": "Bahrain",
        "continent": "Asia",
        "administrative_division": "Bahrain",
        "timezone": "Arabia Time"
      }
    }
    {
      "fqdn": "b-fe41a96156be.pr.edgegap.net",
      "public_ip": "172.234.123.158",
      "tcp_port": 30622,
      "udp_port": 30278,
      "location": {
        "city": "Stockholm",
        "country": "Sweden",
        "continent": "Europe",
        "administrative_division": "Stockholm County",
        "timezone": "Central European Time"
      }
    },
    {
      "fqdn": "b-ee0069bafee6.pr.edgegap.net",
      "public_ip": "172.105.204.125",
      "tcp_port": 32116,
      "udp_port": 32041,
      "location": {
        "city": "Tokyo",
        "country": "Japan",
        "continent": "Asia",
        "administrative_division": "Tokyo",
        "timezone": "Japan Time"
      }
    },
  ]
}

/tickets

🎫 Player Tickets provide a simple interface for players to match together, see Matchmaking Process and 5. Game Integration.

• Create Ticket (POST) - pick a matchmaking profile & submit ticket attributes:

  • override 📍 Server Placement by using beacon IP in place of player_ip in your ticket.

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

• Read a Ticket (GET) - check on matchmaking progress and host assignment.

{
  "id": "cqg0bg550h7uujd77khg",
  "profile": "simple-example",
  "group_id": "0ba34811-7f0d-4bf9-8b20-20d63e9c2640",
  "team_id": "cusf43gmsflc73beiijg",
  "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",
  "status": "HOST_ASSIGNED"
}

• Delete a Ticket (DELETE) - abandon matchmaking immediately.

/group-tickets

Join as Group endpoints allows matching deployments as a group/party/lobby:

• Create Group Ticket (POST) - submit yours and your group members' tickets.

  • Your designated group host/leader is responsible to collect ticket attributes from players through a third party of your choice, and to distribute assignment IDs to individual group members to allow managing individual Matchmaking Process.

{
  "player_tickets": [
    {
      "player_ip": "174.25.48.238",
      "attributes": {
        "beacons": {
          "New York": 12.2,
          "Los Angeles": 45.3,
          "Paris": 78.3
        }
      },
      "id": "c3d057h5h6f7j889fk43"
    },
    {
      "player_ip": "217.34.85.142",
      "attributes": {
        "beacons": {
          "New York": 21.0,
          "Los Angeles": 30.2,
          "Paris": 101.1
        }
      },
      "id": "cqg0bg9583s738h9dkf6"
    },
    {
      "player_ip": "136.224.30.243",
      "attributes": {
        "beacons": {
          "New York": 30.2,
          "Los Angeles": 10.5,
          "Paris": 123.9
        }
      },
      "id": "cqd0785f4ggffd99sk8n"
    }
  ]
}

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:

{
  "version": "2.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "allowed_cors_origins": [
    "https://dev.my-game-server.com",
    "https://prod.my-game-server.com"
  ],
  "profiles": {
    "simple-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 50,
              "max_latency": 200
            }
          }
        },
        "expansions": {}
      }
    }
  }
}

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

{
  "version": "2.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "allowed_cors_origins": ["https://*.my-game-server.com"],
  "profiles": {
    "simple-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 50,
              "max_latency": 200
            }
          }
        },
        "expansions": {}
      }
    }
  }
}

Game Server API

These endpoints are used by the dedicated game server or your game backend.

/backfills

Backfill allows your game server or your backend service to manage player capacity of servers:

• Create a Backfill (POST) - submit current player tickets along with matchmaking profile.

{
  "profile": "simple-example",
  "attributes": {
    "assignment": {
      "request_id": "cd28e6c66554",
      "fqdn": "cd28e6c66554.pr.edgegap.net",
      "ip_address": "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
        }
      },
      "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
        }
      },
      "group_id": "aea7df3c-d391-4ea3-a3ec-dded422fe7c8",
      "id": "cqg0bg9583s738h9dkf6",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    },
    "cqd0785f4ggffd99sk8n": {
      "player_ip": "136.224.30.243",
      "attributes": {
        "beacons": {
          "New York": 30.2,
          "Los Angeles": 10.5,
          "Paris": 123.9
        }
      },
      "group_id": "123er97e-7fd6-4d86-8ce4-61c53c9fet49",
      "id": "cqd0785f4ggffd99sk8n",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    }
  },
  "assigned_ticket": null
}

• Read a Backfill (GET) - retrieve ticket information about the filled player.

{
  "profile": "simple-example",
  "attributes": {
    "assignment": {
      "request_id": "cd28e6c66554",
      "fqdn": "cd28e6c66554.pr.edgegap.net",
      "ip_address": "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
        }
      },
      "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
        }
      },
      "group_id": "aea7df3c-d391-4ea3-a3ec-dded422fe7c8",
      "id": "cqg0bg9583s738h9dkf6",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    },
    "cqd0785f4ggffd99sk8n": {
      "player_ip": "136.224.30.243",
      "attributes": {
        "beacons": {
          "New York": 30.2,
          "Los Angeles": 10.5,
          "Paris": 123.9
        }
      },
      "group_id": "123er97e-7fd6-4d86-8ce4-61c53c9fet49",
      "id": "cqd0785f4ggffd99sk8n",
      "created_at": "2024-08-20T13:38:05.251393+00:00"
    }
  },
  "assigned_ticket": {
    "profile": "simple-example",
    "player_ip": "244.13.201.244",
    "attributes": {
      "beacons": {
        "New York": 30.2,
        "Los Angeles": 10.5,
        "Paris": 123.9
      }
    },
    "id": "cqg0bg550h7uujd77khg",
    "group_id": "e0cf41c0-f88f-456e-a032-03b1d6821a9a",
    "created_at": "2024-08-20T13:38:08.251393+00:00",
    "status": "SEARCHING"
  }
}

• Delete a Backfill (DELETE) - stop backfill depending on game server logic and design.

/inspect

Inspect API provides real time matchmaking insights. The changes you make to your configuration and the impact on your players will be more predictable if you run tests on your matchmaker.

• Inspect Tickets (GET) - list current player tickets, their status, and assignment (if available).

{
  "data": [
    {
      "id": "cusemi0msflc73beiicg",
      "profile": "simple-example",
      "group_id": "53ff24e1-cea9-4317-9eca-a15b1b35bc72",
      "team_id": null,
      "player_ip": "174.93.233.25",
      "assignment": null,
      "created_at": "2025-02-21T21:08:24.2528685Z",
      "status": "SEARCHING"
    },
    {
      "id": "cusem7omsflc73beiiag",
      "profile": "simple-example",
      "group_id": "d25f4886-bfe1-4959-a06e-0e03d04567ca",
      "team_id": "cusemi8msflc73beiidg",
      "player_ip": "174.93.233.25",
      "assignment": null,
      "created_at": "2025-02-21T21:07:43.3824185Z",
      "status": "MATCH_FOUND"
    },
    {
      "id": "cusemhgmsflc73beiibg",
      "profile": "simple-example",
      "group_id": "b5d6a00a-b295-42c6-9bfa-a0feac95dfb0",
      "team_id": "cusemi8msflc73beiidg",
      "player_ip": "174.93.233.25",
      "assignment": null,
      "created_at": "2025-02-21T21:08:22.9357005Z",
      "status": "MATCH_FOUND"
    }
  ],
  "total_count": 3,
  "pagination": {
    "number": 1,
    "next_page_number": null,
    "previous_page_number": null,
    "paginator": {
      "num_pages": 1
    },
    "has_next": false,
    "has_previous": false
  }
}

• Inspect Matches (GET) - list current matches and resolved Rules values.

{
  "data": [
    {
      "id": "matchac085106-1b0c-4519-bb8e-5646c7547356",
      "teams": [
        {
          "id": "cusepkomsflc73beiig0",
          "players": [
            {
              "id": "cusep10msflc73beiie0",
              "profile": "simple-example",
              "group_id": "3fb0b1e5-5566-46d3-b2cc-132131d1160b",
              "team_id": "cusepkomsflc73beiig0",
              "player_ip": "174.93.233.25",
              "assignment": {
                "fqdn": "2821bb04b41b.pr.edgegap.net",
                "public_ip": "69.164.212.65",
                "ports": {
                  "gameport": {
                    "internal": 5000,
                    "external": 30813,
                    "link": "2821bb04b41b.pr.edgegap.net:30813",
                    "protocol": "HTTP"
                  }
                },
                "location": {
                  "city": "Newark",
                  "country": "United States of America",
                  "continent": "North America",
                  "administrative_division": "New Jersey",
                  "timezone": "Eastern Time"
                }
              },
              "created_at": "2025-02-21T21:13:40.4821087Z",
              "status": "HOST_ASSIGNED"
            },
            {
              "id": "cusepkgmsflc73beiif0",
              "profile": "simple-example",
              "group_id": "90762249-fcc4-42dc-968f-4b8d83534647",
              "team_id": "cusepkomsflc73beiig0",
              "player_ip": "174.93.233.25",
              "assignment": {
                "fqdn": "2821bb04b41b.pr.edgegap.net",
                "public_ip": "69.164.212.65",
                "ports": {
                  "gameport": {
                    "internal": 5000,
                    "external": 30813,
                    "link": "2821bb04b41b.pr.edgegap.net:30813",
                    "protocol": "HTTP"
                  }
                },
                "location": {
                  "city": "Newark",
                  "country": "United States of America",
                  "continent": "North America",
                  "administrative_division": "New Jersey",
                  "timezone": "Eastern Time"
                }
              },
              "created_at": "2025-02-21T21:14:58.3907649Z",
              "status": "HOST_ASSIGNED"
            }
          ]
        }
      ]
    }
  ],
  "total_count": 1,
  "pagination": {
    "number": 1,
    "next_page_number": null,
    "previous_page_number": null,
    "paginator": {
      "num_pages": 1
    },
    "has_next": false,
    "has_previous": false
  }
}

Coming Soon: pause and resume matchmaking at specific ticket stages.

🙏 Support & Requests

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.

🚨 Troubleshooting

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

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 /backfills.

🩹 Bugfixes:

• Backfill now uses configured deletion and expiration period (like tickets and group tickets).

• Backfill now correctly matches using configured intersection rules.

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