Running several levels on one server
One server can run several levels at the same time: Kuttenberg, Trosky and the monastery. Each one is a region. A player sent to another region sees a loading screen while their game changes level. They never close the game, and they keep their player ID.
A server runs one level unless you set this up. Nothing changes for a server whose server.toml has no [cluster]
section.
The first half of this page is for server owners: how it works and how to set it up. The second half is for whoever writes
the game mode. Everything it uses is in the Regions group of the server API. The examples
are Lua; a C# mode has the same calls on IServerApi and IGameMode.
How it works
Section titled “How it works”- One server, one port, several levels. The level in
[server] levelis the main level. The levels under[cluster] regionsrun beside it in the same server program, each with its own simulation thread. Players connect to the one address and port as always. - Each level is a world of its own. It has its own NPCs, doors, chests and map, and its own copy of the game mode. A player sees and meets only the players on their own level.
- Some things cover the whole server: the player limit, the bans, the chat, the scoreboard, parties and the entry on the server list (it counts the players on every level).
- A trip is a short reconnect. When the game mode (or an admin’s
/travel) sends a player to another level, the player leaves this level as if they logged out, their game loads the other level behind a loading screen, and they join there as if they logged in. The server signs the trip, so a player cannot fake one. - New players join on the main level. A returning player can start on the level they left, when the game mode keeps that and says so before the game starts. Their game then loads that level straight away.
- A level that fails does not take the server down. A level that crashes, or is stuck for
[server] stall_exitseconds, is shut. Its players are sent to the main level, and it starts again by itself a few seconds later, empty. Only the main level failing stops the whole server.
Setting it up
Section titled “Setting it up”-
Export the game’s data for every level. Each level loads its own terrain, navigation mesh and collision files, as a single-level server does (the guides). The export tools do all three levels by default.
-
List the levels in
server.toml, and give each one a spawn:[server]level = "kutnohorsko" # the main level: new players join here[cluster]regions = ["trosecko", "klaster"][spawn]kutnohorsko = [752.0, 3346.0, 142.3, 0.0]trosecko = [2444.0, 2615.0, 221.0, 0.0] # Trosky castle's yardklaster = [1280.0, 1088.0, -1.0, 0.0]Trosky has no spawn of its own by default. Keep its spawn inside the area the world map draws: a player outside that area has no figure on the map. A
zbelow0puts the player on the ground. -
Check the machine against what the server needs.
-
Start the server. The log names the levels it runs, in a line that starts with
cluster:. Each level also writes its own lines, marked with its name, such as[trosecko].
Each extra level keeps its own small database file beside the main one (data/server-trosecko.db for the doors, gates and
chests of Trosky), and the map editor keeps a map for each level. Everything else in server.toml is shared.
What the server needs
Section titled “What the server needs”For all three levels and about 500 players in total:
| Recommended | Minimum | |
|---|---|---|
| CPU | 8 cores / 16 threads of a recent, fast processor (such as AMD Ryzen 7000 / 9000 or EPYC 4004 / 4005) | 6 cores |
| Memory | 16 GB | 12 GB |
| Upload | 1 Gbit | 500 Mbit |
- Why the cores: every level runs on its own core, and the game mode runs on its level’s core too. The network and the updates sent to each player use the cores left over. Speed per core matters more than the number of cores: a server with shared or slow virtual cores falls behind long before it runs out of them.
- Why the memory: the three levels with their exported data take about 2.5 GB before anyone joins. Each player adds a few megabytes, and the game mode adds its own: its NPCs, carts and items, and the map edits of each level. Take 32 GB for a mode with many NPCs or large edited maps.
- The upload: set
reliable_ratefrom the table on the settings page. One network thread ([server] network_threads = 1, the default) is enough for 500 players.
These figures come from our load tests and the biggest public servers. Every game mode is different, so watch the server
log’s tick time: line every 10 seconds and the memory in the first busy evenings, and adjust.
What players see
Section titled “What players see”- A trip shows the KCD:MP loading screen for about as long as the level takes to load. They keep their player ID, their chat and their party.
- The scoreboard lists the players of every level.
- Trips are tested on the Steam and GOG copies of the game. The Microsoft Store and Epic Games Store copies can travel too, but have not been tested yet.
- A trip on horseback leaves the horse behind.
The shipped game modes
Section titled “The shipped game modes”-
BasicRP keeps a logged-in player logged in across a trip, and brings a player who logged out on Trosky or at the monastery back there at their next join. What they carry goes across through its database, as at any login.
-
freeroam keeps nothing: a player who travels arrives at the level’s spawn.
-
In both, only admins send players, with
/travel <region>or/travel <player> <region>. For players to travel by themselves - at a road’s end, a ferry, a cart driver or a command - the game mode needs a few lines of its own. For example, a circle at the edge of Kuttenberg that leads to Trosky:local toTrosky = GetLevel() == "kutnohorsko" and CreateCircleZone(3500, 1200, 8) or nilfunction OnPlayerEnterZone(pid, zone)if zone == toTrosky thenSendPlayerToRegion(pid, "trosecko") -- the spawn of TroskyendendEach level runs its own copy of the mode, so the
GetLevel()check makes the circle only on Kuttenberg.
For game mode authors
Section titled “For game mode authors”The rest of this page is how a game mode uses the regions.
Sending a player
Section titled “Sending a player”SendPlayerToRegion(pid, "trosecko") -- the level's spawn, or the mode's OnPlayerRequestSpawnSendPlayerToRegion(pid, "trosecko", { x = 125, y = 2045, z = -1, yaw = 90 }) -- a place on that level; z below 0 = on the groundSendPlayerToRegion(pid, "trosecko", { data = "logged" }) -- a short string the other level reads at the arrivalIt returns true, or false and the reason. An admin can do the same with /travel <region> or /travel <player> <region>.
Before the player goes, OnPlayerTravel may keep them here or change the data.
Then OnPlayerDisconnect runs as for any leave. On the other level they
join as any player does, and OnPlayerArrive comes after their spawn.
GetPlayerArrival reads where they came from from their join on.
Each level runs its own copy of your mode, with its own variables. Nothing a player carries crosses by itself: their
bags, money, stats and anything else your mode keeps go across through your database. Save it in OnPlayerDisconnect and
load it at the arrival, just as for a player who logs out and back in. A login can cross the same way: send data = "logged"
from OnPlayerTravel, and on the other level treat an arrival with that data as logged in. The data is signed by the
server, so a player cannot forge it.
Bringing a player back to the level they left
Section titled “Bringing a player back to the level they left”By default a returning player joins on the main level. To bring them back where they left, keep their level in your
database (with their place) and answer OnPlayerChooseRegion. The
launcher asks just before it starts the game, so the game loads that level straight away. There is no load of the main
level first.
function OnPlayerChooseRegion(ask, name, uid) db:Query("SELECT level FROM players WHERE name = @n", { n = name:lower() }, function(rows, err) AnswerPlayerRegion(ask, not err and rows[1] and rows[1].level or nil) end)endAnswerPlayerRegion may come at once or from a database callback, within
2 seconds. No answer in time, nil, or a level that is not running starts the player on the main level. name is what the
player typed in the launcher and uid is the ID their join will have (GetPlayerUid;
"" before their first game on this server). Both are only what the player says, not proof of who they are: use them to
pick a level, never to log someone in. Your login stays as it is, and once they are logged in you put them at their saved
place with SetPlayerPos.
Save the level and place soon after a trip’s arrival, not only when the player leaves. A game that crashes a minute after
a trip would otherwise bring the player back on the level before it. If your mode only knows where a player belongs after
their login, send them on with SendPlayerToRegion after it; that costs them a second loading screen.
A plain join that names another level is accepted, because a player who reconnects after a server restart needs it. A mode
that keeps a level closed checks in OnPlayerConnect: GetPlayerArrival
answers nil when the player did not come on a trip.
Talking across the levels
Section titled “Talking across the levels”SendClientMessageToAlland the players’ own chat reach every level;SendClientMessageToRegionstays on this one, andSendClientMessageToNamefinds a player on any level.TriggerRegionEventsends an event to your mode’s copy on another level (OnRegionEvent).SetClusterValueandGetClusterValueshare short strings between the levels (OnClusterValueChange). They are not saved.GetClusterPlayersandGetPlayerRegionsay who is where. A function that takes a player ID works on the player’s own level only.
When a level goes down
Section titled “When a level goes down”A level that crashes, or stays stuck for [server] stall_exit seconds, is given up while the others go on. Its players are
sent to the main level, the other levels hear OnRegionDown, and trips to it are
refused until it is back: it starts anew after 5 seconds, at most 3 times in 10 minutes, and
OnRegionUp says so. IsRegionUp asks
at any time. A level that starts anew keeps only what is in your database: your mode’s variables, NPCs, carts and
pickups there start fresh. Save as things change, not only when a player leaves. The main level going down stops the server.
Limits
Section titled “Limits”- Trips have not been tested on the Microsoft Store or Epic Games Store copy of the game yet.
- A party invitation reaches players on the same level only.
- A trip on horseback leaves the horse behind.
