Overview
You can stop matchmaking at a "soft cap" (for example 12 players) while still letting invited friends join up to the lobby's true capacity (for example 16). You do this with lobby teams. No filter script or custom server logic is needed.
The problem it solves: matchmaking normally fills a lobby to its maximum. Once it's full, a player who wants to join a friend gets turned away. Holding back a few slots for direct joins keeps room for friends and party invites in busy public lobbies.
The idea in one line: put matchmade players on a team that matchmaking can fill, and put the held-back slots on a second team that only direct joins can reach.
How it works
Each team in a lobby type has an Auto Assign setting, and matchmaking and direct joins treat it differently:
How the player joins | Team code sent | Which teams they can land on |
Matchmaking ( |
| Only teams with Auto Assign on |
Direct join ( | A team list, e.g. | The listed teams, tried in order, including teams with Auto Assign off |
When the auto-assign team fills up, matchmaking stops placing players in that lobby. The lobby still has open slots on the non-auto-assign team, and those can only be reached by a direct join that names it. That team's size is your number of reserved slots.
Setup
In the Design Portal, open App > Design > Multiplayer > Lobbies and edit your lobby type. Replace its single team with two teams. For a 16-player lobby that matchmaking fills to 12:
Team code | Min players | Max players | Auto Assign |
| 0 | 12 | On |
| 0 | 4 | Off |
The lobby's total capacity (the hard cap) is the sum of both teams: 12 + 4 = 16.
The auto-assign team's max (12) is the soft cap that matchmaking fills to.
Keep Min players at 0 on the reserved team. Otherwise the lobby waits for reserved players before it can meet its team minimums and start.
Team codes are up to you.
allandreservedare just examples, and you'll use the same codes in your client.
Lobbies created by FindOrCreateLobby or CreateLobby for this lobby type get these teams automatically.
Joining lobbies
Matchmaking: no change
Keep calling FindOrCreateLobby (or FindOrCreateLobbyWithPingData) with an empty teamCode. Matchmaking only uses auto-assign teams, so players fill all and never reserved.
Direct joins: name the teams in order
When a player joins a specific lobby, such as a friend's lobby or one from an invite or lobby code, call JoinLobby with a team list in teamCode:
teamCode: "___:all,reserved"
The prefix is three underscores followed by a colon, then the team codes separated by commas.
brainCloud tries the teams in the order listed. Here it uses a free
allslot first and falls back toreservedonly ifallis full.One call covers both cases, so you don't need retry logic.
If the player joins with party members (
otherUserCxIds), brainCloud keeps the group on one team when it can, and splits them across the listed teams when no single team has room.
List the teams explicitly. A bare "___" with no list tries every team in random order, so friends could use up reserved slots while public slots are still open.
Example: how a lobby fills
Using the 12 + 4 setup above, a lobby fills like this:
Step | What happens | all | reserved | Matchmaking can place players? |
1 | Matchmaking places 10 players | 10/12 | 0/4 | Yes |
2 | 2 friends direct-join with | 12/12 | 0/4 | No, soft cap reached |
3 | 3 more friends direct-join | 12/12 | 3/4 | No |
4 | 2 public players leave | 10/12 | 3/4 | Yes, 2 slots |
5 | Matchmaking refills | 12/12 | 3/4 | No |
6 | 1 more friend direct-joins | 12/12 | 4/4 | No, lobby full at 16 |
Friends count toward the soft cap while there's room on all, and use reserved only after that. The lobby never goes past its hard cap of 16.
Games with gameplay teams
If your game already uses teams (red vs. blue, for example), give each side its own reserved team. This also lets you decide how the held-back slots are split between sides. A 2 × 8 game that matchmaking fills to 6 per side:
Team code | Min players | Max players | Auto Assign |
| Your minimum | 6 | On |
| Your minimum | 6 | On |
| 0 | 2 | Off |
| 0 | 2 | Off |
A direct join to a friend on red would send "___:red,redReserved". Your game treats red and redReserved as the same side. The team code tells you which slot the player is in, not which side they play on.
Different reservations per lobby
To let the number of reserved slots vary by lobby, create the lobby with a team override. Use this when a host picks how many slots to hold for friends, or when your server creates lobbies with different splits. These APIs are available from brainCloud 6.0:
API | Called from |
| Client |
| Client |
| Cloud Code / S2S |
| Cloud Code / S2S |
Each takes the same parameters as the matching CreateLobby call, plus a required configOverrides map. For example, a host who wants 6 of 16 slots held for friends:
{
"teams": [
{ "code": "all", "minUsers": 0, "maxUsers": 10, "autoAssign": true },
{ "code": "reserved", "minUsers": 0, "maxUsers": 6, "autoAssign": false }
]
}teamsreplaces the lobby type's whole team list for this lobby, so include every team the lobby should have.Each team needs
code,minUsers,maxUsersandautoAssign.maxUserscan't be less thanminUsersor more than your app's maximum players per lobby.The override applies only to the lobby you create. Other lobbies of the same type keep the portal settings.
Overridden lobbies stay in the same lobby type, so matchmaking can still place players in them, up to their own auto-assign limit. You don't need a separate lobby type for each split.
Lobbies created by
FindOrCreateLobbyalways use the portal settings. Overrides only apply to lobbies you create explicitly.Teams are currently the only setting that can be overridden.
Tips and FAQ
Friends need to join a match that has already started. What do I need?
Turn on Join In Progress in the lobby type's rules. Without it, a lobby stops accepting joins of any kind once its room server launches. See Implementing Continuous Lobbies.
Does an empty reserved team keep the lobby from starting?
No. When brainCloud decides whether a lobby is full enough to start, it only counts auto-assign teams. A lobby at 12/12 on all and 0/4 on reserved counts as full. Keep minUsers at 0 on reserved teams so team minimums are still met.
Can I do this with a lobby filter script instead?
You can, but it gets slow as you scale. A filter script runs on every matchmaking attempt, and when it rejects most lobbies, players take longer to find a match. With teams, the slot check is built into matchmaking and no script runs.
Can I change the reserved count on a lobby that's already running?
No. A lobby's teams are fixed when it's created, either from the lobby type or from configOverrides.
What happens if a direct join finds every listed team full?
The join fails because the lobby is full, the same as joining any full lobby. Show the player a "lobby is full" message.
Do players on the reserved team get any special treatment in game?
No. brainCloud doesn't treat them differently. The team code is in the lobby data if your game wants to use it.
