sessions - YoYoGames/GMEXT-EpicOnlineServices GitHub Wiki

Sessions

Epic Online Services Interface: Sessions Interface

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 documentation: Security Considerations section.

Note

See the Sessions Introduction for a more detailed guide.

Session Handles

Sessions in Epic Online Services make use of session handles. Before you can use certain functions you need to obtain a valid handle for that which you're trying to do. The handles themselves are kept by the extension. However, whenever you request a handle, you should still manually release it afterwards, once you are done using it.

The following is an overview of the different session handles and the functions you can use to obtain and release them and the functions that require them.

OutSessionSearchHandle

SessionDetails

SessionModification

Functions

This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.

Structs

This module offers a collection of structs, which serve as custom data models for organizing and structuring data. Explore the provided structs to better understand the relationships between data elements and simplify your data manipulation tasks.

Constants

This module includes a set of predefined constants that can be utilized for various purposes. Browse through the available constants to find values relevant to your needs and enhance the efficiency of your code.


Back To Top

eos_active_session_copy_info

Epic Online Services Function: EOS_ActiveSession_CopyInfo

This function is used to immediately retrieve a copy of active session information. The returned struct will be empty if the result is not EOS_RESULT.SUCCESS.


Syntax:

eos_active_session_copy_info(session_name)
Argument Type Description
session_name String The name of the session



Returns:

ActiveSessionInfo



Back To Top

eos_active_session_get_registered_player_by_index

Epic Online Services Function: EOS_ActiveSession_GetRegisteredPlayerByIndex

This function is used to immediately retrieve individual players registered with the active session.


Syntax:

eos_active_session_get_registered_player_by_index(session_name, player_index)
Argument Type Description
session_name String The name of the session
player_index Real The index of the registered player to retrieve



Returns:

String



Back To Top

eos_active_session_get_registered_player_count

Epic Online Services Function: EOS_ActiveSession_GetRegisteredPlayerCount

This function gets the number of registered players associated with this active session. It returns the number of registered players in the active session or 0 if there is an error.


Syntax:

eos_active_session_get_registered_player_count(session_name)
Argument Type Description
session_name String The name of the session



Returns:

Real



Back To Top

eos_session_details_copy_info

Epic Online Services Function: EOS_SessionDetails_CopyInfo

This function is used to immediately retrieve a copy of session information from a given source such as a active session or a search result.


Syntax:

eos_session_details_copy_info()



Returns:

SessionDetails_Info



Back To Top

eos_session_details_copy_session_attribute_by_index

Epic Online Services Function: EOS_SessionDetails_CopySessionAttributeByIndex

This function is used to immediately retrieve a copy of session attribution from a given source such as a active session or a search result.


Syntax:

eos_session_details_copy_session_attribute_by_index(attr_index)
Argument Type Description
attr_index Real The index of the attribute to retrieve



Returns:

SessionAttribute



Back To Top

eos_session_details_copy_session_attribute_by_key

Epic Online Services Function: EOS_SessionDetails_CopySessionAttributeByKey

This function is used to immediately retrieve a copy of session attribution from a given source such as a active session or a search result.


Syntax:

eos_session_details_copy_session_attribute_by_key(attr_key)
Argument Type Description
attr_key String The name of the key to get the session attribution for



Returns:

SessionAttribute



Back To Top

eos_session_details_get_session_attribute_count

Epic Online Services Function: EOS_SessionDetails_GetSessionAttributeCount

This function gets the number of attributes associated with this session. It returns the number of attributes on the session or 0 if there is an error.


Syntax:

eos_session_details_get_session_attribute_count()



Returns:

Real



Back To Top

eos_session_details_release

Epic Online Services Function: EOS_SessionDetails_Release

This function releases the memory associated with a single session. This must be called on data retrieved from eos_session_search_copy_search_result_by_index.


Syntax:

eos_session_details_release()



Returns:

N/A



Back To Top

eos_session_modification_add_attribute

Epic Online Services Function: EOS_SessionModification_AddAttribute

This function associates an attribute with this session. An attribute is something that may or may not be advertised with the session. If advertised, it can be queried for in a search, otherwise the data remains local to the client.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INVALID_PARAMETERS if the attribution is missing information or otherwise invalid
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_modification_add_attribute(type, attribute)
Argument Type Description
type EOS_SESSION_ATTRIBUTE_ADVERTISEMENT_TYPE Whether this attribute is advertised with the backend or simply stored locally
attribute Struct A struct with two variables key and value, representing the key/value pair that describes the attribute to add to the session



Returns:

EOS_RESULT



Back To Top

eos_session_modification_release

Epic Online Services Function: EOS_SessionModification_Release

This function releases the memory associated with session modification. This must be called on data retrieved from eos_sessions_create_session_modification or eos_sessions_update_session_modification.


Syntax:

eos_session_modification_release()



Returns:

N/A



Back To Top

eos_session_modification_remove_attribute

Epic Online Services Function: EOS_SessionModification_RemoveAttribute

This function removes an attribute from this session.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if removing this parameter was successful
  • EOS_RESULT.INVALID_PARAMETERS if the key is empty
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_modification_remove_attribute(key)
Argument Type Description
key String The session attribute to remove from the session



Returns:

EOS_RESULT



Back To Top

eos_session_modification_set_allowed_platform_ids

Epic Online Services Function: EOS_SessionModification_SetAllowedPlatformIds

This function sets the Allowed Platform IDs for the session.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect
  • EOS_RESULT.INVALID_PARAMETERS if the attribution is missing information or otherwise invalid

Syntax:

eos_session_modification_set_allowed_platform_ids(array_ids)
Argument Type Description
array_ids Array of EOS_ONLINE_PLATFORM_TYPE An array of platform IDs indicating the player platforms allowed to register with the session. The session will be unrestricted if you pass undefined.



Returns:

EOS_RESULT



Back To Top

eos_session_modification_set_bucket_id

Epic Online Services Function: EOS_SessionModification_SetBucketId

This function sets the bucket ID associated with this session. Values such as region, game mode, etc., can be combined here depending on game need. Setting this is strongly recommended to improve search performance.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INVALID_PARAMETERS if the bucket ID is invalid
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_modification_set_bucket_id(bucket_id)
Argument Type Description
bucket_id String The new bucket ID associated with the session



Returns:

EOS_RESULT



Back To Top

eos_session_modification_set_host_address

Epic Online Services Function: EOS_SessionModification_SetHostAddress

This function sets the host address associated with this session. Setting this is optional, if the value is not set, the SDK will fill the value in from the service. It is useful to set if other addressing mechanisms are desired or if LAN addresses are preferred during development.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INVALID_PARAMETERS if the host ID is an empty string
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Note

No validation of this value occurs to allow for flexibility in addressing methods.


Syntax:

eos_session_modification_set_host_address(host_address)
Argument Type Description
host_address String A string representing the host address for the session, its meaning is up to the application



Returns:

EOS_RESULT



Back To Top

eos_session_modification_set_invites_allowed

Epic Online Services Function: EOS_SessionModification_SetInvitesAllowed

This function allows enabling or disabling invites for this session. The session will also need to have presence_enabled true.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_modification_set_invites_allowed(invites_allowed)
Argument Type Description
invites_allowed Boolean If true then invites can currently be sent for the associated session



Returns:

EOS_RESULT



Back To Top

eos_session_modification_set_join_in_progress_allowed

Epic Online Services Function: EOS_SessionModification_SetJoinInProgressAllowed

This function sets whether or not join in progress is allowed. Once a session is started, it will no longer be visible to search queries unless this flag is set or the session returns to the pending or ended state.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_modification_set_join_in_progress_allowed(allow_join_in_progress)
Argument Type Description
allow_join_in_progress Boolean Whether the session allows join in progress



Returns:

EOS_RESULT



Back To Top

eos_session_modification_set_max_players

Epic Online Services Function: EOS_SessionModification_SetMaxPlayers

This function sets the maximum number of players allowed in this session. When updating the session, it is not possible to reduce this number below the current number of existing players.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_modification_set_max_players(max_players)
Argument Type Description
max_players Real The max number of players to allow in the session



Returns:

EOS_RESULT



Back To Top

eos_session_modification_set_permission_level

Epic Online Services Function: EOS_SessionModification_SetPermissionLevel

This function sets the session permissions associated with this session. The permissions range from "public" to "invite only" and are described by EOS_ONLINE_SESSION_PERMISSION_LEVEL.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this parameter was successful
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_modification_set_permission_level(permission_level)
Argument Type Description
permission_level EOS_ONLINE_SESSION_PERMISSION_LEVEL The permission level to set on the session



Returns:

EOS_RESULT



Back To Top

eos_sessions_add_notify_join_session_accepted

Epic Online Services Function: EOS_Sessions_AddNotifyJoinSessionAccepted

This function registers to receive notifications when a user accepts a session join game via the social overlay.

Note

If the returned notification ID is valid, you must call eos_sessions_remove_notify_join_session_accepted when you no longer wish to have the Social Async Event called.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_add_notify_join_session_accepted()



Returns:

Int64


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_add_notify_join_session_accepted"
local_user_id String The Product User ID for the user who initialized the game
ui_event_id Int64 The UI Event associated with this Join Game event. This should be used with eos_sessions_copy_session_handle_by_ui_event_id to get a handle to be used when calling eos_sessions_join_session.


Back To Top

eos_sessions_add_notify_leave_session_requested

Epic Online Services Function: EOS_Sessions_AddNotifyLeaveSessionRequested

This function registers to receive notifications about leave session requests performed by local user via the overlay. When user requests to leave the session in the social overlay, the SDK does not automatically leave the session, it is up to the game to perform any necessary cleanup and call the eos_sessions_destroy_session method using the session_name sent in the notification function.

Note

If the returned notification ID is valid, you must call eos_sessions_remove_notify_join_session_accepted when you no longer wish to have the Social Async Event called.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_add_notify_leave_session_requested()



Returns:

Int64


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_add_notify_leave_session_requested"
local_user_id String The Product User ID of the local user who received the leave session notification.
session_name String The name of the session associated with the leave session request.


Back To Top

eos_sessions_add_notify_send_session_native_invite_requested

Epic Online Services Function: EOS_Sessions_AddNotifySendSessionNativeInviteRequested

This function registers to receive notifications about a session "INVITE" performed by a local user via the overlay. This is only needed when a configured integrated platform has EOS_IPMF_DisableSDKManagedSessions set. The EOS SDK will then use the state of EOS_IPMF_PreferEOSIdentity and EOS_IPMF_PreferIntegratedIdentity to determine when the Social Async Event is triggered.

Note

If the returned notification ID is valid, you must call eos_sessions_remove_notify_join_session_accepted when you no longer wish to have the Social Async Event called.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_add_notify_send_session_native_invite_requested()



Returns:

Int64


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_add_notify_send_session_native_invite_requested"
local_user_id String The Product User ID of the local user who is inviting
target_native_account_type String The Native Platform Account Type. If only a single integrated platform is configured then this will always reference that platform.
target_user_native_account_id String The Native Platform Account ID of the target user being invited
session_id String The session ID that the user is being invited to
ui_event_id Int64 Identifies this event which will need to be acknowledged with eos_ui_acknowledge_event_id.


Back To Top

eos_sessions_add_notify_session_invite_accepted

Epic Online Services Function: EOS_Sessions_AddNotifySessionInviteAccepted

This function registers to receive notifications when a user accepts a session invite via the social overlay.

Note

If the returned notification ID is valid, you must call eos_sessions_remove_notify_join_session_accepted when you no longer wish to have the Social Async Event called.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_add_notify_session_invite_accepted()



Returns:

Int64


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_add_notify_session_invite_accepted"
local_user_id String The Product User ID of the user who accepted the invitation
invite_id String The invite ID that was accepted
session_id String The session ID that should be used for joining
target_user_id String The Product User ID of the user who sent the invitation


Back To Top

eos_sessions_add_notify_session_invite_rejected

Epic Online Services Function: EOS_Sessions_AddNotifySessionInviteRejected

This function registers to receive notifications when a user rejects a session invite.

Note

If the returned notification ID is valid, you must call eos_sessions_remove_notify_join_session_accepted when you no longer wish to have the Social Async Event called.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_add_notify_session_invite_rejected()



Returns:

Int64


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_add_notify_session_invite_rejected"
invite_id String The invite ID
target_user_id String The Product User ID of the user who sent the invitation
session_id String Session ID
local_user_id String The Product User ID of the local user who rejected the invitation


Back To Top

eos_sessions_copy_session_handle_by_invite_id

Epic Online Services Function: EOS_Sessions_CopySessionHandleByInviteId

This function is used to immediately retrieve a handle to the session information from after notification of an invite. If the call returns an EOS_RESULT.SUCCESS result, a handle has been created and you need to manually free it afterwards by calling eos_session_details_release to release the memory associated with it.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if the information is available
  • EOS_RESULT.INVALID_PARAMETERS if you pass an invalid invite ID
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect
  • EOS_RESULT.NOT_FOUND if the invite ID cannot be found

Syntax:

eos_sessions_copy_session_handle_by_invite_id(invite_id)
Argument Type Description
invite_id String The invite ID for which to retrieve a session handle



Returns:

EOS_RESULT



Back To Top

eos_sessions_copy_session_handle_by_ui_event_id

Epic Online Services Function: EOS_Sessions_CopySessionHandleByUiEventId

This function is used to immediately retrieve a handle to the session information from after notification of a join game event. If the call returns an EOS_RESULT.SUCCESS result, a handle has been created and you need to manually free it afterwards by calling eos_session_details_release to release the memory associated with it.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if the information is available
  • EOS_RESULT.INVALID_PARAMETERS if you pass an invalid invite ID
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect
  • EOS_RESULT.NOT_FOUND if the invite ID cannot be found

Syntax:

eos_sessions_copy_session_handle_by_ui_event_id(ui_event_id)
Argument Type Description
ui_event_id Int64 The UI Event associated with the session



Returns:

EOS_RESULT



Back To Top

eos_sessions_copy_session_handle_for_presence

Epic Online Services Function: EOS_Sessions_CopySessionHandleForPresence

This function is used to immediately retrieve a handle to the session information which was marked with presence_enabled on create or join. If the call returns an EOS_RESULT.SUCCESS result, a handle has been created and you need to manually free it afterwards by calling eos_session_details_release to release the memory associated with it.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if the information is available
  • EOS_RESULT.INVALID_PARAMETERS if you pass an invalid invite ID
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect
  • EOS_RESULT.NOT_FOUND if there is no session with presence_enabled

Syntax:

eos_sessions_copy_session_handle_for_presence(local)
Argument Type Description
local String The Product User ID of the local user associated with the session



Returns:

EOS_RESULT



Back To Top

eos_sessions_create_session_modification

Epic Online Services Function: EOS_Sessions_CreateSessionModification

This function creates a session modification handle. The session modification handle is used to build a new session and can be applied with eos_sessions_update_session. The handle must be released by calling eos_session_modification_release once it is no longer needed.

The function returns EOS_RESULT.SUCCESS if we successfully created the session modification handle, or an error result if the input data was invalid.


Syntax:

eos_sessions_create_session_modification(allowed_platform_ids, presence_enabled, sanctions_enabled, bucket_id, local_user_id, max_players, session_id, session_name)
Argument Type Description
allowed_platform_ids Array of EOS_ONLINE_PLATFORM_TYPE An array of platform IDs indicating the player platforms allowed to register with the session. The session will be unrestricted if you pass undefined.
presence_enabled Boolean Determines whether or not this session should be the one associated with the local user's presence information. If true, this session will be associated with presence. Only one session at a time can have this flag set to true. This affects the ability of the Social Overlay to show game related actions to take in the user's social graph. * using the presence_enabled flags within the Sessions interface * using the presence_enabled flags within the Lobby interface * using eos_presence_modification_set_join_info.
sanctions_enabled Boolean If true, sanctioned players can neither join nor register with this session and, in the case of join, will return EOS_RESULT code EOS_RESULT.SESSIONS_PLAYER_SANCTIONED.
bucket_id String The bucket ID associated with the session
local_user_id String The Product User ID of the local user associated with the session
max_players Real The maximum number of players allowed in the session
session_id String An optional session ID - set to a globally unique value to override the backend assignment. If not specified, the backend service will assign one to the session. Do not mix and match. This value can be of size [EOS_SESSIONMODIFICATION_MIN_SESSIONIDOVERRIDE_LENGTH, EOS_SESSIONMODIFICATION_MAX_SESSIONIDOVERRIDE_LENGTH]
session_name String The name of the session to create



Returns:

EOS_RESULT



Back To Top

eos_sessions_create_session_search

Epic Online Services Function: EOS_Sessions_CreateSessionSearch

This function creates a session search handle. This handle may be modified to include various search parameters. Searching is possible in three methods, all mutually exclusive:

  • set the session ID to find a specific session
  • set the target user ID to find a specific user
  • set session parameters to find an array of sessions that match the search criteria

The function returns one of the following:

  • EOS_RESULT.SUCCESS if the search creation completes successfully
  • EOS_RESULT.INVALID_PARAMETERS if any of the options are incorrect

Syntax:

eos_sessions_create_session_search()



Returns:

EOS_RESULT



Back To Top

eos_sessions_destroy_session

Epic Online Services Function: EOS_Sessions_DestroySession

This function destroys a session given a session name.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_destroy_session(session_name)
Argument Type Description
session_name String The name of the session to destroy



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_destroy_session"
status EOS_RESULT The result of the function call
status_message String Text representation of the status code
identifier Real The identifier returned in the original call to the function


Back To Top

eos_sessions_dump_session_state

Epic Online Services Function: EOS_Sessions_DumpSessionState

This function dumps the contents of active sessions that exist locally to the log output, purely for debug purposes.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if the output operation completes successfully
  • EOS_RESULT.NOT_FOUND if the session specified does not exist
  • EOS_RESULT.INVALID_PARAMETERS if any of the options are incorrect

Syntax:

eos_sessions_dump_session_state(session_name)
Argument Type Description
session_name String The name of the session



Returns:

EOS_RESULT



Back To Top

eos_sessions_end_session

Epic Online Services Function: EOS_Sessions_EndSession

This function marks a session as ended, making it available to find if "join in progress" was disabled. The session may be started again if desired.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_end_session(session_name)
Argument Type Description
session_name String The name of the session to set as no longer in progress



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_end_session"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned in the original call to the function


Back To Top

eos_sessions_get_invite_count

Epic Online Services Function: EOS_Sessions_GetInviteCount

This function gets the number of known invites for a given user. It returns the number of known invites for a given user or 0 if there is an error.


Syntax:

eos_sessions_get_invite_count(local)
Argument Type Description
local String The Product User ID of the local user who has one or more invitations in the cache



Returns:

Real



Back To Top

eos_sessions_get_invite_id_by_index

Epic Online Services Function: EOS_Sessions_GetInviteIdByIndex

This function retrieves an invite ID from a list of active invites for a given user.


Syntax:

eos_sessions_get_invite_id_by_index(local_user_id, index)
Argument Type Description
local_user_id String The Product User ID of the local user who has an invitation in the cache
index Real The index of the invite ID to retrieve



Returns:

String



Back To Top

eos_sessions_is_user_in_session

Epic Online Services Function: EOS_Sessions_IsUserInSession

This function returns whether or not a given user can be found in a specified session.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if the user is found in the specified session
  • EOS_RESULT.NOT_FOUND if the user is not found in the specified session
  • EOS_RESULT.INVALID_PARAMETERS if you pass an invalid invite ID
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect
  • EOS_RESULT.INVALID_PRODUCT_USER_ID if an invalid target user is specified
  • EOS_RESULT.SESSIONS_INVALID_SESSION if the session specified is invalid

Syntax:

eos_sessions_is_user_in_session(session_name, target_user_id)
Argument Type Description
session_name String The active session name to search within
target_user_id String The product User ID to search for in the session



Returns:

EOS_RESULT



Back To Top

eos_sessions_join_session

Epic Online Services Function: EOS_Sessions_JoinSession

This function joins a session, creating a local session under a given session name. The backend will validate various conditions to make sure it is possible to join the session.

The function returns the async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_join_session(presence_enabled, local_user_id, session_name)
Argument Type Description
presence_enabled Boolean Determines whether or not this session should be the one associated with the local user's presence information. If true, this session will be associated with presence. Only one session at a time can have this flag true. This affects the ability of the Social Overlay to show game related actions to take in the user's social graph. * using the presence_enabled flags within the Sessions interface * using the presence_enabled flags within the Lobby interface * using eos_presence_modification_set_join_info
local_user_id String The Product User ID of the local user who is joining the session
session_name String Name of the session to create after joining session



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_join_session"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function


Back To Top

eos_sessions_query_invites

Epic Online Services Function: EOS_Sessions_QueryInvites

This function retrieves all existing invites for a single user.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_query_invites(target_user_id)
Argument Type Description
target_user_id String The Product User ID to query for invitations



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_query_invites"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function
local_user_id String The Product User of the local user who made the request


Back To Top

eos_sessions_register_players

Epic Online Services Function: EOS_Sessions_RegisterPlayers

This function registers a group of players with the session, allowing them to invite others or otherwise indicate they are part of the session for determining a full session.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_register_players(session_name, array_product_user_ids)
Argument Type Description
session_name String The name of the session for which to register players
array_product_user_ids Array Array of players to register with the session



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_register_players"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function
registered_players Array of String The players that were successfully registered
sanctioned_players Array of String The players that failed to register because they are sanctioned


Back To Top

eos_sessions_reject_invite

Epic Online Services Function: EOS_Sessions_RejectInvite

This function rejects an invite from another player.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_reject_invite(local_user_id, invite_id)
Argument Type Description
local_user_id String The Product User ID of the local user rejecting the invitation
invite_id String The invite ID to reject



Returns:

N/A


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_reject_invite"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function


Back To Top

eos_sessions_remove_notify_join_session_accepted

Epic Online Services Function: EOS_Sessions_RemoveNotifyJoinSessionAccepted

This function unregisters from receiving notifications when a user accepts a session join game via the social overlay.


Syntax:

eos_sessions_remove_notify_join_session_accepted(notification_id)
Argument Type Description
notification_id Real A handle representing the registered callback



Returns:

N/A



