Lobby Interface

Lobbies provide a persistent connection between users for the purpose of sharing game and user state with real-time updates. Typically, users can create or join lobbies to form teams, select pre-game options, and wait for additional players to join in before playing together. Using the Lobby Interface, your users can create, join, leave, and manage lobbies.

To access the Lobby Interface, acquire an EOS_HLobby handle through the Platform Interface function, EOS_Platform_GetLobbyInterface. All Lobby Interface functions require this handle as their first parameter. You must ensure that the EOS_HPlatform handle is ticking for appropriate callbacks to trigger when operations complete.

The EOS_Lobby_CreateLobby function creates a lobby. For more properties and full details see EOS_Lobby_CreateLobbyOptions. Initialize EOS_Lobby_CreateLobbyOptions as follows:

When the operation finishes, your EOS_Lobby_OnCreateLobbyCallback run with an EOS_Lobby_CreateLobbyCallbackInfo data structure. If the data structure's ResultCode field indicates success, its LobbyId field contains the new lobby's ID value. You need this ID value to interact with the lobby further.

To destroy the lobby, the lobby's owner must call EOS_Lobby_DestroyLobby with an EOS_Lobby_DestroyLobbyOptions structure initialized with the following information:

Once complete, your EOS_Lobby_OnDestroyLobbyCallback callback function runs with an EOS_Lobby_DestroyLobbyCallbackInfo data structure indicating if the destruction was successful the ID of the lobby. When the lobby closes, it automatically removes all remaining members and triggers a member status update with state EOS_LMS_CLOSED.

The lifecycle of a lobby generally follows this sequence:

• A user creates the lobby. This user automatically joins the lobby and becomes both the first member and the owner.
• The owner sets up the lobby's initial state, and may invite users to join.
• Other users join and leave the lobby. While connected, members update state information about themselves and can invite other users.
• The lobby owner can update data specific to the state of the game.
• The owner can remove members from the lobby or transfer ownership status to another member.
• Users can play multiple rounds of the game without leaving or destroying the lobby. Your game's logic determines the lifetime of a lobby.
• Finally, the owner destroys the lobby.

Calling EOS_Lobby_JoinLobby with a valid EOS_HLobbyDetails handle causes the user to attempt to join the lobby that the handle references. A user can be in multiple lobbies at the same time; joining one lobby does not require the user to leave another. Joining a new lobby does not leave any existing lobbies. Leaving or destroying a lobby must be explicit.

To leave a lobby, call EOS_Lobby_LeaveLobby. If the departing user is the current lobby owner, EOS will select a new owner from the remaining users. All members will receive notification when any user leaves, as well as when ownership changes.

Users who are in a lobby can invite others to join them with the EOS_Lobby_SendInvite function. The EOS_Lobby_OnSendInviteCallback triggers locally once the invitation is successfully sent. The target user receives a notification when the invitation arrives. The game then uses EOS_Lobby_AddNotifyLobbyInviteAccepted to know when the player clicks Accept in the overlay. For more information about the interaction between the Invite button, the social overlay, and lobbies, see Social Overlay Integration: Using Lobbies. For invite functionality with the Epic Games Launcher, be sure to map your deployments to your artifacts as well.

To reject the invitation, call EOS_Lobby_RejectInvite with an EOS_Lobby_RejectInviteOptions structure containing the following information:

Once complete, your EOS_Lobby_OnRejectInviteCallback function triggers locally with an EOS_Lobby_RejectInviteCallbackInfo data structure. If successful, the invitation is permanently deleted from the system.

To ensure that your local cache contains all pending invitations, call EOS_Lobby_QueryInvites with an EOS_Lobby_QueryInvitesOptions structure containing the following data:

When the operation finishes, your EOS_Lobby_OnQueryInvitesCallback runs with an EOS_Lobby_QueryInvitesCallbackInfo data structure. On success, the local cache contains all pending invitations for the specified user that you can search. This is useful at startup to discover any invitations that were sent while the user was offline. During play, users with a registered notification should rarely need to call this function.

To examine a cached invitation, first call EOS_Lobby_GetInviteCount with an EOS_Lobby_GetInviteCountOptions structure, initialized as follows:

This function runs against your local cache, and will immediately return a uint32_t indicating the number of pending invitations in the cache. You can then call EOS_Lobby_GetInviteIdByIndex with an EOS_Lobby_GetInviteIdByIndexOptions structure containing the following data:

EOS_Lobby_GetInviteIdByIndex also runs against the local cache and will immediately return EOS_Success if the call succeeds. On success, the output parameters that you provided will contain a copy of the invitation data and its size. You are responsible for freeing the buffer when you no longer need it.

