Sessions Interface

This page is not available in the language you have chosen. It will be displayed in **** by default. If you would like to view it in a different language, you can try selecting another language.

The Online Services Session Interface handles the creation, destruction, and management of online game sessions. A session is the representation of an online match in a game, running on either a player's machine or a dedicated server. Sessions can have the following join policies:

• Invite Only: Players with an invitation can join the session.
• Friends Only: Friends of any session member can join the session.
• Public: Anyone can find and join the session. You can define a public session using a set of properties that act as filters, allowing players to search for specific game modes or maps.

API Overview

The following table provides a high-level description of the functions included in the Sessions Interface.

Process Flow

Session Lifecycle

• Create a new session using the desired settings.
• At any point during the lifetime of a session, you can update the session to reflect changes in the properties of the online match it represents. These changes can include:Altering parameters regarding how the session appears in searches, or whether it shows up at all.
• Restricting new players from joining the session once the game is in progress. Players that discover the session can join it.

Using information obtained by joining the session, new players can connect to the session host or dedicated server.

• After connecting, the players need to get registered with the session. This process will be automatically handled by the engine in future releases. Play the game.

When the game is over, the player can leave the session or destroy it (if the player is the owner or host).

Disconnecting from the host or server needs to be followed by unregistering the player or players from the session. This process will be automatically handled by the engine in future releases.

Create

The first step in the session lifecycle is creating a session using the desired parameters. These parameters include some that remain constant throughout the lifetime of the session (like bIsLANSession and bAllowSanctionedPlayers from the CreateSession function) and some you can update at any time (like the options provided by the function SessionSettings).

At most one session per user can be set as the Presence Session. This means it will appear in the user's Presence information and be visible to friends and followers as exposed through the Presence Interface. If a user is a member of many sessions, which session appears as the presence session can be changed by SetPresenceSession (this functionality might not be available in all platform implementations).

Discover

A user can discover new sessions in a few different ways:

Search FindSessions allows users to define search parameters such as tags that match a desired session's custom settings or a specific user ID to find the session that their friend is in. This returns a list of session IDs each representing cached session information, which the user can search and access with GetSessionById.

Invitation Users can receive session invitations from other users. After receiving an invitation, a user can view the information about the session by accessing the invitation with GetSessionInviteById. Afterwards, the user decides whether to join the session with the session ID provided by the invite information.

Presence Specific platform UIs may show users information about sessions their friends have joined.

Join

Once a user has information about a session obtained either through search, invitation, or presence, they can attempt to join it by calling JoinSession. They can also choose if they want to set this new session as their presence session with SetPresenceSession.

Matchmaking Another way you can join a session is by calling StartMatchmaking. This function acts as a combination of CreateSession and FindSessions. StartMatchmaking looks for sessions matching a predefined set of search filters and it will create a session using the given information if it cannot find any.

Once you have joined a session, you can call IOnlineServices::GetResolvedConnectString, which returns the platform specific connection information needed to join the match. The string obtained from this function can then be passed to APlayerController::ClientTravel or UWorld::ServerTravel to send the player into the match. If the travel succeeds, the player will be added to the session and AddSessionMember is called to register the player with the session.

Inviting After joining a session, either by creating it or joining it, you can send the session information to other players with SendSessionInvite. This is a good way to get friends together in the same online match. Once a player receives an invite, they can access its information using GetAllSessionInvites to access all invites for a given user, or GetSessionInviteById to get the information about a particular invite. They can also reject session invites using a call to RejectSessionInvite by passing the corresponding invite ID as a parameter.

Update

You can update session settings at any point during the session's lifetime by calling UpdateSessionSettings. These settings include, but are not limited to:

• Maximum number of players in session
• Join policy for the session:Invite Only
• Friends Only
• Public Restrict access to new players

Add, modify, or remove custom settings and user-defined parameters

Leave and Destroy

You can leave a session by calling LeaveSession. The owner of the session can set the additional parameter bDestroySession to true if they want to remove the session from the backend services as they leave. This forces all other members of the session to leave as well.

