Redistributable installer

Redistributable used to integrate and unify the user authentication and social experience.

8 mins to read

If your game is distributed on multiple PC storefronts, or independently of any storefront, you can use Epic Online Services (EOS) to integrate and unify the user authentication and social experience across each of your distributions. For example on Steam, using the in-game overlay of EOS, users will be able to see and interact with all of their Epic friends and Steam friends in a single list.

Read more about crossplay social features for PC on Epic Games Store and Steam in this page: Crossplay using Epic Account Services.

Overview

The EOS Social Panel and Epic Accounts login experience, provided through the EOS SDK integration for games, uses an in-game overlay that is distributed separately to players. For distributing the overlay technology component, a separate EOS service redistributable is provided for games to install as part of the game installation prerequisites.

This allows the overlay to be kept automatically up-to-date by Epic through backend-controlled updates, decoupled from the game’s own update cycle. Automatic updates delivered through this mechanism adds new cross-platform social features, even for games that are no longer actively updated for new content.

Game client startup flow

Game client startup flow

Click to enlarge image.

Adding EOS overlay to your game, when distributed outside Epic Games Store, includes the following steps:

  • Adding the EOS service redistributable EpicOnlineServicesInstaller.exe to be installed as part of your game installation, or whenever the game files are validated, and uninstalling it when the game is uninstalled.
  • Adding the EOS bootstrapper application as the main executable to launch the game. This application is responsible for initializing the local installed EOS service, and then starting the game client application.
  • Updating the game client to call the EOS_Platform_GetDesktopCrossplayStatus SDK API at startup.

Calling the EOS_Platform_GetDesktopCrossplayStatus SDK API during the game client initialization verifies that the following prerequisites have been met:

  • The game was started through the EOS Boostrapper.
  • The EOS redistributable service was found installed as expected.
  • The EOS Overlay was loaded successfully by the EOS SDK.

This check allows you to perform any necessary error handling before the user attempts to log in to your game. For example, you can inform the player that the game was started incorrectly, or you can ask them to verify that the game installation is valid and all required game files are present. This ensures that the player has the best experience possible.

Service redistributable installer

The EOS service redistributable is responsible for downloading and installing the EOS overlay, and keeping it automatically up-to-date. The service is run when the game is started by the user, and automatically exits when the game is terminated. The service is only running when the game is running. The check for overlay updates is performed at the game start up time.

This component is distributed to end-users as part of the game files, and installed as a prerequisite as part of the game installation. When the game is installed or uninstalled, the EOS service redistributable is also installed or uninstalled respectively. It is also important to note that if the distribution platform client provides users ability to verify and fix their game installation, the EOS service redistributable installer should be invoked to ensure that it is fixed if needed.

Steam installscript

This is a template installscript.vdf file that you can use when distributing your game on the Steam platform. You will only need to change the YOUR_EOS_PRODUCT_ID and YOUR_STEAM_APP_ID to match your game’s identifiers. The template assumes that your game distributes the EpicOnlineServicesInstaller.exe under a EpicOnlineServices folder in the game root directory.

Running the service for local development

Applications using Epic accounts login (EOS_Auth_Login), with either the EOS_LCT_AccountPortal or EOS_LCT_ExternalAuth login types, require the EOS service to be running in the background. During local development, for example when running your game within the Unreal Engine or Unity, you do not need to use the bootstrapper application.

To run the service for local development purposes, navigate to the service installation directory in Program Files (x86)\Epic Games\Epic Online Services\ and start it via the EpicOnlineServices - Development.cmd shortcut. You can stop the service by right clicking its system tray icon in the Windows taskbar. Note that you may need to restart your code development environment for the service to take effect.

Bootstrapper application

The EOS bootstrapper is an executable that is used as a transient launcher application to run the actual game client executable. It is intended to be used as the target executable to run when users launch the game.

The EOS bootstrapper is responsible for starting the EOS service that has already been installed as part of the game installation. The EOS service will perform an automatic update check on its own software version and for the EOS overlay component, and automatically install any available software updates.

Once the EOS service has been initialized, the EOS bootstrapper automatically proceeds to run the target game client executable. This flow ensures that when the game is started, the EOS overlay is readily available for the game application and EOS SDK to use. The EOS overlay is a requirement for the in-game Epic Accounts login experience and the Epic Social Panel to work.

Bootstrapper application usage

The EOS bootstrapper executable is distributed as part of the game files. It is typically placed next to the main game executable, but can also be located in another folder within the game installation directory. The EOS bootstrapper executable is paired with a config file that is named identically to the EOS bootstrapper executable. For example, LaunchGame.exe with LaunchGame.ini.

To generate the config file, and optionally change the program icon of the EOS bootstrapper executable, see the next section for EOS bootstrapper tool.

Troubleshooting

For each run, the EOS bootstrapper will write a log file into %LOCALAPPDATA%\Epic Games\Epic Online Services\Bootstrapper\Logs\EOSBootstrapper.log. If the game client process does not get started, or the EOS SDK returns unexpected errors related to Epic Accounts login or the EOS overlay, check the bootstrapper log for any errors.

Bootstrapper tool

The EOS bootstrapper tool is a command-line tool that is used to generate a config file to be used by the EOS bootstrapper application. It allows you to optionally also update the EOS bootstrapper executable with your own program icon, for example to match the program icon of the game client executable.

The EOS bootstrapper tool is a development tool, and is not distributed to end-users as part of the game files. It is typically added into the end of the game client build pipeline, but can also be used as a one-time standalone tool to create the EOS bootstrapper config file.

Bootstrapper tool usage

When run, the tool performs the following operations:

  1. Copies the local Boostrapper executable (EOSBootstrapper.exe) to the output file path (--output-path).
  2. If set, updates the program icon and version info of the copied bootstrapper executable, using the target application executable to run (--app-path).
  3. Creates a new config .ini file next to the copied output bootstrapper executable.

Run EOSBootstrapperTool.exe --help via command-line prompt to see full usage information and all available options.

Example usage

Let’s say your development directory tree looks as following:

Then you would run the EOS bootstrapper tool using the following command-line:

This will copy and rename the original EOSBootstrapper.exe as LaunchGame.exe into the game build directory, next to the game client executable, and generate the LaunchGame.ini config file.

Bootstrapper config

The config file is used and required by the EOS bootstrapper application to work. It can be generated using the EOS bootstrapper tool, or manually created by hand for convenience.

The config file specifies the following runtime options for the EOS bootstrapper application:

OptionTypeDescription
ApplicationPathStringPoints to the target application executable to run. If the bootstrapper executable and the game client executable both are located in the same folder, then this is the game client executable name. For example, Game.exe. If they are located in different folders, then this is the relative path from the bootstrapper executable’s location to the game client executable, including the executable name itself. For example, Bin\\Game.exe.
WorkingDirectoryString(Optional). Relative working directory to set when running the target application.
NoOperationBoolean[True, False], Integer[0, 1]Optional, false by default. If set, the target application will be started directly without initializing the EOS service. This setting can be used to run the game without the EOS service, for example, if you have not fully integrated the service redistributable installer to be run in your development environment for other developers and game testers.
WaitForExitBoolean[True, False], Integer[0, 1](Optional, false by default.) If set, the bootstrapper will exit only after the launched target application has exited. This setting can be used in scenarios where for example the platform launcher would mark the game as not running when its target executable exited. As the bootstrapper will be the target executable to launch for the platform client, you can configure the bootstrapper to remain silently running in the background until the game client itself has exited.

Example config