Using the Anti-Cheat interfaces

To use the Anti-Cheat interface(s), you must:

1. Review and adhere to the Development Prerequisites.
2. Determine your network architecture and client policy type.
3. Configure your client module, anti-cheat integrity tool, and Anti-Cheat Bootstrapper executable.
4. (Windows Only) Configure the Windows Service Installer.
5. Integrate the Anti-Cheat interfaces with your game code:
   1. Establish user identity with the Connect Interface.
   2. Register callbacks for Client-Server or Peer-to-Peer mode.
   3. Set up session notifications.
6. Confirm the Anti-Cheat interfaces are working properly by going through the Integration Checklist.

At each game start, the anti-cheat bootstrapper fetches the latest configured anti-cheat client module for your game. Updates may include bug fixes and improvements to anti-cheat prevention and detection.

1. Go to your Developer Portal.
2. Click Your Product > Game Services > Anti-Cheat.
3. Select the appropriate System (Windows, Linux, or macOS) from the dropdown menu.
4. (For updating and reverting) Test that the module works with your game as expected.
5. Select Activate Build from the More Options button of the Client Module you want active.

When you need to update your client module with a live game, it is important to test if the new module works as expected in your game before activating it.

1. From the list of Client Module Releases in the Developer Portal, select the More Options button of the new Client Module.
2. Choose Download Config File. This downloads a plain text configuration file to force a test system to download and use the specified anti-cheat module instead of your active one.
3. Place the downloaded configuration file in the same directory as your game executable with the same name.
   1. For example, if your game’s executable name is MyGame-Win64-Shipping.exe, then the configuration file must be placed in the same directory with the name MyGame-Win64-Shipping.exe.eac.
4. Start your game as normal with the anti-cheat bootstrapper.
5. Locate the anti-cheat bootstrapper’s log file.
6. Verify that the anti-cheat bootstrapper’s log file shows the expected timestamp and indicates that the URL in the configuration file was used.
7. Run the game through an appropriate testing procedure selected for your game. At minimum, you should be able to successfully connect to a protected multiplayer game session and use any critical functionality like in-game purchasing overlays.
8. Remove the .eac configuration file when finished so that your test system aligns with your live environment. This .eac file should never be shipped as part of your game distribution.
9. When you are confident that the new module works as expected in your game, choose Activate Build.

You may need to revert to a previous anti-cheat module if you suspect a recent update is causing problems in your game.

Follow the same instructions as you would for an update, but select a previous version instead of the most recent.

At the top of the anti-cheat service page in the EOS Developer Portal, two configuration statuses are displayed. Client Protection indicates whether the anti-cheat client module and protection are being delivered through the anti-cheat bootstrapper when each player starts the game. Server Kicks indicates whether the anti-cheat protection is being enforced in protected game sessions and players who are not running the anti-cheat or have a violation will be marked for removal through the appropriate SDK callback.

Clicking the Configure button will allow you to choose between three different configuration options.

• Enable all

  • This configuration should be used in normal operation. The anti-cheat client module will be delivered at game start and its presence will be enforced during protected game sessions.

• Enable Client protection while Server kicks is disabled

  • This configuration may be used temporarily if there is a problem that is causing too many players to be removed from protected game sessions with anti-cheat errors. The anti-cheat client module will be delivered at game start but its presence will not be enforced during protected game sessions so it will not be effective in preventing or detecting cheats.

• Disable all

  • This configuration may be used temporarily in case of emergency such as a crash related to anti-cheat affecting many players that cannot be solved by reverting to an earlier anti-cheat client module. The anti-cheat client module will not be delivered at game start and its presence will not be enforced during protected game sessions. Reverting to an earlier anti-cheat client module is always preferable instead if possible. If you use this configuration setting you must enable the Client Protection only for a transition period of several hours before returning to the Enable all state to avoid large numbers of players being suddenly removed from protected game sessions.

