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 |
| InvalidOperationException | Thrown when |
| 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 |
| InvalidOperationException | Thrown when |
| 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 |
| 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 |
| 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 |
| LobbyServiceException | Thrown when the lobby service returns an error. |
See Also
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 |
| LobbyServiceException | Thrown when the lobby service returns an error. |
See Also
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| LobbyServiceException | Thrown when the lobby service returns an error.The LobbyExceptionReason property reflects the error. MigrationDataRequestTimeout in case of request timeout. |