Lobbies API

Requirements

In order to be able to use the Lobbies feature, you must enable Persisted Player Accounts in the Game Services section of your Project dashboard settings.

Since Lobbies use Rooms under the hood for the Game Session, you must also have at least one region enabled in the Rooms section of your dashboard.

Simulators cannot currently use lobbies because a valid player account is required.

Lobbies Service API

Accessible from CoherenceBridge.CloudService.CloudRooms, the Lobbies Service API has access to every endpoint you need to interface with the Lobbies feature.

Lobby and Player Attributes

Attributes are one of the main avenues available for customizing the Lobbies logic and fitting it to the needs of your game project.

Every Player in the Lobby and the Lobby itself can have custom Attributes associated to them.

An Attribute is defined by:

• Key: Identifier for the Attribute.

• Value: Value of the Attribute, can be either an integer number or a string.

• Index: A predetermined value that will allow the Attribute to be used in Filter Expressions.

• Aggregate: This only applies to the lobby indexes and can be: “sum”, “avg”, “min”, “max” or “owner” for the integer indexes or “owner” for the string indexes. When a player joins/leaves the lobby their indexes are aggregated into the lobby indexes.

• Public: Public Attributes will be returned and visible to all Players.

Player or Lobby Attributes cannot be deleted, you can only add new ones or update existing ones.

If you wish to stop using an Attribute, we recommend setting a default value that you can interpret as such, like an empty string for a string Attribute, or a zero value for an integer Attribute.

Indexes and Aggregators

Indexed Attributes are aggregated from the Player Attributes into a Lobby Attribute.

For example, let's say every Player in my Lobby has a Matchmaking integer rating value Attribute associated to him, and we index this Attribute to n1.

We want Players to be able to do Matchmaking with Lobbies using the average Matchmaking rating of all the players present in the Lobby. The Lobby will have a "Matchmaking rating average" integer Attribute associated with it, that is also indexed to n1, with an aggregator of type "avg" to do the average of every Player present in the Lobby.

Every time a Player joins or leaves the Lobby, the Lobby Attribute indexed to n1 will be updated accordingly.

When you're entering the Matchmaking phase, you can use a Lobby Filter Expression to search for specific Lobbies that match the current rating of the Player that is initiating the Matchmaking phase.

Matchmaking

In order to start the Matchmaking process, you can use the FindOrCreateLobby method. Based on the given parameters to find a Lobby, the response of this method will be either an existing Lobby or a fresh new Lobby where your player will be the owner.

The bread and butter of the Matchmaking logic can be done through our powerful filter expression building system. The FindOrCreateLobby method accepts up to three different filters.

Lobby Filter Expressions

This is similar to the WHERE clause in an SQL-like expression. You can build filter expressions using Lobby Attribute indexes and most of the Lobby properties.

The player can use up to three filter expressions to filter out Lobbies. The expressions are tried in order until one of them succeeds. This can be used to increasingly expand the search criteria and can be very efficient if the amount of players is low.

Currently, these are the properties that you can use to customize your Matchmaking process:

• Room Regions

• Tags

• Max Players

• Number of Players

• Available Slots

• Simulator Slug

• Is Private Lobby

• Integer Attribute Index

• String Attribute Index

For example:

• “region in [‘us’, ‘eu’] and (s1 = ‘map1’ or s1 = ‘map2’)”

In Unity, you will build this filter expression using the builder pattern, if we wanted to match using the expression from the example, we would do it like this:

using Coherence.Cloud;
using Coherence.Toolkit;
using UnityEngine;
using Coherence.Cloud.Coroutines;
using System.Collections;
using System.Collections.Generic;

public class ExampleClass : MonoBehaviour
{
    public CoherenceBridge bridge;

    void Start()
    {
        CoherenceBridgeStore.TryGetBridge(gameObject.scene, out bridge);
        StartCoroutine(MatchmakingRoutine());
    }

