Another major feature of the Namazu Elements Roblox Kit is custom global matchmaking, powered by Namazu’s MultiMatch 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, 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 endpoint (POST /app/rest/robloxkit/match) that your server scripts call when a player wants to find a game. The matchmaking 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 and 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 for a Roblox user in Namazu Elements. This includes configuring a Roblox secret and an Application.
1. Ensure you have a Matchmaking Application Configuration #
In order to make use of the Roblox matchmaker, you must first have a Matchmaking Application Configuration. Refer to the existing Matchmaking Guide to configure one. The simplest configuration will be the easiest to use.
2. Obtain a Session Secret for the User #
Obtaining a session key using the same Application you configured from authentication guide and ensure that the Matchmaking Application Configuration matches the Application used to create the 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 for the game play session. UPon obtaining the reserve server id, the host will update the match using PUT /match/{matchid} and finally teleport that 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.