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:
|The name of the product using the SDK. The name string must not be empty and supports a maximum of 64 characters in length.|
|The product version of the application using the SDK|
|Your custom |
This function must return pointers that honor memory alignment.
|Your custom |
|Your custom |
|A field for any system-specific initialization. If provided then the information will be passed to the |
|A field for any thread affinity initialization that is |
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 firstname.lastname@example.org, 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.
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.
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:
|The Product ID of the game, provided by Epic Games|
|The Sandbox ID of the game, provided by Epic Games|
|The 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.
|Set to |
|256-bit Encryption Key for file encryption in hexadecimal format (64 hex chars)|
|The override country code for the logged-in user|
|The override local code for the logged-in user|
|The Deployment ID of the game, provided by Epic Games|
|Platform creation flags, expressed as a bitwise-or union of |
|Absolute path to the folder that is going to be used for caching temporary data|
|A budget, measured in milliseconds, for |
|Pointer to |
|A 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.|
EOS_Platform_Create will return a handle to the Platform Interface, of type
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:
|Player Data Storage|
|Real Time Communications (RTC)|
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
By passing an
EOS_HPlatform handle into
EOS_Platform_CheckForLauncherAndRestart, EOS will check whether the app was launched through the Launcher. If it wasn't, it will restart the app through the Launcher. This returns an
EOS_EResult with the following codes:
EOS_Success: The app is being relaunched with the Launcher. The current app process must be terminated as soon as possible to make way for the newly launched process.
EOS_NoChange: If the app was already launched through the Launcher, no additional action needs to be taken.
EOS_UnexpectedError: The LauncherCheck module failed to initialize, or the module tried and failed to restart the app.
This function is only relevant for apps that are published on the store and therefore are already accessible through the Launcher.
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
EOS_Platform_SetApplicationStatus must be called when the application status changes. The application status can be set using the
The following application states are defined with the
EOS_Platform_GetApplicationStatus can also be used to get the current application status.
The nature of these application changes will depend on the platform (see the platforms-specific documentation for more information).
EOS_Platform_SetNetworkStatus must be called when the network status changes. The network status can be set using the
The following network states are defined with the
|Network cannot be used.|
|We may not be connected to the internet. The network can still be used, but is expected to probably fail.|
|We think we're connected to the internet.|
EOS_Platform_GetNetworkStatus can also be used to get the current network status.
The nature of these network changes will depend on the platform (see the platforms-specific documents for more information).
Note: On certain platforms the default network state is
EOS_Platform_SetNetworkStatus needs to be called when the network is available (see the 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:
EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainerto create a new temporary container for the platform options.
Create the platform specific
EOS_IntegratedPlatform_<Platform>_Optionsstruct to specify desired options to use.
EOS_IntegratedPlatformOptionsContainer_Addto register the options for SDK initialization.
After a successful call to
EOS_Platform_Create, release the temporary container by calling