How to Install Mods on a Vintage Story Server

To install mods on a Vintage Story server, download each mod's .zip from the ModDB at mods.vintagestory.at for your exact game version and upload it, still zipped, into the Mods folder inside the server's data folder (on GamezServers, data/Mods), then restart. Or run /moddb install <modid> as an admin. Players do not install anything by hand: when they join, the game offers to download the server's mods into a separate folder for that server. Server and players must run the same game version.

What you are working with

The ModDB page of each mod shows which game versions it supports and whether it is client side only.

What goes where

The gotcha: there are two Mods folders

A Vintage Story server install has a Mods folder of its own, next to the server program. It holds the game's built in mods: VSSurvivalMod, VSEssentials and VSCreativeMod. That is not where your mods go, and deleting or replacing those files breaks the game.

Your mods go in the Mods folder inside the data path, the folder the server was started with --dataPath. That is the same folder that holds serverconfig.json, Saves and Logs. Our servers start with --dataPath ./data, so the right folder is data/Mods. Mixing your mods into the install folder puts them next to the game's own files, where a reinstall or game update can remove them, and makes it hard to tell later which mods you added.

Before you start

• Check the game version. Look at the version in the panel's release setting, and download mod versions that support it.
• Back up the world. Big content mods change the world as soon as they load, and removing them later can leave missing blocks.
• Read the dependencies. Many mods need a library mod. The ModDB page lists them, and the server log names any that are missing.

Method 1: Upload the zips (works for any mod)

Step 1: Download the right versions

On mods.vintagestory.at, open each mod's Files tab and download the release made for your game version. Keep the file as a .zip. The official wiki says it plainly: do not extract the mod zip.

Step 2: Stop the server and upload

Stop the server and upload the zips into data/Mods/. Add any dependency mods at the same time.

Step 3: Start and read the log

Start the server and watch the console. It lists every mod it loads, and it names mods it skipped for a wrong version or a missing dependency. Fix those before anyone joins.

Method 2: Install from the server console

Vintage Story has a ModDB command built in, listed on the wiki's server commands page:

/moddb install primitivesurvival
/moddb install primitivesurvival 1.22.0
/moddb list
/moddb remove primitivesurvival

The mod ID is the last part of the mod's ModDB address. Give a game version as the second argument when the mod has several releases. Run it from the panel console or in game as an admin, then restart the server so the mod loads.

How players get the mods

Since version 1.16, the client detects a modded server's mods when connecting and asks to download them. They go into ModsByServer, a separate folder for each server, so a player's single player mods and different servers never clash. Client only mods are optional: players add those to their own Mods folder if they want them.

One known catch from the wiki: when a mod author fixes a bug but keeps the same file name, players' games may not fetch the new version because they think they already have it. If players crash after a mod update, have them delete that server's folder in ModsByServer and join again.

Updating mods and the game

Update mods and the game version together. When you change the release version in the panel, download the matching mod versions, replace the old zips in data/Mods, back up, then start. Players update their game to the same version before joining.

Common problems

• Mod does nothing: it was unzipped, or it sits in a folder the server does not read. ModPaths in serverconfig.json lists the folders it loads mods from.
• Server log says a mod was skipped: the mod does not support your game version, or a dependency is missing.
• Players cannot join after an update: their game version differs from the server's. Everyone updates together.
• Missing blocks after removing a mod: the world still contains that mod's blocks. Restore the backup or put the mod back.
• Players crash on join after a mod update: they kept an old copy with the same file name. Clear their ModsByServer folder for your server.

Mods on GamezServers

On a Vintage Story server from GamezServers, mods go into data/Mods through the file manager or the SFTP login in Settings, and the file manager can download a mod from a ModDB link straight to the server. You pick the exact release version in the panel, Backup is one click before any update, and the world keeps turning through the seasons without anyone's PC on. Bringing a world too? See how to move a Vintage Story world to a server.

FAQ

Where do I put mods on a Vintage Story server?

In the Mods folder inside the server's data path, which is data/Mods on GamezServers. Not the Mods folder next to the server program.

Do players need to install the server's mods?

No. The game offers to download them when players join, into a separate folder for that server.

Do I unzip Vintage Story mods?

No. Upload the .zip exactly as you downloaded it.

Can I install mods with a command?

Yes. Run /moddb install <modid> as an admin, then restart the server so the mod loads.