Project Zomboid server settings that actually matter

Project Zomboid gives you several hundred settings across three files, and about six of them decide what your server feels like. The rest is detail you can leave alone until somebody asks. The trouble is that the six are scattered - two live in the ini, three in a Lua file, one in a database - and that editing the wrong copy of any of them is the single most common reason a change appears to do nothing.

This guide covers where each setting lives, which ones matter, what the defaults are, how mods and workshop items differ, why the Java heap has to be smaller than your plan, and the errors that actually get reported.

Where a Zomboid server keeps its settings#

The dedicated server is a Java application, installed from SteamCMD as app id 380870. Unlike most Steam servers it will not download anonymously: it needs a Steam account login. Use a spare account for that, on any host, because the credential is stored as you type it.

$ steamcmd +force_install_dir /home/pz/server +login your_spare_account \    +app_update 380870 validate +quit

Everything the server remembers lives under the user's Zomboid folder, and every file in it is named after the server:

Zomboid/  Server/    servertest.ini                 ports, PVP, safehouses, mods, backups    servertest_SandboxVars.lua     zombies, loot, time, weather    servertest_spawnregions.lua    where new characters appear  db/    servertest.db                  accounts, whitelist, admin password, bans  Saves/Multiplayer/servertest/    the world, one file per explored cell  backups/                         the server's own zipped backups

servertest is the default server name, set by -servername on the start script. Change it and you get a different ini, a different sandbox file and a different world - which is a perfectly good way to run two servers from one install and an excellent way to spend an evening editing settings that nothing reads. Before you debug anything else, confirm which name the server is actually started with.

The ini file: the keys that matter#

PauseEmpty deserves a paragraph because it changes the character of a small server. With it on, time stops when the last player logs out: crops do not grow, generators do not burn fuel, and nothing rots while you are at work. With it off, the world keeps running and a fortnight away is a fortnight of decay. For a group of friends who play together, on is almost always right. For a persistent public server, off is the point.

The safehouse keys are the ones people look for in the sandbox file and never find, because they are here: PlayerSafehouse, AdminSafehouse, SafehouseAllowTrepass, SafehouseAllowLoot, SafehouseAllowFire, SafehouseAllowRespawn, SafehouseDaySurvivedToClaim and SafeHouseRemovalTime. Safehouses are a social setting rather than a mechanical one: they decide whether players can lock each other out of buildings, and therefore whether your server is one where strangers can be robbed. Set them deliberately.

There is also a block of numbered anti-cheat checks, AntiCheatProtectionType1 through AntiCheatProtectionType24, each with a matching threshold multiplier. They exist because Zomboid trusts the client with a lot of movement and inventory logic. Mods, particularly ones that add vehicles or change movement, trip them and produce mystifying kicks. The log names the type that fired: disable that one, not all of them.

The six settings that decide how it feels#

The original claim holds up: out of everything in those files, six choices make the server.

1. Zombie population. How many exist at all. This is the difference between a survival game and a horror game.
2. Respawn. Whether cleared areas stay cleared, which decides whether progress is permanent or Sisyphean.
3. Loot rarity. The difference between scavenging and shopping.
4. Day length. How much real time a survival day costs, and therefore how fast skills, farming and illness move.
5. Safehouse rules. In the ini, above. Whether players can be locked out.
6. PVP. In the ini. Decide it before launch, because changing it later changes who plays, not just how they play.

The first four live in servertest_SandboxVars.lua, which is a Lua table rather than a key-value file:

SandboxVars = {    VERSION = 5,    Zombies = 3,    Distribution = 1,    DayLength = 3,    StartYear = 1,    StartMonth = 7,    StartDay = 9,    StartTime = 2,    WaterShut = 2,    ElecShut = 2,    ZombieLore = {        Speed = 2,        Strength = 2,        Toughness = 2,        Transmission = 1,        Mortality = 5,        Reanimate = 3,        Cognition = 3,        Memory = 2,        Sight = 2,        Hearing = 2,    },    ZombieConfig = {        PopulationMultiplier = 1.0,        PopulationStartMultiplier = 1.0,        PopulationPeakMultiplier = 1.5,        PopulationPeakDay = 28,        RespawnHours = 72.0,        RespawnUnseenHours = 16.0,        RespawnMultiplier = 0.1,        RedistributeHours = 12.0,    },}

