Redistributable installer

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

Redistributable installer

Note: The EOS redistributables are currently available for Windows. See the EOS public roadmap for information on Linux and macOS support.

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

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.

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 {EosProductId} and {SteamAppId} 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.

"InstallScript"
{
    "Firewall"
    {
        "EOS Bootstrapper - {SteamAppId}"       "%INSTALLDIR%\\EOSBootstrapper.exe"
    }
    "Run Process"
    {
        "EpicOnlineServices"
        {
            "HasRunKey"     "HKEY_LOCAL_MACHINE\\Software\\Valve\\Steam\\Apps\\{SteamAppId}\\EOS"
            "Process 1"     "%INSTALLDIR%\\EpicOnlineServices\\EpicOnlineServicesInstaller.exe"
            "Command 1"     "/install productId={EosProductId} /quiet"
        }
    }
    "Run Process On Uninstall"
    {
        "EpicOnlineServices"
        {
            "Process 1"     "%INSTALLDIR%\\EpicOnlineServices\\EpicOnlineServicesInstaller.exe"
            "Command 1"     "/uninstall productId={EosProductId} /quiet"
        }
    }
}

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

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.

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.

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.

Note: When changing the program icon, remember to digitally code sign the copied output EOS Bootstrapper executable.

Example usage

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

.\
GameBuild\Bin\GameClient.exe
Tools\EOSBootstrapper.exe
Tools\EOSBootstrapperTool.exe

Then you would run the EOS Bootstrapper Tool using the following command-line:

EOSBootstrapperTool.exe --output-path ..\GameBuild\Bin\LaunchGame.exe --app-path GameClient.exe

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:

Option

Type

Description

ApplicationPath

String

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

WorkingDirectory

String

(Optional). Relative working directory to set when running the target application.

NoOperation

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

WaitForExit

Boolean[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

ApplicationPath=GameClient.exe
WorkingDirectory=
NoOperation=0
WaitForExit=0