[Beta][v0.2][2025] MatchMaker: A flexible matchmaking module built on promises and memorystores

Resources Community Resources
1

:video_game: Matchmaker Package Introduction

The Matchmaker package is a modular and scalable matchmaking system built for Roblox multiplayer games. It handles regionalized player queues, asynchronous matchmaking coordination, private server management, and cross-server state syncing using MemoryStore and Promise-based operations.

Key Features

  • Region-Based Queues: Players are grouped by their geographic region for optimal latency and fairness.
  • Promise-Driven Asynchrony: All operations are non-blocking and structured using robust promise chains.
  • Auto-Match Coordination: One server becomes a match coordinator and is responsible for generating matches based on customizable logic.
  • Private Server Integration: Matches are hosted on dynamically reserved private servers with persistent metadata and lifecycle tracking.
  • Graceful Error Handling: Errors are propagated and isolated cleanly, avoiding unwanted chain continuation.
  • Custom Matchmaking Logic: Plug in your own logic to define how players are grouped into matches.

Documentation:

Demo:

Original theoretical thinking

Release Notes

This is the initial release of the tool. It has been tested on a limited scale (just myself and a second account), so there may be edge cases that aren’t fully handled yet. You’re encouraged to try it out and share any feedback or issues you encounter. It’s also my first time building a tool entirely with Promises, so if you notice any misuses or areas for improvement, I’d really appreciate your guidance.

32 Likes
2

[v0.2]

  • Fixed an issue where the party data was not registered in the regional queue when using :AddPartyAsync
  • Fixed an issue where the partyremoved event would fire twice for parties which found a match
2 Likes
3

This is dead? It’s very sad, such a good resource! You need to implement party features to play in the same match with your friends

1 Like
4

Hey there! The main goal is to give developers the flexibility to implement their own party system as they see fit, this is why I didn’t develop a party builder module included.

Could you clarify what do you mean by "party features to play in the same match with your friends
"? Note that the system already supports queueing groups of players using :AddPartyAsync(PartyMemberIds, PartyData).

5

Sorry, I didn’t know. Can I ask if this system will still group players into the same match even when they’re from very different locations? Right now, it seems to separate players by region, but if my game has few players, splitting them could make it hard to find matches. I just want to confirm that distant players can still be grouped when necessary (When the queue is little)

6

Some important points:

  • For players of the same party: This system works best if the players of the party are in the same server instance (they can be across different location/region in the same party). It could also work if the players of the same party are placed across different servers but you’d need to do the logic of when when the party leader goes into a matchmaking or when it finds a match with messaging service (this is more of a party module to be implemented).
  • Matchmaking across Regions: The current limitation of this system is that if you queue one party in Brazil and another in Europe, they will never be matched. Queuing a party from Spain against one from France is fine, because countries are grouped roughly by continent. I understand the concerns for games with small player bases, but do you really want your players to play with high ping—probably not?

Happy to discuss more :grinning_face:

7

Can parties made from just 1 player? Also I thought you could implement an algorithm with different weights based on what PolicyService | Documentation - Roblox Creator Hub gives. It is likely what roblox does

8

Yes, just give a list with one userID.

I guess you are talking about MatchmakingService | Documentation - Roblox Creator Hub but it has its limitations on its own, I recommend reading more documentation on this if you are interested by Roblox’s official matchmaking module.

9

I was talking about this service that you can use a method to see if an user is 13+ or not, so we could make matchs based on ages like roblox mathmaking does

10

How do I make a system for ranked matchmaking on this module?
I’m assuming the current version doesn’t have the option to check player’s rating.

11

This is possible, when you add a party to a queue with :AddPartyAsync, you can add metadata as well and give the rating of each player in the party.

When you create the matchmaking queue with .new the MatchMaking function that you give to the queue will be fire with the parties that are in queue as parameter. See the example given of a solo matchmaker mode in the documentation.

local SoloMatchMaker = MatchMakerService.new({
    Name = "Solo",
    MatchMaking = function(parties)
        local matches = {}
        for _, party in ipairs(parties) do
            table.insert(matches, {
                PlaceId = game.PlaceId,
                Parties = { party },
            })
        end
        return matches
    end,
})
2 Likes