    private IEnumerator MatchmakingRoutine()
    {
        CloudService cloudService = bridge.CloudService;

            yield return cloudService.WaitForCloudServiceLoginRoutine();

        var regionsYield = cloudService.Rooms.WaitForFetchRegions();

        yield return regionsYield;

        IReadOnlyList<string> regions = regionsYield.RequestResponse.Result;

        // Build filter for regions and either map1 or map2
        LobbyFilter lobbyFilter = new LobbyFilter()
            .WithAnd()
            .WithRegion(FilterOperator.Any, new List<string>(regions))
            .WithOr()
            .WithStringAttribute(FilterOperator.Equals, StringAttributeIndex.s1, "map1")
            .WithStringAttribute(FilterOperator.Equals, StringAttributeIndex.s1, "map2")
            .End();

        // You can use the ToString method to debug what your filters look like
        // This outputs: “region in [‘us’, ‘eu’] and (s1 = ‘map1’ or s1 = ‘map2’)”
        Debug.Log($"{lobbyFilter.ToString()}");

        FindLobbyOptions findOptions = new FindLobbyOptions()
        {
            Limit = 20,
            LobbyFilters = new List<LobbyFilter>() { lobbyFilter }
        };

        // If we don't find a suitable Lobby, we will create one with Lobby Attribute map1 and the first available region
        CloudAttribute mapAttribute = new CloudAttribute("map", "map1", StringAttributeIndex.s1, StringAggregator.None, true);

        var createOptions = new CreateLobbyOptions()
        {
            LobbyAttributes = new List<CloudAttribute>() { mapAttribute },
            Region = regions[0]
        };
        
        // We start the Matchmaking process with the coherence Cloud
        cloudService.Rooms.LobbyService.FindOrCreateLobby(findOptions, createOptions, OnRequestFinished);
    }

    private void OnRequestFinished(RequestResponse<LobbySession> requestResponse)
    {
        if (requestResponse.Status == RequestStatus.Success)
        {
            // On successful request, we fetch the LobbySession instance from the response result
            LobbySession myLobby = requestResponse.Result;
        }
    }
}

Lobby Session

When you successfully join a Lobby, an instance of type LobbySession will be returned via the Lobbies API.

You can use this LobbySession instance to interface with the Lobby itself, you will find methods to leave the Lobby, update your Player Attributes or send a message to other Players. You will also be able to query all the information about the Lobby itself, like every Player present, their Attributes, maximum Players and other Lobby properties.

Additionally, if you're the owner of the Lobby, you will have an instance of type LobbyOwnerActions available to you (for non-owners this instance will be null referenced). As an owner of the Lobby, you will be able to kick other Players, update the Attributes of the Lobby, or start the Game Session.

LobbySession instance will have a number of callbacks you can subscribe to that will inform you of any updates that happen to the Lobby, like a Player joining or leaving, or Attributes being updated.

If a Room associated with a Lobby is closed, Players will also receive a callback.

Game Session

When the owner of the Lobby starts the Game Session, every Player will receive a callback with the Room endpoint data that can be used to connect to the Replication Server using the associated CoherenceBridge instance.

If you need to perform custom logic before actually joining the Room, you can subscribe a custom listener through the LobbiesService instance in CoherenceBridge.CloudService.Rooms.LobbyService.OnPlaySessionStarted. If no custom listener is registered, coherence will automatically connect to the Replication Server.

Handling Lobbies when logging in

If the player has closed the game abruptly without leaving the Lobby, when the game is restarted and the Player authenticates with the coherence Cloud, in the Login response you will receive the ID of the Lobbies that the Player is currently a part of. You can use these Lobby IDs to fetch again the LobbySession instance from the Lobbies Service API.

Additionally, the Lobby might have a current Game Session active, so you can use the Room data that is available to reconnect to the Replication Server Room.

Here is an example of how to handle this scenario:

using Coherence.Cloud;
using Coherence.Toolkit;
using UnityEngine;
using Coherence.Runtime;

public class LobbyLoginExample : MonoBehaviour
{
    public CoherenceBridge bridge;

    void Start()
    {
        CoherenceBridgeStore.TryGetBridge(gameObject.scene, out bridge);

        IAuthClient authClient = bridge.CloudService.GameServices.AuthService;

        // We subscribe to the On Login callback from the Authentication Service
        authClient.OnLogin += AuthClientOnLogin;
    }

    private async void AuthClientOnLogin(LoginResponse loginResponse)
    {
        // We check the Lobby Ids returned by the Login Response object
        if (loginResponse.LobbyIds == null || loginResponse.LobbyIds.Count == 0)
        {
            return;
        }

        // We fetch a LobbySession instance from the Lobby Service API
        LobbySession lobbySession = await bridge.CloudService.Rooms.LobbyService.GetActiveLobbySessionForLobbyId(loginResponse.LobbyIds[0]);

        if (lobbySession == null)
        {
            return;
        }

        // Found LobbySession, we check if there is a GameSession active by querying the RoomData attached to LobbyData
        var hasRoomSession = lobbySession.LobbyData.RoomData.HasValue;

        if (hasRoomSession)
        {
            // The Lobby has an ongoing Game Session so we reconnect to the Room using the CoherenceBridge
            bridge.JoinRoom(lobbySession.LobbyData.RoomData.Value);
        }
        else
        {
            // The Lobby doesn't have an ongoing Game Session, here we can update our UI accordingly
        }
    }
}