EOS SDK in C#

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_Login in the EOS SDK in C is accessible in the EOS SDK in C# as Epic.OnlineServices.Auth.AuthInterface.Login.
• 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#.

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#: Introduction to Epic Online Services (EOS) (at dev.epicgames.com/news).

1. Include the SDK in C# source files in your project.

• (Unity users) Place these files (including Core and Generated folders) into your Assets folder.

2. 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 EOSSDK-Win64-Shipping.dll.

3. 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_64 if targeting Windows x64 or EOS_PLATFORM_WINDOWS_32 if targeting Windows x86.

4. (Unity users) Create a new script to control the SDK. For this example, we used the name EOSSDKComponent.

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

6. Write your EOS SDK code in this component. See our sample code for examples.

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.

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 Epic.OnlineServices.Platform.PlatformInterface instance.

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.

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.

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:

1. Create a native library and implement the 3 memory functions,
2. For each of the 3 memory functions, implement an export function that returns a pointer to the memory function,
3. 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 async, await, Thread, Task, or similar patterns.

To use the EOS Overlay in your application, complete the following before any graphics devices are created:

1. Load the SDK library into memory
2. Initialize with EOS_Initialize
3. 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:

1. Create a native library with a name prefixed with GfxPlugin,
2. Add an export function named UnityPluginLoad(void*) that loads the SDK library and invokes EOS_Initialize and EOS_Platform_Create successfully,
3. 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 Epic.OnlineServices.Platform.PlatformInterface.

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:

1. Define EOS_DYNAMIC_BINDINGS
2. Dynamically load the SDK library and retrieve a library handle
3. When the application session begins, call Epic.OnlineServices.Bindings.Hook to pass in the library handle and function pointer loader delegate.
4. When the application session ends, call Epic.OnlineServices.Bindings.Unhook and 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:

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.

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

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.

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 Samples/CSharp/Common/Settings.cs:

• ProductId
• SandboxId
• DeploymentId
• ClientId
• ClientSecret

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

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\OverlayPath to the directory of where the dll resides.

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.