Back To Top

eos_sessions_remove_notify_leave_session_requested

Epic Online Services Function: EOS_Sessions_RemoveNotifyLeaveSessionRequested

This function unregisters from receiving notifications when a user performs a leave lobby action via the overlay.


Syntax:

eos_sessions_remove_notify_leave_session_requested(notification_id)
Argument Type Description
notification_id Real A handle representing the registered callback



Returns:

N/A



Back To Top

eos_sessions_remove_notify_send_session_native_invite_requested

Epic Online Services Function: EOS_Sessions_RemoveNotifySendSessionNativeInviteRequested

This function unregisters from receiving notifications when a user requests a send invite via the overlay.


Syntax:

eos_sessions_remove_notify_send_session_native_invite_requested(notification_id)
Argument Type Description
notification_id Real A handle representing the registered callback



Returns:

N/A



Back To Top

eos_sessions_remove_notify_session_invite_accepted

Epic Online Services Function: EOS_Sessions_RemoveNotifySessionInviteAccepted

This function unregisters from receiving notifications when a user accepts a session invite via the social overlay.


Syntax:

eos_sessions_remove_notify_session_invite_accepted(notification_id)
Argument Type Description
notification_id Real A handle representing the registered callback



Returns:

N/A



Back To Top

eos_sessions_remove_notify_session_invite_received

Epic Online Services Function: EOS_Sessions_RemoveNotifySessionInviteReceived

This function unregisters from receiving session invites.


Syntax:

eos_sessions_remove_notify_session_invite_received(notification_id)
Argument Type Description
notification_id Real A handle representing the registered callback



Returns:

N/A



Back To Top

eos_sessions_remove_notify_session_invite_rejected

Epic Online Services Function: EOS_Sessions_RemoveNotifySessionInviteReceived

This function unregisters from receiving notifications when a user rejects a session invite via the social overlay.


Syntax:

eos_sessions_remove_notify_session_invite_rejected(notification_id)
Argument Type Description
notification_id Real A handle representing the registered callback



Returns:

N/A



Back To Top

eos_sessions_send_invite

Epic Online Services Function: EOS_Sessions_SendInvite

This function sends an invite to another player. User must have created the session or be registered in the session or else the call will fail.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_send_invite(local_user_id, session_name, target_user_id)
Argument Type Description
local_user_id String The Product User ID of the local user sending the invitation
session_name String The name of the session associated with the invite
target_user_id String The Product User of the remote user receiving the invitation



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_send_invite"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function


Back To Top

eos_sessions_start_session

Epic Online Services Function: EOS_Sessions_StartSession

This function marks a session as started, making it unable to find if session properties indicate "join in progress" is not available.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_start_session(session_name)
Argument Type Description
session_name String The name of the session to set in progress



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_start_session"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function


Back To Top

eos_sessions_unregister_players

Epic Online Services Function: EOS_Sessions_UnregisterPlayers

This function unregisters a group of players with the session, freeing up space for others to join.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_unregister_players(session_name, array_product_user_ids)
Argument Type Description
session_name String The name of the session for which to unregister players
array_product_user_ids Array An array of players to unregister from the session



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_unregister_players"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function
unregistered_players Array of String The players that successfully unregistered


Back To Top

eos_sessions_update_session

Epic Online Services Function: EOS_Sessions_UpdateSession

This function updates a session given a session modification handle created by eos_sessions_create_session_modification or eos_sessions_update_session_modification.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_sessions_update_session()



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_sessions_update_session"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function
session_id String ID of the session that was created/modified
session_name String Name of the session that was created/modified


Back To Top

eos_sessions_update_session_modification

Epic Online Services Function: EOS_Sessions_UpdateSessionModification

This function creates a session modification handle. The session modification handle is used to modify an existing session and can be applied with eos_sessions_update_session. The handle must be released by calling eos_session_modification_release once it is no longer needed.

The function returns EOS_RESULT.SUCCESS if the session modification handle could be successfully created, or an error result if the input data was invalid.


Syntax:

eos_sessions_update_session_modification(session_name)
Argument Type Description
session_name String The name of the session to update



Returns:

EOS_RESULT



Back To Top

eos_session_search_copy_search_result_by_index

Epic Online Services Function: EOS_SessionSearch_CopySearchResultByIndex

This function is used to immediately retrieve a handle to the session information from a given search result. If the call returns an EOS_RESULT.SUCCESS result, a handle has been created and you need to manually free it afterwards by calling eos_session_details_release to release the memory associated with it.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if the information is available
  • EOS_RESULT.INVALID_PARAMETERS if you pass an invalid index
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_search_copy_search_result_by_index(session_index)
Argument Type Description
session_index Real The index of the session to retrieve within the completed search query



