Lobby Interface

Interface to handle lobbies

Lobbies provide a persistent connection between users, hosted by Epic Online Services (EOS), 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 players to join in before playing together. The EOS SDK supports this feature with the Lobby Interface. 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. Initialize the function's EOS_Lobby_CreateLobbyOptions as follows:

Property

Value

ApiVersion

EOS_LOBBY_CREATELOBBY_API_LATEST

LocalUserId

The user who is creating the lobby. This user will automatically join the lobby as its owner.

MaxLobbyMembers

The maximum number of users who can be in the lobby at any time

Visibility

Whether or not the lobby is visible to the public (see the Permission Levels section below).

When the operation finishes, your EOS_Lobby_OnCreateLobbyCallback will 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, which you will need 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:

Property

Value

ApiVersion

EOS_LOBBY_DESTROYLOBBY_API_LATEST

LocalUserId

The user requesting destruction of the lobby; this user must currently own the lobby.

LobbyId

The ID of the lobby to destroy.

Upon completion, your EOS_Lobby_OnDestroyLobbyCallback callback function will run with an EOS_Lobby_DestroyLobbyCallbackInfo data structure that indicates whether or not destruction was successful, and contains the ID of the lobby. When the lobby closes, it automatically removes all remaining members and triggers a member status update with state EOS_LMSC_LOBBYCLOSED.

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 owner can remove members from the lobby or transfer ownership status to another member.

  • Users can play sessions of the game without leaving or destroying the 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.

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. A callback of type EOS_Lobby_OnSendInviteCallback will trigger locally once the invitation is successfully sent. The target user will receive a notification when the invitation arrives.

Rejecting an Invitation

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

Property

Value

ApiVersion

EOS_LOBBY_REJECTINVITE_API_LATEST

LobbyId

The ID of the lobby associated with the invitation

LocalUserId

The ID of the user who is rejecting the invitation

Upon completion, your EOS_Lobby_OnRejectInviteCallback function will trigger locally with an EOS_Lobby_RejectInviteCallbackInfo data structure. If successful, the invitation will be permanently deleted from the system.

Updating All Invitations

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

Property

Value

ApiVersion

EOS_LOBBY_QUERYINVITES_API_LATEST

LocalUserId

The ID of the user whose invitations you want to retrieve

When the operation finishes, your callback, of type EOS_Lobby_OnQueryInvitesCallback, will run with an EOS_Lobby_QueryInvitesCallbackInfo data structure. On success, the local cache will contain all pending invitations for the specified user, which you can search. This is useful at startup to discover any invitations that were sent while the user was offline. During play, with a registered notification, users 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:

Property

Value

ApiVersion

EOS_LOBBY_GETINVITECOUNT_API_LATEST

LocalUserId

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:

Property

Value

ApiVersion

EOS_LOBBY_GETINVITEIDBYINDEX_API_LATEST

LocalUserId

The local user who owns the invitation

Index

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.

Notifications

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:

Property

Value

ApiVersion

EOS_LOBBY_KICKMEMBER_API_LATEST

LobbyId

The ID of the lobby from which the member should be removed.

LocalUserId

The ID of the lobby member requesting the removal. This must be the lobby owner.

EOS_ProductUserId TargetUserId

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 EOS_LMSC_KICKED event.

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

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

Seaching 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

  • 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

  • Lobby Attributes: Key-value pairs associated with the lobby

  • Lobby Member Attributes: Key-value pairs associated with each individual user

To find the ID of the lobby's owner, call EOS_LobbyDetails_GetLobbyOwner. 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 under which 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_PUBLICADVERTISED

This is a public lobby; any user can find or use it at any time as long as it isn't full.

EOS_LPL_JOINVIAPRESENCE

This is a friends-only lobby; the lobby does not show up in public searches, and only friends of the owner can join.

EOS_LPL_INVITEONLY

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

After joining a lobby, users can modify data about themselves. Additionally, the lobby owner can make modifications to the lobby itself, or choose another user to become the new owner. All of these processes start 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 will lose owner status in the process. All members will receive notification of this event.

Lobby and Lobby Member Properties

The lobby and the users joined to it can have application-specific key-value attributes, supported by the EOS_Lobby_Attribute data type. as long as these attributes can be represented as numerical, string, or boolean data. The EOS_Lobby_Attribute data structure contains this information.

Field

Contents

Key

This is the identifying string for the attribute. The system will compare against this string when you search for an attribute.

Value

This is the numerical, string, or boolean data associated with Key.

ValueType

This indicates the type of data that Value contains.

Visibility

This 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 exceed`EOS_LOBBYMODIFICATION_MAX_ATTRIBUTE_LENGTH` characters.

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

Function

Effect

EOS_LobbyModification_SetPermissionLevel

Use this to set the lobby's Permission Level.

EOS_LobbyModification_SetMaxMembers

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

EOS_LobbyModification_AddAttribute

This adds a new key-value pair to the lobby data.

EOS_LobbyModification_RemoveAttribute

This removes a key-value pair from the lobby data.

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

Function

Effect

EOS_LobbyModification_AddMemberAttribute

Add a new key-value pair to a specific member of the lobby.

EOS_LobbyModification_RemoveMemberAttribute

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 will also receive a call to your callback function.

Event Notifications

Users have a persistent connection to the lobby and will be notified of events that happen during a lobby's lifetime. Registering for a notification can be done at startup as 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 will 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 will 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 type

Meaning

EOS_LMSC_JOINED

A new user has joined the lobby; expect a lobby member update shortly afterward.

EOS_LMSC_LEFT

An existing user has left the lobby and their specific data has been removed.

EOS_LMSC_DISCONNECTED

An existing user unexpectedly left the lobby.

EOS_LMSC_KICKED

The lobby owner removed a specific user from the lobby.

EOS_LSMC_PROMOTED

An existing user was promoted either explicitly by the previous owner or implicitly when the lobby owner left the lobby.

EOS_LMS_LOBBYCLOSED

The lobby has closed either because it was destroyed by the owner, or there was an error.

Usage Limitations

Please consult the Service Usage Limitations page for information about usage limits that you should observe to maintain performance and speed.