Examples

You can access the Sessions Interface through a reference to an OnlineServices instance. From here, the functionality of the Sessions Interface is exposed. We provide a few examples of accessing the Sessions Interface and performing synchronous and asynchronous operations.

Get Session By Name

C++

UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();
UE::Online::FGetSessionByName::Params Params;
Params.SessionName = FName(TEXT("MySession"));

UE::Online::TOnlineResult Result = SessionsInterface->GetSessionByName(MoveTemp(Params));
if(Result.IsOk())
{
    TSharedRef Session = Result.GetOkValue().Session;
    // now we can read information from the session

Expand code Copy full snippet(11 lines long)

Walkthrough

1. Use the default online services by calling GetServices with no parameters specified: C++ UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); Copy full snippet(1 line long)
2. Access the Sessions interface for the default online services: C++ UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); Copy full snippet(1 line long)
3. Initialize a FGetSessionByName struct using the necessary parameters to call GetSessionByName: C++ UE::Online::FGetSessionByName::Params Params; Params.SessionName = FName(TEXT("MySession")); UE::Online::FGetSessionByName::Params Params; Params.SessionName = FName(TEXT("MySession")); Copy full snippet(2 lines long)
4. Call GetSessionByName passing in the parameters from the previous step and save the result: C++ UE::Online::TOnlineResult Result = SessionsInterface->GetSessionByName(MoveTemp(Params)); UE::Online::TOnlineResult<UE::Online::FGetSessionByName> Result = SessionsInterface->GetSessionByName(MoveTemp(Params)); Copy full snippet(1 line long)
5. Process the result of the call to GetSessionByName after ensuring the function call did not throw an error and the result can be accessed: C++ if(Result.IsOk()) { TSharedRef Session = Result.GetOkValue().Session; // now we can read information from the session } if(Result.IsOk()) { TSharedRef<const UE::Online::ISession> Session = Result.GetOkValue().Session; // now we can read information from the session } Copy full snippet(5 lines long)

Update Session Settings

C++

UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();

UE::Online::FUpdateSessionSettings::Params Params;
Params.LocalAccountId = AccountId;
Params.SessionName = FName(TEXT("MySession"));
Params.Mutations.bAllowNewMembers = false;

SessionsInterface->UpdateSessionSettings(MoveTemp(Params))
.OnComplete([this](const UE::Online::TOnlineResult& Result)

Expand code Copy full snippet(19 lines long)

Walkthrough

1. Use the default online services by calling GetServices with no parameters specified and access the Sessions interface for the default online services: C++ UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); Copy full snippet(2 lines long)
2. Initialize a struct using the necessary parameters to call UpdateSessionSettings: C++ UE::Online::FUpdateSessionSettings::Params Params; Params.LocalAccountId = AccountId; Params.SessionName = FName(TEXT("MySession")); Params.Mutations.bAllowNewMembers = false; UE::Online::FUpdateSessionSettings::Params Params; Params.LocalAccountId = AccountId; Params.SessionName = FName(TEXT("MySession")); Params.Mutations.bAllowNewMembers = false; Copy full snippet(4 lines long)
3. Handle the UpdateSessionSettings.OnComplete callback by processing the error or the queried stats if it resulted in an error, or the result if it returns okay with a lambda function: C++ SessionsInterface->UpdateSessionSettings(MoveTemp(Params)) .OnComplete([this](const UE::Online::TOnlineResult& Result) { if(Result.IsError()) { const UE::Online::FOnlineError OnlineError = Result.GetErrorValue(); // update was not successful, process OnlineError return; } // update was successful Expand code Copy full snippet(11 lines long)

Converting Code from Online Subsystem

The Online Services Sessions Interface is responsible for all code owned by the Online Subsystem Sessions Interface.

More Information

Header File

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

C++

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

Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online Copy full snippet(1 line long)

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

Function Parameters and Return Types

Refer to 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.