Modding:Setting up your Windows Development Environment

From Vintage Story Wiki
Jump to navigation Jump to search

This tutorial is about advanced modding. It should teach you how to setup your development environment and should introduce you into the basics of Visual Studio.

Install VintageStory

First of all download VintageStory and make sure you have installed the newest version of the game, otherwise errors may occur.

Download & Install Visual Studio

As you might know Vintage Story is programmed in C#. Luckily you can get Visual Studio Community for free here. Installation should be simple to do, but depending on your internet connection will may take a while.

Getting started

To get started download the VSModTemplate solution (here). Now you simply need to extract the zip archive to your desired place:


Navigate to VSMods and double click VSMods.sln (only works if VisualStudio is installed). Alternatively you can also start VisualStudio hit Open Project/ Solution, navigate to the extracted folder and select VSMods.sln. Once it has loaded you can run your first test by hitting start VSMods10.png. If everything has been done correctly VintageStory should start.

Also make sure you have installed the latest version of VintageStory, otherwise some of the following tutorials might be outdated.

How to create a new mod

The mod launcher is ready, but how can you add your own mods to it? The idea behind it is rather simple, all mods inside mods (in your extracted folder) will be recognized by VintageStory. Through that way your modding environment is separated from your actual game files. So what you need to do is to create another project to your solution, which is located in the mods folder. Therefore open up VisualStudion navigate to the top left corner and click on File -> Add -> New Project...


Now this window should popup ...


Make sure you select ClassLibrary (.NET Standard).

  1. Type in the name of the mod
  2. Add \mods to the path (otherwise your mod won't be loaded)


After you have saved it a new project should appear in your solution. Before you can start to work with it you need to make sure that your mod depends on the mod launcher. In order to add it as an dependency right click your project -> Build Dependencies -> Project Dependencies


Now enable VSModLauncher ...


Now you can add all kinds of file to your mod, such as the modinfo.json and assets


The last thing remaining is to add the VintageStoryAPI.dll to your project. So just start modding and fix the compiling errors:


And there we are ... everything is setup properly and you can start to go crazy with modding.

API Overview

The API interface is mostly documented, but if you feel a need for a reference documentation is is available at

Example mods are available on Github:

!== Creating a solution (project group) ==

There are 2 options. You download this template (Mod-Template) or you can create the project yourself. Either way you have to follow the instructions below ...

!=== Creating a new project ===

If you are using the template instead you can skip this chapter. In order to create a new project, select on the top right corner: File -> New -> Project...

Basic -1 New Project.png

Select the template 'Class Library' and type in your desired names.

!=== Set up configurations ===

Open up the properties of your project, by right-clicking your project:


Navigate to Build Events and copy the following lines into the textfield Post-build event command line:

copy "$(TargetPath)" "%appdata%\Vintagestory\Mods\"

copy "$(TargetDir)\$(TargetName).pdb" "%appdata%\Vintagestory\Mods\"

ATTENTION: If you have selected a different folder for the game you have to change those lines to your new Vintagestory folder.


Eventually navigate to Debug ...

  • Check Start external program and select the 'Vintagestory.exe' inside your Vintagestory folder.
  • Copy -oTestworld -pcreativebuilding to Comand line arguments if you want it to automatically start a superflat world named 'Testworld'
  • See "Additional command line arguments when debugging" below for more options


!=== Include the Vintagestory Library ===

Right-click your project again. Select Add -> Reference...


Select Browse on the bottom right of the window and navigate to your Vintagestory folder. Eventually select VintagestoryAPI.dll and add it. Now hit Ok to add the Vintagestory API to your current project.

!=== Hook up logging ===

The template already includes this feature.

If you want to you can download File:RedirectLogs.cs and add it to your project, which will allow to see the log of Vintagestory in Visual Studio. Once you have downloaded the file you can just drag and drop it right on your project's name (inside the 'Solution Explorer', in our example it is 'MyModName').

!=== Additional command line arguments when debugging ===

  • -oFoobar open a world named "foobar", if it doesn't exists it will create a new one
  • -p3 new worlds are created with given playstyle (1=normal terrain&survival, 3=superflat terrain&creative)
  • --rndWorld always creates a new world with an incrementing file name
Main Page: Modding
Basics Mod Types | Asset System | Textures | Items | Recipes | Blocks | Model Creator | Release
Advanced Setup(Windows,Linux) | Items (Code, JSON) | Blocks | Item-Block interactions | Block Behaviors | Block Entities | Particles | World Access
Worldgen Terrain | Ores | Trees | WorldGen API
Rendering Shaders and Renderers
Property Overview Item | Block | Block Behaviors | Block Classes | Block Entities | Block Entity Behaviors