12. Multiplayer in the editor#

For: configurators, and C++ programmers in the “Under the hood” dropdowns. Needs: Tutorial 6. You will: run a feature that starts a listen server with two clients in Play In Editor, check that every client joins, keep the feature out of packaged runs with a filter tag, and learn the usual ways to test multiplayer in packaged builds.

In the editor, Play In Editor can run a listen server and several clients in one process. Each player gets its own world. The server world holds one player controller per player; each client world holds only its own. The Networking feature checks exactly that.

The feature as text#

Source/ZagalaSpecExamples/Features/Networking.zagalaspec:

@ZagalaSpec.Import.Features.Networking
Feature: Networking
  As a developer testing multiplayer, I want to verify that every client joins
  a listen server started in the editor (Play In Editor with several clients in one process).

  Shared Context Extensions:
    Given the tick limit is set to 1500 ticks
    Given a test world is ready

  @ZagalaSpec.Import.Features.Networking.EveryClientConnectsToTheListenServer
  Scenario: Every client connects to the listen server
    When all clients have joined the server
    Then the server has all player controllers

  @ZagalaSpec.Import.Features.Networking.EachClientOwnsASinglePlayerController
  Scenario: Each client owns a single player controller
    When all clients have joined the server
    Then every client has one local player controller

Run it: search Features.ZagalaSpec.Import.Features.Networking in the Session Frontend. A server window and two client windows open, the scenario runs, and all three close. Two green rows.

Play In Editor running the Networking feature with a listen server and two client windows

The setup sentences#

Given the tick limit is set to 1500 ticks

The same safety net as in Tutorial 6, with a larger number. Three worlds start and the two clients go through a connection handshake, which takes longer than spawning one actor. The other world-based examples use 500.

Given a test world is ready

The same step as in Hoverboard and Checkpoint. Its capture group test world has Group Value Class set to BP_Networking_Data_PlaySettings, whose default points at DA_Networking_PlaySettings:

Field

Networking value

Meaning

Map To Load

L_Networking_TestLevel

A small level with a default game mode and player starts.

Use Fixed Time Step / Fixed Time Step FPS

true / 60

Applied to the server and to every client.

Listen Server

true

Play In Editor starts as a listen server, all players in one editor process.

Number Of Clients

2

Clients that connect to the server. The host is not counted, so the server ends up with 3 players.

The step always starts a fresh session. If one is still running from the previous scenario, it is ended first. Your own Play In Editor multiplayer settings are not used, so the scenario behaves the same on every machine.

Waiting and asserting#

When all clients have joined the server

Checks every tick of the server world until the server holds one player controller per player (3 here) and every client world has its own player controller. The server sees a client join before that client receives its controller, so both conditions are needed. If the play settings do not start a listen server, it fails with the play session settings do not start a listen server. If the clients do not join in time, it fails with tick limit 1500 exceeded without satisfying condition.

Then the server has all player controllers

Counts the player controllers in the server world and compares the count with Number Of Clients + 1. A mismatch fails with Expected 3 player controllers on the server, but found 2.

Then every client has one local player controller

Finds every client world and checks that there are exactly Number Of Clients of them, that each holds one local player controller and that each is connected to the server. Failures name the client: Client 2 has 0 local player controllers, expected 1. or Client 1 is not connected to the server.

None of the sentences contains a number. The expected counts come from the play settings, so changing Number Of Clients to 3 changes the test without touching the text.

Editor-only scenarios#

Play In Editor multiplayer exists only in the editor. In a packaged build, this feature would load one map in one process with no clients. Both scenarios are therefore tagged so they never run there:

  1. Open DA_Networking, select a scenario and open the Advanced section of its Details panel.

  2. Filter Tags contains ZagalaSpec.ScenarioFilter.Require.Editor.

Scenario Details panel with the Advanced section open and Filter Tags set to ZagalaSpec.ScenarioFilter.Require.Editor

In the editor nothing changes. In a packaged test run both scenarios are left out of the test list, and the log reports each one under LogAutomationController. Filter tags are not part of import or export, so set them again after re-importing the feature. All tags and rules are in Filter scenarios by environment in Usage.

Under the hood: starting the session

The play settings asset (UZagalaSpecPlaySessionSettings) gains two fields and a helper:

UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category = "PlaySession|Network")
bool bListenServer = false;

UPROPERTY(EditDefaultsOnly, BlueprintReadWrite, Category = "PlaySession|Network", meta = (ClampMin = "1", UIMin = "1", EditCondition = "bListenServer"))
int32 NumberOfClients = 1;

int32 GetExpectedPlayerCount() const;

GetExpectedPlayerCount() returns NumberOfClients + 1 for a listen server and 1 otherwise.

UZagalaSpecCEEnsureTestWorld builds a ULevelEditorPlaySettings for the request. It sets the net mode to PIE_ListenServer (or PIE_Standalone), sets the number of players to GetExpectedPlayerCount() (Play In Editor counts the host as a player), enables run under one process and disables a separate server. When PostPIEStarted fires, it stores the listen server world (not GEditor->PlayWorld) as UZagalaSpecDataPlaySessionWorld. If no listen server world exists, it fails with EnsureTestWorld: PIE started without a listen server world.

