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.
The setup sentences#
Given the tick limit is set to 1500 ticksThe 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 readyThe same step as in Hoverboard and Checkpoint. Its capture group
test worldhas Group Value Class set toBP_Networking_Data_PlaySettings, whose default points atDA_Networking_PlaySettings:Field
Networking value
Meaning
Map To Load
L_Networking_TestLevelA 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 serverChecks 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 controllersCounts 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 controllerFinds 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:
Open
DA_Networking, select a scenario and open the Advanced section of its Details panel.Filter Tags contains
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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
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 theNet PktLagconsole 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.Gameso 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.Editorkeeps 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.