Anti-cheat must be able to verify that critical game files on each player’s machine match the files you shipped as a developer. You can use the anticheat_integritytool included with the SDK’s EOS_AntiCheatTools package to configure file integrity checks.

The Anti-Cheat Integrity Tool is a command line tool designed to be easily added at the end of your build process that generates the following two files:

• A signed list (catalog) of hashes for game files that you can define using a config file. At runtime, the anti-cheat service loads this signed catalog and confirms the content files match as they are accessed.
• A signed runtime configuration for the client-side anti-cheat, allowing for the developers to configure certain product-specific settings.

Because game files are verified upon access, the tool does not prevent cataloged files from being deleted. If a critical file is missing from disk then the game code is responsible for handling it appropriately.

If the catalog file itself or a cataloged file it covers has been modified and is then loaded, the game client will automatically be blocked from protected multiplayer sessions. However, the game will not be prevented from running in offline, solo, or unprotected modes which are outside the scope of anti-cheat protection.

You must run the tool for every game release or update that operates with anti-cheat enabled. You should configure it to run automatically for every shipping build of your game and ensure that the output files are included in the correct directory with the final distribution.

1. On your Developer Portal, go to Your Product > Game Services > Anti-Cheat and click Download Integrity Keys. A zip file containing required files for integrity checks will automatically download.

   1. These files are specific to the product you are currently viewing. If you are working on multiple products be sure to use the matching package.

   2. Make sure that you keep the private key secret and do not distribute it, or players can bypass the integrity protection.

2. Extract and move the base_private.key and base_public.cer files from the tooling zip file so that they are in the same directory as anticheat_integritytool.cfg and anticheat_integritytool.exe.

3. Modify the values in anticheat_integritytool.cfg to match your desired behavior.

   1. Modifying fields under search_options to control which files are cataloged:

      1. Include every file your game distributes that contains executable code (.dll, .exe, and so on) to be integrity checked, or an opportunity to inject cheats may be exposed. It is often not necessary to include other game assets, since modifying them cannot give a significant unfair advantage in gameplay.

      2. In some cases, the game engine may support verifying specific asset file formats itself.

         1. For example, the Unreal Engine supports signing and verifying its .pak archive files in an efficient way. When such support is available, it is better to use it and not include those files in the anti-cheat file integrity checks.

   2. Modifying fields under runtime_configuration to specify the following runtime settings: Note: Despite being generated across platforms, this runtime configuration is currently only respected by the Windows clients.

      1. max_active_game_instances: Configures the maximum amount of active game instances that can be run on a single PC. Leaving this undefined or setting it to zero will result in unlimited instance count.

      2. crash_reporter_name: Defines the crash reporter name which is passed to the client-side anti-cheat sandbox. The crash reporter is allowed to access the game process should a crash occur, but we will forcefully terminate the game process within 30 seconds of granting said access to maintain game integrity.

      3. anti_tamper_solution_name: Name of an antitamper solution the game is using. Currently recognized ones are: Arxan, Denuvo, Themida, StarForce, VMrotect, SteamDRM. Should your game use a proprietary solution or another unlisted solution you may pass “Generic” as the argument here to ensure compatibility with the service.Open a command prompt and run the tool as follows: anticheat_integritytool.exe -target_game_dir <game_root_directory> -productid <your eos_product_id>

4. On success, the tool will output files to the EasyAntiCheat\Certificates subdirectory of the target_game_dir you specified.

You must launch your game with the Anti-Cheat Bootstrapper helper executable to ensure that anti-cheat protection components can load immediately when the game process is created. Any command line arguments you pass to the Anti-Cheat Bootstrapper will be automatically forwarded to your game executable.

