Platform Interface

Interface that grants access to all other interfaces.

11 mins to read

The Platform Interface sits at the heart of the Epic Online Services (EOS) SDK and holds the handles you need to access every other interface and keep them all running. When your application starts up, you can initialize the SDK and get a handle to the Platform Interface. This handle is usable for the lifetime of the SDK.

Initializing the SDK

The first step to using the Epic Online Services (EOS) SDK is to initialize it. During initialization, your code will identify your product and have the opportunity to set up custom memory allocation functions.

Configuring and Creating the SDK

Initialize the EOS SDK by calling EOS_Initialize with an EOS_InitializeOptions data structure. Populate the structure as follows:

PropertyValue
ApiVersionEOS_INITIALIZE_API_LATEST
ProductNameThe name of the product using the SDK. The name string must not be empty and supports a maximum of 64 characters in length.
ProductVersionThe product version of the application using the SDK
ReservedNULL
AllocateMemoryFunctionYour custom malloc function, of type EOS_AllocateMemoryFunc, or NULL
This function must return pointers that honor memory alignment.
ReallocateMemoryFunctionYour custom realloc function, of type EOS_ReallocateMemoryFunc, or NULL
ReleaseMemoryFunctionYour custom free function, of type EOS_ReleaseMemoryFunc, or NULL
SystemInitializeOptionsA field for any system-specific initialization. If provided then the information will be passed to the EOS_<system>_InitializeOptions structure, where <system> is the system being initialized.
OverrideThreadAffinityA field for any thread affinity initialization that is EOS_Initialize_ThreadAffinity type. The information, if it is provided, will be used when creating any threads during the operation of the EOS SDK. When set to null, the EOS SDK will use a default scheme for determining thread affinity. The EOS_Initialize_ThreadAffinity structure is a set of affinity masks which identify categories of threads to use.

EOS_Initialize returns an EOS_EResult to indicate success or failure. The value will be EOS_Success if the SDK initialized successfully; otherwise, the value will indicate an error, such as EOS_AlreadyConfigured. After initializing the SDK, you can create a Platform Interface.

Requesting Access to the Console SDK

The Developer Portal supports console developers who want to use the EOS SDK, including the ability to authenticate users on the PlayStation Network and XBox Live online services. However, developers must first confirm their status with the console platform holders. Each platform holder offers their own procedures for confirmation.

  • Nintendo Switch: Sign into your account on the Nintendo Developer Portal and click through Getting Started > Nintendo Switch Middleware > Unreal Engine: Learn More. Complete and submit the form.

  • PlayStation 4, PlayStation 5: Sign into your account on the PlayStation Partners Portal, go to the PlayStation 4 DevNet, and click through Development > Tools & Middleware > Tools & Middleware directory > Epic Online Services. Click the Confirm Status button.

  • Xbox One and Series X: Contact your Microsoft account representative and ask them to send an email to consoles@unrealengine.com, confirming your status and referencing your email address.

Once you have confirmed your status, you are eligible to receive access to, and support for, the console SDK. Eligibility includes Unreal Engine partners, either under EULA or under a custom license, and non-Unreal Engine partners.

Logging Callbacks

The SDK logs useful information at various levels of verbosity. Registering a callback with EOS_Logging_SetCallback will allow access to this output. Implement a function of type EOS_LogMessageFunc to receive the EOS_LogMessage data structure.

  • Category: A string corresponding to the category of the log message (see the EOS_ELogCategory API reference)
  • Message: The message itself, as a string.
  • Level: The verbosity level of the log message (see the EOS_ELogLevel API reference)

You may use EOS_Logging_SetLogLevel to adjust logging detail level.

Platform Interface

The Platform Interface provides access to all other EOS SDK interfaces, and keeps them running. Once you have created the platform interface, you can use it to retrieve handles to other interfaces, or tell it to run its per-frame update code, known as ticking.

Creating the Platform Interface

Create the Platform Interface by calling the EOS_Platform_Create function with an EOS_Platform_Options structure containing the following information:

