If you plan on launching your game on consoles with Epic Account Services integration before October 2022, please contact us at eas-on-console-beta@epicgames.com to coordinate a release plan.
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.
Handling Exclusive Input Mode
While the Social Overlay (or any overlay managed by the EOS SDK such as checkout or authentication) is visible, there is a potential that all keyboard and mouse input will be consumed by the overlay. The overlay should only be visible due to user intent. Based on this intent, the user wishes to interact with the overlay rather than the game. This will result in the game not receiving the keyboard or mouse input.
Some system SDK user input methods (such as the Win32 API function ShowCursor) will change behavior during this time. To support this and provide general user state information, the game can use EOS_UI_AddNotifyDisplaySettingsUpdated to register a callback. The callback data will contain both a Visible and an Exclusive Input flag. The callback will always fire on the next EOS_Platform_Tick call to inform the game of the current state of any overlay.
Multiple browser instances can affect the Visible flag at the same time, for example, receiving a social toast while making a purchase. The more important use case is if a visible browser instance desires user interaction. In this case, the Exclusive Input flag will be true. The browser instance must also be visible to have any impact on the Exclusive Input flag.
Localization
The locale code used for localization of the Social Overlay's text will come from one of two sources: the language that the player selected when creating their Epic Account, or an override value provided by the game. If a game uses an override value, then this will be the value used regardless of what the user has selected within their Epic Account. This can be done by using EOS_Platform_SetOverrideLocaleCode.
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.
Titles are in control of their presence information. Epic recommends setting presence information to codenames during development as an additional safeguard for the most sensitive games. The ProductName field in EOS_Initialize is where the default game name comes from.
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. The status of a player's friends will be shown in the Friends page of the Social Overlay.
Active Game
Within the Status Panel, the displayed app 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
The rich presence text should provide some game context to other players. The string provided to EOS_PresenceModification_SetRawRichText will be shared as is. It will be displayed as part of a friends status within the Friends Page.
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 or Lobby Service. The game will also need to use the Connect APIs to associate the player's account with the Sessions Service.
When using the Social Overlay, you have two implementation options:
Use the Lobbies or Sessions interfaces with
bPResenceEnabled = trueYou can use these features and EOS maintains the accuracy of joins and invites
Do NOT use Lobbies or Sessions interfaces and use
SetJoinInfoYou are responsible to keep that value set/empty as appropriate to reflect joinability in your game
The Join Button
The Join button enables players to join a friend's game. The integration with the SDK depends on which game management service is being used. The button will be enabled if the presence for the remote player contains either a Lobby ID, Session ID, or a Join Info String. This data is transferred to all friends using the Presence Service. All three identifiers have an associated callback for when the user presses the Join Button. It is expected that the game will honor this intent for the user after any cleanup of the current state.
Using Lobbies
When using the Lobby Service, the Lobby ID is transmitted automatically. The game then uses EOS_Lobby_AddNotifyJoinLobbyAccepted to know when the player clicks the Join Button. After any cleanup, the game must use the provided UiEventId to retrieve the associated Lobby by using EOS_Lobby_CopyLobbyDetailsHandleByUiEventId and then join it. If the join fails, the game is expected to call EOS_UI_AcknowledgeEventId to allow the Social Overlay to refresh its state.
Using Sessions Matchmaking
When using the Sessions Matchmaking Service, the Session ID is transmitted automatically. The game then uses EOS_Sessions_AddNotifyJoinSessionAccepted to know when the player clicks the Join Button. After any cleanup, the game must use the provided UiEventId to retrieve the associated Session by using EOS_Session_CopySessionHandleByUiEventId and then join it. If the join fails then the game is expected to call EOS_UI_AcknowledgeEventId to allow the Social Overlay to refresh its state.
Using Custom Service
To set up the Join Info String for the player manually, use EOS_PresenceModification_SetJoinInfo. The developer is free to define the meaning of the Join Info String as needed.
The game then uses EOS_Presence_AddNotifyJoinGameAccepted to know when the player clicks the Join button. The callback data will contain the Join Info String.
The Invite Button
The Invite button enables players to invite friends to their game. The integration with the SDK depends on which game management service is being used. Each will have an associated notify callback. Like Join, the game should make the best effort to honor the intent of the user. For invite functionality with the Epic Games Launcher, be sure to map your deployments to your artifacts as well.
Custom Invites
For titles that do not use Epic Matchmaking, Custom Invites Interface exists to send and receive invites with an arbitrary payload. When the Invite Button is clicked, the Social Overlay sends a custom invite using EOS_CustomInvites_SendCustomInvite. EOS_CustomInvites_AddNotifyCustomInviteReceived and EOS_CustomInvites_RemoveNotifyCustomInviteReceived allows detection, custom UI indication, and processing of custom invites.
Using Lobbies
When the Invite button is clicked, the Social Overlay transmits an invite through the Lobbies Service on behalf of the user and the game using EOS_Lobby_SendInvite. The game uses EOS_Lobby_AddNotifyLobbyInviteAccepted to know when the player clicks Accept in the overlay. The callback data contains the Invite ID, which you can use to locate the information about the game within the Lobbies Interface.
Using Sessions Matchmaking
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.
Sessions Matchmaking 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. 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.
Supporting Achievements
The Social Overlay provides a user interface for achievements. To make use of this it is important to set up the data properly within the Developer Portal.
Localization of achievements follows the same rules as the rest of the Social Overlay, which is discussed briefly at the top of this document as well as within the Social Overlay Overview.
If an achievement is marked as hidden then the locked icon will be used but the displayed text will be provided by the Social Overlay page. If an icon is not provided within the dev portal, then a default icon will be provided by the Social Overlay page.