1. Fill in your ProductId, SandboxId and DeploymentId in the EasyAntiCheat/Settings.json file. These values can be found on the Product Settings page of your Developer Portal.
2. List your final game executable in the Settings.json file to call the EOS SDK APIs and be protected by anti-cheat.
   1. For example, Unreal Engine is often configured to output a small BootstrapPackagedGame helper executable in the game root directory while the actual game executable resides in a subdirectory such as Binaries\Win64. The executable listed in Settings.json must be the one in Binaries\Win64 since this is what actually needs to be protected by the anti-cheat.
3. Optional configurations:

   1. title: Provide a desired title (caption) for the launcher process, if one is not provided the default “Easy Anti-Cheat Launcher” will be used.

   2. wait_for_game_process_exit: To access the game process’s exit code, set this to 1 to keep the launcher process open. The launcher window hides itself once the game process window becomes visible.

   3. requested_splash: Path to a custom splash screen image, typically one with the game’s own graphics

      1. Format: only .png is supported.
      2. Size: Must be 800x450 pixels.

   4. Icon Customization

      1. Windows

         1. Starting with EOS SDK 1.15 the bootstrapper will attempt to extract the target executable’s icon, specified in the executable field.

            Should that fail, the embedded Easy Anti-Cheat logo icon will be used.

            If you wish to use another icon for the bootstrapper, you may do so by placing your icon file at EasyAntiCheat/BootstrapperIcon.ico

            Note that these changes only affect the icon displayed in the Windows taskbar and task manager.

            To customize the icon shown in the Windows taskbar, place your custom icon file at EasyAntiCheat/BootstrapperIcon.ico.

            The icon that Windows Explorer shows for the bootstrapper executable when browsing files on disk is embedded in the file itself and cannot be changed. However, most PC stores including the Epic Games Store (Usage Reference) and Steam can be configured so that game shortcuts use any icon of your choice.

      2. Mac

         1. Starting with EOS SDK 1.15 the bootstrapper will be stored in its own .app bundle.

            This adds the Easy Anti-Cheat icon for the bootstrapper while also making it possible to modify it. To change the icon, you may replace the AntiCheatIcon.icns with your own .icns file.

            Note that the bundle expects the file name to remain the same and since the bundle is signed, modifying the icon will require for you to sign the bundle again using your own signature.

Should you encounter any issues with either required or optional configuration the bootstrapper’s log file is always the best reference.

In some cases it is useful to distribute multiple bootstrapper configuration files and switch between them at launch time, for example if the same game distribution may be used in either a production or a test environment where SandboxId or DeploymentId values differ, or if multiple different game executables may be used depending on the user’s chosen launch settings.

You can specify the configuration file to use at game launch by passing a command line argument of the format -anticheat_settings=SecondarySettings.json where SecondarySettings.json is replaced with the filename of the config file you want to use. This argument will be consumed by the bootstrapper and not forwarded to the game executable.

The Anti-Cheat Client and Server interfaces generate callback events during multiplayer game sessions to maintain connectivity and enforce anti-cheat protection for players. You must configure these before the first protected multiplayer game session begins, but there are some differences depending on the mode you use.

The Anti-Cheat Client has a mode-agnostic callback that informs the game process on any anti-cheat client integrity violations which have occurred.

To register a callback when the anti-cheat has violation information to provide for the game process, use EOS_AntiCheatClient_AddNotifyPeerAuthStatusChanged.

The messages provided to the callback must be displayed to the player in the provided format. This helps them in understanding why they may be unable to join online multiplayer sessions. The provided message is always provided in a localized format.

The functionality does not expose information to the users that they could leverage to gain advantage in these protected sessions.

To register callbacks triggered when an anti-cheat message must be delivered to a connected client or to the game server using the game’s own networking features, use EOS_AntiCheatServer_AddNotifyMessageToClient and EOS_AntiCheatClient_AddNotifyMessageToServer. When the callback associated with EOS_AntiCheatServer_AddNotifyMessageToClient triggers on the game server, you must use the game’s own networking features to send the opaque message data to the appropriate client. Then call EOS_AntiCheatClient_ReceiveMessageFromServer with the message data when it is received.

