What is Epic Online Services (EOS)?

Epic Online Services (EOS) are free, cross-platform services created to enable fast, easy, and dependable high-quality game launching, operation, and scaling.

With a single SDK, we can help build a user-friendly ecosystem for both developers and users. 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.

These services encompass both games services and can integrate with our Epic Account Services and Epic Games Store.

SDK Fundamentals

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

Presently, the EOS SDK supports the following platforms:

  • Nintendo Switch

  • PlayStation

  • Xbox

  • iOS

  • Android

  • Windows

  • Mac

  • Linux

Versioning

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.

Interface handles

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.

Naming conventions

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

Convention

Use

Create

The function allocates memory and expects to be paired with a Release function.

Copy

Retrieves cached data from a previous call to a Query function and expects to be paired with a Release function.

Release

The function frees memory. These have a corresponding Create or Copy function.

Query

Interacts with backend services asynchronously, over an unspecified period of time. These calls may be throttled or retried depending on connectivity.

Get

Used when the cache value does not require a structure and is just a value. Includes Get for strings that require a buffer.

Function signatures

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 handling

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:

Error Code

Meaning

EOS_InvalidParameters

There was at least one unset or invalid input parameter passed to the function.

EOS_InvalidUser

The operation requires a user, but the provided user was invalid or unspecified.

EOS_MissingPermissions

The backend system rejected the request due to access restrictions.

EOS_UnrecognizedResponse

The SDK was unable to parse the backend's response.

EOS_OperationWillRetry

Backend connectivity is impaired and the SDK will try again.

EOS_IncompatibleVersion

The API version parameter that the calling code sent does not match the function's version number in the SDK.

EOS_Auth_TokenInvalid

Specific to the Auth Interface, the local authentication session has expired or become invalid, and the user needs to log in again.

Strings

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

Memory Allocation

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.

Service Usage Limitations

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.

Request Throttling

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.

Service Usage Quotas

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.