Simulated players

Introduction

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 test your game at scale.

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

You can start simulated players inside a standalone cloud deployment, and they connect to a target cloud deployment. You can also start local simulated players in the Unreal Editor, and they connect to a local 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:

Specify a class for simulated players.
Set IsSimulated to true for that class.
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++:

ATP_SpatialGDKGameMode::ATP_SpatialGDKGameMode()
{
	// 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()
{
    Super::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.

Starting simulated player deployments

Worker configuration file

To start 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, start, 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 start simulated players that connect to local deployments, and you can choose which one to use.

Start simulated players using the Multiplayer Options window
You can start 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

Start simulated players automatically using batch scripts
You can start simulated players that connect to local deployments using a batch file. The Example Project contains LaunchSimPlayerClient.bat which starts a single Simulated Player client, and Launch10SimPlayerClients.bat which starts 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 test your game at scale right from the start by having simulated players connect to your cloud deployment. To start simulated player deployments from the Unreal Editor, see the Cloud deployment summary. You can add simulated players in the Cloud Deployment Configuration dialog box.

If you want to start simulated player deployments programmatically, you can use the Deployment Launcher helper script. You can use the script to start multiple simulated deployments at once for greater scale.

For more information, see the following pages:

Outside China: Cloud deployment configuration
In China: Cloud deployment configuration

Logs

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

2020-09-23 Page updated with editorial review: added link to the deployment launcher helper script
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 11 months ago

GDK for Unreal

Simulated players

Introduction