Conversely, when the callback associated with EOS_AntiCheatClient_AddNotifyMessageToServer triggers on the game client, you must use the game’s own networking features to send the opaque message data to the game server and call EOS_AntiCheatServer_ReceiveMessageFromClient when it is received.

EOS_AntiCheatServer_AddNotifyClientActionRequired registers a callback triggered when an action must be applied to a connected client, such as removing them from the game because their anti-cheat protection is not working as expected.

These callbacks must be removed with the corresponding functions EOS_AntiCheatClient_RemoveNotifyMessageToServer, EOS_AntiCheatServer_RemoveNotifyMessageToClient, and EOS_AntiCheatServer_RemoveNotifyClientActionRequired if the code they point to becomes invalidated.

The following callbacks are optional for the Client-Server mode and provide additional information for your game.

You may want to register a callback to trigger when a connected client reaches a new anti-cheat authentication state to limit abuse, such as preventing them from spawning into the level before the appropriate callback and status level is received. Use EOS_AntiCheatServer_AddNotifyClientAuthStatusChanged to register a callback for the new state, and remove this callback with the corresponding function EOS_AntiCheatServer_RemoveNotifyClientAuthStatusChanged if the code it points to becomes invalidated.

EOS_AntiCheatClient_AddNotifyMessageToPeer registers a callback that triggers when an anti-cheat message must be delivered to a peer. You must use the game’s own networking features to send the opaque message data to the appropriate peer and then call EOS_AntiCheatClient_ReceiveMessageFromPeer when it is received. EOS_AntiCheatClient_AddNotifyPeerActionRequired registers a callback triggered when you must apply an action to a connected peer, such as removing them from the game because their anti-cheat protection is not working. It is up to the game to decide the most appropriate way to handle this action in the current gameplay context.

The simplest way for a non-authoritative client to react when notified that a peer should be removed is to disconnect from the game with a clear error message. This solution works well in small game sessions such as 1v1 matches, but more complex game logic may be required for larger scales. EOS_ANTICHEATCLIENT_PEER_SELF is a special handle representing the local game client used to signal that the local game client cannot participate in online play (it will be rejected by peers).

To register a callback triggered when the authentication status of a peer changes, use EOS_AntiCheatClient_AddNotifyPeerAuthStatusChanged. It may take up to 60 seconds for this callback to trigger after a new peer is registered and communications established. For example, this callback may be used to allow only some actions from a peer until anti-cheat authentication is fully completed.

The authentication is considered as fully completed when the above-mentioned callback is called with EOS_EAntiCheatCommonClientAuthStatus::EOS_ACCCAS_RemoteAuthComplete. This means the user has successfully authenticated with the anti-cheat back-end.

If players are allowed to participate in online play prior to the authentication fully completing it’s not guaranteed that they are running the anti-cheat client-side protection. In these circumstances they could play until the authentication timeout kick occurs.

Should the game’s integrity depend on players not leaving active online sessions this full authentication check must be in place.

The Anti-Cheat interfaces are only active when your players are participating in a multiplayer game to be protected. You must use the following APIs to notify the interfaces when a player joins or leaves a protected multiplayer session.

The Anti-Cheat Client interface must be notified when the local user is entering a protected multiplayer game session using EOS_AntiCheatClient_BeginSession.

When using the Client-Server mode, the Anti-Cheat Server interface must also be notified when a protected multiplayer session is starting with EOS_AntiCheatServer_BeginSession.

EOS_Platform_Tick must be called frequently. See the Platform Interface for more information.

For a dedicated server (Client-Server Mode), you must register each client present in a protected game session using EOS_AntiCheatServer_RegisterClient. Call this function for each player present at the beginning of the protected game session, and any time during a protected game session for players who join while it is in progress.

These calls on the game server must match calls to EOS_AntiCheatClient_BeginSession and EOS_AntiCheatClient_EndSession on the client.