PropertyValue
ApiVersionEOS_PLATFORM_OPTIONS_API_LATEST
ReservedNULL
ProductIdThe Product ID of the game, provided by Epic Games
SandboxIdThe Sandbox ID of the game, provided by Epic Games
ClientCredentialsThe Client ID and Client Secret pair assigned to the host application
Publicly exposed applications, such as the end-user game client, will use different credentials than a trusted game server backend.
bIsServerSet to EOS_False if the application is running as a client with a local user. Set to EOS_True for a dedicated game server.
EncryptionKey256-bit Encryption Key for file encryption in hexadecimal format (64 hex chars)
OverrideCountryCodeThe override country code for the logged-in user
OverrideLocaleCodeThe override local code for the logged-in user
DeploymentIdThe Deployment ID of the game, provided by Epic Games
FlagsPlatform creation flags, expressed as a bitwise-or union of EOS_PF_ flags
CacheDirectoryAbsolute path to the folder that is going to be used for caching temporary data
TickBudgetInMillisecondsA budget, measured in milliseconds, for EOS_Platform_Tick to do its work. When the budget is met or exceeded (or if no work is available), EOS_Platform_Tick will return. This allows your game to amortize the cost of SDK work across multiple frames in the event that a lot of work is queued for processing. Zero is interpreted as "perform all available work".
RTCOptionsPointer to EOS_Platform_RTCOptions structure for using Real Time Communication features. Use NULL to disable the Real Time Communications (RTC) features, such as Voice.
IntegratedPlatformOptionsContainerHandleA handle that contains all the options for setting up integrated platforms. When set to NULL, the default integrated platform behavior for the host platform will be used.

Upon success, EOS_Platform_Create will return a handle to the Platform Interface, of type EOS_HPlatform.

In applications that support multiple views, such as editors, you may want to create multiple Platform Interface handles. This is not necessary to support multiple users playing on the same device, such as splitscreen games. The SDK supports multiple Platform Interface instances, each with its own internal state. Other interfaces that you retrieve will be unique to the Platform Interface from which you retrieve them. Do not attempt to initialize more than one instance of the SDK itself.

Using the Platform Interface

Once you have an EOS_HPlatform handle, you can use it to gain access to the other EOS SDK interfaces through their handle access functions:

InterfaceAccess Function
AchievementsEOS_Platform_GetAchievementsInterface
Anti-CheatEOS_Platform_GetAntiCheatClientInterface
EOS_Platform_GetAntiCheatServerInterface
AuthenticationEOS_Platform_GetAuthInterface
ConnectEOS_Platform_GetConnectInterface
Custom InvitesEOS_Platform_GetCustomInvitesInterface
EcommerceEOS_Platform_GetEcomInterface
FriendsEOS_Platform_GetFriendsInterface
LeaderboardsEOS_Platform_GetLeaderboardsInterface
LobbyEOS_Platform_GetLobbyInterface
MetricsEOS_Platform_GetMetricsInterface
ModsEOS_Platforms_GetModsInterface
P2PEOS_Platform_GetP2PInterface
Player Data StorageEOS_Platform_GetPlayerDataStorageInterface
PresenceEOS_Platform_GetPresenceInterface
Progression SnapshotEOS_Platform_GetProgressionSnapshotInterface
Real Time Communications (RTC)EOS_Platform_GetRTCInterface
EOS_Platform_GetRTCAdminInterface
ReportsEOS_Platform_GetReportsInterface
SanctionsEOS_Platform_GetSanctionsInterface
SessionsEOS_Platform_GetSessionsInfoInterface
StatsEOS_Platform_GetStatsInterface
Title StorageEOS_Platform_GetTitleStorageInterface
User InfoEOS_Platform_GetUserInfoInterface

In addition to gaining access to the other interfaces, the Platform Interface keeps them all running. Call EOS_Platform_Tick from your game's main loop every frame to make sure that asynchronous functions continue updating.

Restarting the App with the Launcher

When you pass an EOS_HPlatform handle into EOS_Platform_CheckForLauncherAndRestart, EOS checks whether the Epic Games Launcher launches the app. If the Epic Games Launcher doesn't launch the app, EOS_Platform_CheckForLauncherAndRestart restarts the app with the Epic Games Launcher.

EOS_Platform_CheckForLauncherAndRestart is only relevant for apps that are published on the store and, therefore, are already accessible through the Launcher.

Note: During the call to EOS_Platform_Create, the command line used to launch the app is inspected. If it is recognized as coming from the Epic Games Launcher, the environment variable, EOS_PLATFORM_CHECKFORLAUNCHERANDRESTART_ENV_VAR, is set to 1.

You can force the EOS_Platform_CheckForLauncherAndRestart API to relaunch the app by explicitly unsetting EOS_PLATFORM_CHECKFORLAUNCHERANDRESTART_ENV_VAR before calling EOS_Platform_CheckForLauncherAndRestart.

Note: The APIs you use to interact with the environment variable, EOS_PLATFORM_CHECKFORLAUNCHERANDRESTART_ENV_VAR, are dependent on the operating system:

  • On Windows, you must use SetEnvironmentVariable and GetEnvironmentVariable.
  • On other platforms, you must use setenv and getenv.

