Lobbies Interface

The Online Services Lobbies Interface provides an API for creating and managing lobbies. A lobby is a group of players within the context of a client application where all of the players have some shared state. This could mean that they are all playing in the same online match together or all waiting for the same match to begin. Both the lobby and its members have attributes used to share this state. Changes to a lobby's attributes or the attributes of any of its members are seen by all joined lobby members in real-time.

The lobby leader may change a lobby's attributes, and each member (including the leader) may change their own attributes at any time. A lobby schema defines these attributes, along with their types and value constraints, that are then used to create a lobby. This lobby schema is defined in the application config files and is validated when the application starts. You are not required to define all attributes to create a lobby, but if you define an attribute that fails schema validation, lobby creation will fail.

A common use of Lobbies is to group players together before proceeding into a match. Several game matches may be played within the lifetime of a single lobby. Below is an example lifecycle of a lobby:

• A player creates a new lobby with the desired privacy settings and attributes. This player is designated the lobby leader.

• Additional players locate and join the lobby through public search, invitation, or social presence.

• Players share attributes within the lobby through attribute updates.

• Once the lobby chooses to play a match, the lobby leader records the match session ID as a lobby attribute.

• Other lobby members see this session ID and join the same game session.

• Players join or leave the lobby throughout the lifetime of multiple game matches.

API Overview

Functions

The following table provides a high-level overview of the functions provided by the Lobbies Interface:

Enumeration Classes

The Lobbies Interface provides enumeration classes to reflect Lobby Join Policy and Lobby Member Leave Reasons through two enumeration classes: ELobbyJoinPolicy and ELobbyMemberLeaveReason.

ELobbyJoinPolicy

ELobbyMemberLeaveReason

Primary Structs

The Lobby Interface functionality is primarily communicated through two structs: FLobbyMember and FLobby, in addition to the function specific structs for passing parameters and return values.

FLobbyMember

FLobby

Configuration

Lobbies use a schema system to define the structure and properties of the lobby as well as lobby member attributes. A game may declare multiple individual schema definitions to support many different types of lobbies. All lobby schemas must derive from the LobbyBase schema.

The LobbyBase schema contains all attributes players can use to search for a lobby. This inheritance structure means that the Lobbies interface knows which game-provided schema to apply to a search result. SchemaCompatibilityId is a special attribute within LobbyBase that exists to ensure that a schema is compatible between two clients.

A game must declare a definition for each schema attribute present in a schema definition. Schemas are defined in a project's configuration files (*.ini) files. These definitions include an attribute's type, maximum size, and visibility, as well as additional behaviors such as whether the attribute is available as a search parameter.

In general, a schema has categories which contain attribute definitions. The Lobbies interface schema has two categories: Lobby and LobbyMember. These categories contain attribute definitions which apply to the lobby object and lobby member objects, respectively.

Example

Here is an example configuration for the Lobbies interface:

[OnlineServices.Lobbies]
+SchemaDescriptors=(Id="GameLobby", ParentId="LobbyBase")

!SchemaCategoryAttributeDescriptors=ClearArray
+SchemaCategoryAttributeDescriptors=(SchemaId="LobbyBase", CategoryId="Lobby", AttributeIds=("SchemaCompatibilityId", "ExampleSearchableLobbyAttribute"))
+SchemaCategoryAttributeDescriptors=(SchemaId="LobbyBase", CategoryId="LobbyMember")

+SchemaCategoryAttributeDescriptors=(SchemaId="GameLobby", CategoryId="Lobby", AttributeIds=("GameMode", "GameSessionId", "MapName", "MatchTimeout"))
+SchemaCategoryAttributeDescriptors=(SchemaId="GameLobby", CategoryId="LobbyMember", AttributeIds=("Appearance"))

Process Flow

Create

A player initiates lobby creation, and will be designated the lobby leader once the lobby is created. The creating player decides the initial lobby settings. These settings can include:

• Visibility

• Join Policy

• Schema ID

• Lobby Attributes

• Lobby Member Attributes

Other players can see the public attributes when they search for a lobby. The lobby leader has additional privileges as outlined in the Leader Actions section of this page. All lobby members, including the leader, can change their personal attributes or invite players to join the lobby. These actions are summarized in the Member Actions section.

