Using the Anti-Cheat interfaces

Preview Only

The Anti-Cheat Client interface supports the Windows, Mac, and Linux platforms and requires a 64-bit operating system installation.

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

Client Module Setup and Updates

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.

Set Up, Update, and Revert Your Client Module

  1. Go to your Developer Portal.

  2. Click Your Product > Player Moderation > 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.

Check regularly for new anti-cheat modules to appear in the list of Client Module Releases in the Developer Portal.

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.

Testing a Module
  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 Details. 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.

Reverting Your Client Module

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.

We recommend reverting to the most recent previous version rather than going further into the past.

File Integrity Tool Configuration

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

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.

Configure Your Integrity Tool

  1. On your Developer Portal, go to Your Product > Player Moderation > Anti-Cheat > Download Tooling and click Download. 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 other values in anticheat_integritytool.cfg to include or exclude files as desired.

    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.

  4. Open a command prompt and run the tool as follows: anticheat_integritytool.exe -target_game_dir <game_root_directory> -productid <your eos_product_id>

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

Launch Configuration

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.

Configure the Anti-Cheat Bootstrapper Executable

  1. Fill in your ProductId and SandboxId 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. **r**equested_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 800 pixels and 450 pixels in height.

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

Registering Callbacks

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.

Client-Server Mode

Client-Server mode requires both the Anti-Cheat Client and the Anti-Cheat Server interfaces, so be aware of the naming difference between EOS_AntiCheatClient… and EOS_AntiCheatServer… when registering your callbacks.

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.

Peer-to-Peer Mode

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.

Protected Game Session Notifications

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.

Beginning a Protected Game 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.

During a Protected Game Session

Callbacks rely on calling EOS_Platform_Tickregularly. See the Platform Interface for more information.

The game client must also call EOS_AntiCheatClient_PollStatus regularly to log and display any anti-cheat client integrity errors for the player.

These messages 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.Registering Clients (Client-Server Mode)

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.

Ending a Protected Game Session

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.

Define Events for Data Functionality (Client-Server Mode)

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.

Working with Cheat Detections

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.

Troubleshooting

Logs

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.

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

Anti-Cheat Bootstrapper
  • Windows:

    • Module download info: %AppData%\EasyAntiCheat<Your ProductId><Your SandboxId>\loader.log

    • Bootstrapper log: %AppData%\EasyAntiCheat\anticheatlauncher.log

  • Linux:

    • Module download info: .cache/com.epicgames.easyanticheat/Your ProductId>Your SandboxId>/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 SandboxId>/loader.log

    • Bootstrapper log: /Users/<Current_User>/Library/Caches/com.epicgames.easyanticheat/anticheatlauncher.log

    • Launcher's own log: %AppData%\EasyAntiCheat\anticheatlauncher.log

Common Errors

AuthenticationFailed / Authentication Timed Out (1/2)

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.

HeartbeatTimeout

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.

Using Debuggers with Anti-Cheat

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.

External Crash Dumpers

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.

Integration Checklist

Note: The Anti-Cheat Client interface supports the Windows, Mac, and Linux platforms and requires a 64-bit operating system installation.

You should use these checklists to verify the integration of the Anti-Cheat interfaces and your game works properly before release.

Service Installer (Windows)

  1. Fully remove any existing Easy Anti-Cheat installation by running EasyAntiCheat_EOS_Setup.exe qa-factory-reset from a command prompt..

This ensures that your test system is in the same state as the system of a player who has never played any Easy Anti-Cheat protected game before. If you have other Easy Anti-Cheat protected games installed then they will need to be repaired or reinstalled after this operation.

  • Success criteria:

    * The command `sc query EasyAntiCheat_EOS` reports that the specified service does not exist as an installed service.
    * Registry keys do not exist at the following location: `HKLM\Software\Wow6432Node\EasyAntiCheat_EOS\`.
  1. Install the game as a player would, using e.g. the Epic Games Store, Steam, etc.

    • Success criteria:

      • EasyAntiCheat_EOS_Setup executes with Administrator rights, and it closes with exit status 0.

      • The command sc query EasyAntiCheat_EOS reports that the service exists and is in a STOPPED state when the game is not running.

  2. Uninstall the game

    • Success criteria:

      • EasyAntiCheat_EOS_Setup executes to uninstall the Easy Anti-Cheat Service.

      • The command sc query EasyAntiCheat_EOS reports that the specified service does not exist as an installed service.

Game Client & Anti-Cheat Bootstrapper

  1. Go to your Developer Portal > Your Product > Player Moderation > Anti-Cheat > Configure. Select Enable All and click Save Changes.

    • Success criteria:

      • Client Protection and Server Kicks remain enabled after refreshing the Anti-Cheat page.

  2. Start the game without the anti-cheat bootstrapper.

    • Success criteria:

      • Your game should function normally.

      • However, the player should not be able to join protected multiplayer game sessions with other players.

      • Anti-cheat authentication should fail and an appropriate message should display.

  3. Start the game with the anti-cheat bootstrapper.

    • Success criteria:

      • Your game should function normally.

      • The player should be able to join protected multiplayer game sessions with other players successfully and remain connected for more than 10 minutes.

      • The player should be able to disconnect from one protected multiplayer game session and join a different one successfully.

  4. Go to your Developer Portal > Your Product > Player Moderation > Anti-Cheat > Configure. Select Enable Client Protection Only and click Save Changes.

    • Success criteria:

      • Client Protection remains enabled after refreshing the Anti-Cheat page.

  5. Start the game without the anti-cheat bootstrapper.

    • Success criteria:

      • Your game should function normally.

      • The player should be able to join protected multiplayer game sessions with other players successfully and remain connected for more than 10 minutes.

      • The player should be able to disconnect from one protected multiplayer game session and join a different one successfully.

  6. Start the game with the anti-cheat bootstrapper.

    • Success criteria:

      • Your game should function normally.

      • The player should be able to join protected multiplayer game sessions with other players successfully and remain connected for more than 10 minutes.

      • The player should be able to disconnect from one protected multiplayer game session and join a different one successfully.

  7. Go to your Developer Portal > Your Product > Player Moderation > Anti-Cheat > Configure. Select Disable All and click Save Changes.

    • Success criteria:

      • Client Protection and Server Kicks remain disabled after refreshing the Anti-Cheat page.

  8. Start the game with the anti-cheat bootstrapper.

    • Success criteria:

      • Your game should function normally.

      • (For Windows) The command sc query EasyAntiCheat_EOS reports that the service is in state STOPPED while the game is running.

      • The player should be able to join protected multiplayer game sessions with other players successfully and remain connected for more than 10 minutes.

      • The player should be able to disconnect from one protected multiplayer game session and join a different one successfully.

  9. Go to your Developer Portal > Your Product > Player Moderation > Anti-Cheat > Configure. Select Enable All, enable Force Enable Server Kicks, and click Save Changes.

    • Success criteria:

      • Client Protection and Server Kicks remain enabled after refreshing the Anti-Cheat page.

  10. Remove one of the game's required static dependency libraries and start the game with the anti-cheat bootstrapper.

    • Success criteria:

      • Anti-cheat bootstrapper gives a descriptive error.

      • Game client process gives the standard operating system error dialog, for example, "The program can't start because libExample.dll is missing from your computer. Try reinstalling the program to fix this problem."