Epic Online Services (EOS) gives players the ability to host, find, and interact with online gaming sessions through the Sessions Interface. A session can be short, like filling a certain number of player slots before starting a game, then disbanding after the game ends, or it could be longer, like keeping track of a game that cycles through matches on multiple maps or levels. The Sessions Interface also manages game-specific data that supports the back-end service searching and matchmaking functionality. For more information on the considerations you should take for matchmaking, see the Matchmaking Security Considerations section below. This document covers some of the definitions and headers for the Sessions Interface. See the Sessions Interface API Reference documentation for a complete list.
To use the Sessions Interface, acquire an EOS_HSessions
handle through the Platform Interface function, EOS_Platform_GetSessionsInterface
. All Sessions Interface functions require this handle as their first parameter. You must ensure that the EOS_HPlatform
handle is ticking for callbacks to trigger when requests are completed. See the EOS SDK in C# documentation for more information on ticking.
Active Sessions
Active sessions are at the core of everything the Sessions Interface does. An application can have multiple active sessions at the same time, each identified by a unique, local name. For example, there might be a session called "Party" with the local player's friends, keeping them together as they play matches against other teams, and another called "Game" that includes some or all of those friends as well as other players in the match currently in progress. Each session has its own EOS_HActiveSession
handle on each participating player's system. An active session forms on a player's machine whenever that player creates a session, or joins a session found in an online search or through an invitation. Since active sessions exist locally, the local application must destroy them when they are no longer needed. If a host fails to do this, the back-end service server will delay destruction of the session, which can lead to other players falsely discovering sessions in their online searches.
To get a copy of the high-level information (type EOS_ActiveSession_Info
), for an active session, including its name, the ID of the local user who created or joined it, its current state, a reference to the session details (a const pointer to EOS_SessionDetails_Info
), and any user-defined data attributes, you must first get its active session handle (type EOS_HActiveSession
) by calling the local function EOS_Sessions_CopyActiveSessionHandle
with an EOS_Sessions_CopyActiveSessionHandleOptions
initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_COPYACTIVESESSIONHANDLE_API_LATEST |
SessionName | Name of the session for which to retrieve a session handle |
With this handle, you can call EOS_ActiveSession_CopyInfo
. You will also need to initialize and pass in an EOS_ActiveSession_CopyInfoOptions
as follows:
Property | Value |
---|---|
ApiVersion | EOS_ACTIVESESSION_COPYINFO_API_LATEST |
This function also runs locally and, on success, makes a copy of the session's EOS_ActiveSession_Info
data. You are responsible for releasing the copy with EOS_ActiveSession_Info_Release
when you no longer need it.
Session Details
Active sessions that you create locally or discover through searches, invitations, or other users' presence data store an internal data structure called EOS_SessionDetails_Info
, which contains basic details about the session:
-
Session ID
-
Host address
-
Number of open slots in the session
The structure also contains a pointer to another structure, EOS_SessionDetails_Settings
, which provides more detail about the state of a session, including:
-
Top-level filtering criteria, called the Bucket ID, which is specific to your game; often formatted like "GameMode:Region:MapName"
-
Total number of connections allowed on the session
-
Join-in-progress settings
-
Privacy setting
Accessing Session Details
If you have an EOS_ActiveSession_Info
data structure, its SessionDetails
variable gives you access to the EOS_SessionDetails_Info
for that session. If not, you can use an EOS_HSessionDetails
handle to call EOS_SessionDetails_CopyInfo
to acquire a copy of the EOS_SessionDetails_Info
data. Call EOS_SessionDetails_CopyInfo
with an EOS_SessionDetails_CopyInfoOptions
structure containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONDETAILS_COPYINFO_API_LATEST |
On success, this will return a copy of the session's EOS_SessionDetails_Info
, which contains the session's ID, the address of the host, and the number of open slots in the session. When you no longer need this information, call EOS_SessionDetails_Info_Release
to free it.
Creating a Session
Creating a session is a two-step process.
First, establish the initial state and settings for the session locally with the EOS_Sessions_CreateSessionModification
function. You'll need to pass in an EOS_Sessions_CreateSessionModificationOptions
structure with the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_CREATESESSIONMODIFICATION_API_LATEST |
SessionName | The name of the session, unique among sessions created by this user |
BucketId | The top-level, game-specific filtering information for session searches. This criteria should be set with mostly static, coarse settings, often formatted like "GameMode:Region:MapName". |
MaxPlayers | The maximum number of players allowed in the session at any time |
LocalUserId | The user ID associated with the session |
bPresenceEnabled | Whether or not this session should be the one associated with the local user's presence information (see the Presence Interface for more details) |
SessionId | (OPTIONAL) Set this value to override the unique ID that would regularly be assigned to this session on creation. It is possible to use this to set values that correlate with other developer identifiers. In this way, it is not necessary to add additional attributes to the session and require the session to advertise publicly in order to find “private sessions”. This value must be globally unique within the application ecosystem. Failure to do so will result in 'EOS_Sessions_SessionAlreadyExists' errors. |
bSanctionsEnabled | Whether or not this session should enforce preventing sanctioned users from joining this session. It will prevent calls to Join and RegisterPlayers from succeeding with those users. See the Sanctions Interface documentation for details. |
AllowedPlatformIdsCount | The number of platform IDs in the AllowedPlatformIds array. |
AllowedPlatformIds | An array of platform IDs that specify the player platforms that are allowed to register with the session. Platform IDs are found in the EOS header file, e.g. EOS_OPT_Epic . For some platforms, the value is in the EOS Platform specific header file. If null, the lobby is unrestricted. |
If the EOS_Sessions_CreateSessionModification
call succeeds, it will return EOS_Success
and the default EOS_HSessionModification
you provided will contain a valid handle.
Second, continue to modify the session's initial setup (see the section on modifying a session until you have made all the modifications you need. You can then complete the creation process by calling EOS_Sessions_UpdateSession
with an EOS_Sessions_UpdateSessionOptions
structure initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_UPDATESESSION_API_LATEST |
SessionModificationHandle | The handle (EOS_HSessionModification ) for the session you want to create or update |
EOS_Sessions_UpdateSession
is asynchronous, and will call your delegate (of type EOS_Sessions_OnUpdateSessionCallback
) upon completion with an EOS_Sessions_UpdateSessionCallbackInfo
data structure. On success, the local name that you provided will be paired with a searchable, unique ID string from the server.
Player Details
You can retrieve the following player data from the active session:
- The total number of registered players.
- The product user ID (PUID) of each registered player.
Accessing the Total Number of Registered Players
You can call EOS_ActiveSession_GetRegisteredPlayerCount
to get the total number of registered players associated with the active session. To do this, call EOS_ActiveSession_GetRegisteredPlayerCount
with an ActiveSessionGetRegisteredPlayerCountOptions
structure that contains the following information:
Property | Value |
---|---|
ApiVersion | EOS_ACTIVESESSION_GETREGISTEREDPLAYERCOUNT_API_LATEST |
Accessing the Product User ID of Each Registered Player
You can iterate through the registered players for the active session to get the product user ID (PUID) of each registered player. To do this, call EOS_ActiveSession_GetRegisteredPlayerByIndex
with an ActiveSessionGetRegisteredPlayerByIndexOptions
structure that contains the following information:
Property | Value |
---|---|
ApiVersion | EOS_ACTIVESESSION_GETREGISTEREDPLAYERBYINDEX_API_LATEST |
PlayerIndex | Index of the registered player to retrieve. |
On success, this returns the product user ID (PUID) of the player at the specified index for the active session.
Modifying a Session
To modify an existing session, first call EOS_Sessions_UpdateSessionModification
with a pointer to a default EOS_HSessionModification
object and an EOS_Sessions_UpdateSessionModificationOptions
structure initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_UPDATESESSIONMODIFICATION_API_LATEST |
SessionName | The name of the session you want to modify |
If this call succeeds, it will return EOS_Success
, the modification will be applied to the local session, and the EOS_HSessionModification
object you provided will now be a valid handle. If you are the session owner, you can use that handle to apply the local changes you've made to the back-end service's version of the session, by calling EOS_Sessions_UpdateSession
. This function works for both new sessions (those that have not yet been created on the server) and pre-existing ones. The following functions modify different aspects of the session:
Function | Effect |
EOS_SessionModification_SetHostAddress | This changes the string containing the data required to reach the server. The host address does not have to be an IP address; a socket ID, URL, or other attribution can work. |
EOS_SessionModification_SetBucketId | The Bucket ID is the main search criteria, containing game-specific information that is required in all searches. For example, a format like "GameMode:Region:MapName" could be used to form the Bucket ID. |
EOS_SessionModification_SetMaxPlayers | Use this to set the maximum number of players allowed in the session. |
EOS_SessionModification_SetJoinInProgressAllowed | You can permit or forbid players to join games that have already begun (see the section on starting and ending play for more details) with this function. |
EOS_SessionModification_SetPermissionLevel | This function can change the session's privacy settings to any of the following:
|
EOS_SessionModification_AddAttribute | Adds a custom attribute (type EOS_SessionDetails_AttributeData ) to the session. See the Custom Attributes section for more information. |
EOS_SessionModification_RemoveAttribute | Removes a custom attribute from the session. See the Custom Attributes section for more information. |
After modifying the session locally, you can update the session on the back-end service if you are the session owner. To do this, call EOS_Sessions_UpdateSession
with an EOS_Sessions_UpdateSessionOptions
containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_UPDATESESSION_API_LATEST |
SessionModificationHandle | The handle (EOS_HSessionModification ) for the session you want the server to create or update |
This operation will call your callback function, of type EOS_Sessions_OnUpdateSessionCallback
, with an EOS_Sessions_UpdateSessionCallbackInfo
data structure upon completion.
Custom Attributes
Sessions can contain user-defined data, called attributes. Each attribute has a name, which acts as a string key, a value, an enumerated variable identifying the value's type, and a visibility setting. The following variable types are currently supported:
EOS_ESessionAttributeType | Value Type |
---|---|
EOS_SAT_BOOLEAN | EOS_Bool |
EOS_SAT_INT64 | int64_t |
EOS_SAT_DOUBLE | double |
EOS_SAT_STRING | const char* (null-terminated UTF8 string) |
The following visibility types are available:
EOS_ESessionAttributeAdvertisementType | Visbility |
---|---|
EOS_SAAT_DontAdvertise | Not visible to other users |
EOS_SAAT_Advertise | Visible to other users |
Accessing an Attribute
You can find out how many attributes a session has by calling EOS_SessionDetails_GetSessionAttributeCount
with a valid EOS_HSessionDetails
handle and an EOS_SessionDetails_CopySessionAttributeByIndexOptions
containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONDETAILS_GETSESSIONATTRIBUTECOUNT_API_LATEST |
To get a copy of an attribute, call EOS_SessionDetails_CopySessionAttributeByIndex
with a valid EOS_HSessionDetails
handle and an EOS_SessionDetails_CopySessionAttributeByIndexOptions
initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONDETAILS_COPYSESSIONATTRIBUTEBYINDEX_API_LATEST |
AttrIndex | The index of the attribute to copy |
On success, this will return EOS_Success
and your output parameter will contain a copy of the EOS_SessionDetails_Attribute
structure corresponding to the attribute index you requested. This structure contains the Attribute's value and type in an EOS_Sessions_AttributeData
data structure, and its visibility in an EOS_ESessionAttributeAdvertisementType
enumerated value. When you no longer need this data, release it with EOS_SessionDetails_Attribute_Release
.
Adding an Attribute
You can set up an attribute that you would like to add or modify by filling an EOS_Sessions_AttributeData
data structure with the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_SESSIONATTRIBUTEDATA_API_LATEST |
Key | The name of the attribute |
Value | The attribute's value, or, in the case of strings, a pointer to the string |
ValueType | An EOS_ESessionAttributeType that describes Value |
Once you have this data ready, call EOS_SessionModification_AddAttribute
to add the attribute. You must provide your EOS_HSessionModification
handle and an EOS_SessionModification_AddAttributeOptions
, intialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONMODIFICATION_ADDATTRIBUTE_API_LATEST |
SessionAttribute | A const pointer to an EOS_Sessions_AttributeData containing the modification you want to make |
AdvertisementType | An EOS_ESessionAttributeAdvertisementType indicating whether or not this attribute should be publicly visible |
You can store up to EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTES
(currently 64) in a session, and each attribute's name can be up to EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTE_LENGTH
(currently 32) characters long.
This function only sets up the attribute that you want to add or update. It does not actually add or update the attribute, or interact with the session in any way. You will still need to call EOS_Sessions_UpdateSession
as described at the top of this section.
Removing an Attribute
To remove an attribute, call EOS_SessionModification_RemoveAttribute
with the EOS_HSessionModification
handle for your session, and an EOS_SessionModification_RemoveAttributeOptions
structure containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONMODIFICATION_REMOVEATTRIBUTE_API_LATEST |
Key | The name (key) of the attribute you want to remove |
This function only establishes that you want to remove a certain attribute. It does not actually remove the attribute, or interact with the session in any way. You will still need to call EOS_Sessions_UpdateSession
as described at the top of this section.
Inviting Players to a Session
To invite another player to join an active session, a registered member of the session can call EOS_Sessions_SendInvite
with an EOS_Sessions_SendInviteOptions
structure containing the following data:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_SENDINVITE_API_LATEST |
SessionName | The name of the session to which the player is invited |
LocalUserId | The local user sending the invitation |
TargetUserId | The remote user being invited |
Once the server has processed the invitation request, your callback, of type EOS_Sessions_OnSendInviteCallback
, will run with an EOS_Sessions_SendInviteCallbackInfo
structure containing a result code. This result indicates success if there was no error in the process of sending the invitation; success does not mean that the remote user has accepted, or even seen, the invitation.
For invite functionality with the Epic Games Launcher, be sure to map your deployments to your artifacts as well.
The remote user will receive notification of the invitation when it arrives, and the payload will provide the user ID that has been invited as well as the ID of the invitation itself. Upon receipt, use EOS_Sessions_CopySessionHandleByInviteId
to retrieve the EOS_HSessionDetails
handle from the invitation. You can use this handle to gain access to the session details data for the associated session, or to accept or reject the invitation. Once you are finished with the handle, call EOS_SessionDetails_Release
to release it.
In order to receive this notification, you must register a callback with EOS_Sessions_AddNotifySessionInviteReceived
. You only need to do this once, typically at startup, after which your callback will run as each invitation is received. When you no longer need notification, call EOS_Sessions_RemoveNotifySessionInviteReceived
to remove your callback.
Accepting an Invitation
The Sessions Interface does not feature a dedicated function for accepting an invitation. You can join the session using the standard method with the EOS_HSessionDetails
handle that you retrieved from the invitation. To request a list of all pending invitations, call EOS_Sessions_QueryInvites
with an EOS_Sessions_QueryInvitesOptions
data structure initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_QUERYINVITES_API_LATEST |
LocalUserId | The local user whose invitations are being requested |
This operation is asynchronous. When it finishes, it will call your callback function, of type EOS_Sessions_OnQueryInvitesCallback
, with an EOS_Sessions_QueryInvitesCallbackInfo
data structure. On success, EOS will have all of the user's pending invitations cached locally. You can use EOS_Sessions_GetInviteCount
to determine the number of invitations in the cache. Pass in an EOS_Sessions_GetInviteCountOptions
structure with the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_GETINVITECOUNT_API_LATEST |
LocalUserId | The local user who has cached invitations |
This function runs locally and will return a uint32_t
that represents the number of invitations currently in the cache. To get the ID of any cached invitation, call EOS_Sessions_GetInviteIdByIndex
with an EOS_Sessions_GetInviteIdByIndexOptions
containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_GETINVITEIDBYINDEX_API_LATEST |
LocalUserId | The local user who has cached invitations |
Index | The cache index of the invitation whose ID we want to retrieve |
If EOS_Sessions_GetInviteIdByIndex
returns EOS_Success
, the output parameters you passed to it contain the invitation's ID as a null-terminated character string and the length of that string.
The max length of an invitation's ID string is EOS_SESSIONS_INVITEID_MAX_LENGTH
(currently 64).
As described above, the EOS_Sessions_CopySessionHandleByInviteId
function will provide an EOS_HSession
handle which gives you access to the session details data for the associated session. You can then choose to accept the invitation by joining the session, ignore the invitation, or reject it. Once you are finished with the EOS_HSession
handle, call EOS_SessionDetails_Release
to release it.
Rejecting an Invitation
To reject an invitation, call EOS_Sessions_RejectInvite
with an EOS_Sessions_RejectInviteOptions
initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_REJECTINVITE |
LocalUserId | The local user rejecting the invitation |
InviteId | The ID of the invitation |
Upon completion, you will receive a call to your EOS_Sessions_OnRejectInviteCallback
callback function with an EOS_Sessions_RejectInviteCallbackInfo
data structure indicating success or failure. Successfully rejecting an invitation permanently deletes it from the system.
Discovering a Remote Session
To find a remote session, you need to configure a search, execute that search, then examine the results.
Configuring a Search
To begin a search, first call EOS_Sessions_CreateSessionSearch
to create a search handle. Pass in an EOS_Sessions_CreateSessionSearchOptions
structure, initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_CREATESESSIONSEARCH_API_LATEST |
MaxSearchResults | Maximum number of search results to return |
This function runs locally and will fill out the default search handle (of type EOS_HSessionSearch
) on success. The next step is to configure the handle to perform a specific search with the criteria you require. EOS provides three methods to search for sessions:
-
Session ID: Finds a single session with a known ID
-
User ID: Finds all sessions involving a known user — presently limited to local users
-
Attribute Data: Finds all sessions that match some user-defined filtering criteria
Configuring for Session ID
If you want a specific session and know its server-side ID, call EOS_SessionSearch_SetSessionId
with your search handle and an EOS_SessionSearch_SetSessionIdOptions
initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONSEARCH_SETSESSIONID_API_LATEST |
SessionId | The ID of the session you want to find |
This is the only step required to configure a session ID search. Unlike the other search methods, this will never return more than one result.
Only sessions marked as EOS_OSPF_PublicAdvertised
or EOS_OSPF_JoinViaPresence
can be found this way.
Configuring for User ID
To find all sessions that involve a known user, call EOS_SessionSearch_SetTargetUserId
with your search handle and an EOS_SessionSearch_SetTargetUserIdOptions
containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONSEARCH_SETTARGETUSERID_API_LATEST |
TargetUserId | The user ID to find within sessions |
This is the only step required to configure a user ID search. Must be a local, logged-in user.
The application can only find locally authenticated users or remote users that are registered in public sessions.
Configuring for Attribute Data
The most robust way to find sessions is to search based on a set of search parameters, which act as filters. Some parameters could be exposed to the user, such as enabling the user to select a certain game type or map, while others might be hidden, such as using the player's estimated skill level to find matches with appropriate opponents. This search method can take multiple parameters, and will only find sessions that pass through all of them. To set up a search parameter, call EOS_SessionSearch_SetParameter
with your search handle and an EOS_SessionSearch_SetParameterOptions
containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONSEARCH_SETPARAMETER_API_LATEST |
Parameter | A key and a value to compare to an attribute associated with the session |
ComparisonOp | The type of comparison to make |
This function can be called multiple times to set up multiple filters, all of which must be satisfied for a session to show up in the search results. The following table lists the types of comparisons you can use, what value types they work on, and what condition must be met in order to pass:
ComparisonOp | Acceptable Value Types | Success Condition |
---|---|---|
EOS_CO_EQUAL | All | Attribute is equal to the search value |
EOS_CO_NOTEQUAL | All | Attribute is not equal to the search value |
EOS_CO_GREATERTHAN | Numerical Types | Attribute is greater than the search value |
EOS_CO_GREATERTHANOREQUAL | Numerical Types | Attribute is greater than or equal to the search value |
EOS_CO_LESSTHAN | Numerical Types | Attribute is less than the search value |
EOS_CO_LESSTHANOREQUAL | Numerical Types | Attribute is less than or equal to the search value |
EOS_CO_DISTANCE | Numerical Types | Not a filter; attributes are sorted based on how close they are to to the search value, or Abs(AttributeValue - SearchValue) |
EOS_CO_ANYOF | Strings | Attribute matches any member of a semicolon-delimited list (for example, "This;OrThis;MaybeThis") |
EOS_CO_NOTANYOF | Strings | Attribute does not match any member of a semicolon-delimited list (for example "NotThis;OrThisEither") |
Executing a Search
To execute the search, call EOS_SessionSearch_Find
with your search handle and an EOS_SessionSearch_FindOptions
structure initialized as follows:
This is an asynchronous operation. When it finishes, your callback function, of type EOS_SessionSearch_OnFindCallback
, will receive an EOS_SessionSearch_FindCallbackInfo
structure notifying you of the success or failure of the search. Following successful completion, you can get copies of the search results from the EOS cache.
EOS supports running multiple EOS_SessionSearch_Find
operations in parallel.
Tip: You can search by the attribute EOS_SESSIONS_SEARCH_MINSLOTSAVAILABLE
to find sessions that are not full (still have slots available). Set the value type to int64_t
, and use the EOS_CO_GREATERTHANOREQUAL
comparison operator to set the value to at least 1
. This excludes full sessions from the results.
Examining Search Results
EOS_SessionSearch_GetSearchResultCount
for a given EOS_HSessionSearch
handle and
EOS_SessionSearch_CopySearchResultByIndex
will return the session details one by one through individual EOS_HSessionDetails
handles.
After completing a successful search, use EOS_SessionSearch_GetSearchResultCount
with your search handle to get the number of results that the search returned. You can then call EOS_SessionSearch_CopySearchResultByIndex
to get a copy of the EOS_HSessionDetails
handle associated with the active session at that index. This handle provides access to session details data, which you can use to display information about the session to the local user or determine whether or not to join the session using your own game logic. You must release the EOS_HSessionDetails
handle with EOS_SessionDetails_Release
when you no longer need it.
Joining a Session
You can join an existing session if you have a valid EOS_HSessionDetails
handle to it by calling EOS_Sessions_JoinSession
and providing an EOS_Sessions_JoinSessionOptions
structure with the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_JOINSESSION_API_LATEST |
SessionName | The unique name that the local system will use to refer to the session |
SessionHandle | The EOS_HSessionDetails handle for the session you want to join |
LocalUserId | The local user joining the session |
bPresenceEnabled | Whether or not this session should be the one associated with the local user's presence information (see the Presence Interface for more details) |
When the operation finishes, your callback function, of type EOS_Sessions_OnJoinSessionCallback
, will receive an EOS_Sessions_JoinSessionCallbackInfo
indicating success or failure. If the operation succeeds, EOS will create an active session on the joining client's system. As this new session is locally-owned, the joining user is responsible for destroying it once it is no longer needed.
Registering a Player
When a player joins the session, the session owner is responsible for registering the player with the session. This keeps the back-end service aware of the number of players so that it may stop advertising the session publicly when it is full. EOS accepts registration of multiple players at once through the EOS_Sessions_RegisterPlayers
function. Call this function from the owning client with an EOS_Sessions_RegisterPlayersOptions
structure containing the following data:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_REGISTERPLAYERS_API_LATEST |
SessionName | The local name of the session |
PlayersToRegister | An array of IDs for the joining players |
PlayersToRegisterCount | The number of elements in PlayersToRegister |
On completion, your callback of type EOS_Sessions_OnRegisterPlayersCallback
will run with an EOS_Sessions_RegisterPlayersCallbackInfo
parameter that contains the following data:
Property | Value |
---|---|
ResultCode | Result code indicating success or failure |
Registered Players | A list of players successfully registered |
Registered Players Count | The number of registered players |
Sanctioned Players | A list of players that were not registered due to sanctions |
Sanctioned Players Count | The number of players not registered due to sanctions |
If the call succeeds, the newly-registered players will receive access to some session management functionality, such as the ability to invite other players to the session. Note that no errors are returned when one or more sanctioned players are denied registration; the SanctionedPlayers
list must be checked manually. See Enforcing Sanctions for more details. EOS does not provide notification when a player joins a session, so you must notify the owner when you join, or provide the owner with a way to detect when a player has successfully joined the session.
After a user registers with a publicly visible session (a session configured with EOS_OSPF_PublicAdvertised
or EOS_OSPF_JoinViaPresence
), others can find the session with EOS_SessionSearch_SetTargetUserId
.
Leaving a Session
The Sessions Interface does not feature a dedicated function for leaving a session. To leave a session, destroy your local session through the standard method, using its local name.
Unregistering a Player
When a player leaves the session, the session's owner is responsible for unregistering the player. This enables the server to free up player slots so that future players can join. EOS accepts unregistration of multiple players at once through the EOS_Sessions_UnregisterPlayers
function. Call this function from the owning client with an EOS_Sessions_UnregisterPlayersOptions
structure containing the following data:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_UNREGISTERPLAYERS_API_LATEST |
SessionName | The local name of the session |
PlayersToUnregister | An array of IDs for the departing players |
PlayersToUnregisterCount | The number of elements in PlayersToUnregister |
On completion, your callback of type EOS_Sessions_OnUnregisterPlayersCallback
will run with an EOS_Sessions_UnregisterPlayersCallbackInfo
parameter that indicates success or failure. If the call succeeds, the back-end service will revoke the session management access that those players received when they were originally registered. For example, players who are not registered with the session cannot invite others to join it. EOS does not provide notification of a player leaving a session, so you must notify the owner when you leave a session, or provide the owner with a way to detect that a player has left the game or disconnected.
Host migration is not supported for sessions. If the owner of the session leaves or they lose their connection to the network, the session is orphaned, and no one else can manage the session on the back-end.
Starting and Ending Play
A player can declare that a match has started or ended for a local active session. If that session maps to a session on the back-end service that the local player owns, the back-end version will also start or end play. While playing, the back-end service will automatically reject attempts to join a session if that session has Join in Progress disabled (see the section on Modifying a Session for more information). Although starting a session typically implies that a match has begun, the specific usage of this functionality is up to the game's developers.
To start play, call EOS_Sessions_StartSession
with an EOS_Sessions_StartSessionOptions
initialized as follows:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_STARTSESSION_API_LATEST |
SessionName | The local name of the session |
When the operation completes, your callback, of type EOS_Sessions_OnStartSessionCallback
, will run with an EOS_Sessions_StartSessionCallbackInfo
data structure indicating success or failure. If the operation succeeds, the session is considered "in progress" until you end play by calling EOS_Sessions_EndSession
with an EOS_Sessions_EndSessionOptions
containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_ENDSESSION_API_LATEST |
SessionName | The local name of the session |
Upon completion, your EOS_Sessions_OnEndSessionCallback
function will receive a call with an EOS_Sessions_EndSessionCallbackInfo
data structure indicating success or failure. On success, the session is no longer considered "in progress" and will once again permit players to join. Ending a session does not remove players or destroy the session; it effectively returns to its pre-start state and remains usable, including the ability to start play again. If you intend to destroy the session, you do not need to call EOS_Sessions_EndSession
first.
Destroying a Session
When you no longer need a session, you must destroy it using EOS_Sessions_DestroySession
. Call this function with an EOS_Sessions_DestroySessionOptions
data structure containing the following information:
Property | Value |
---|---|
ApiVersion | EOS_SESSIONS_DESTROYSESSION_API_LATEST |
SessionName | The name of the session to destroy |
When the destruction operation completes, you will receive a callback of type EOS_Sessions_OnDestroySessionCallback
with an EOS_Sessions_DestroySessionCallbackInfo
data structure. Upon success, the session will cease to exist and its name will be available for reuse. However, due to the asynchronous nature of this system, it is possible for a player to make a request after you have called EOS_Sessions_DestroySession
but before the back-end service has destroyed the session. In this case, you may receive requests to join the session after having started the destruction operation. It is important to reject these players, or shut down the network to prevent them from joining the defunct session.
Mirroring Session Management on Remote Clients
Through the Sessions Interface, the session owner (the user who created the session) can manage the session's state as it exists on the back-end service. The life cycle of a session starts with its creation and ends with its destruction. Between those two events, the Sessions Interface can modify the session, change its privacy settings, send invitations, register and unregister players as they join and leave, and start, play, and end matches. A session's life cycle is not rigid; for example, sessions can modify their data at any time, and can start and end multiple matches.
In general, only the owner of the session can make modifications to session data on the back-end service. However, remote clients who join a session will have their own local view of the session, and this view does not automatically receive data updates about the back-end version. It is not required, but can be beneficial for remote clients to keep their local view in sync with the back-end session by mirroring the following function calls:
-
EOS_Sessions_StartSession
-
EOS_Sessions_EndSession
-
EOS_Sessions_RegisterPlayers
-
EOS_Sessions_UnregisterPlayers
These functions will modify the local state of the session on remote (non-owner) clients without affecting the back-end service's version.
Enforcing Sanctions
If you are using EOS Sanctions, then you can enforce sanctions when players attempt to join or register with the session. See the Sanctions Interface documentation for more information on sanctions.
Sanctioned players may neither join nor register with a session that has sanctions enabled. This includes sanctioned sessions that the player creates themselves; they are still not able to join those sessions if they are a sanctioned player.
Sanctions are enforced through the Sessions Interface. Sanctions enforcement is enabled at session creation based on the value of the bSanctionsEnabled
member in the EOS_Sessions_CreateSessionModificationOptions
structure. If bSanctionsEnabled
is true, then the created session enforces sanctions. See the Creating a Session section for more information.
If a player has a RESTRICT_GAME_ACCESS
sanction, they are automatically kicked from multiplayer sessions in games protected by Anti-Cheat. See the documentation on Anti-cheat for more information.
The EOS_Sessions_JoinSession
function does not join a player with a RESTRICT_MATCHMAKING
sanction, and it returns the error EOS_Sessions_PlayerSanctioned
on any attempt to do so. However, the function EOS_Sessions_RegisterPlayers
supports multiple players, and, unlike EOS_Sessions_JoinSession
, it does not return an error when one or more sanctioned players attempts to register with a session that has sanctions enabled. Instead, you must check the response object to ensure that all players are registered. If the session has sanctions enabled, any sanctioned players who failed to register are listed in the SanctionedPlayers
member of the callback result struct EOS_Sessions_RegisterPlayersCallbackInfo
. See the Registering a Player section for more details.
Usage Limitations
Users can host, find, and interact with online gaming sessions through the Sessions Interface. A session can be short, like filling a certain number of player slots before starting a game, then disbanding after the game ends. Or it can be longer, like keeping track of a game that cycles through matches on multiple maps or levels. The Sessions Interface also manages game-specific data that supports the back-end service searching and matchmaking functionality.
For general information about throttling, usage quotas, and best practices, see Service Usage Limitations.
The following general limitations apply to sessions:
Feature | Limitation |
---|---|
Concurrent players | 1000 per session |
Session attributes | 100 per session |
Attribute name length | 1000 characters |
User interaction with the Sessions Interface must respect the following limitations:
Feature | Limitation | Per-Deployment Limitation |
---|---|---|
Create a session | 30 requests per minute | 30 request per 1 CCU per minute |
Delete a session | 30 requests per minute | 30 request per 1 CCU per minute |
Update a session | 30 requests per minute | 30 request per 1 CCU per minute |
Add or remove players | 100 requests per minute | 30 request per 1 CCU per minute |
Start or stop a session | 30 requests per minute | 30 request per 1 CCU per minute |
Invite a user | 100 requests per minute | 30 request per 1 CCU per minute |
Filter sessions | 30 requests per minute | 30 request per 1 CCU per minute |
Additionally, there are per-user rate limitations. Consider the following limitations to avoid throttling:
Feature | User Limit |
---|---|
Amount of sessions a single user can join at once | 16 |
Matchmaking Security Considerations
Matchmaking functionality requires that you take a set of information such as player identifiers or server IP address and broadcast that data to other potential players. Typically session data consists of:
-
A Host IP Address, set either using
EOS_SessionModification_SetHostAddress
or automatically detected by EOS services. This address is mandatory when attempting to join the game. -
The EOS Product User ID of all players registered to the session.
-
Any custom attributes that have been added to the session using
EOS_SessionModification_AddAttribute
. These could be anything set by the developer.
Matchmaking takes game data and creates a searchable index, so you should always be conscious of what data is being exposed when creating your sessions. For games with dedicated servers you are exposing the IP address of the server, and for Peer to Peer sessions you could be exposing the IP address of end users.
Note: If you have security concerns about exposing the host IP address, you can use EOS_SessionModification_SetHostAddress
to set the host address to something else, such as the P2P socket ID if you use the P2P Interface.
When you create a session you can specify a permission level for the session using EOS_SessionModification_SetPermissionLevel
. Sessions have 3 levels of security:
Security Level | Description |
---|---|
EOS_OSPF_PublicAdvertised | Any client can get the session in search results without needing to know the session id and can read session information as long as the session is not started or session allows join in progress. Any client/player that has access to the unique session identifier can view session information even if the session is not joinable. Players can also find the session using a registered player's ID, as long as the registered player is in a public session. |
EOS_OSPF_JoinViaPresence | Any client/player that has access to the unique session identifier can view session information (typically this information is shared via presence data but can be shared in other ways as well). |
EOS_OSPF_InviteOnly | Only players which have been explicitly invited to the session by an existing member of the session can view session information. |
Best Practices
-
Make sure your sessions are scoped to the lowest amount of exposure necessary.
-
Don’t add information to session attributes that should not be exposed to everyone that is looking for the session.
-
If you are using JoinViaPresence then make sure to keep the session id hidden from players/UI. If it is exposed then it will allow access to the session data.
-
If your game doesn’t support JoinInProgress, make sure your server starts the session with EOS_Sessions_StartSession to remove the session from future searches while the game is in progress.
FAQ
Q: Why can't I find the server that I just created?
A: Indexing takes two seconds to refresh, so you might not be able to find your server immediately.
Q: Why can't I see the same list of servers as my co-worker or friend?
A: Matchmaking has a two-second delay to ensure that no two people get the same list of servers at the same time. This deliberate jittering avoids race conditions that can affect the efficiency of the servers.
Q: I want to see the sessions that are set up in my game. How can I see all the sessions in my game?
A: You can find the list of sessions in your game in the Developer Portal. Sign in to the Developer Portal (at dev.epicgames.com/portal), and select your product under the Products section in the left sidebar. Go to Game Services > MULTIPLAYER > Matchmaking.