A way to do matchmaking using coherence Player accounts.

What is a Lobby

A lobby is a virtual room that is not backed by a Replication Server. Lobbies have attributes and contain up to a certain number of players. Players also have attributes and can exchange messages in real time.

Matchmaking is the process of grouping players together based on a certain game-specific criteria.


The entire process consists of three phases - Matchmaking, Lobby Session and Game Session. The phases happen in exactly this order. Not all phases are mandatory.


The matchmaking phase is where players are grouped together based on certain criteria. In the case where players just want to jump into the game, the interface can be very simple - press the button to find other players to play with and that’s it.

The matching logic underneath is entirely game-specific so it is up to the developer to properly use the Lobby API in order to get the best possible result. To players it may look deceptively simple on the surface but under the hood the logic can get quite complex. Some games may require more sophisticated matchmaking logic so the matchmaking phase can be represented by an advanced UI that allows players themselves to create, browse and join lobbies on their own.

In the mockup above, Lobbies are filtered using the same matchmaking logic as in the previous scenario. The difference is that more than one result can be returned so players get to choose the best possible match out of the already curated list.

Lobby Session

The Lobby Session phase begins once the player has found and joined a Lobby. Inside the Lobby players can exchange messages and have their data attributes synchronized until everyone is ready to start the game.

The first player to join a Lobby becomes the owner. There can only be one owner. Only the owner can change Lobby attributes and start the game. If the owner leaves the Lobby, one of the other players becomes the new owner.

Deciding when to start the game as an owner is entirely game-specific, and even the fact that a Lobby owner exists can be a hidden implementation detail and not exposed to the players. Alternatively, you may want to give the power to the Lobby owner to start the game whenever they want through an UI action. It is up to the game to decide how Lobby owners are handled.

Players can leave the lobby and new players can join at any time until the Lobby is full or until it is manually closed. Empty Lobbies are automatically deleted 5 minutes after the last player has left both the Lobby and the associated Replication Server Room (this can be adjusted on the project Dashboard). A couple of Lobby examples are shown below. You as the game developer have full freedom to come up with the logic and UX suited for your game.

Once enough players have joined the lobby the owner can start the game.

Game Session

What we call the game phase is playing the game in a Room hosted by a Replication Server.

The process of creating Rooms and connecting all players at the same time, which can be quite complex to orchestrate, is handled by the SDK/backend.

When the Game Session starts, every player in the Lobby will receive a callback in Unity through the Lobby API with the Room endpoint data so they can connect to the Replication Server Room.

If no game-specific callback is registered, coherence will automatically connect the player to the Room using the CoherenceBridge component.

The Lobby still exists while the players are connected to the Replication Server. If you happen to disconnect or close your game and then log into the coherence Cloud again, the successful Login response will have the Room endpoint data available so you can reconnect and continue the Game Session phase.

Lobby State and Lifecycle

When a Lobby is created, it can be either public or unlisted. Public Lobbies can be matched/searched and then joined by anybody. Unlisted Lobbies can be joined only if the player knows the Lobby ID. If a player leaves the Lobby they can rejoin again at any time.

When players start the Game Session, the Lobby can be optionally set to unlisted or closed as part of the process. If neither is set then the lobby remains in whatever state it was, i.e. either public or unlisted. In addition it is also marked as “in-game” (a room number is attached to the Lobby). Players can either choose to stay in the Lobby while in the game or leave the Lobby when they join the game.

Closed Lobbies can still contain players, i.e. if a Lobby is closed this doesn’t kick out the players. New players cannot join, only players who were in the Lobby when it closed can leave and rejoin. Closed Lobbies cannot be reopened.

Inactive players with no connection to the backend are removed from the Lobby after 1 minute. They can rejoin if the Lobby is not full.

When the last player has left both the Lobby and the associated RS room (if any), then and only then the Lobby is deleted after 5 minutes of inactivity.

Handling Lobbies in Unity

Please refer to the Cloud Service API: Lobbies section.

Last updated