Simulated players


A simulated player is a client-worker instance that is controlled by simulated player logic as opposed to real player input. You can use simulated players to scale-test your game.

You set up simulated players by creating a character class specifically for them, and adding custom behaviour to this class. For example, you could create a player character class for simulated players and add custom movement input to it.

You launch simulated players inside a standalone cloud deployment, and they connect to a target cloud deployment.

There is no built-in logic for simulated players. However, you can look at the Example Project implementation for reference, or use the Starter Template as a starting point to implement simulated player behavior in your own project.

Setting up simulated players

To set up simulated players, you need to:

  1. Specify a class for simulated players.
  2. Set IsSimulated to true for that class.
  3. Define the logic for your simulated players.

1. Specify a class for simulated players

Inside your Game Mode constructor, specify a character class to be used for simulated players. This can be any character class, but we recommend that the simulated player character class extends your game’s player character class, so that simulated player characters inherit all the properties of your default player character class. In the following examples we will assume that you have created a character class named SimulatedPlayerCharacter_BP for simulated players.

You can specify the simulated player character class either in your C++ GameMode class or in the Class Defaults tab of your GameMode’s Blueprint class.

For example, in C++:

	// Set default pawn class to our Blueprint character.
	static ConstructorHelpers::FClassFinder<APawn> PlayerPawnBPClass(TEXT("/Game/StarterProject/Characters/PlayerCharacter_BP"));
	static ConstructorHelpers::FClassFinder<APawn> SimulatedPawnBPClass(TEXT("/Game/StarterProject/Characters/SimulatedPlayers/SimulatedPlayerCharacter_BP"));

	if (PlayerPawnBPClass.Class != NULL)
		DefaultPawnClass = PlayerPawnBPClass.Class;
	if (SimulatedPawnBPClass.Class != NULL)
		SimulatedPawnClass = SimulatedPawnBPClass.Class;

2. Set IsSimulated to true for that class

In the Unreal Editor, within your simulated player character class's Class Defaults, set the property IsSimulated to true.

3. Define the logic for your simulated players

The simulated player character class is automatically spawned for simulated players instead of the default player character class. You can define custom logic for simulated players in this class. For example, you can spawn an AIController with your simulated player logic in the BeginPlay method, and have the controller possess the simulated player character.

As an example, you could create a new project using the Starter Template and look at SimulatedPlayerCharacter_BP:

Image: SimulatedPlayerCharacter_BP from the Starter Template project

Altering client-side logic

You might want to alter some client-side simulated player logic that is not directly related to the simulated player’s character. For example, you might want to bypass a login menu, cinematics, or a tutorial.

To do this, you can use a Blueprint function library that exposes the IsSimulatedPlayer function and returns a boolean indicating whether the game client is a simulated player. This can be executed in both C++ and Blueprints.

C++ example

#include "SimulatedPlayer.h"

void AExampleActor::BeginPlay()

    if (USimulatedPlayer::IsSimulatedPlayer(this))
        // Execute simulated player related logic here.
        // ...

Blueprint example

Image: You can call Is Simulated Player from any Blueprint class, and it will return true if the current process is a simulated player client.

Launching simulated player deployments

Worker configuration file

To launch a simulated player deployment, you need to provide a worker configuration file with the following name:
spatialos.SimulatedPlayerCoordinator.worker.json. This tells SpatialOS how to build, launch, and interact with the simulated player coordinator worker, which will run the simulated players.

The Example Project and Starter Template already include this worker configuration file in the right location, but for new projects you need to add it yourself to the spatial/workers/<worker> directory.

We recommend that you copy our example configuration file, and adapt it to your project where necessary. This file contains the arguments that are passed to the simulated player game clients. For information on customising this configuration file, please visit this page.

Once you have copied the file, you'll need to run spatial build build-config from the spatial directory of your project. This will apply this new configuration to your project's executable.

Local deployments

There are two ways to launch simulated players that connect to local deployments, and you can choose which one to use.

  • Launch simulated players using the Multiplayer Options window
    You can launch simulated players as Play In Editor clients by configuring the “Number of Simulated Players” option (Edit > Editor Preferences > Level Editor > Play > Multiplayer Options):

Image: In the "Multiplayer Options" section, enter the number of simulated players

  • Launch simulated players automatically using batch scripts
    You can launch simulated players that connect to local deployments using a batch file. The Example Project contains LaunchSimPlayerClient.bat which launches a single Simulated Player client, and Launch10SimPlayerClients.bat which launches 10. If you use simulated players to test your project locally we recommend taking these scripts and modifying them for your project, to save you time.

Cloud deployments

You can scale test your game right from the start by having simulated players connect to your cloud deployment. For more information, see Launch cloud deployment.


Logs for simulated players are stored as raw logs in the simulated player deployment.

2019-11-28 Page updated without editorial review: added batch scripts to launch simulated players.
2019-11-14 Page updated without editorial review: added missing spatial build build-config step.
2019-07-31 Page added with limited editorial review.

Updated 4 months ago

Simulated players

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.