Unreal Engine 5.8

The Unreal plugin

WorldPlane's game side is two Unreal Engine 5.8 plugins: WorldPlane, which every game needs, and WorldPlaneGAS, for games that use the Gameplay Ability System. The plugin knows nothing about any particular game: your game takes part through settings, a few hooks and components, and keeps its own rules in its own code.

What you need#

• Unreal Engine 5.8. A dedicated server target needs a C++ project and an engine built from source, as for any Unreal dedicated server.
• The Linux cross-compile toolchain for your engine version, to package the Linux server WorldPlane runs (LINUX_MULTIARCH_ROOT set).
• An active WorldPlane subscription: subscribers download the plugins from the panel.
• The worldplane CLI, to check the project and push builds (see CLI). Everything it does can also be done in the panel or the API.

Installing the plugins#

The download holds two plugin folders. Copy them into your project's Plugins folder, next to the .uproject:

MyGame/
  MyGame.uproject
  Plugins/
    WorldPlane/        WorldPlane.uplugin, Source/, Binaries/
    WorldPlaneGAS/     WorldPlaneGAS.uplugin, Source/   (only with the Gameplay Ability System)
  Source/
  Config/

Then enable them in the .uproject, or in the editor's Edit → Plugins (both are under Networking, marked experimental):

"Plugins": [
  { "Name": "WorldPlane", "Enabled": true },
  { "Name": "WorldPlaneGAS", "Enabled": true }
]

• WorldPlane has three runtime modules: WorldPlaneCore (settings, entities, coordinator, telemetry), WorldPlaneIris (handoff, ghosts, owner calls) and WorldPlaneProxy (the gateway). It enables the engine plugins it needs: Iris, MultiServerReplication and OnlineSubsystemUtils.
• WorldPlaneGAS is off by default. It needs WorldPlane and GameplayAbilities, which it enables.
• The server library. WorldPlane loads a native library, wp_runtime, from Plugins/WorldPlane/Binaries/ThirdParty/WPRuntime: Win64/wp_runtime.dll for editors and Windows servers, Linux/x86_64-unknown-linux-gnu/libwp_runtime.so for Linux servers. It is staged into packaged servers by itself. Client targets build without it. If the file is missing, a server or editor build stops with WorldPlane: ... is missing.

Regenerate project files and build the editor target once, so the plugin's modules compile with your project.

Project setup#

Four engine settings and one module line make a project ready. worldplane check --fix makes these changes for you (see checking a project).

Config/DefaultEngine.ini#

[ConsoleVariables]
net.Iris.UseIrisReplication=1
net.EnableSupportForNoPawnConnection=1
net.SubObjects.DefaultUseSubObjectReplicationList=1

[/Script/IrisCore.ObjectReplicationBridgeConfig]
NetRefHandleGeneratorClass=/Script/WorldPlaneIris.WPNetRefHandleGenerator

[/Script/Engine.Engine]
LocalPlayerClassName=/Script/WorldPlaneCore.WPLocalPlayer

Iris support in your modules#

Every module that declares replicated FFastArraySerializer properties, third-party plugins included, calls SetupIrisSupport in its Build.cs:

public MyGame(ReadOnlyTargetRules Target) : base(Target)
{
    // ...
    SetupIrisSupport(Target);
}

Project Settings → Plugins → WorldPlane#

The plugin's settings are saved in Config/DefaultGame.ini under [/Script/WorldPlaneCore.WPSettings]. The defaults suit most games; the ones you are most likely to touch:

Checking a project#

worldplane check reads a project's config and C++ (no editor, no build) and lists what it needs before it runs on WorldPlane, each finding with a file and line. It exits 1 when there are errors.

worldplane check path/to/MyGame          # or path/to/MyGame.uproject
worldplane check path/to/MyGame --fix    # make the mechanical changes first
worldplane check path/to/MyGame --json

