--- title: Global Matchmaking description: "❗Pre-Release ❗ **Note:** The Namazu Elements Roblox Kit is currently in pre-release. To access the Roblox Support in Namazu Elements please reach out and request access using our [Contact Us Form](https://namazustudios.com/contact-us/). Another major feature of the Namazu Elements Roblox Kit…" url: "https://namazustudios.com/docs/add-ons/roblox/global-matchmaking/" updated: "2026-08-13" category: "Add-Ons / Roblox" --- # Global Matchmaking ❗Pre-Release ❗ **Note:** The Namazu Elements Roblox Kit is currently in pre-release. To access the Roblox Support in Namazu Elements please reach out and request access using our [Contact Us Form](https://namazustudios.com/contact-us/). Another major feature of the Namazu Elements Roblox Kit is **custom global matchmaking**, powered by Namazu’s **[MultiMatch](https://namazustudios.com/docs/configuration/matchmaking/)** system. This allows you to match players **across your entire game (all servers)** using flexible rules that you define, going beyond Roblox’s built-in matchmaking capabilities. With Namazu’s MultiMatch [Service](https://namazustudios.com/glossary/service/), you can configure matchmaking criteria in the Namazu Elements Admin Panel (for example, game mode, skill brackets, team sizes, etc.), and then use the Roblox Kit to create or join matches for players at runtime. The kit exposes a simple [REST](https://namazustudios.com/glossary/rest/) endpoint (`POST /app/REST/robloxkit/match`) that your server scripts call when a player wants to find a game. The matchmaking [Service](https://namazustudios.com/glossary/service/) will either **find an appropriate existing match or create a new match** according to the configuration you specified. The response includes details of the match, such as a unique match [id](https://namazustudios.com/glossary/id/) and [Metadata](https://namazustudios.com/glossary/metadata/), and indicates whether the player is designated as the match **host**. (When a new match is created, one player is marked as the host who will orchestrate the match, while others are added as clients.) This **global matchmaking** approach means players from different server instances (or different places in your experience) can be pooled together by the backend. The Namazu MultiMatch system handles the logic of grouping players, so you’re not limited by Roblox’s server-bound matchmaking. For example, you could have players in multiple lobbies all request to join a “battle” match – Namazu will group them and respond with a match assignment. Because Roblox server scripts do not support real-time WebSocket connections, the kit uses a **polling** mechanism for match updates. Your server can periodically call a `GET /app/REST/robloxkit/match/{matchId}` endpoint to check if the match is ready (i.e. enough players have joined or a host has signaled to start). This polling design ensures compatibility with Roblox’s architecture, where continuous connections aren’t possible. ## Using the Roblox Global Matchmaker This guide walks you through using the matchmaking system. In order to use the API, you must have worked through [obtaining a session key](https://namazustudios.com/docs/add-ons/game-engines/roblox/secure-player-authentication-registration/) for a Roblox [User](https://namazustudios.com/glossary/user/) in Namazu Elements. This includes configuring a Roblox secret and an [Application](https://namazustudios.com/docs/namazu-elements-core/features/applications/). ### 1. Ensure you have a Matchmaking [Application](https://namazustudios.com/glossary/application/) Configuration In order to make use of the Roblox matchmaker, you must first have a Matchmaking [Application](https://namazustudios.com/glossary/application/) Configuration. Refer to the existing [Matchmaking Guide](https://namazustudios.com/docs/configuration/matchmaking/) to configure one. The simplest configuration will be the easiest to use. ### 2. Obtain a [Session](https://namazustudios.com/glossary/session/) Secret for the [User](https://namazustudios.com/glossary/user/) Obtaining a [Session](https://namazustudios.com/glossary/session/) key using the same [Application](https://namazustudios.com/glossary/application/) you configured from authentication guide and ensure that the Matchmaking [Application](https://namazustudios.com/glossary/application/) Configuration matches the [Application](https://namazustudios.com/glossary/application/) used to create the [Session](https://namazustudios.com/glossary/session/). ### 3. Attempt to Find a Match The process of finding a match involves making an initial request to the `POST /match` endpoint. If there is a match meeting the requested criteria, the player will join that match. If there are matches meeting the requested criteria, the system will create a new match and wait for other players to join. ⚠️ Use Only Once ⚠️ Use the `POST /match` endpoint only **once** when the player enters the queue as it may result in many abandoned matches degrading player experience. While the database will eventually clean up orphaned matches, it may take time leaving other players waiting for a match which never will start. The Roblox Kit provides few guardrails due to the polling nature of the matchmaking system. ### 4. Poll for Start Conditions For each MultiMatch, Namazu Elements will assign a single player as the "host" player. The host flag designates which player is responsible for orchestrating the start of the game. Depending on the host flag, perform the following actions. #### 4a. Host Player Responsibility The host player will continue to poll the match until start conditions are met. For example, the minimum player count has been met to initiate a game. When to orchestrate the start will depend on the specific rules and design of your game. Once start conditions are met, the host player will [reserve a server](https://create.roblox.com/docs/reference/engine/classes/TeleportService#ReserveServerAsync) for the game play [Session](https://namazustudios.com/glossary/session/). UPon obtaining the reserve server [id](https://namazustudios.com/glossary/id/), the host will update the match using `PUT /match/{matchid}` and finally teleport that [User](https://namazustudios.com/glossary/user/) to the server they just created. ⚠️ Reserving a Server ⚠️ Once the host reserves a server, the Roblox Kit will automatically designate the match as `CLOSED`, which will disallow other players from joining even if the match is not full. #### 4b. Non-Host Player Responsibility The non-host or "client" players will poll `GET /match/{matchId}` waiting for the match to start. Once a response indicates that a reserved server exists, then the client players will follow the host player to that match. #### 5. Delete and Leave Match Once the game has concluded, the host must clear the match from the database by calling `DELETE /match/{matchId}`. ⚠️ Leaving a Match ⚠️ In order to maintain consistency, we strongly recommending using `DELETE /match/{matchId}/{profileId}` to remove the player from an in-progress match. In the event that the host player leaves Namazu Elements will assign a new host automatically.