This returns an EOS_EResult with the following codes:

  • EOS_Success: The Epic Games Launcher is relaunching the app. You must terminate the current app process as soon as possible to make way for the newly launched process.
  • EOS_NoChange: The Epic Games Launcher has already launched the app. You don't need to do anything.
  • EOS_UnexpectedError: The LauncherCheck module failed to initialize, or the module tried and failed to restart the app.

Shutting Down the SDK

To close the game, you must release the memory held by the Platform Interface as well as the global state held by the SDK. First, pass your EOS_HPlatform handle to the EOS_Platform_Release function to shut it down. After that, you can call EOS_Shutdown to complete the process and shut down.

Once you call EOS_Shutdown, you will not be able to reinitialize the EOS SDK, and any further calls to it will fail.

Application and Network Status

You must set your players' application (game) status and network status when you change either status. Setting these will prompt the EOS SDK, ensuring that RTC transitions properly for your game.

Application Status

The application status notifies the EOS SDK whether the game is currently suspended.

EOS_Platform_SetApplicationStatus must be called when the application status changes. The application status can be set using the NewStatus parameter.

The following application states are defined with the EOS_EApplicationStatus structure:

EOS_AS_BackgroundSuspendedNotifies the SDK that the application has been put into a suspended state by the platform. This is sometimes called "background mode."
EOS_AS_ForegroundNotifies the SDK that the application has been resumed from a suspended state. This is the default active state on all platforms.

EOS_Platform_GetApplicationStatus can also be used to get the current application status.

The nature of these application status changes depends on the platform (see the platforms-specific documentation for more information).

You can only access console documentation if you have the appropriate permissions. See the Get Started Steps: EOS SDK Download Types documentation for more information on how to access the EOS SDKs for consoles and their associated documentation.

What your game does for RTC rooms when your game transitions between states is up to you. The common practice is for all platforms to leave all RTC rooms and disallow joining back while in a suspended state (background mode). You can control this default behavior with the BackgroundMode option. See the Background Mode section of the Using the Voice Interface documentation for more information on how to set BackgroundMode.

Network Status

The network status sets the status of the player's network connection.

You must call EOS_Platform_SetNetworkStatus when the network status changes. The network status can be set using the NewStatus parameter.

The following network states are defined with the EOS_ENetworkStatus structure:

EOS_NS_DisabledNetwork cannot be used.
EOS_NS_OfflineThe player may not be connected to the internet. The network can still be used, but is likely to fail.
EOS_NS_OnlineThe player thinks they are connected to the internet.

EOS_Platform_GetNetworkStatus can also be used to get the current network status.

The nature of these network status changes depends on the platform (see the platforms-specific documents for more information).

You can only access console documentation if you have the appropriate permissions. See the Get Started Steps: EOS SDK Download Types documentation for more information on how to access the EOS SDKs for consoles and their associated documentation.

The common pattern is to clear resources and prevent further room joins when you change the network status to disabled (EOS_NS_Disabled) or offline (EOS_NS_Offline). The EOS SDK does this by default. This is the same for each platform. Lobby RTC restarts any paused RTC rooms when foregrounded and online. It does not try to reconnect otherwise.

Note: When you turn the network on and off, RTC can run into network interruptions, as it has to reconfigure its webRTC threads.

For PlayStation 4, PlayStation 5, Nintendo Switch and Xbox, the network status defaults to EOS_NS_Disabled. When the network is online, you must update the network status to EOS_NS_Online with EOS_Platform_SetNetworkStatus. See the relevant platform-specific documentation for more information.

Native Platform Integration

The SDK provides functionality to integrate automatically with the native platform. These integrations allow the game to:

  • include platform friends in the EOS overlay’s friends list

  • mirror presence state of the local Epic user with their native platform presence

  • replicate game invites of EOS Lobbies and EOS Sessions with the native platform system

  • enable join-via-presence to the local user’s EOS lobby or session for platform friends

  • control system used to show game invite notifications (Game UI, Platform UI, EOS Overlay)

To configure the platform integrations to use:

  1. Call EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainer to create a new temporary container for the platform options.

  2. Create the platform specific EOS_IntegratedPlatform_<Platform>_Options struct to specify desired options to use.

  3. Call EOS_IntegratedPlatformOptionsContainer_Add to register the options for SDK initialization.

  4. After a successful call to EOS_Platform_Create, release the temporary container by calling EOS_IntegratedPlatformOptionsContainer_Release.

Sample Code