Adding mods

From Vintage Story Wiki

With Vintage Story you can have your cake and eat it too. 1000 or more player-made modifications ("mods") can be added to the already rich, high performance base game of Vintage Story! It is a very mod-friendly game.

If you desire to expand your gaming experience with some of the awesome mods made by other players - there are new blocks and objects, new creatures, beautiful shaders, recipe tweaks, quality of life improvements, one which transforms Locusts into minions to do your every bidding, and many others - the best place to look for them is on the official Mod DB. You can also find a few additional mods on the official forums. We generally advise that you check which game version or versions a mod requires, to make sure it matches the game version you are currently playing.

TL;DR: Download mods and drag them to the game's Mods folder. Using the in-game Mod Manager, you can enable or disable mods as you want, for each time you play.

Modded multiplayer Vintage Story

If you want to play on a modded server, it's even easier. Starting from Vintage Story 1.16, when you connect to a multiplayer server which offers a modded game, your game will automatically set up the mods correctly for that server on the player's side. Your game will create a sub-folder for the server's mods (folder is automatically named by server name or IP address) in the ModsByServer folder - one sub-folder for each different multiplayer server. The full folder location is %AppData%\Roaming\VintagestoryData\ModsByServer

Pro-tip: very occasionally a mod updates its code to fix a bug, but keeps the same filename. In this case, your game will not download the new version of the mod when playing multiplayer because it thinks it already has the correct version. Therefore, in multiplayer if you encounter bugs or crashes which might be caused by a mod, it is worth trying this: quit the server, delete the server's mods sub-folder and re-join the server to let it download all the mods afresh.

(For older Vintage Story prior to 1.15 - that's pretty old these days - mods must be installed in the same way as for Single Player, you can follow the server-owner's instructions about which mods to install, and remember to go to the in-game Mod Manager and activate those mods (and no others!) when you want to join that specific server. You will likely be unable to join the server (or you might experience crashes) unless your mod set-up - including version numbers -exactly matches the mods the server requires.)

Installation in detail (Single Player)

Most mods download as a .zip file. Locate the file you just downloaded - in modern browsers such as Chrome, you can right-click on the file downloaded notification and choose "Show in Folder". Or your browser's downloads list (Ctrl+J) may have a button to show each downloaded file in its folder. Or on Windows you can perhaps look in the Downloads folder through File Explorer.

Once you got a hold of the mod file in question, copy or move it into the game's Mods folder. The Mods folder can be accessed through the game: in the main menu screen, click on the Mod Manager tab then click the Open Mods Folder button, and a new window will open with the Mods folder.

Alternatively, you can access the Mods folder through your OS's file browser in one of these paths:

  • On Windows, the path is %appdata%/VintagestoryData/Mods
  • On Linux, the path is ~/.config/VintagestoryData/Mods

On Windows, you can get there fast by using the run file dialog. Hit the key combination Win+R and type %appdata%/VintagestoryData/Mods into the box.

This is how the run window dialog looks like on Windows 10

Once you're in the Mods folder, drag and drop the mod file from the download folder to the Mods folder - or you can use cut/copy and paste commands as you prefer. Do not extract the mod zip. Just place the .zip file into your Mods folder, that's all you have to do. In the game's main menu Mod Manager, click the Reload Mods button - or else close and reopen your game. The mod should be loaded and listed in the mod manager. Congratulations on your very first modded Vintage Story Experience!

Pro-tip: There is actually a second Mods folder found in the game code's installation folder. Both of these folders are checked for mods. This installation folder's Mods folder is normally only used for the mods which come with the base game (Essentials, Survival and Creative - see next section) - and normally the mods which you download should be placed in %appdata%/VintagestoryData/Mods . In specialised situations you can customise the Mods folder locations by editing the settings file clientsettings.json and editing the "modPaths" config.

The base game is a mod!

Note that the game comes with three mods pre-installed named Essentials, Creative Mode and Survival Mode. Those three are the standard 'vanilla' game: they are required, you should normally always have all three enabled! That's right, the standard Vintage Story game is actually a mod itself! The developers do that to show what is possible in a mod, and to make sure that modders have the same access to the game engine that Vintage Story has.

Getting started with modding

It's pretty easy to make your own mod for Vintage Story. You don't have to be a coder, around half of mods are made without any code and the game is designed to make this possible - it is however necessary to write JSON files in the correct format. Tweaks to existing game assets, recipes, models, textures etc can be made using JSON patch files. New blocks, items and creatures can be added. For more help, see Modding:Getting Started


In the following video you can see how to install mods (German).

Wiki Navigation
Vintage Story Guides[[::Category:Guides| ]]Frequently Asked Questions Soundtrack Versions Controls
Game systems Crafting Knapping Clay forming Smithing Cooking Temperature Hunger Mining Temporal stability Mechanical power Trading Farming Animal husbandry
World World generation Biomes Weather Temporal storms
Items Tools Weapons Armor Clothing Bags Materials Food
Blocks Terrain Plants Decorative Lighting Functional Ore
Entities Hostile entities Animals NPCs Players
Miscellaneous List of client commands List of server commands Creative Starter Guide Bot System WorldEdit Cinematic Camera Adjustable FPS Video Recording ServerBlockTicking

Icon Sign.png

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.

Modding Introduction Getting Started Theme Pack
Content Modding Content Mods Developing a Content Mod Basic Tutorials Intermediate Tutorials Advanced Tutorials Content Mod Concepts
Code Modding Code Mods Setting up your Development Environment
Property Overview ItemEntityBlockBlock BehaviorsBlock ClassesBlock EntitiesBlock Entity BehaviorsWorld properties
Workflows & Infrastructure Modding Efficiency TipsMod-engine compatibilityMod ExtensibilityVS Engine
Additional Resources Community Resources Modding API Updates Programming Languages List of server commandsList of client commandsClient startup parametersServer startup parameters
Example ModsAPI DocsGitHub Repository