Documentation

WorldPlane docs

WorldPlane is a hosted multi-server backend for Unreal Engine 5.8. A zone of your game runs across several dedicated servers at once, and your players connect to it as if it were one server. These pages cover the concepts, the Unreal plugin, the worldplane CLI, the web panel, billing and the control plane's API.

How it works#

Your game's dedicated server runs as several processes that share one world. A coordinator splits the zone's map into areas and gives each server some of them. As players and NPCs move, each one belongs to the server whose area it is in. When it crosses into another server's area, WorldPlane hands it off to that server: its pawn, controller and PlayerState move, and the player stays connected.

Players connect to one address, the zone's gateway. The gateway is WorldPlane's fork of Epic's multi-server proxy. It holds each client's connection and joins the player to every server of the zone, so a handoff never needs a reconnect. Replication runs on Iris.

The control plane at https://app.worldplane.net is where studios sign in, upload builds and deploy them. The panel, the worldplane CLI and your CI all use the same API. Each environment's zone is its own WorldPlane instance, with its own coordinator, servers, gateway and budget.

Concepts#

Organisation (tenant)#

An organisation is usually your studio. It holds your projects, your team, your API keys and your billing. The panel calls it an organisation; the API and the CLI call it a tenant.

• Its slug is its short name in URLs and commands: 2 to 18 lowercase letters, digits or dashes, starting with a letter. Slugs never change. platform, worldplane, system, kube, aws and local are reserved.
• Whoever creates it becomes its owner. Owners add members with a role, on the whole organisation or on one project: owner, admin, operator, developer, viewer or billing (see roles).
• The subscription is per organisation (see billing).
• Every change in it is written to its audit log, which owners and admins can read.

Project#

A project is one game. Its environments and its builds live in it. Its slug follows the same rules as an organisation's, and is unique within the organisation.

Environment#

An environment is one place a project runs, such as dev, test or prod. Each one has:

• a region, fixed once it is made (another region is another environment);
• zone settings: the map every server opens, the fewest and most servers, the server size, warm servers, when to sleep, and arguments for your servers;
• an optional budget, the most its zone may spend in USD an hour;
• secrets, values your servers get in their arguments without them being in a build;
• the build it runs once deployed, and a state: stopped, starting, running, sleeping or failed.

One environment is one world. A game with several realms or regions has several environments, each its own WorldPlane instance. The environment names dev and test matter for roles: developers may deploy to and set secrets on those two only. smoke is reserved.

Build#

A build is a packaged Unreal Linux server, uploaded as a zip of the LinuxServer folder (see packaging). Before anything runs it, the control plane checks the archive: one <Name>Server.sh, an x86-64 Linux server binary, the WorldPlane plugin at a supported version, and no files that look like secrets.

On app.worldplane.net a checked archive then becomes a server image (imaging), and starts once on its own (starting): the server must keep running for a minute. The build ends ready, rejected (with the reason in plain words) or failed (imaging or the start could not run; it can be tried again without another upload). A build record never changes after that.

Deploy#

A deploy puts a ready build on an environment. The control plane starts the zone's coordinator, which starts its servers and gateway. Settings changed since the last deploy take effect at the next one, and rolling back is a deploy of an older build. Stopping an environment stops its zone; its build and settings stay.

A deploy is refused when the build isn't ready, when the organisation has no active subscription or has an unpaid invoice or has reached its spend limit (402), or when the server arguments use a secret the environment doesn't have (409).

Zones and servers#

A zone is the world an environment runs: one map, served by between min_servers and max_servers servers. The coordinator orders the map's cells along a Hilbert curve, which keeps neighbouring cells together, and cuts that line into one piece per server with equal load; cells are finer where load is dense. As load moves, the areas drift toward balance, and the autoscaler adds or removes servers between those bounds and within the environment's budget.

• Server sizes: standard (1 vCPU, 2 GiB), plus (2 vCPUs, 4 GiB) or max (4 vCPUs, 8 GiB). A minute of a plus server counts as 2 server-minutes on the bill, of a max one 4.
• Warm servers (default 1) are booted, idle servers kept ready to take part of the zone at once. Each runs, and is billed, like any server. With 0, a split waits for a server to boot.
• Sleep: with sleep_after_minutes set, a zone with no players for that long stops its servers and gateway; nothing is metered while it sleeps. The public wake endpoint starts it again.

Handoff#

When a player or NPC goes far enough past the border into another server's area, the old server hands it to the new one. The plugin moves the pawn, controller and PlayerState with their SaveGame properties, the movement mode and the character movement timestamps, and waits until the new server has the player's connection and the client has acknowledged the pawn. Your game can carry more state with handoff hooks and restore providers (see what game code needs).

Near a border each server also shows its neighbour's entities as ghosts, so gameplay on one side sees what is on the other. Damage, gameplay effects and listed function calls aimed at a ghost run on the entity's owner.

Atlas#

Atlas is WorldPlane's live map. It shows a running zone's servers and their areas, and every player and NPC, coloured by the server that owns it. Open it from a running environment's page in the panel (Open in Atlas). The control plane relays the zone's live feed to anyone who may read the environment.

Getting started#

The path from nothing to players in your world. Each step works in the panel, with the CLI, or with one API call.

1. Sign up. Register at app.worldplane.net with your e-mail, name and a password of at least 10 characters. Then create your organisation in the panel, or with the CLI:

   worldplane login --url https://app.worldplane.net --email you@studio.example
   worldplane tenant create mystudio --name "My Studio"

2. Subscribe. In the organisation's Billing & usage, Subscribe at Stripe opens Stripe Checkout for the Studio plan: $100 a month for the organisation, plus server time by the minute. Owners and billing members can subscribe. Until the subscription is active, uploading builds, deploying and waking zones answer 402. Studios with $1M or more in annual revenue or budget write to info@artisangameworks.com for an Enterprise agreement. See billing.

3. Make a project for your game:

   worldplane project create mystudio/mygame --name "My Game"

4. Make an environment. Choose a region (the panel lists them; GET /v1/regions in the API), the map your servers open and how many servers the zone may use:

   worldplane env create mystudio/mygame/test --region us-east-2 --map /Game/Maps/World --max-servers 4 --budget 2

   From Git Bash, set MSYS_NO_PATHCONV=1 first, or the shell rewrites /Game/... as a Windows path, which is refused.

5. Push a build. Set up the Unreal plugin, run worldplane check on the project, package a Linux server and zip its LinuxServer folder. Then:

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

   build push uploads the archive, waits while it is checked and imaged, and prints the build's id once it is ready.

6. Deploy the build to the environment:

   worldplane deploy mystudio/mygame/test <build id>

7. Players connect. The environment's page in the panel shows Players connect to: the gateway's host:port once it is up (zone.gateway from GET .../environments/test). Point your game client there. If the zone sleeps when empty, your launcher or login service calls POST /v1/play/mystudio/mygame/test/wake first, every few seconds, until it answers running with the gateway's address.

Getting help#

The control plane's errors say what to change. If one doesn't, or something here is wrong, write to info@artisangameworks.com with what you sent and what came back.