The EOS Overlay is installed by the Epic Games Launcher. Game applications can also install it as part of their prerequisites using the EOS service redistributable installer.

It is important to initialize the EOS SDK and call EOS_Platform_Create before initializing Direct3D. This gives the EOS Overlay a chance to install graphics API hooks necessary to render the overlay with each game frame presented to the user.

In some cases, it may be desirable to disable the overlay functionality entirely. An example of this might be when a developer is running the game in an editor, and hooking the graphics API of the editor would cause problems. The EOS_Platform_Options passed to EOS_Platform_Create has been extended to take a Flags member, a bit-field with room for 64 flags. Currently there are three flags that will disable the overlay:

1. EOS_PF_LOADING_IN_EDITOR - This flag should be set whenever the EOS SDK is being used in a game editor such as UE4 Play-in-Editor (PIE) or Unity.
2. EOS_PF_DISABLE_OVERLAY - This flag should be set whenever you want to explicitly disable the overlay functionality. Purchase related functionality in the Ecom Interface will fail.
3. EOS_PF_DISABLE_SOCIAL_OVERLAY - This flag should be set whenever you want to explicitly disable only the social features of the overlay functionality.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

The lifetime of an invite is tied to the lobby or session it is a part of, not the player who sent the invite. Therefore, it is possible for a player to leave a lobby or session and have their friend join it long after they have gone. An invite is only destroyed on the backend service, not on the receiving game client. The invite is destroyed when the invite is used or the lobby/session for the invite is destroyed.

If an invite goes unused for too long, the lobby or session the invite was originally tied to may have been destroyed. In this case, the invite is stale. If a game client tries to access a stale invite, when it attempts to use it, the call fails. When an invite is stale, these are the kinds of errors a player may see:

• The invite is not found.
• The game is full.
• The session doesn't exist anymore.

Errors recognized by the SDK immediately bubble up to the Social Overlay. However, the receiving game client must handle any errors/race conditions that occur. This should be done after the player of the receiving game client accepts the invite. For example, your game may notify the player that the session is no longer available for the invite. Your game must then let the Social Overlay know that the invite is processed, regardless of whether it succeeds or fails. To do this, your game must call EOS_UI_AcknowledgeEventId(). In this API call, your game must include any error codes.

The invite button is not available if the current session is full, and it is disabled if the invited player is already in the session they've been invited to. You can override the invite state by making session modifications that mutate the "allow invites" state of the session. All clients in the session must maintain the state of the session via the (Un)RegisterPlayer API calls.

Players can use the Social Overlay for seamless interaction with both their Epic friends and their native platform friends. For showing native platform friends in the Social Overlay, the game needs to provide IntegratedPlatform options as part of the EOS SDK initialization. See the Platform Interface documentation for integration details.

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.