Users receive invitations in real time as long as they have registered a callback through EOS_Lobby_AddNotifyLobbyInviteReceived. The callback data includes all of the relevant information about the invitation. At this point, users can use EOS_Lobby_CopyLobbyDetailsHandleByInviteId to retrieve the invitation in the form of an EOS_HLobbyDetails, which the user must have to join the lobby. When shutting down the application or going offline, use EOS_Lobby_RemoveNotifyLobbyInviteReceived to remove your callback from the notification list.

The lobby owner may remove a lobby member at any time. To do this, call EOS_Lobby_KickMember with an EOS_Lobby_KickMemberOptions data structure initialized as follows:

When the operation finishes, you will receive a call to your EOS_Lobby_OnKickMemberCallback function, with an EOS_Lobby_KickMemberCallbackInfo data structure. In addition, all remaining lobby members will receive notification of the EOS_LMSC_KICKED event.

EOS_Lobby_CreateLobbySearch creates a handle (type EOS_HLobbySearch) that you can use to search for lobbies that are set up to be discoverable (see "Permission Levels" for more information). Use the functions below to configure this handle, then call EOS_LobbySearch_Find to execute it. On successful completion, the application can navigate through the search results. Multiple search operations can run simultaneously with different handles.

After a search completes, use EOS_LobbySearch_GetSearchResultCount to get the number of results for a given EOS_HLobbySearch handle. You can then request copies of individual results with EOS_LobbySearch_CopySearchResultByIndex. When you are finished with your copy of the data, dispose of it with EOS_LobbyDetails_Release to reclaim the memory it was using.

If a user has the exact lobby ID, they can search directly for it with EOS_LobbySearch_SetLobbyId. Sharing the lobby ID with other users is outside the scope of the API.

EOS_LobbySearch_SetTargetUserId takes a known user ID and will return search results representing lobbies for which the target user is a member.

The most robust way to find lobbies is to search for a desired subset of settings. This could be in response to the user choosing a collection of filters in a user interface, it could be done automatically behind the scenes based on the user's skill and other factors, or it could be a combination of both methods.

EOS_LobbySearch_SetParameter allows for the user to set up EOS_Lobby_AttributeData and provide an EOS_EComparisonOp that dictates how the attribute is compared against all existing lobbies stored with the service. One or more of these calls will set the search parameters with an implicit boolean AND between them.

To limit the maximum number of search results that you can retrieve, use the EOS_LobbySearch_SetMaxResults function.

To learn about a lobby, users can request an EOS_HLobbyDetails handle. There are three functions that provide this information, based on the local user's connection to the lobby:

• EOS_Lobby_CopyLobbyDetailsHandle is available to users currently connected to the lobby.
• EOS_Lobby_CopyLobbyDetailsHandleByInviteId requires an invitation to the lobby.
• EOS_LobbySearch_CopySearchResultByIndex works with lobbies that a local user found in a search.

After successfully completing any of the the preceding operations, you will receive an EOS_HLobbyDetails handle, which gives access to the following information:

• Lobby ID: The unique identifier for the lobby
• Lobby Owner: The current owner of the lobby
• Lobby Members: The current members of the lobby
• Permission level: Restrictions on who can find or join the lobby; see "Permission Levels" below
• Space Available: The number of open slots currently available
• Max Members: The maximum number of users who can be in the lobby at any time
• Member Count: The current number of members in the lobby
• Lobby Attributes: Key-value pairs associated with the lobby
• Lobby Member Attributes: Key-value pairs associated with each individual user
• Lobby Member Platform: The hardware platform for an individual user as identified by the server. Note that this value is only provided for lobby members on console platforms; otherwise it returns a placeholder value. This placeholder value indicates it is not possible to reliably identify the hardware platform for the given user.

To find the ID of the lobby's owner, call EOS_LobbyDetails_GetLobbyOwner. To find the IDs of the lobby's members, first call EOS_LobbyDetails_GetMemberCount to retrieve the current member count, then iterate over the current member count and call EOS_LobbyDetails_GetMemberByIndex. Details about the lobby, in the form of an EOS_LobbyDetails_Info data structure, are available through the EOS_LobbyDetails_CopyInfo function. The EOS_LobbyDetails_Info that you receive will be a copy of the EOS SDK's cached information. You own this data and must release it with EOS_LobbyDetails_Info_Release function to avoid leaking memory. The data is a snapshot and will not update if any information about the lobby changes after you receive it.

A lobby's Permission Level controls the conditions that users can discover and join the lobby. The owner can change these at any time by calling EOS_LobbyModification_SetPermissionLevel. The following settings are available:

A lobby owner can modify a lobby or a member can change their user information by calling EOS_Lobby_UpdateLobbyModification to acquire a lobby modification handle (type EOS_HLobbyModification).