Two traps in that file. The first is that Zombies runs backwards: 1 is Insane, 2 High, 3 Normal, 4 Low and 5 None. People who set it to 1 expecting a quiet server get the opposite of what they asked for, and it is always funnier from the outside. The second is that most of the other numbered options are positions on a scale that you cannot guess from the number.

Because of that, the reliable way to produce a sandbox file is to configure it in the game's own sandbox editor - start a single-player or hosted game with the settings you want, then copy the generated Lua onto the server - rather than typing numbers into a file and hoping. DayLength = 3 is one hour of real time per in-game day, which is the default and a fair starting point; anything shorter turns farming into a full-time job.

Zombie population, respawn and lore#

ZombieConfig is where the server's difficulty really lives, and it is worth understanding rather than copying.

RespawnHours = 0 is the single biggest quality-of-life change available to a multiplayer server, and it is the one most admins eventually make. On default settings, a town you spent a week clearing gradually refills, which on a solo playthrough is tension and on a server with eight people who each cleared a street is a reason to stop playing. Turning respawn off entirely makes the map a finite resource that the group consumes, which changes the long game: after two months, safe territory is something you built rather than something you defend.

ZombieLore.Speed is the other headline: 1 is sprinters, 2 fast shamblers, 3 shamblers. 2 is the default and is what most people mean by "normal Zomboid". Sprinters on a public server with a full map is a novelty server, and it will have the population of one.

RedistributeHours is subtle and worth leaving alone unless you know why you are touching it. It is what makes hordes wander, and on a multiplayer server it is also what carries the consequences of one player's gunshot into another player's town.

Ports and connecting#

Both game ports are UDP and both are required; a firewall that opens one gets you a server that shows in the list and refuses to finish connecting. Older builds also used 8766 and 8767 for Steam, set by SteamPort1 and SteamPort2, so if you are following an old guide and have spare allocations, opening them costs nothing. Game server ports explained covers testing them properly from outside, which is faster than guessing.

RCON is a plain TCP protocol with the password sent in the clear, so treat it accordingly - using RCON safely is two minutes well spent. On a panel host the console does the same job over an internal connection, which is generally the better habit.

Admins, access levels and live changes#

The admin password is not in the ini. It is set on the first start, prompted for on the console or passed to the start script, and stored in db/<servername>.db along with every account, whitelist entry and ban. On RE:NODE it is generated per server rather than shipped as a default, which is the right way round: a default admin password on a public server is a griefing incident with a timer on it.

Access levels, from most to least: admin, moderator, overseer, gm, observer. Promote with /setaccesslevel "PlayerName" moderator.

/changeoption and /reloadoptions together are the feature nobody knows about: most ini options can be changed on a live server without dropping anyone. Sandbox variables cannot. Those are read when the world loads, and several of them - the ones baked into the map at generation - will not change an existing world at all. Project Zomboid admin commands goes through the full list and what each access level can reach.

Mods, workshop items and load order#

Two ini keys, and they are not the same thing. This is the most common mod problem on any Zomboid server.

WorkshopItems=2392709985;2169435993;1299328280Mods=Authentic Z - Current;ImprovedBuildMenu;HydrocraftMap=RavenCreek;Muldraugh, KY

Those three lines do three different jobs.

• `WorkshopItems` takes the numeric Steam Workshop id. It tells the server what to download.
• `Mods` takes the mod id from the mod's own mod.info file. It tells the server what to load.

A workshop item can contain several mods, and the ids look nothing alike, so listing the number in both places downloads the mod and then loads nothing. Order matters in Mods: later entries override earlier ones, which is how compatibility patches work and why a patch listed before the mod it patches does nothing.

Map is a third list, for map mods, and the base map goes last. Everything before it is layered on top.

The other thing that catches servers is a workshop mod updating while the server runs. Clients download the new version from Steam, the server is still on the old one, and joins fail with a mismatch that says nothing useful. /checkModsNeedUpdate reports it and a restart fixes it. Mods and the workshop on a Zomboid server covers collections and load order in detail, and what to do when a mod update breaks is the general version of the problem.

Memory, map cells and the Java heap#

Zomboid holds loaded map cells, and players scatter. Ten players in one town costs less than four players in four towns - the server is loading, simulating and saving four separate regions instead of one. This is why player-count sizing advice is wrong for Zomboid in both directions.

That third column is not decoration. The server is a JVM, and its heap is set in ProjectZomboid64.json:

