The Epic Online Services (EOS) SDK has downloads in C# in addition to C. This page outlines some of the implementation differences between working with the EOS SDK in C# to working with the EOS SDK in C. While the core functionality remains the same regardless of the language you use, the SDK in C# differs in design in the following ways:
- The EOS SDK in C# adheres to C# best practices and follows an object-oriented approach. It uses handle objects rather than C-style handles to manage asynchronous operations.
- Naming conventions match typical C# patterns. For example, the
EOS_Auth_Loginin the EOS SDK in C is accessible in the EOS SDK in C# as
- Data structures in the EOS SDK in C require macro-based API version numbers to ensure compatibility. These values are pre-populated in the EOS SDK in C#.
EOS SDK in C# Dependencies
To work with the EOS SDK in C#, you need the following installed in your development environment.
.NET Framework 3.5 or higher (or an API-compatible equivalent)
Note: Previous versions might work, but we have not tested them.
To work with the EOS SDK samples in C#, you need the following installed in your development environment.
- .NET Core 3.1
- Visual Studio 2019 or higher
See the main System Requirements page for full details of what your development environment needs.
See the EOS Get Started documentation for guidance on setting up your Epic Games account and working with the EOS SDK, before you follow the guidance below.
You can also follow the introduction blogs on the Online Services website, which focus on getting started in C#: dev.epicgames.com/news/~.
- Include the SDK in C# source files in your project.
- (Unity users) Place these files (including Core and Generated folders) into your Assets folder.
- Ensure that the appropriate library binary file for your target platform is accessible by your application.
- (Unity users) copy the appropriate library binary file into your Assets folder for your target platform.
- For example, a Windows x64 integration would use
- The SDK in C# determines the library binary name to target in
Epic.OnlineServices.Config. Several platforms are preconfigured to point to the correct name for convenience.
- If your target platform has not been preconfigured, make the appropriate changes to the configuration and your project symbols to avoid a build error. For example, you may need to set
EOS_PLATFORM_WINDOWS_64if targeting Windows x64 or
EOS_PLATFORM_WINDOWS_32if targeting Windows x86.
- (Unity users) Create a new script to control the SDK. For this example, we used the name
- (Unity users) To create a component when needed, select Add Component to assign it to an entity.For demonstration purposes, we added it to the Main Camera.
- Write your EOS SDK code in this component. See our sample code for examples.
Implementing the SDK
Once you have set up your product and integrated the SDK in C#, you can begin writing code. You'll need to initialize the SDK, call its
Tick method regularly to ensure that the SDK can execute and that callbacks can run, and shut it down when your application finishes.
Managing the SDK's Life Cycle
There are three main parts of the SDK's life cycle: Initialization, Ticking (normal operation), and Shutdown.
The Platform Interface is the entry point to the SDK, and you will need an instance of this interface to use EOS. To create one, call
Epic.OnlineServices.Platform.PlatformInterface.Initialize with some basic information about your application, then call
Epic.OnlineServices.Platform.PlatformInterface.Create with the values you have obtained from the Developer Portal to get an
Epic.OnlineServices.Platform.PlatformInterface instance. Store this instance; you will need it to interact with the SDK.
For example, to perform authentication, you first need an instance of
Epic.OnlineServices.Auth.AuthInterface, and you can retrieve this by calling GetAuthInterface() on your
You can only initialize the SDK once; subsequent calls to
Epic.OnlineServices.Platform.PlatformInterface.Initialize will return the
AlreadyInitialized failure code. We recommend initializing the SDK when your application starts up and not releasing it until the application shuts down.
In order for the SDK to operate, you must call
Epic.OnlineServices.Platform.PlatformInterface.Tick on your Platform Interface instance regularly. These calls do not need to happen every frame, but should happen fairly often; one call every 100 milliseconds is considered reasonable, but you can adjust the exact frequency to your needs. SDK callbacks can only run when you call
Tick, so all of your asynchronous operations depend on it.
When you no longer need the SDK — generally, at application shutdown time — you can shut it down by calling
Epic.OnlineServices.Platform.PlatformInterface.Release to release your Platform Interface instance, and then
Epic.OnlineServices.Platform.PlatformInterface.Shutdown to complete the shutdown process. This process is final;
Epic.OnlineServices.Platform.PlatformInterface.Release puts the SDK into a finalized state, and you cannot acquire another Platform Interface handle or reinitialize the SDK after that point. For this reason, we advise against shutting down the EOS SDK until application shutdown.
Some editor environments, including Unity, load external libraries like EOS during editor startup and do not unload them until the editor shuts down. In these cases, you should not call
Epic.OnlineServices.Platform.PlatformInterface.Shutdown at the end of an in-editor play session, because you will be unable to initialize the SDK successfully in any future session without restarting the editor. In addition, because these editor environments use one continuous instance of the SDK, operations that began right before the end of a play session could finish and trigger callbacks in the following session.
Most callback data structures and some return values use
Epic.OnlineServices.Result to convey the results of SDK operations. Make sure to use this to handle errors and ensure operations are performing as expected.
The SDK outputs useful debugging information through an internal interface. To enable this feature, set up
Epic.OnlineServices.Logging.LoggingInterface as early as possible, preferably immediately after initializing the SDK, by calling
Epic.OnlineServices.Logging.LoggingInterface.SetLogLevel with parameters indicating the level of detail you require, followed by
Epic.OnlineServices.Logging.LoggingInterface.SetCallback with a callback function to receive log information. This feature can provide insight into internal operations and can help with identifying the causes of unexpected behaviors you may encounter.
In the SDK in C, some APIs such as
EOS_Leaderboards_CopyLeaderboardDefinitionByIndex pass out structs of data that must be manually released. In the SDK in C#, you don’t need to concern yourself with releasing these structs as they are automatically handled by the wrapper’s marshaling code.
In the SDK in C, some APIs such as
EOS_Presence_CreatePresenceModification pass out handles that let you set data in memory that is owned by the SDK library. These handles must be manually released. In the SDK in C#, these handles are represented by objects with an underlying type of
Epic.OnlineServices.Handle, and contain functions that let you set the unmanaged data. They also contain a Release function that you must manually call when you are finished with it.
Custom Memory Delegates
On some platforms, such as consoles, the SDK requires you to implement your own allocate, reallocate, and release functions. Because the SDK will call these functions with very high frequency, it is highly performant for the SDK to be able to access them directly without being routed through delegates in managed code.
You have the option to pass these functions into the SDK when initializing the platform with
Epic.OnlineServices.Platform.InitializeOptions. It is recommended that you:
- Create a native library and implement the 3 memory functions,
- For each of the 3 memory functions, implement an export function that returns a pointer to the memory function,
- Before initializing the platform in C#, call the export functions, and set the returned IntPtr values to the options struct.
The following sample code demonstrates the structure of what your native library may look like:
And the following sample code demonstrates what the C# bindings may look like:
The SDK is not currently thread safe. We recommend that all calls to the SDK come from your application's main thread. At this time, we recommend against using
Task, or similar patterns.
The EOS Overlay
To use the EOS Overlay in your application, complete the following before any graphics devices are created:
- Load the SDK library into memory
- Initialize with EOS_Initialize
- Create your platform with EOS_Platform_Create
In Unity, one way you can achieve this is by creating a low-level native rendering plugin. At a minimum, you will need to:
- Create a native library with a name prefixed with
- Add an export function named
UnityPluginLoad(void*)that loads the SDK library and invokes EOS_Initialize and EOS_Platform_Create successfully,
- Add an export function to return the created platform interface handle back to C# when needed, where it can be used to construct a new instance of
The EOS overlay is not supported in editor environments such as the Unity editor. It is recommended that you explicitly disable the overlay in editor environments to prevent unintended behavior.
As a best practice for Unity users, we recommend that your standalone build controls the lifetime of the SDK inside a low-level native rendering plugin, and your editor build should exclude the plugin to control the lifetime of the SDK inside a MonoBehaviour with dynamic bindings.
Typically, the SDK in C# uses
extern DllImport bindings. However, you may need to use dynamic bindings.
To begin using dynamic bindings:
- Dynamically load the SDK library and retrieve a library handle
- When the application session begins, call
Epic.OnlineServices.Bindings.Hookto pass in the library handle and function pointer loader delegate.
- When the application session ends, call
Epic.OnlineServices.Bindings.Unhookand free the library to clean up.
For example, you may have the following extern functions defined on Windows:
Then to begin using the SDK, load the library and hook the dynamic bindings with:
When the application is finished, unhook the dynamic bindings and free the library with:
Some platforms have platform specific APIs. These platforms have their own bindings class.
To use platform specific APIs, you must hook the corresponding platform-specific bindings class, in addition to the base
As of 1.12, the default behavior of the SDK in C# is to require dynamic bindings for editor environments such as the Unity editor. This is to enable on-demand loading and unloading of the SDK library, and allow the SDK to be initialized each time the game is run in the editor. More detailed sample code for using dynamic bindings in Unity is provided below.
Sample Code and Projects
There are a variety of SDK in C# samples to show you different Epic Online Services (EOS) functionality implementations, such as authentication, presence, the purchasing flow, and voice. Additionally, we have sample code for setting up the platform, signing in, and implementing the Unity EOS SDK component.
The sample code in this section is intended to demonstrate and help familiarize you with the SDK in C#.
Setting up the Platform
Unity EOSSDK Component
Note: The code below requires SDK 1.15 or above.
These samples are in a folder of your SDK in C# download containing the following libraries and applications.
Common contains the SDK code and other useful shared functionality.
WpfCommon contains functionality that is common to all of the WPF samples.
VoiceCommon contains functionality that is common to all of the voice samples.
SimpleAuth is a WPF application that demonstrates how to perform authentication and presence related functions for the logged in user.
SimpleOverlayPurchasing is a managed DirectX11 application that demonstrates how to initiate and complete the purchasing flow by utilising the in-game overlay.
VoiceServer is an application that demonstrates how to implement a RESTful API service that acts as a trusted voice server between voice clients and EOS.
VoiceClient is a WPF application that demonstrates how to connect to a voice room, switch audio devices, transmit audio, client mute, server mute, and kick.
Before You Begin
To run the samples, you must install:
- .NET Core 3.1
- Visual Studio 2019 or higher
You must also set the following values associated with your application in
You can also set the LoginType. Use of the Id and Token fields differs based on the login type. For more information, see Auth.Credentials and Auth Interface.
The sample application uses Epic Account Services to authenticate the local user for demonstration purposes. This requires that the Client Credentials used to initialize the SDK have been assigned to an Application used for Epic Account Services.
The demonstrated SDK functionality can be used with any of the supported identity providers for user authentication.
SimpleAuth is a sample application demonstrating how to perform authentication and presence related functions for a logged in user.
To begin, you are presented with a sign in screen. You can select the type of sign in you want to use. We recommend using the Developer type to login with credentials assigned by the Developer Auth Tool.
Viewing Your Presence
Once signed in, you are presented with a page showing your current presence, and a form that allows you to change it. It contains fields for the online status, rich text, and data entries associated with your current presence.
This feature is only available for products that are part of the Epic Games store. You must be a store partner, and you must have offers set up with the store.
In order for the overlay to work, you must have done one of the following:
- Installed the Epic Games Launcher and ran it for the first time.
- Downloaded the EOSOVH dll file and set the registry key
HKEY_CURRENT_USER\Software\Epic Games\EOS\OverlayPathto the directory of where the dll resides.
Initiating the Purchasing Flow
The sample will automatically proceed with signing in and the necessary ecom functions in order to launch the overlay into the purchasing flow. Keep an eye on the output to ensure there are no problems.