The owner may promote another member of the lobby to owner status by calling EOS_Lobby_PromoteMember. A lobby can only have one owner, so the caller loses owner status in the process. All members will receive notification of this event.

The lobby and each member can have application-specific, key-value attributes, supported by the EOS_Lobby_Attribute data type. These attributes must be represented as numerical, string, or boolean data. The EOS_Lobby_Attribute data structure contains this information.

Lobby and lobby member attributes have public and private visibilities. In public visibility, data is visible to all members outside of the lobby for lobby attributes, and data is visible inside the lobby for lobby member attributes. Conversely, for private visibility, data is visible inside the lobby for lobby attributes, and data is visible to the member only for lobby member attributes.

A single user within a lobby, or the lobby itself, can have at most EOS_LOBBYMODIFICATION_MAX_ATTRIBUTES attributes. Attribute names (in the Key) field must not exceedEOS_LOBBYMODIFICATION_MAX_ATTRIBUTE_LENGTH characters.

The current lobby owner can make changes to the lobby through the following functions:

Any connected user can modify their own data with the following functions:

After making all desired attribute modifications, you must commit those changes to the lobby for them to take effect. Do so by calling EOS_Lobby_UpdateLobby. When the operation finishes, the modifications will have been made and other lobby members will receive notification. You also receive a call to your callback function.

Users have a persistent connection to the lobby and are notified of events that happen during a lobby's lifetime. Registering for a notification can be done at startup since enough information is provided with each callback to fully describe the lobby affected.

Any time the lobby owner makes a change to the properties of the lobby, all lobby members receive a notification. The notification simply states that something has changed. The game should evaluate all the available data in the lobby and reapply it to the game.

Any time a lobby member makes a change to the properties of their own data, all lobby members receive a notification. The notification simply states that something has changed. The game should evaluate all the available data for the lobby member and reapply it to the game.

The following activities of users in the lobby cause notifications to go out to all other users in the lobby as they occur:

You can host EOS Voice chat rooms on Epic servers using EOS Lobbies, or on your own backend servers. Users can communicate one-on-one or in groups across multiple platforms, during a match, or in your product’s lobby. See Voice with Lobbies and Voice Interface for more information.

Applications that use the EOS Lobbies RTC rooms features do not need to manually join or leave voice rooms, this is automatically handled internally by the Lobby system. If the lobby is successfully created with an RTC Room enabled, the lobby system will automatically join and maintain the connection to the RTC room as long as the local user remains in the lobby.

Applications may use the optional EOS_Lobby_IsRTCRoomConnected, EOS_Lobby_AddNotifyRTCRoomConnectionChanged, and EOS_Lobby_RemoveNotifyRTCRoomConnectionChanged functions for informational purposes if desired. An appropriate example would be showing a disconnected icon when disconnected from Lobby RTC services while in a multiplayer lobby.

To interact with the the EOS_RTC_* or EOS_RTCAudio_* suites of functions, applications must first use the EOS_Lobby_GetRTCRoomName function to get the room name associated with their lobby. The earliest that EOS_Lobby_GetRTCRoomName can be called successfully is inside of the EOS_Lobby_OnJoinLobbyCallback or EOS_Lobby_OnCreateLobbyCallback, when the Result parameter is EOS_Success. It is also at this time an application should register for all RTC notifications specific to the Lobby’s RTC room, to avoid missing any notifications, such as existing members of the room, that can happen very shortly after these notifications.

Example uses of the RTC Room Name:

• When registering for notifications, such as talking status, or room membership
• When muting or unmuting the local user's audio output for the room
• When blocking or unblocking room participants
• When setting local audio device settings.

The following functions are used to replace EOS_RTC_* functions that would normally be used, but are incompatible Lobbies, either due to the feature being handled internally, the data no longer being application-provided, or the functionality being an EOS_RTCAdmin_* function.

As a lobby owner you can hard-mute an existing lobby member by calling EOS_Lobby_HardMuteMember with an EOS_Lobby_HardMuteMemberOptions data structure. This structure holds information if the given member should be muted or not. Hard-muting changes the audibility of a lobby member for everyone, regardless of their local mute status.

When the operation finishes, your EOS_Lobby_OnHardMuteMemberCallback runs with an EOS_Lobby_HardMuteMemberCallbackInfo data structure. If the data structure's ResultCode field indicates success, its LobbyId field contains the lobby's ID value and TargetUserId contains the member whose hard mute status has been updated.

Lobbies provide a persistent connection between your users, for the purpose of sharing game and user state with real-time updates. Typically, users can create or join lobbies to chat with other users, form teams, select pre-game options, and wait for additional users to join in before playing together. For general information about throttling, usage quotas, and best practices, see Service Usage Limitations.

The following are general limitations for the lobby service:

Additionally, there are per-user rate limitations. Consider the following limitations to avoid throttling: