If you've already got your server up and running (if not, start with our Getting Started Guide), this is where we get into the meat of server configuration. Vintage Story has a surprisingly deep set of server options, and knowing which ones actually matter will save you a lot of headaches.
The Golden Rule: Stop Before You Edit
I'm putting this right at the top because I've seen it burn people more times than I can count.
Never edit serverconfig.json while the server is running.
Vintage Story writes its current config to disk when the server shuts down. So if you edit the file while it's running, the server just overwrites your changes the moment it stops. You lose everything you changed and wonder why nothing took effect.
The workflow is always:
- Stop the server from the Web Console or the control panel
- Open Configuration Files in the sidebar
- Edit serverconfig.json
- Save
- Start the server
Every time. No exceptions.
Where serverconfig.json Lives
You'll find it through Configuration Files in the sidebar of your LOW.MS Control Panel. You can also browse to it via the File Manager if you prefer – it's in the root of your server directory.
If you need to do bulk edits or work on the file locally, you can download it via SFTP on port 8822. Your SFTP credentials are the same as your control panel login.
Core Server Settings
These are the settings most server owners will want to touch first.
ServerName
What shows up in the server browser. Make it descriptive – players scrolling through a list need to know what they're getting.
"ServerName": "My Vintage Story Server"
Port
Default is 42420. You generally shouldn't change this on a LOW.MS server unless support tells you to. Since v1.20, VS uses both TCP and UDP on this port.
"Port": 42420
MaxClients
How many players can connect simultaneously. Default is 16. Set this based on your RAM – remember, each player adds roughly 300 MB of usage on top of the ~1 GB base.
"MaxClients": 16
If you've got a 4 GB plan, I'd keep this at 8-10 max. Going higher than your RAM can handle leads to lag, crashes, or both.
Password
Leave empty for a public server, or set a string to require a password on connect.
"Password": ""
PassTimeWhenEmpty
Controls whether in-game time progresses when nobody's online. Default is false, which means the world freezes when the last player disconnects.
"PassTimeWhenEmpty": false
I'd recommend leaving this off unless you specifically want crops growing and seasons changing while nobody's playing. Turning it on also means the server does real work 24/7 instead of just idling, which affects performance when people do log in because the server has to catch up on any queued events.
World Configuration
These settings define the world itself. Changing most of them means generating a new world, so get them right before your group invests hours building.
World Type
Two options:
"WorldType": "standard"
- standard – normal terrain generation with caves, mountains, rivers, the works
- superflat – flat world, mainly useful for creative building or testing
Play Style
"PlayStyle": "surviveandbuild"
Your options are surviveandbuild, creativebuilding, exploration, wildernesssurvival, and homosapiens. I covered these in the Getting Started Guide – the short version is that most servers want surviveandbuild.
Map Size
"MapSizeX": 1024000,
"MapSizeY": 256,
"MapSizeZ": 1024000
MapSizeX and MapSizeZ control the horizontal world size in blocks. The defaults are massive – over a million blocks in each direction. You almost certainly don't need that much, and honestly, reducing these can help with performance because the server won't let players wander into infinity.
For a small group of friends, something like 100000 x 100000 is still enormous and more than enough. MapSizeY is the vertical height and 256 is fine for almost everyone.
Default Role
"DefaultRoleCode": "suplayer"
This is the permission role assigned to new players who join. The default suplayer (survival player) is correct for most servers. Don't change this unless you've set up custom roles and know what you're doing.
Performance Tuning
This is the section that actually matters once your server starts getting busy. I've spent a lot of time testing these settings across different player counts and hardware configs.
MaxChunkRadius
"MaxChunkRadius": 12
This controls how far from each player the server loads and processes chunks. The default of 12 is reasonable, but if you're seeing lag with more than a few players online, dropping this to 8 or even 6 makes a noticeable difference. Each reduction shaves a significant amount of chunk processing work off every tick.
For servers with 8+ players, I'd start at 8 and increase only if players complain about the view distance.
TickTime
"TickTime": 33.33
This is the time in milliseconds per server tick. 33.33ms gives you 30 ticks per second, which is the default. Lower values mean faster simulation but more CPU load.
Don't reduce this unless you have a specific reason. Increasing it (to say 50ms, which gives 20 ticks/sec) can help an overloaded server stay stable, but gameplay will feel noticeably slower.
RandomBlockTicksPerChunk
"RandomBlockTicksPerChunk": 16
Controls how many random block updates happen per chunk per tick. These updates handle things like crop growth, grass spreading, and leaf decay. The default of 16 is fine for most servers.
If you're getting lag and you've already reduced MaxChunkRadius, try dropping this to 8 or 10. Crop growth will slow down a bit, but the performance gain on a busy server is worth it. I've seen servers go from borderline unplayable to smooth just by halving this value.
BlockTickChunkRange
"BlockTickChunkRange": 5
How far from each player block ticks are processed. Works hand-in-hand with RandomBlockTicksPerChunk. Reducing this to 3 or 4 means crops and other block updates only happen close to players, which reduces load without most people noticing.
SpawnCapPlayerScaling
"SpawnCapPlayerScaling": 0.5
Controls how mob spawn caps scale with player count. At the default of 0.5, each additional player adds half as many potential mob spawns as the first player. This is a solid default – it keeps mob density reasonable without the server drowning in entities as more people join.
If your server is struggling with entity counts, try lowering this to 0.3 or 0.25.
Gameplay Settings
AllowPvP
"AllowPvP": true
Exactly what it sounds like. Set to false for a PvE-only server. I'd recommend deciding this before launch – nothing causes drama like changing the PvP setting after people have been playing for a while.
AllowFireSpread
"AllowFireSpread": true
Whether fire spreads to adjacent blocks. On a PvP server with griefers, you might want this off. On a chill building server, it probably doesn't matter either way. Personally I keep it on for the realism, but I've seen entire wooden villages burn down because someone was careless with a torch.
In-Game Config Changes
You don't always need to edit the file directly. Many settings can be changed live with the /serverconfig command from the Web Console:
/serverconfig maxclients 12
/serverconfig password MySecret
/serverconfig allowpvp false
Changes made this way take effect immediately and get saved to serverconfig.json when the server shuts down. This is the safest way to tweak things on the fly without risking the stop-edit-start dance.
Not every setting is available through /serverconfig though – world generation options and some performance settings require a file edit and restart.
Mod Configuration
Mods go in the data/Mods/ folder. You can upload them through the File Manager in your control panel, or via SFTP on port 8822 if you're uploading a bunch at once.
A few things worth knowing:
- Server-side mods and universal mods are automatically downloaded by clients when they connect. Players don't need to manually install them. This is one of VS's best features honestly.
- Client-only mods aren't relevant for server hosting – those stay on each player's local install
- Drop the .zip files directly into
data/Mods/– don't extract them - After adding mods, restart the server. Check the Log Viewer to make sure they loaded without errors.
If you're running into mod problems, check our Troubleshooting Guide for the disable-and-test method.
SFTP Access
For larger file operations – uploading a world backup, bulk mod installs, or downloading your world save – SFTP is much faster than the web file manager. Connect on port 8822 with the same credentials you use for the control panel. Any SFTP client works – FileZilla, WinSCP, whatever you prefer.
If you need help with anything in this guide, our support team is available 24/7. And if your server's misbehaving after config changes, the Troubleshooting Guide is the next stop.