{    "mainClass": "zombie/network/GameServer",    "classpath": ["."],    "vmArgs": [        "-Djava.awt.headless=true",        "-Xms2g",        "-Xmx6g"    ]}

The file ships with more arguments than that; change only the -Xms and -Xmx lines. And leave headroom: the JVM's heap is not the whole process, because metaspace, thread stacks and native buffers sit outside it and the container limit counts all of them. Setting -Xmx equal to your plan's memory is how you get a server that is killed while Java still believes it has room to spare. Seventy to eighty per cent of the limit is the rule.

On RE:NODE a server that reaches its memory limit is stopped and restarted clean rather than being allowed to swap, which is kinder to the node and to your neighbours but does mean an undersized heap setting shows up as an abrupt restart rather than a slow decline. CPU vs RAM for game servers covers telling which of the two you are short of before buying either.

Disk grows quietly. The save folder holds one file per explored map cell, so a server that has run for a year with a well-travelled map is measured in gigabytes. Project Zomboid plans here start at 3 GB with three port allocations, from $9 a month, and the Steam login the install needs goes on the Setup tab.

Backups, resets and the save folder#

Zomboid's own backups are real and better than nothing: BackupsOnStart, BackupsPeriod and BackupsCount produce zip files in Zomboid/backups. They also sit on the same disk as the thing they protect, which makes them a defence against a bad update and no defence at all against a deleted server. Keep real backups somewhere else, and restore one occasionally to prove it works - backups that actually restore is the argument in full.

To wipe a world properly:

1. Stop the server with /quit so the current state is written out.
2. Take a backup you can go back to.
3. Delete Zomboid/Saves/Multiplayer/<servername>/.
4. Increment ResetID in the ini, which tells clients to throw away their cached copy of the old world.
5. Start the server. A new map generates on first load.

Player accounts live in the database, not the world, so a map wipe leaves everyone's login, whitelist entry and ban intact. Delete db/<servername>.db as well only if you actually want to reset the roster.

A weekly restart at a quiet hour is worth scheduling regardless. Long-running Zomboid servers accumulate, and a restart is cheap on a game where sessions are short; restart schedules that help covers doing it without dropping someone mid-fight.

Troubleshooting#

The settings I changed did nothing. Either the server is started with a different -servername, or you edited the copy in the install folder rather than the one under Zomboid/Server/. Run /showoptions and compare.

Players cannot connect but the server is listed. UDP 16262 is closed. The listing uses the first port; joining needs both.

"Connection lost" a second after joining. Mod mismatch, almost always. Check Mods against what clients are subscribed to, and run /checkModsNeedUpdate.

The client says the version does not match. One side is on a beta branch and the other is on stable. Pin both.

Random kicks with an anti-cheat message. Read the type number in the log and disable that specific AntiCheatProtectionType. Mods that alter movement or vehicles are the usual trigger.

The server restarts on its own under load. The Java heap is set too close to the plan's limit, so the container is killed before the JVM ever garbage-collects its way out. Lower -Xmx.

Zombies keep coming back to a cleared town. RespawnHours and RespawnMultiplier. Set RespawnHours = 0 if you want clearing to be permanent.

The world will not load after a mod change. A map mod was removed. Restore the backup, put the mod back, and move players out of that region before removing it properly.

FAQ#

How much RAM does a Project Zomboid server need?

Three gigabytes runs a small group in one town, 4-6 GB covers eight to sixteen players spread out, and 8-10 GB is a large modded server. Set the Java heap to roughly three quarters of that, never all of it.

Where is the admin password stored?

In Zomboid/db/<servername>.db, not in the ini. It is set on the first start or passed to the start script, and it is separate from the Password key that players use to join.

Can I change sandbox settings on a running server?

Most ini options, yes, with /changeoption and /reloadoptions. Sandbox variables are read when the world loads, so they need a restart, and the ones baked into the map at generation will not change an existing world at all.

What is the difference between Mods and WorkshopItems?

WorkshopItems is the numeric Steam Workshop id and controls what gets downloaded. Mods is the mod id from mod.info and controls what gets loaded. You need both, and they are different strings.

Does turning off zombie respawn break the game?

No, it changes it. The map becomes a finite resource the group works through, which suits a persistent server with regular players far better than the default slow refill does.

Why does the server lag when everyone splits up?

Because each player loads and simulates the map cells around them. Four players in four towns is four regions being kept alive; ten players in one town is one. It is the clearest example in any game of why player count is a bad sizing input.