Returns:

EOS_RESULT



Back To Top

eos_session_search_find

Epic Online Services Function: EOS_SessionSearch_Find

This function finds sessions matching the search criteria set up via this session search handle. When the operation completes, this handle will have the search results that can be parsed.

The function returns an async identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

eos_session_search_find(local_user_id)
Argument Type Description
local_user_id String The Product User ID of the local user who is searching



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String the string "eos_session_search_find"
status EOS_RESULT The result code for the operation. EOS_RESULT.SUCCESS indicates that the operation succeeded; other codes indicate errors.
status_message String Text representation of the status code
identifier Real The identifier returned by the original call to the function


Back To Top

eos_session_search_get_search_result_count

Epic Online Services Function: EOS_SessionSearch_GetSearchResultCount

This function gets the number of search results found by the search parameters in this search. It returns the number of search results found by the query or 0 if the search is not complete.


Syntax:

eos_session_search_get_search_result_count()



Returns:

Real



Back To Top

eos_session_search_release

Epic Online Services Function: EOS_SessionSearch_Release

This function releases the memory associated with a session search. This must be called on data retrieved from eos_sessions_create_session_search.


Syntax:

eos_session_search_release()



Returns:

N/A



Back To Top

eos_session_search_remove_parameter

Epic Online Services Function: EOS_SessionSearch_RemoveParameter

This function removes a parameter from the array of search criteria.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if removing this search parameter was successful
  • EOS_RESULT.INVALID_PARAMETERS if the search key is invalid
  • EOS_RESULT.NOT_FOUND if the parameter was not a part of the search criteria
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_search_remove_parameter(key, comparison_op)
Argument Type Description
key String The search parameter key to remove from the search
comparison_op EOS_COMPARISON_OP The search comparison operation associated with the key to remove



Returns:

EOS_RESULT



Back To Top

eos_session_search_set_max_results

Epic Online Services Function: EOS_SessionSearch_SetMaxResults

This function sets the maximum number of search results to return in the query, can't be more than EOS_SESSIONS_MAX_SEARCH_RESULTS.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting the max results was successful
  • EOS_RESULT.INVALID_PARAMETERS if the number of results requested is invalid
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_search_set_max_results(max_search_results)
Argument Type Description
max_search_results Real The maximum number of search results returned with this query, may not exceed EOS_SESSIONS_MAX_SEARCH_RESULTS



Returns:

EOS_RESULT



Back To Top

eos_session_search_set_parameter

Epic Online Services Function: EOS_SessionSearch_SetParameter

This function adds a parameter to an array of search criteria combined via an implicit AND operator. Setting SessionId or TargetUserId will result in eos_session_search_find failing.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this search parameter was successful
  • EOS_RESULT.INVALID_PARAMETERS if the search criteria is invalid
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_search_set_parameter(comparison_op, attribute)
Argument Type Description
comparison_op EOS_COMPARISON_OP The type of comparison to make against the search parameter
attribute Struct A struct with two variables key and value, representing the key/value pair that describes the search parameter



Returns:

EOS_RESULT



Back To Top

eos_session_search_set_session_id

Epic Online Services Function: EOS_SessionSearch_SetSessionId

This function sets a session ID to find and will return at most one search result. Setting TargetUserId or SearchParameters will result in eos_session_search_find failing.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this session ID was successful
  • EOS_RESULT.INVALID_PARAMETERS if the session ID is invalid
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_search_set_session_id(session_id)
Argument Type Description
session_id String Search sessions for a specific session ID, returning at most one session



Returns:

EOS_RESULT



Back To Top

eos_session_search_set_target_user_id

Epic Online Services Function: EOS_SessionSearch_SetTargetUserId

This function sets a target user ID to find and will return at most one search result. Setting SessionId or SearchParameters will result in eos_session_search_find failing.

Note

A search result will only be found if this user is in a public session.

The function returns one of the following:

  • EOS_RESULT.SUCCESS if setting this target user ID was successful
  • EOS_RESULT.INVALID_PARAMETERS if the target user ID is invalid
  • EOS_RESULT.INCOMPATIBLE_VERSION if the API version passed in is incorrect

Syntax:

eos_session_search_set_target_user_id(target_user_id)
Argument Type Description
target_user_id String The Product User ID to find; return any sessions where the user matching this ID is currently registered



Returns:

EOS_RESULT



Back To Top

EOS_ATTRIBUTE_TYPE

