Lobbies Interface

Interface to handle lobbies

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

PropertyValue
ApiVersionEOS_LOBBY_CREATELOBBY_API_LATEST
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:

PropertyValue
ApiVersionEOS_LOBBY_DESTROYLOBBY_API_LATEST
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:

PropertyValue
ApiVersionEOS_LOBBY_REJECTINVITE_API_LATEST
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:

PropertyValue
ApiVersionEOS_LOBBY_QUERYINVITES_API_LATEST
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:

PropertyValue
ApiVersionEOS_LOBBY_GETINVITECOUNT_API_LATEST
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:

PropertyValue
ApiVersionEOS_LOBBY_GETINVITEIDBYINDEX_API_LATEST
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.

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