Social Overlay Integration

Accessing the EOS social overlay and friends list from in-game

The Social Overlay is an Epic Online Services (EOS) UI that can be accessed in-game. The default integration accesses the Social Overlay using Shift+F3. The main feature that the Social Overlay provides is a Friends List, which provides game management and player presence. Game management allows players to invite friends to their game session or to join friends who are already in a game session. Player presence provides details about their online state, active game, and any game-defined, rich presence text.

Using Player Presence in the Friends List

The Presence Service maintains a presence state that is shared with all of the user's friends who are online, and updated anytime it changes. A player's login state is used to initialize and clear their online state. The ProductName provided to EOS_Initialize is used to identify the game they are playing. The service will also share any RichText provided to EOS_PresenceModification_SetRawRichText.

Online State

The player's online state is set to Online or Offline when a player connects or disconnects from the EOS services using EOS_Auth_Login and EOS_Auth_Logout. The EOS_PresenceModification_SetStatus API can be used to provide a more discrete status.

Active Game

Active Game

The displayed game name will be shared directly from the ProductName provided to EOS_Initialize. This should be the product name as defined by the host's language settings.

Rich Presence Text

Active Game Rich Presence Text

The rich presence text should provide some game context to other players. The string provided to EOS_PresenceModification_SetRawRichText will be shared as is.

Using Game Management in the Friends List

The game management interface provides a Join button and an Invite button. The exact way these are integrated is up to the game and how it uses the Sessions Service. The game will also need to use the Connect APIs to associate the player's account with the Sessions Service.

The Join Button

Join Button

The Join button enables players to join a friend's game. To make the game visible to other players, it must set up the Join Info String of the player using EOS_PresenceModification_SetJoinInfo. This will allow the Presence Service to transmit this to all friends. The game is free to define the meaning of the Location String as needed. One possible implementation is to use a Session ID from the Sessions Service.

The game then uses EOS_Presence_AddNotifyJoinGameAccepted to know when the player clicks the Join button. The callback data will contain the Location String. It is expected that the game will honor this intent for the user after any cleanup of the current state.

The Invite Button

Invite Button

The Invite button enables players to invite friends to their game. When the Invite button is clicked, the Social Overlay transmits an invite through the Sessions Interface on behalf of the user and the game using EOS_Sessions_SendInvite. The game uses EOS_Sessions_AddNotifySessionInviteAccepted to know when the player clicks Accept in the overlay. The callback data contains the Session ID, which you can use to locate the information about the game within the Sessions Interface. Like Join, the game should make the best effort to honor the intent of the user.

Caveats

The Invite button will not be available if the current session is full, and it will be disabled if two users are in the same session. It is up to the game to maintain the state of the session via the (Un)RegisterPlayer API calls, and the Location String must also be maintained to reflect the current state of the joinability of the game. It is possible to override the invite state via session modifications that mutate the "allow invites" state of the session.

The overlay does not handle race conditions. Accepting an invite does not imply that the user will be able to successfully join the session, only that it is very likely. The game is still responsible, via other mechanisms, for enforcing or moderating the act of clients joining the host, such as when two clients accept an invite at exactly the same time for only one slot.

The lifetime of an invite is tied to the session it is a part of, not the user who sent the invite. It is possible for a user to leave a session and have their friend join that session long after they have gone. The invite is destroyed when the session it is tied to is over. The state of the invite is not reflected in the social overlay, and it is possible for the call to fail. The overlay will present any errors that occur as a message box.