Skip to content

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.

  • One server, one port, several levels. The level in [server] level is the main level. The levels under [cluster] regions run 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_exit seconds, 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.
  1. 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.

  2. 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 yard
    klaster = [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 z below 0 puts the player on the ground.

  3. Check the machine against what the server needs.

  4. 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.

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_rate from 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.

  • 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.
  • 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 nil
    function OnPlayerEnterZone(pid, zone)
    if zone == toTrosky then
    SendPlayerToRegion(pid, "trosecko") -- the spawn of Trosky
    end
    end

    Each level runs its own copy of the mode, so the GetLevel() check makes the circle only on Kuttenberg.

The rest of this page is how a game mode uses the regions.

SendPlayerToRegion(pid, "trosecko") -- the level's spawn, or the mode's OnPlayerRequestSpawn
SendPlayerToRegion(pid, "trosecko", { x = 125, y = 2045, z = -1, yaw = 90 }) -- a place on that level; z below 0 = on the ground
SendPlayerToRegion(pid, "trosecko", { data = "logged" }) -- a short string the other level reads at the arrival

It 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)
end

AnswerPlayerRegion 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.

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.

  • 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.