This enumeration holds the supported types of data that can be stored inside an attribute (used by sessions/lobbies/etc.).


Member Description
BOOLEAN A boolean value (true/false)
INT64 A 64 bit integer
DOUBLE A double precision floating point value
STRING A UTF-8 string

Back To Top

EOS_ONLINE_SESSION_STATE

Epic Online Services Enum: EOS_EOnlineSessionState

This enum contains all possible states of an existing named session.

These constants are referenced by the following structs:


Member Description
NO_SESSION An online session has not been created yet
CREATING An online session is in the process of being created
PENDING Session has been created but the session hasn't started (pre match lobby)
STARTING Session has been asked to start (may take time due to communication with backend)
IN_PROGRESS The current session has started. Sessions with join in progress disabled are no longer joinable
ENDING The session is still valid, but the session is no longer being played (post match lobby)
ENDED The session is closed and any stats committed
DESTROYING The session is being destroyed

Back To Top

EOS_SESSION_ATTRIBUTE_ADVERTISEMENT_TYPE

Epic Online Services Enum: EOS_ESessionAttributeAdvertisementType

This enum holds the possible advertisement properties for a single attribute associated with a session.

These constants are referenced by the following functions:

These constants are referenced by the following structs:


Member Description
DONT_ADVERTISE Don't advertise via the online service
ADVERTISE Advertise via the online service only

Back To Top

EOS_ONLINE_SESSION_PERMISSION_LEVEL

Epic Online Services Enum: EOS_EOnlineSessionState

This enum holds the possible permission levels for a session. The permission level gets more restrictive further down.

These constants are referenced by the following functions:

These constants are referenced by the following structs:


Member Description
PUBLIC_ADVERTISED Anyone can find this session as long as it isn't full
JOIN_VIA_PRESENCE Players who have access to presence can see this session
INVITE_ONLY Only players with invites registered can see this session

Back To Top

EOS_SESSIONS_MAX_SEARCH_RESULTS

This macro defines the maximum number of session search results.



Back To Top

ActiveSessionInfo

Epic Online Services Struct: EOS_ActiveSession_Info

This struct holds top level details about an active session.

This struct is referenced by the following functions:


Member Type Description
session_name String The name of the session
state EOS_ONLINE_SESSION_STATE The current state of the session
details SessionDetails_Info Details about the session
settings SessionDetails_Settings The session's settings

Back To Top

SessionDetails_Info

Epic Online Services Struct: EOS_SessionDetails_Info

This struct holds internal details about a session, found on both active sessions and within search results.

This struct is referenced by the following functions:

This struct is referenced by the following structs:


Member Type Description
host_address String The IP address of this session as visible by the backend service
num_open_public_connections Real The number of remaining open spaces on the session (num_public_connections - registered_players)
owner_user_id String The Product User ID of the session owner. Pass an empty string "" if the session is not owned by a user.
owner_server_client_id String The client ID of the session owner. Pass an empty string "" if the session is not owned by a server. The session is owned by a server if EOS_Platform_Options::bIsServer is true.
session_id String The session ID assigned by the backend service
settings SessionDetails_Settings The additional settings associated with this session

Back To Top

SessionDetails_Settings

Epic Online Services Struct: EOS_SessionDetails_Settings

This struct holds common settings associated with a single session.

This struct is referenced by the following structs:


Member Type Description
allowed_platform_ids Array of EOS_ONLINE_PLATFORM_TYPE An array of platform IDs indicating the player platforms allowed to register with the session. The session will be unrestricted if you pass an empty array.
allow_join_in_progress Boolean Whether players are allowed to join the session while it is in the "in progress" state
invites_allowed Boolean Whether players are allowed to send invites for the session
sanctions_enabled Boolean Whether sanctioned players are allowed to join or not - sanctioned players will be rejected if set to true
bucket_id String The main indexed parameter for this session, can be any string (i.e. "Region:GameMode")
num_public_connections Real The number of total players allowed in the session
permission_level EOS_ONLINE_SESSION_PERMISSION_LEVEL The permission level describing allowed access to the session when joining or searching for the session

Back To Top

SessionAttribute

Epic Online Services Struct: EOS_SessionDetails_Attribute

This struct holds an attribution value and its advertisement setting stored with a session.

This struct is referenced by the following functions:


Member Type Description
advertisement_type EOS_SESSION_ATTRIBUTE_ADVERTISEMENT_TYPE Whether this attribution is advertised with the backend or simply stored locally
key String The name of the session attribute
value Any The value of the session attribute

GameMaker 2025

⚠️ **GitHub.com Fallback** ⚠️