Under the hood: finding every world

FZagalaSpecWorldHelper has two lookups used by the Networking drivers:

static TArray<UWorld*> GetPlaySessionWorlds(ENetMode NetMode);
static UZagalaSpecPlaySessionSettings* GetPlaySessionSettingsFromCache(IZagalaSpecTaggedDataCacher* Cacher);

GetPlaySessionWorlds walks the engine’s world contexts and returns the Play In Editor worlds with the given net mode, in instance order; pass NM_Client for the clients. In a packaged build it only considers the current game world. GetPlaySessionSettingsFromCache loads the settings asset that the test world step cached, so drivers read the expected counts from the same place the session was started from.

Under the hood: the steps

Each sentence follows the Step → DSL → protocol driver layering from Tutorials 10 and 11 (Source/ZagalaSpecExamples/Public/Networking/).

Sentence

Pattern

Protocol driver

When all clients have joined the server

^(?:When |And )all clients have joined the server$

UZagalaSpecPDWaitForClientConnections

Then the server has all player controllers

^(?:Then |And )the server has all player controllers$

UZagalaSpecPDAssertServerHasAllPlayerControllers

Then every client has one local player controller

^(?:Then |And )every client has one local player controller$

UZagalaSpecPDAssertAllClientsOneController

The wait is a UZagalaSpecPDWaitForTicks subclass with no fixed tick count; only the tick limit bounds it:

class ZAGALASPECEXAMPLES_API UZagalaSpecPDWaitForClientConnections : public UZagalaSpecPDWaitForTicks
{
protected:
    virtual void InternalExecute_Implementation(const TScriptInterface<IZagalaSpecTaggedDataCacher>& AssignedCacher) override;
    virtual EZagalaSpecTickCheckResult OnTickCheck(IZagalaSpecTaggedDataCacher* Cacher, int32 TicksSoFar, FString& OutFailureReason) override;
};

InternalExecute reads the play settings, fails without them or without a listen server, stores the expected player and client counts, then calls Super, which starts counting ticks of the server world. OnTickCheck returns Continue until the server world holds the expected number of player controllers and every client world has a player controller, then Succeed.

The client assertion counts controllers for which IsLocalController() is true, then checks that the client world’s net driver has a server connection.

Going further: packaged builds#

The bundled feature stops at the editor. Multiplayer tests against packaged builds depend heavily on your project, platforms and build machines, so ZagalaSpec does not ship them. These are the approaches teams usually take, and how ZagalaSpec fits each one.

A step that launches client processes. The test runner becomes the listen server. A context extension opens the map with ?listen and starts N copies of the same executable as clients (FPlatformProcess::CreateProc with arguments such as 127.0.0.1:<port> -game -nullrhi -nosound -unattended -log=Client1.log). A wait like the one above polls the server until every client has joined, and the extension’s teardown terminates every process it started, on success and on failure. Checks run on the server. For client-side state, add a small test component whose client sends its state to the server with a server RPC. The scenario then reads it in the server world. This works on Windows, macOS and Linux, but not on consoles or mobile, which cannot start processes.

Gauntlet on the outside, ZagalaSpec inside. Gauntlet is Epic’s framework for multi-process and multi-device tests. It runs from the Automation Tool, not from inside the game. A Gauntlet test declares a server role and N client roles and starts each process with role-specific arguments. The server process runs the ZagalaSpec scenario (for example through -ExecCmds="Automation RunTests Features.<tag>" or a small Gauntlet test controller), and the clients connect and wait. Gauntlet then collects logs and results. Starting Gauntlet from inside a scenario step reverses this: the scenario’s process would not be part of the session it is testing, and it would only see an exit code.

How teams usually split it.

How often

What runs

Every change

Editor tests with multiplayer Play In Editor, like this feature

Nightly

Packaged builds through Gauntlet or a launch script: boot, connect, a few scripted flows

Milestones

Bot, soak and load tests, plus playtests

Tips for packaged runs.

  • Run clients headless with -nullrhi -nosound -unattended, and give each process its own -log= file.

  • Use a fixed port and bind to loopback (-port=, -multihome=127.0.0.1) to avoid port clashes and firewall prompts on build machines.

  • Always terminate the processes you started, including when a step fails, so orphaned clients do not block the next run.

  • Add lag and packet loss with -PktLag= and -PktLoss= (or the Net PktLag console command) to test bad connections.

  • A listen server works in a normal game build. A dedicated server needs a Server build target, which requires an engine built from source.

  • Tag packaged-only scenarios with ZagalaSpec.ScenarioFilter.Require.Game so the editor run skips them, the mirror of this feature.

What you learned#

  • A multiplayer scenario is a world-based scenario whose play settings ask for a listen server and a number of clients.

  • The server world holds every player controller; each client world holds only its own. Wait for both sides before asserting.

  • Expected counts come from the play settings, so the sentences stay free of numbers.

  • ZagalaSpec.ScenarioFilter.Require.Editor keeps editor-only scenarios out of packaged runs.

  • Packaged multiplayer tests are usually either a step that launches clients or Gauntlet starting the processes with ZagalaSpec running in the server.

You have now read every bundled feature. The API reference covers the remaining classes; the FAQ collects the questions these tutorials usually raise.