For example, you may choose to unregister clients when a level transition starts and re-register them when it ends. You must just ensure each client also ends and restarts its own protected game session the same way.

Registered clients must also be unregistered when they leave the protected game session or when it ends by using EOS_AntiCheatServer_UnregisterClient.

When the local user leaves a protected multiplayer game session, the Anti-Cheat Client Interface must be notified using EOS_AntiCheatClient_EndSession.

When a game server ends a protected multiplayer game session, the Anti-Cheat Server Interface must be notified using EOS_AntiCheatServer_EndSession.

Gameplay data functionality is optional and can provide additional data about the game state for anti-cheat purposes. These are currently specific to action/shooter genre games and not applicable for other genres.

For example, the anti-cheat service may be able to detect aim-assisting cheats in shooter games using this data from the server without any reliance on the client.

A set of common, built-in events can be logged using the EOS_AntiCheatServer_LogGame… and EOS_AntiCheatServer_LogPlayer... functions. You should call these functions as frequently as the associated events occur. The SDK contains logic to process the events in an efficient way and limit the amount of network traffic generated.

In addition to built-in events, you can define arbitrary custom events by calling EOS_AntiCheatServer_RegisterEvent at game startup prior to the beginning of the first protected game session. EOS_AntiCheatServer_LogEvent can then be used to log these events during a protected game session. Is it recommended to use built-in events whenever possible since these benefit from specific optimizations.

If cheat detections are generated for your game, they appear as pending sanctions on the Sanctions page of your Developer Portal. You must review and decide whether to activate each of these sanctions in your game according to your own best judgement.

To avoid disclosing detection details to cheat developers, the raw data that led to a cheat detection is not available. If an incorrect cheat detection is discovered, sanctions associated with it will be automatically marked as removed with an appropriate message.

If a new anti-cheat client module was activated and issues appeared around the same time, revert to the previously used client module.

If excessive numbers of players are suddenly being removed from protected game sessions due to anti-cheat violations, change the Anti-Cheat Service Configuration to “Enable Client protection while Server kicks is disabled” to unblock players and provide more time for troubleshooting.

For most anti-cheat issues, the best place to start is with log data.

The Anti-Cheat interfaces are components of the EOS SDK that generate log output programmatically instead of creating a direct log file by using the Logging Interface. Your game code must write this log data to a useful location for troubleshooting use.

To troubleshoot issues during development, we recommend setting the log level for anti-cheat to VeryVerbose.

The Service and Anti-Cheat Bootstrapper create their own log files automatically.

• Windows: %AppData%\EasyAntiCheat\service.log

• Windows:
  • Module download info: %AppData%\EasyAntiCheat\<Your ProductId>\<Your DeploymentId>\loader.log
  • Bootstrapper log: %AppData%\EasyAntiCheat\anticheatlauncher.log
• Linux:
  • Module download info: .cache/com.epicgames.easyanticheat/<Your ProductId>/<Your DeploymentId>/loader.log
  • Bootstrapper log: .cache/com.epicgames.easyanticheat/anticheatlauncher.log
• Mac:
  • Module download info: /Users/<Current_User>/Library/Caches/com.epicgames.easyanticheat/<Your ProductId>/<Your DeploymentId>/loader.log
  • Bootstrapper log: /Users/<Current_User>/Library/Caches/com.epicgames.easyanticheat/anticheatlauncher.log

In Client-Server Mode, this error means that the game server did not receive any anti-cheat authentication messages from the game client. The timeout period begins at the moment when EOS_AntiCheatServer_RegisterClient is called and ends after RegisterTimeout seconds. The most common causes for this are:

• Message passing between the game server and game client is not implemented correctly. Verify that the messages are being passed as documented and that they are not being corrupted or truncated during processing by your game’s own networking features.
• The game server called EOS_AntiCheatServer_RegisterClient while the game client was in a blocking load phase and unable to communicate. Verify that the client has finished any blocking load phases before the server calls EOS_AntiCheatServer_RegisterClient, but do not allow the client to take any meaningful gameplay actions until afterwards to prevent exploits.
• The game client was started without the anti-cheat bootstrapper so it does not have anti-cheat protection. Verify that the normal launch flow includes the anti-cheat bootstrapper.

This error means that anti-cheat data flow stopped for an extended period of time after the initial authentication. The most common causes for this are:

• The game server or local peer is experiencing performance problems and anti-cheat messages are being delivered very slowly or not at all. Verify that the game logic is running normally by checking your own performance metrics.
• The client or peer disconnected but the corresponding UnregisterClient function was not called. Verify that the UnregisterClient function is always called upon disconnection.

This error means that the Anti-Cheat Bootstrapper was unable to load the anti-cheat module and started in failsafe “null client” mode instead. See Anti-Cheat Bootstrapper logs on the affected machine for more details. The most common causes for this are:

• The Anti-Cheat Bootstrapper was unable to download the anti-cheat module at game start because of an internet connection problem or firewall.
• The player is launching the game on a platform where no client module has been activated, for example using Wine/Proton when no Linux module has been activated.
• The Client Protection setting in your Developer Portal was disabled, then the service was fully re-enabled without waiting for the recommended transition period.

This error means that an anti-cheat client violation error occurred on the corresponding game client. Full details are provided by either the ClientIntegrityViolated`` callback or the EOS_AntiCheatClient_PollStatus function. See Protected Game Session Notifications.

In Client-Server Mode, this error means that a player has been temporarily blocked from playing on the current game server. The most common causes for this are:

• Anti-cheat messages are being frequently lost or discarded in transmission between the game client and game server.
  • Verify that the player's internet connection is working normally.
  • Verify that the game server is performing normally using your own performance metrics.
  • Verify that game code is not applying network prioritization logic that may cause anti-cheat messages to be selectively discarded.
  • Verify that EOS_AntiCheatServer_RegisterClient is being called with a valid and correct AccountId or UserId. Using the same value for different users may cause this error.

This error may be displayed on a game client if a critical anti-cheat component is terminated or if the machine is configured in a way that bypasses default Windows kernel security features.

One common cause of this error is hardware control (e.g. RGB lighting) software packages that bundle and run drivers with well known security vulnerabilities which have been abused for cheating. In these cases, we recommend that players update to the latest available version of the software package or contact the software vendor if no fixed version is available.

Debuggers will not work while the anti-cheat protection is active.

For normal game development tasks, we recommend that you simply run the game without the anti-cheat protection active by starting the game executable directly instead of using the anti-cheat bootstrapper executable.

When the game is started this way, the anti-cheat protection will not be active and will not interfere with debuggers. If the anti-cheat has been integrated correctly, it should not be possible to join a protected multiplayer session in this situation.

Crash dumper tools that run as a separate process in Windows need to read the memory of the game process to work correctly. Unfortunately, this level of access can be easily hijacked or abused for cheating so it is prevented in normal circumstances by the anti-cheat protection.

To be compatible with the anti-cheat protection, an external crash dumper must not attempt to open a Windows process or thread handle to the game process with memory access rights until an abnormal condition that should trigger a dump is recognized. When an abnormal condition is recognized, a full access handle can be opened and the game process memory briefly accessed for crash handling purposes. During this time, the game process threads will be automatically suspended. After a short delay, the game process will be terminated to prevent abuse.

The anti-cheat protection will automatically recognize the Windows WerFault and Unreal Engine CrashReportClient dumpers which are known to meet these requirements. If your crash dumper also meets the requirements, then setting the executable’s file name to anything that begins with “CrashReport” will allow it to operate in the same way.

Note that some crash dumper tools which are not compatible will immediately open a full access handle to the game process every time it starts. Attempting to use one of these tools will cause the game to hang then terminate soon after starting because of the logic described earlier.