BirdHouse documentation
Documentation for BirdHouse Matchmaking: the Roblox Luau SDK, matching rules, ticket lifecycle, and HTTP API for multiplayer games.
CreateSession()Start a search → receive a match → move playersBirdHouse Matchmaking groups players into matches using rules your game server sends with each ticket. You describe the party and the rules for a good match. The service brings compatible tickets together, and your game takes it from there.
Availability. Matchmaking is in early access. These docs are written for SDK version 0.4.0. SDK package access and a service endpoint are arranged with the team; the docs describe how the integration works and do not confirm that a package is published or a service is hosted. Apply for early access.
What you can build
Create exact-size lobbies, match parties by game mode, gradually widen skill ranges, or require a specific mix of roles. Rules are composable data, so you can express different queues without building a separate matching service for each one.
The first integration is a server-side Roblox SDK. Other server environments can use the same HTTP API directly.
How matchmaking works
- Create a ticket. A ticket represents a party: one or more players, optional metadata, and matching constraints.
- Keep the search alive. The Roblox SDK sends heartbeats while the ticket is waiting. Direct HTTP clients send
confirmactions. - Receive a match. The service combines at least two compatible tickets. Every ticket’s rules must pass against the full group.
- Move players into the game. Your game owns server reservation, teleporting, and recovery if the handoff fails.
A published match completes the search. There is no acknowledgement action; the service retains the result for a fixed retry window.
Choose your path
| Your next step | Read |
|---|---|
| Understand why we’re building BirdHouse | Our mission |
| Compare ways to build matchmaking on Roblox | Roblox matchmaking options |
| Connect a Roblox experience | Quickstart |
| Install the Luau package | Installation |
| Design a queue | Matching rules |
| Tune a ranked or skill-based queue | Skill-based matchmaking |
| Move a matched group into one Roblox server | Match handoff on Roblox |
| Build a server integration for another engine | HTTP API |
| Understand production behavior | Ticket lifecycle |
| Plan analytics events for a multiplayer game | Analytics events for multiplayer games |
| Get SDK package and service access | Apply for early access |
Before you ship
Choose the correct environment and add explicit constraints for required grouping such as game mode. Metadata by itself does not separate queues.
Keep handling matches after requesting cancellation: a published match can win that race. Retain the match while your game completes its handoff, and avoid overlapping sessions for the same players.
Confirm the available package version and the compatible service deployment before integrating. See release notes.