Lobby Interface

Use this to add lobbies to your game so players can create, join, leave, and manage lobbies.

18 mins to read

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

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

LocalUserIdThe user creating the lobby. This user automatically joins the lobby as its owner.
MaxLobbyMembersThe maximum number of users who can be in the lobby at any time
PermissionLevelWhether or not the lobby is visible to the public (see the Permission Levels section for more information).
BucketIdBucket ID associated with the lobby.
bPresenceEnabledIf true, this lobby will be associated with presence information. A user's presence can only be associated with one lobby at a time.
bAllowInvitesWhether members of the lobby allowed to invite others.
bDisableHostMigrationWhether host migration is allowed / will the lobby stay open if the original host leaves.
bEnableRTCRoomCreates 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:

LocalUserIdThe user requesting destruction of the lobby; this user must currently own the lobby.
LobbyIdThe 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 EOS_LMS_CLOSED.

Lobby Lifecycle

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

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.

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:

LobbyIdThe ID of the lobby associated with the invitation
LocalUserIdThe 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:

LocalUserIdThe 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:

LocalUserIdThe 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:

LocalUserIdThe local user who owns the invitation
IndexThe 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:

LobbyIdThe ID of the lobby from which the member should be removed.
LocalUserIdThe ID of the lobby member requesting the removal. This must be the lobby owner.
EOS_ProductUserId TargetUserIdThe 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 EOS_LMSC_KICKED event.

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.

Comparison Operators

Operator Description
Comparisons that work on all attribution types
EOS_CO_EQUAL Search value is exactly the attribute.
EOS_CO_NOTEQUAL Search value is exactly not the attribute.
Comparisons that operate on number types
EOS_CO_GREATERTHAN Attribute is greater than the search value.
EOS_CO_GREATERTHANOREQUAL Attribute is greater than or equal to the search value.
EOS_CO_LESSTHAN Attribute is less than the search value.
EOS_CO_LESSTHANOREQUAL Attribute is less than or equal to the search value.
EOS_CO_DISTANCE Attribute is close to the search value, following the formula abs(attribute - searchvalue) = 0
Comparisons that operate on string types
EOS_CO_ANYOF The attribute is any in a list of string values separated by semicolons. Example: "This;OrThis;MaybeThis"
EOS_CO_NOTANYOF 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 EOS_LobbySearch_SetMaxResults function.

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_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.

Permission Levels

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
EOS_LPL_PUBLICADVERTISEDThis is a public lobby; any user can find or use it at any time as long as it isn't full.
EOS_LPL_JOINVIAPRESENCEThis 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.
EOS_LPL_INVITEONLYThis 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 EOS_HLobbyModification).

Changing Ownership

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.

KeyThis is the identifying string for the attribute. The system will compare against this string when you search for an attribute.
ValueThis is the numerical, string, or boolean data associated with Key.
ValueTypeThis indicates the type of data that Value contains.
VisibilityThis is the attribute advertised or simply stored locally with the session EOS_ELobbyAttributeVisibility.

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:

EOS_LobbyModification_SetPermissionLevelUse this to set the lobby's Permission Level.
EOS_LobbyModification_SetMaxMembersThis 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 EOS_LOBBY_MAX_LOBBY_MEMBERS.
EOS_LobbyModification_AddAttributeThis adds a new key-value pair to the lobby data.
EOS_LobbyModification_RemoveAttributeThis removes a key-value pair from the lobby data.

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

EOS_LobbyModification_AddMemberAttributeAdd a new key-value pair to a specific member of the lobby.
EOS_LobbyModification_RemoveMemberAttributeRemove 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.

Event Notifications

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:

Event typeMeaning
EOS_LMS_JOINEDA new user has joined the lobby; expect a lobby member update shortly afterward.
EOS_LMS_LEFTAn existing user has left the lobby and their specific data has been removed.
EOS_LMS_DISCONNECTEDAn existing user unexpectedly left the lobby.
EOS_LMS_KICKEDThe lobby owner removed a specific user from the lobby.
EOS_LSM_PROMOTEDAn existing user was promoted either explicitly by the previous owner or implicitly when the lobby owner left the lobby.
EOS_LMS_CLOSEDThe lobby has closed either because it was destroyed by the owner, or there was an error.

Voice Communications

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_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.

Interacting with RTC Functions

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.

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 EOS_RTCAdmin_* function.

EOS_Lobby_GetRTCRoomNameGet the name of the RTC room associated with a specific lobby a local user belongs to.
EOS_Lobby_IsRTCRoomConnectedGet the current connection status of the RTC Room for a lobby.
EOS_Lobby_AddNotifyRTCRoomConnectionChangedRegister 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.
EOS_Lobby_RemoveNotifyRTCRoomConnectionChangedUnregister from receiving notifications when an RTC Room's connection status changes.
EOS_Lobby_HardMuteMemberAllows a host of a lobby to mute or unmute a specific lobby member for the entire room.

Hard Mute

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.

LobbyIdThe ID of the lobby.
LocalUserIdThe user requesting the hard mute; this user must be the lobby owner.
TargetUserIdThe user to be hard (un)muted.
bHardMuteThe 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.

Usage Limitations

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:

FeatureService Limit
Max players in a lobby64
Max session attributes100
Max member attributes100
String attribute length1000 characters

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

FeatureUser Limit
Connect30 requests per minute
Create a lobby30 requests per minute
Delete a lobby30 requests per minute
Join a lobby30 requests per minute
Amount of lobbies a single user can join at once16
Read lobby data100 requests per minute
Update lobby attributes100 requests per minute
Update member attributes100 requests per minute
Change lobby settings30 requests per minute
Invite a user30 requests per minute
Delete an invitation30 requests per minute
Kick a player out30 requests per minute
Promote a member to lobby owner30 requests per minute
Find lobbies30 requests per minute
Get a lobby by ID100 requests per minute
Find lobbies by user30 requests per minute
Find invitations by user30 requests per minute
Find lobby by invitation30 requests per minute
Max number of search results for a query256