Skip to main content

Reserving Lobby Slots for Friends and Invites

Cap matchmaking below a lobby's full capacity so invited friends can always join, using lobby teams.

Written by Paul Winterhalder

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 (FindOrCreateLobby, FindOrCreateLobbyWithPingData)

"" (empty)

Only teams with Auto Assign on

Direct join (JoinLobby, JoinLobbyWithPingData)

A team list, e.g. "___:all,reserved"

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

all

0

12

On

reserved

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. all and reserved are 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 all slot first and falls back to reserved only if all is 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 "___:all,reserved"

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 all

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

red

Your minimum

6

On

blue

Your minimum

6

On

redReserved

0

2

Off

blueReserved

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

CreateLobbyWithConfig

Client

CreateLobbyWithConfigAndPingData

Client

SysCreateLobbyWithConfig

Cloud Code / S2S

SysCreateLobbyWithConfigAndPingData

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 }
  ]
}
  • teams replaces the lobby type's whole team list for this lobby, so include every team the lobby should have.

  • Each team needs code, minUsers, maxUsers and autoAssign. maxUsers can't be less than minUsers or 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 FindOrCreateLobby always 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.

Did this answer your question?