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.
Creating and Destroying a Lobby
EOS_Lobby_CreateLobby function creates a lobby. For more properties and full details see EOS_Lobby_CreateLobbyOptions. Initialize
EOS_Lobby_CreateLobbyOptions as follows:
|The user creating the lobby. This user automatically joins the lobby as its owner.|
|The maximum number of users who can be in the lobby at any time|
|Whether or not the lobby is visible to the public (see the Permission Levels section for more information).|
|Bucket ID associated with the lobby.|
|If true, this lobby will be associated with presence information. A user's presence can only be associated with one lobby at a time.|
|Whether members of the lobby allowed to invite others.|
|Whether host migration is allowed / will the lobby stay open if the original host leaves.|
|Creates a real-time communication (RTC) room for all members of this lobby. All members of the lobby will automatically join the RTC room when they connect to the lobby and they will automatically leave the RTC room when they leave or are removed from the lobby. While the joining and leaving of the RTC room is automatic, applications will still need to use the EOS RTC interfaces to handle all other functionality for the room.|
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:
|The user requesting destruction of the lobby; this user must currently own the lobby.|
|The ID of the lobby to destroy.|
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
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.
Joining or Leaving a Lobby
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.
Inviting Users to a Lobby
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.
Rejecting an Invitation
To reject the invitation, call
EOS_Lobby_RejectInvite with an
EOS_Lobby_RejectInviteOptions structure containing the following information:
|The ID of the lobby associated with the invitation|
|The ID of the user who is rejecting the invitation|
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.
Updating All Invitations
To ensure that your local cache contains all pending invitations, call
EOS_Lobby_QueryInvites with an
EOS_Lobby_QueryInvitesOptions structure containing the following data:
|The ID of the user whose invitations you want to retrieve|
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.
Retrieving an Invitation from the Cache
To examine a cached invitation, first call
EOS_Lobby_GetInviteCount with an
EOS_Lobby_GetInviteCountOptions structure, initialized as follows:
|The local user whose invitations you want to count|
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:
|The local user who owns the invitation|
|The index of the invitation you want to retrieve|
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.
Removing a Member from a Lobby
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:
|The ID of the lobby from which the member should be removed.|
|The ID of the lobby member requesting the removal. This must be the lobby owner.|
|The ID of the lobby member to be removed.|
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
Searching for a Lobby
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.
Searching By Lobby ID
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.
Searching By User ID
EOS_LobbySearch_SetTargetUserId takes a known user ID and will return search results representing lobbies for which the target user is a member.
Searching By Attributes
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.
|Comparisons that work on all attribution types|
||Search value is exactly the attribute.|
||Search value is exactly not the attribute.|
|Comparisons that operate on number types|
||Attribute is greater than the search value.|
||Attribute is greater than or equal to the search value.|
||Attribute is less than the search value.|
||Attribute is less than or equal to the search value.|
||Attribute is close to the search value, following the formula abs(attribute - searchvalue) = 0|
|Comparisons that operate on string types|
||The attribute is any in a list of string values separated by semicolons. Example: "This;OrThis;MaybeThis"|
||The attribute is not any in a list of string values. Example: "NotThis;OrThisEither"|
Limiting Search Results
To limit the maximum number of search results that you can retrieve, use the
Getting Information about a Lobby
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_CopyLobbyDetailsHandleis available to users currently connected to the lobby.
EOS_Lobby_CopyLobbyDetailsHandleByInviteIdrequires an invitation to the lobby.
EOS_LobbySearch_CopySearchResultByIndexworks 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:
|Permission Level (macro)||Lobby Behavior|
|This is a public lobby; any user can find or use it at any time as long as it isn't full.|
|This is a friends-only lobby; the lobby does not show up in public searches, and only friends of the owner can join. However, this lobby is not private and can be found if the lobby ID is known.|
|This type of lobby is private, and does not appear searches. Users can only join the lobby through an invitation from a user already inside.|
Modifying the Lobby or User Information
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
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.
Lobby and Lobby Member Properties
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.
|This is the identifying string for the attribute. The system will compare against this string when you search for an attribute.|
|This is the numerical, string, or boolean data associated with |
|This indicates the type of data that |
|This is the attribute advertised or simply stored locally with the session |
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 exceed
The current lobby owner can make changes to the lobby through the following functions:
|Use this to set the lobby's Permission Level.|
|This function changes the maximum number of users who can be in the lobby at the same time. The acceptable range for this value is between the number of users currently in the lobby and |
|This adds a new key-value pair to the lobby data.|
|This removes a key-value pair from the lobby data.|
Any connected user can modify their own data with the following functions:
|Add a new key-value pair to a specific member of the lobby.|
|Remove a key-value pair to a specific member of the lobby.|
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.
Lobby Data Update
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.
User Data Update
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.
Lobby Member Status
The following activities of users in the lobby cause notifications to go out to all other users in the lobby as they occur:
|A new user has joined the lobby; expect a lobby member update shortly afterward.|
|An existing user has left the lobby and their specific data has been removed.|
|An existing user unexpectedly left the lobby.|
|The lobby owner removed a specific user from the lobby.|
|An existing user was promoted either explicitly by the previous owner or implicitly when the lobby owner left the lobby.|
|The lobby has closed either because it was destroyed by the owner, or there was an error.|
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.
Maintaining a Connection
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_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.
Interacting with RTC Functions
To interact with the the
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_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.
Lobby RTC-Replacement Functions
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
|Get the name of the RTC room associated with a specific lobby a local user belongs to.|
|Get the current connection status of the RTC Room for a lobby.|
|Register to receive notifications when the RTC Room for any lobby has a connection status change. The notification callback info includes the RTC Room and local user which the notification refers to.|
|Unregister from receiving notifications when an RTC Room's connection status changes.|
|Allows a host of a lobby to mute or unmute a specific lobby member for the entire room.|
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.
|The ID of the lobby.|
|The user requesting the hard mute; this user must be the lobby owner.|
|The user to be hard (un)muted.|
|The user’s hard mute status (mute on or off).|
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:
|Max players in a lobby||64|
|Max session attributes||100|
|Max member attributes||100|
|String attribute length||1000 characters|
Additionally, there are per-user rate limitations. Consider the following limitations to avoid throttling:
|Connect||30 requests per minute|
|Create a lobby||30 requests per minute|
|Delete a lobby||30 requests per minute|
|Join a lobby||30 requests per minute|
|Amount of lobbies a single user can join at once||16|
|Read lobby data||100 requests per minute|
|Update lobby attributes||100 requests per minute|
|Update member attributes||100 requests per minute|
|Change lobby settings||30 requests per minute|
|Invite a user||30 requests per minute|
|Delete an invitation||30 requests per minute|
|Kick a player out||30 requests per minute|
|Promote a member to lobby owner||30 requests per minute|
|Find lobbies||30 requests per minute|
|Get a lobby by ID||100 requests per minute|
|Find lobbies by user||30 requests per minute|
|Find invitations by user||30 requests per minute|
|Find lobby by invitation||30 requests per minute|
|Max number of search results for a query||256|