Interface ILobbyService

Service for Lobbies. Provides user the ability to create, delete, update, and query Lobbies. Includes operations for interacting with given players in a Lobby context.

Namespace: Unity.Services.Lobbies

Assembly: Unity.Services.Multiplayer.dll

Syntax

public interface ILobbyService

Properties

ConcurrencyControlEnabled

Applies concurrency control by adding an If-match header with the latest version of the lobby to applicable lobby operations. When enabled, operations are only allowed if the latest version matches the current version on the server. Applies to the following operations:

• deleting a lobby
• removing a player from a lobby
• updating a lobby player
• updating a lobby information

Declaration

bool ConcurrencyControlEnabled { get; set; }

Property Value

Type	Description
bool

Methods

CreateLobbyAsync(string, int, CreateLobbyOptions)

Create a Lobby with a given name and specified player limit. Async operation.

Declaration

Task<Lobby> CreateLobbyAsync(string lobbyName, int maxPlayers, CreateLobbyOptions options = null)

Parameters

Type	Name	Description
string	lobbyName	Name of new lobby.
int	maxPlayers	Player limit.
CreateLobbyOptions	options	Optional request parameters.

Returns

Type	Description
Task<Lobby>	Lobby data for the lobby that was just created.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyName is null or only contains whitespaces.
InvalidOperationException	Thrown when maxPlayers is less than one.
LobbyServiceException	Thrown when the lobby service returns an error.

CreateOrJoinLobbyAsync(string, string, int, CreateLobbyOptions)

Create or join a Lobby with a given name and ID and specified player limit. Async operation.

Declaration

Task<Lobby> CreateOrJoinLobbyAsync(string lobbyId, string lobbyName, int maxPlayers, CreateLobbyOptions options = null)

Parameters

Type	Name	Description
string	lobbyId	ID of the lobby to create/join.
string	lobbyName	Name of the lobby to create/join.
int	maxPlayers	Player limit.
CreateLobbyOptions	options	Optional request parameters.

Returns

Type	Description
Task<Lobby>	Lobby data for the lobby that was just created/joined.

Exceptions

Type	Condition
ArgumentNullException	Throw when lobbyId or lobbyName is empty or only contains whitespaces.
InvalidOperationException	Thrown when maxPlayers is less than one.
LobbyServiceException	Thrown when the lobby service returns an error.

DeleteLobbyAsync(string)

Delete a Lobby by specifying a Lobby ID. Async operation.

Declaration

Task DeleteLobbyAsync(string lobbyId)

Parameters

Type	Name	Description
string	lobbyId	ID of the Lobby to delete.

Returns

Type	Description
Task	Awaitable task.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyId is null or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

DownloadMigrationDataAsync(MigrationDataInfo, LobbyDownloadMigrationDataOptions)

Download lobby migration data.

Declaration

Task<LobbyMigrationData> DownloadMigrationDataAsync(MigrationDataInfo migrationDataInfo, LobbyDownloadMigrationDataOptions options)

Parameters

Type	Name	Description
MigrationDataInfo	migrationDataInfo	Is the lobby migration data information.
LobbyDownloadMigrationDataOptions	options	Is the migration Data download request Parameters.

Returns

Type	Description
Task<LobbyMigrationData>	Task for MigrationData. Data is null if not present.

Remarks

This task is not cancellable. Timeout can be configured in DownloadMigrationDataOptions.

Exceptions

Type	Condition
ArgumentNullException	Thrown when migrationDataInfo is null or does not contain a valid Read url.
LobbyServiceException	Thrown when the lobby service returns an error. MigrationDataRequestTimeout in case of request timeout.

GetJoinedLobbiesAsync()

Async Operation. Get currently joined lobbies.

Declaration

Task<List<string>> GetJoinedLobbiesAsync()

Returns

Type	Description
Task<List<string>>	List of lobbies the active player has joined.

Exceptions

Type	Condition
LobbyServiceException	Thrown when the lobby service returns an error.

GetLobbyAsync(string)

Retrieve data for a Lobby by specifying a Lobby ID. Async operation.

Declaration

Task<Lobby> GetLobbyAsync(string lobbyId)

Parameters

Type	Name	Description
string	lobbyId	ID of the Lobby to retrieve.

Returns

Type	Description
Task<Lobby>	Lobby data.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyId is null or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

See Also

https://services.docs.unity.com/lobby/v1/#tag/Lobby/operation/getLobby

GetLobbyAsync(string, string)

Retrieve data for a Lobby by specifying a Lobby ID. Async operation.

Declaration

Task<Lobby> GetLobbyAsync(string lobbyId, string ifNoneMatchVersion)

Parameters

Type	Name	Description
string	lobbyId	ID of the Lobby to retrieve.
string	ifNoneMatchVersion	If provided, the version will be submitted in the If-None-Match header.

Returns

Type	Description
Task<Lobby>	Lobby data.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyId is null or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

See Also

https://services.docs.unity.com/lobby/v1/#tag/Lobby/operation/getLobby

GetMigrationDataInfoAsync(string)

Get lobby migration data information.

Declaration

Task<MigrationDataInfo> GetMigrationDataInfoAsync(string lobbyId)

Parameters

Type	Name	Description
string	lobbyId	The ID of the lobby to get migration data information.

Returns

Type	Description
Task<MigrationDataInfo>	The migration data information for the lobby.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyId is null or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

JoinLobbyByCodeAsync(string, JoinLobbyByCodeOptions)

Join a Lobby using a given Lobby Invite Code. Async operation.

Declaration

Task<Lobby> JoinLobbyByCodeAsync(string lobbyCode, JoinLobbyByCodeOptions options = null)

Parameters

Type	Name	Description
string	lobbyCode	Invite Code for target lobby.
JoinLobbyByCodeOptions	options	Optional request parameters.

Returns

Type	Description
Task<Lobby>	Lobby data for the lobby joined.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyCode is null or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

JoinLobbyByIdAsync(string, JoinLobbyByIdOptions)

Join a Lobby by specifying the Lobby ID. Async operation.

Declaration

Task<Lobby> JoinLobbyByIdAsync(string lobbyId, JoinLobbyByIdOptions options = null)

Parameters

Type	Name	Description
string	lobbyId	ID of the Lobby to join.
JoinLobbyByIdOptions	options	Optional request parameters.

Returns

Type	Description
Task<Lobby>	Lobby data for the lobby joined.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyId is null or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

QueryLobbiesAsync(QueryLobbiesOptions)

Query and retrieve a list of lobbies that meet specified query parameters. Async operation.

Declaration

Task<QueryResponse> QueryLobbiesAsync(QueryLobbiesOptions options = null)

Parameters

Type	Name	Description
QueryLobbiesOptions	options	Query parameters.

Returns

Type	Description
Task<QueryResponse>	Query response that includes list of Lobbies meeting specified parameters.

Exceptions

Type	Condition
LobbyServiceException	Thrown when the lobby service returns an error.

QuickJoinLobbyAsync(QuickJoinLobbyOptions)

Query available lobbies and join a randomly selected instance. Async operation.

Declaration

Task<Lobby> QuickJoinLobbyAsync(QuickJoinLobbyOptions options = null)

Parameters

Type	Name	Description
QuickJoinLobbyOptions	options	Optional parameters (includes queryable arguments).

Returns

Type	Description
Task<Lobby>	Lobby data for the lobby joined.

Exceptions

Type	Condition
LobbyServiceException	Thrown when the lobby service returns an error.

ReconnectToLobbyAsync(string)

Reconnects to the lobby.

Declaration

Task<Lobby> ReconnectToLobbyAsync(string lobbyId)

Parameters

Type	Name	Description
string	lobbyId	The ID of the lobby to reconnect to.

Returns

Type	Description
Task<Lobby>	The lobby you reconnected to.

RemovePlayerAsync(string, string)

Remove a player from a specified Lobby. Async operation.

Declaration

Task RemovePlayerAsync(string lobbyId, string playerId)

Parameters

Type	Name	Description
string	lobbyId	Target Lobby ID to remove player from.
string	playerId	Player ID to remove.

Returns

Type	Description
Task	Awaitable task.

Exceptions

Type	Condition
ArgumentNullException	Throw when lobbyId or playerId is empty or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

SendHeartbeatPingAsync(string)

Send a heartbeat ping to keep the Lobby active. Async operation.

Declaration

Task SendHeartbeatPingAsync(string lobbyId)

Parameters

Type	Name	Description
string	lobbyId	ID of the Lobby to ping.

Returns

Type	Description
Task	Awaitable task.

Exceptions

Type	Condition
ArgumentNullException	Thrown when lobbyId is null or only contains whitespaces.
LobbyServiceException	Thrown when the lobby service returns an error.

SubscribeToLobbyEventsAsync(string, LobbyEventCallbacks)

A subscription to the given lobby is created and the given callbacks are associated with it. The return ILobbyEvents interface can be used to unsubscribe and re-subscribe to the connection. The callbacks object provided will be used to provide the notifications from the subscription.

Declaration

Task<ILobbyEvents> SubscribeToLobbyEventsAsync(string lobbyId, LobbyEventCallbacks callbacks)

Parameters

Type	Name	Description
string	lobbyId	The ID of the lobby you are subscribing to events for.
LobbyEventCallbacks	callbacks	The callbacks you provide, which will be called as notifications arrive from the subscription.

Returns

Type	Description
Task<ILobbyEvents>	An interface to change the callbacks associated with the subscription, or to unsubscribe and re-subscribe to the lobby's events.

UpdateLobbyAsync(string, UpdateLobbyOptions)

Update the specified Lobby with the given option parameters. Async operation.

Declaration

Task<Lobby> UpdateLobbyAsync(string lobbyId, UpdateLobbyOptions options)

Parameters

Type	Name	Description
string	lobbyId	Lobby ID to update.
UpdateLobbyOptions	options	Parameters to update.

Returns

Type	Description
Task<Lobby>	Lobby data of the updated Lobby.

Exceptions

Type	Condition
ArgumentNullException	Throw when lobbyId is null or only contains whitespaces or when options is null.
LobbyServiceException	Thrown when the lobby service returns an error.

UpdatePlayerAsync(string, string, UpdatePlayerOptions)

Update player lobby associated data with the given option parameters. Async operation.

Declaration

Task<Lobby> UpdatePlayerAsync(string lobbyId, string playerId, UpdatePlayerOptions options)

Parameters

Type	Name	Description
string	lobbyId	Lobby ID to update.
string	playerId	Player ID to update.
UpdatePlayerOptions	options	Parameters to update.

Returns

Type	Description
Task<Lobby>	Lobby data of the updated Lobby

Remarks

For the modern, streamlined workflow see here.

Exceptions

Type	Condition
ArgumentNullException	Throw when lobbyId or playerId is null or only contains whitespaces or when options is null.
LobbyServiceException	Thrown when the lobby service returns an error.

UploadMigrationDataAsync(MigrationDataInfo, byte[], LobbyUploadMigrationDataOptions)

Upload lobby migration data.

Declaration

Task<LobbyUploadMigrationDataResults> UploadMigrationDataAsync(MigrationDataInfo migrationDataInfo, byte[] data, LobbyUploadMigrationDataOptions options)

Parameters

Type	Name	Description
MigrationDataInfo	migrationDataInfo	Is the lobby migration data information.
byte[]	data	Is the binary migration data.
LobbyUploadMigrationDataOptions	options	Is the migration data download request Parameters.

Returns

Type	Description
Task<LobbyUploadMigrationDataResults>	Task for LobbyUploadMigrationDataResults.

Remarks

This task is not cancellable. Timeout can be configured in DownloadMigrationDataOptions.

Exceptions

Type	Condition
ArgumentNullException	Thrown when migrationDataInfo is null or does not contain a valid Write url or when data is null or empty.
LobbyServiceException	Thrown when the lobby service returns an error.The LobbyExceptionReason property reflects the error. MigrationDataRequestTimeout in case of request timeout.