Upon successful lobby creation, the creating player receives an OnLobbyJoined event followed by an OnLobbyMemberJoined for themselves, since they are now the designated lobby leader. As long as this player is designated as the lobby leader, they will receive additional OnLobbyMemberJoined and OnLobbyMemberLeft events as players join and leave the lobby.

Find

To join a lobby, a player first needs to know the lobby's ID. Players can find the ID by:

• Search

• Invite

Both search and invitation provide a snapshot of the lobby data to the client application. Attributes within the snapshot are not updated until the player has joined the lobby.

Search

Lobby search allows a player to specify attributes to find lobbies which match their desired configuration. Players can search for lobbies by:

• Attribute filters

• Target player

• Specific lobby ID

Invite

Depending on a lobby's privacy setting, lobby members may invite additional players to join the lobby. When an invitation is sent, the target player receives an OnLobbyInvitationAdded event to notify them of the waiting invitation. The OnLobbyInvitationRemoved event triggers when the invitation is addressed or expires.

Social Presence

Some online service implementations allow players to join a friend's lobby through a social user interface, such as the Online Services Presence Interface. When a player chooses to join in this way, an OnUILobbyJoinRequested event triggers the application to indicate the player's desire to join the lobby.

Join

Once a player knows the ID of the lobby they wish to join, calling JoinLobby starts the process of adding the local player. The local player must provide their initial LobbyMember attributes, which are shared with the other existing lobby members upon joining the lobby.

After successfully joining a lobby, the player receives an OnLobbyJoined event. Every existing member of the lobby receives an OnLobbyMemberJoined event notifying them a new player has joined. While a player remains in this lobby, they receive additional OnLobbyMemberJoined and OnLobbyMemberLeft events as other players join and leave the lobby.

Leave

When a player no longer wishes to remain in a lobby, LeaveLobby removes the player from the lobby with the supplied lobby ID and stops notifications. Once a player leaves a lobby, all other players in the lobby receive an OnLobbyMemberLeft notification. This notifies them a player has left the lobby. These notifications are followed by an OnLobbyLeft event sent to the player who has left the lobby..

Restore

RestoreLobbies restores all lobbies previously joined by the calling player. This is typically done by a game at application startup to rejoin the local player to lobbies they were in when the application last exited.

Leader Actions

The lobby leader has additional, exclusive privileges they can use to help maintain the lobby.

Promote Member

The lobby leader can promote another lobby member to become the leader with a call to PromoteLobbyMember. This action triggers an OnLobbyLeaderChanged event for all lobby members. The player who was previously the leader becomes a normal lobby member.

Kick Member

The lobby leader can remove a target member from the lobby with a call to KickLobbyMember. This action triggers an OnLobbyLeft event for the kicked lobby member and an OnLobbyMemberLeft event for all other lobby members.

Update Lobby Attributes

The lobby leader can change the attributes of the lobby object. This is handled with a call to ModifyLobbyAttributes. When the lobby attributes change, all lobby members receive an OnLobbyAttributesChanged event to notify them of the changed attributes.

Change Lobby Join Policy

The lobby's join policy affects whether the lobby appears in search results, is invitation only, or can be joined by social presence. The lobby leader can change this setting with a call to ModifyLobbyJoinPolicy.

Member Actions

Lobby members are limited to two actions. Members can update their own attributes and invite other members to join the lobby.

Change Member Attributes

Lobby members can change their own attributes with a call to ModifyLobbyMemberAttributes. An OnLobbyMemberAttributesChanged event notifies other lobby members of this change.

Invite Players to Join the Lobby

If the lobby join policy currently allows invitations, lobby members can invite additional players with a call to InviteLobbyMember. The target of the invitation receives an OnLobbyInvitationAdded event that notifies them of the pending invitation. The invited player chooses to join the lobby with a call to JoinLobby or rejects the invitation with DeclineLobbyInvitation.

Converting Code from Online Subsystem

Lobbies is a new interface for the Online Services and does not have a direct counterpart from the Online Subsystem.

More Information

Header File

Consult the Lobbies.h header file directly for more information as needed. The Lobbies Interface header file Lobbies.h is located in the directory:

Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

For instructions on how to obtain the UE source code, see our documentation on Downloading Unreal Engine Source Code.

Function Parameters and Return Types

See the Functions section of the Online Services Overview page for an explanation of function parameters and return types, including how to pass parameters and processing the results when functions return.