--fix makes the changes that need no judgment about the game, then reports what is left: it lists or enables the plugin in the .uproject, sets the four DefaultEngine.ini settings, adds SetupIrisSupport(Target) to modules with fast arrays, and adds the damage-forwarding line to pawns' TakeDamage (with the include and module dependency it needs). Files keep their byte-order mark and line endings; a file that isn't UTF-8 is left alone, with the reason.

It parses C++ by its shape, not with a compiler, so it can miss things and, rarely, flag what is fine. Blueprints and levels are binary and are not read.

What game code needs#

Plain game code works across servers. Most of what a single-server game does needs nothing new; a few patterns that only hold on one server need a change.

What needs nothing#

• Entity identity. Zone servers give every pawn, player controller and PlayerState a UWPEntityComponent as it spawns or loads. A pawn is a player's while a player controls it, otherwise an NPC.
• Network handles are deterministic through the handle generator in the config.
• Moving players. Pawn, controller and PlayerState move with their SaveGame properties, movement mode and character movement timestamps.
• Registering with the coordinator. A zone server started with -WPServerId and -WPCoordinator registers before its first world has actors.
• NPCs. An arriving NPC gets its default AI controller.
• Plain references across a border. An AActor* or UObject* in a client RPC or a replicated property that names another server's entity resolves to that server's ghost of it. Around each handoff of that entity (about 3 s) it still arrives as null.
• Blueprint damage and movement on a ghost (ApplyDamage, ApplyPointDamage, LaunchCharacter, AddImpulse, AddForce) runs on the owner.
• Owner-only state. COND_OwnerOnly and COND_SkipOwner properties reach the right clients through the gateway, as on one server.
• Agones. On hosted zones each server and the gateway runs as an Agones GameServer; the plugin sends its health and ready signals.

What needs a change#

Carrying more state in a handoff#

FWPPlayerHandoffHooks lets a game take part in a player's handoff:

• CanHandOff(Controller, Pawn): on the old server, each time the player is past the border; return false to wait (for example while a save is in flight).
• OnGather(Controller, Pawn, OutState): on the old server, before its actors stop.
• OnApply(Controller, Pawn, State): on the new server, after spawn and possession.
• RegisterRestoreProvider(Provider): once, at module startup. A restore provider carries one named, versioned piece of player state (skills, cooldowns, a quest log) from the old server to the new one, so the new server reads nothing from your backend.

FWPRestoreProvider Provider = FWPRestoreProvider::ForStruct<FMySkills>(TEXT("mygame.skills"), /*Version*/ 2,
    [](const FWPRestoreContext& Context, FMySkills& Out) { /* old server: fill Out */ return true; },
    [](const FWPRestoreContext& Context, const FMySkills& In, int32 SentVersion) { /* new server: apply In */ return true; });
Provider.MinVersion = 1;                              // still reads v1 from servers on the previous build
Provider.DependsOn = { TEXT("mygame.character") };    // applied after that provider
Provider.OnFailed = [](const FWPRestoreContext& Context, EWPRestoreFailure Reason) { /* read your backend instead */ };
FWPPlayerHandoffHooks::RegisterRestoreProvider(MoveTemp(Provider));

• Gather also runs every wp.CheckpointSeconds (2 s) with Context.bCheckpoint set, for crash recovery: keep it cheap and free of side effects. If a server stops, the server that now owns the player's position rebuilds them from the last checkpoint, and the gateway keeps the player connected meanwhile.
• Apply runs before the arriving actors first replicate, and must not wait for anything.
• Failures are never silent: each is logged on the new server, and OnFailed gets the reason (not_sent, version_mismatch, apply_failed, dependency_failed, scope_mismatch).
• A game with persistence makes sure the old server writes nothing after the handoff.

WorldPlane player accounts (optional)#

A game without accounts of its own can use WorldPlane's, per environment:

1. Your launcher or login screen signs the player in with POST /v1/play/{tenant}/{project}/{env}/sessions (or /accounts to sign up) and gets a token, good for an hour.
2. The client connects to the gateway with ?token=<token>. token is in ForwardedLoginOptions by default.
3. Turn on bRequirePlayerToken. The zone's coordinator checks the token on the player's first join, and refuses that player alone if it is missing, expired or for another environment.
4. Read who the player is from the login options WPPlayer= (a stable id) and WPPlayerName=, in PreLogin, Login or PostLogin.

Games with their own accounts leave it off and forward their own token through ForwardedLoginOptions. A server that should accept the gateway's own connection without the game's normal login check calls WorldPlane::IsTrustedGatewayLogin(World, Options) in its PreLogin.

Packaging a Linux server build#

WorldPlane runs the dedicated server for Linux x86-64. Servers and the gateway run the same build.

1. A server target. Add Source/MyGameServer.Target.cs if your project has none:

   using UnrealBuildTool;
   
   public class MyGameServerTarget : TargetRules
   {
       public MyGameServerTarget(TargetInfo Target) : base(Target)
       {
           Type = TargetType.Server;
           DefaultBuildSettings = BuildSettingsVersion.Latest;
           IncludeOrderVersion = EngineIncludeOrderVersion.Latest;
           ExtraModuleNames.Add("MyGame");
       }
   }

2. Build, cook and stage it for Linux with Unreal's automation tool, from your engine folder (or package Linux Server from the editor's Platforms menu):

   Engine\Build\BatchFiles\RunUAT.bat BuildCookRun -project="C:\Path\MyGame\MyGame.uproject" -noP4 ^
     -noclient -server -serverplatform=Linux -serverconfig=Development ^
     -build -cook -stage -pak -map=/Game/Maps/World ^
     -stagingdirectory="C:\Builds\MyGame" -unattended -utf8output

   The staged server is in C:\Builds\MyGame\LinuxServer, with MyGameServer.sh at its top.

3. Zip the LinuxServer folder and check the archive as the control plane will:

   worldplane build check MyGameLinuxServer.zip

4. Push it, or upload it in the panel's Builds:

   worldplane build push --project mystudio/mygame --label 0.4.1 MyGameLinuxServer.zip

An archive is accepted when it has:

• exactly one <Name>Server.sh;
• a <Name>Server binary under Binaries/Linux that is an x86-64 Linux executable;
• the WorldPlane plugin, loose (Plugins/WorldPlane/WorldPlane.uplugin) or listed in the staging manifest Manifest_UFSFiles_*.txt that packaging writes beside the pak, at plugin Version 1 or later;
• no files that look like secrets: .env, *.pem, *.key, id_rsa*, id_ed25519*. Secrets come from the environment, never from builds;
• at most 20 GiB.

Server arguments#

You don't start servers yourself: the zone's coordinator does. Every zone server gets the map, then:

-log -unattended -nosteam -port={game_port} -WPServerId={index} -WPScope={tenant}/{project}/{env}
-WPCoordinator={coordinator} -WPTransportPort={transport_port} -WPSessionKey=...

The gateway is the same build, started with the map and:

-log -unattended -nosteam -port=7777 -ini:Engine:[ConsoleVariables]:wp.proxy.Enabled=1
-WPScope={tenant}/{project}/{env} -WPCoordinator={coordinator} -WPSessionKey=...

Your own arguments come after these, on every server and the gateway: the environment's extra_args, set with --server-arg in the CLI or Extra server arguments in the panel. They can use placeholders:

worldplane env secret set mystudio/mygame/test API_TOKEN
worldplane env update mystudio/mygame/test "--server-arg=-ApiToken={env:API_TOKEN}"
worldplane deploy mystudio/mygame/test <build id>

Read it in your game as any command-line value:

FString Token;
FParse::Value(FCommandLine::Get(), TEXT("ApiToken="), Token);

--server-arg replaces the arguments, so give every one the servers need. Arguments and secrets take effect at the next deploy.

The plugin's own arguments#