EOS SDK Key Information

With a single SDK, we can help build a user-friendly ecosystem for both developers and players. Creators and developers benefit no matter how you choose to build and publish your games. Players can then play these games with friends across different platforms at the same quality experience. Our mission is to design the SDK to be as portable as possible to work on any engine, any store, and integrate with any major platform.

SDK Fundamentals

The Epic Online Services (EOS) SDK comes in two flavors: C and a C# wrapper.

By focusing on C, we can provide stable application binary interfaces (ABI) to ensure integration functionality, regardless of compiler choice, implementation, calling conventions, data sizes, or alignments.

This also allows independent code patching for the SDK to limit interruptions in your own development, and helps maintain the life of the SDK without recompiling the application after distributing fixes and updates. Additionally, focusing on C APIs enforces a more deliberate exposure of the public API.

There are different types of SDK download to use, depending on the platform your game clients run on:

• Windows, macOS, Linux - the EOS SDK in C, and the EOS SDK in C#.
• Mobile - the EOS SDK for iOS, and the EOS SDK for Android.
• Consoles - there are EOS SDK downloads for game consoles in C, and in C#.
  The SDK downloads for consoles are only available to developers approved by the platform holders and approved by Epic Games.
  The platform holders are: Microsoft (Xbox One, Xbox Series X), Sony (PlayStation 4, PlayStation 5), Nintendo (Switch).
  To get access to the SDK downloads for consoles and associated documentation:
  • See the Developer Portal (dev.epicgames.com/dev-portal) for guidance on applying for console developer access from the platform holders.
  • Once you have platform-holder approval, you can apply to Epic Games using the Console Developer Request for Epic Online Services form, which is at eoshelp.epicgames.com.

EOS SDK versioning guarantees backwards compatibility with products using an older version of the SDK, even with API changes. Every interface, function, and data type has a version associated with it.

When a new SDK version is released, the SDK recognizes and supports older versions and reacts appropriately to data and function calls coming from them. This may include calling the original version of the function internally, migrating the original input structures to newer forms, or setting up reasonable defaults where possible.

Older products using the SDK maintain compatibility with EOS without updates.

The EOS features group together by modular, service-specific interfaces. For example, the Lobbies Interface handles the creation and interactions of your product’s lobbies, the Friends Interface manages functionality with your friends list, and so on.

The EOS SDK exposes its interfaces through opaque handles provided by the Platform Interface. An interface handle's lifetime lasts as long as the Platform Interface itself and is required as the first parameter to every API function using an interface.

To help convey usage and intent, EOS SDK interfaces use consistent naming conventions and prefixes:

Every function in the EOS SDK has a similar, predictable signature:

• The handle is always the first parameter for an interface.
  • For C#, you do not need to pass a handle parameter.
• An "options" data structure encapsulates all of the function's parameters and contains API versioning information.
• Finally, asynchronous functions feature an application-specific callback function, and can accept user-defined context information for the callback function to process. This callback function runs when the asynchronous operation ultimately succeeds or fails, and may also run in response to delays caused by connectivity issues.

Error codes from the EOS C SDK functions use the type EOS_EResult to include common error values and errors specific to a single interface. For example, the enum type EOS_EResult with a EOS_Success value appears as EOS_EResult::EOS_Success.

For C#, the error codes are slightly different by using the type Result to include the common error values and interface-specific errors. To compare with the C SDK example, the enum type Result with a Success value appears as Result.Success.

Common errors take the form EOS_<ErrorCode>, while interface-specific error codes appear as EOS_<Interface>_<ErrorCode>. Some examples follow:

For further information on error codes, see: EOS SDK Error Codes.

Strings, both as input and as output, must be in UTF-8 form.

When an SDK function needs to provide a data structure to a callback, the SDK allocates the memory for the data, and frees the memory as soon as the callback function completes. If you need to cache a copy of that data, you must make your copy during the lifetime of the callback function. In addition, if your system requires custom memory allocators, you must specify them at SDK creation time.

SDK Functions with the verb Get in their names also own the memory they use. Like callbacks, you must make a copy of the data if you want to have access to it later.

SDK Functions with the verb Copy in their names are the exception. These functions return copies of cached data, and expect that the caller takes ownership of the copy. The C SDK will never free the copy, so the user must call the corresponding Release function before shutting the SDK down. The C# SDK does not need to manually release copied structs because the wrapper does this automatically for you.

For a stable and reliable ecosystem for all users, Epic Online Services (EOS) implements client request rate limiting and service usage quotas. When the SDK APIs are integrated correctly with your code, the request limits and usage quotas should never be reached.

However, be mindful of the limits and pay attention to the SDK’s log output. During internal play testing, any erroneous log output should be checked to verify that EOS functions are not returning the EOS_TooManyRequests result or warning about incorrect use patterns.

Client request throttling and service usage quotas work in parallel to limit the impact an individual product can have on the overall EOS ecosystem.

When the EOS SDK detects that calls to the backend service are coming in too rapidly, the local client self-throttles by rejecting API calls with the EOS_TooManyRequests error code.

The backend service has a similar feature to reject requests from individual clients or hosted servers that have exceeded the maximum usage guidelines. The EOS SDK reports this as EOS_TooManyRequests and internally handles the retry logic with the time specified in the HTTP data.

Each service applies usage quotas on a per-deployment basis to ensure that the backend services always have the necessary capacity readily available for products.

Depending on the service type, quotas are either fixed or adjusted based on the number of concurrent users online for each deployment. All quotas apply equally to every product in the EOS ecosystem.

If an application reaches a usage quota limit for a backend service, any following requests for new resource allocations fail until the usage rate of the service lowers to acceptable levels.

See the EOS API Reference documentation.

Note: To use Epic Online Services (EOS) SDK, your local network, router, and firewall must allow access to specific host addresses. For a complete list of these host addresses, see the Firewall Considerations documentation.