Modding:Preparing For Code Mods
This page was last verified for Vintage Story version 1.19.8.
There is a small number of steps that must be followed before you can create a code mod. These steps only have to be done once - If you have completed this tutorial before, you may start from Creating a Code Mod. For more information on what can be achieved with a code mod, see Code Mods.
This tutorial is suitable for Windows users. If you are using a differing operating system, please view the older Setting up your Development Environment tutorial page.
Installing an IDE
When developing a code mod, it is extremely important to choose a suitable IDE. For Vintage Story, it is highly recommended that you use Visual Studio Community - A free and powerful development environment that is used by the Vintage Story team to develop the game. When installing Visual Studio, you should also install the .NET desktop development workload, which can be done during installation or by following these steps.
Although some other IDEs are suitable, this tutorial will assume you are using Visual Studio. If you cannot use Visual Studio, please view the older Setting up your Development Environment tutorial page.
Installing .NET 7.0 SDK
An SDK (Software Development Kit) is used to help you develop programs and code for specific platforms. Since Vintage Story relies on the .NET 7.0 SDK, it is important that you download and install this too. This SDK is sometimes referred to as dotnet.
Download and install the latest .NET 7.0 SDK, ensuring you select the version that is correct for you. This will likely be the Windows x64 version.
When the SDK has finished installing, it is recommended to check it has been configured correctly. Launch a command prompt in Windows, either by searching for 'cmd' or 'PowerShell' in Windows' search bar, and enter the following command:
dotnet --list-sdks
This should give you a list of installed SDKs. If there is an entry that starts with 7.0., then you may continue.
| SDK not showing or getting an error? |
| Restart your PC, and redo the given command in the command prompt or powershell. If it is still not visible, then repeat the installation for this section. |
Creating an Environment Variable
An Environment Variable is a value that can be used by numerous applications across your PC. Because the modding environment is separate to the game itself, you need to create a new environment variable that links to the path of your game.
Firstly, you need to open Vintage Story in your file explorer. If you have a shortcut to Vintage Story on your Desktop, you can right-click it and select 'Open file location'. If you do not have a shortcut, but have installed Vintage Story to the default install location, it will be found in your appdata folder. You can find this folder by using this method. If you have installed it elsewhere, you will need to find this folder in the file explorer.
The opened folder should contain the 'assets', 'mods', and 'lib' folders. Ensure you are not in the VintageStoryData folder.
When you have your game folder open in Windows file explorer, you need to open this folder in PowerShell. Ensure you do not have a file or folder selected, and click 'File' in the menu bar, then click 'Open Windows PowerShell'.
PowerShell will open with your current file path. Ensure that the file path stated does not include the 'assets', 'mods', or 'lib' folders. Paste the following line into PowerShell, and press enter to run it.
[Environment]::SetEnvironmentVariable("VINTAGE_STORY", ($pwd.path), "User")
This will create the environment variable called "VINTAGE_STORY", and set its value to be the current working directory (the Vintage Story folder). The "user" parameter simply stores this variable as a user-only environment variable, meaning other users on your PC will not be able to use this variable.
| Test your environment variable |
To ensure your environment variable has been created correctly, run the following command in the opened powershell:echo $env:VINTAGE_STORY
|
When you have set a new environment variable, it is recommended to restart your PC. This will ensure that all programs are using your updated environment variables.
Installing Modding Templates
The final step is to install the mod templates. These mod templates will automatically setup your mod for you in Visual Studio, automatically adding any libraries and code that is needed to get your mods up and running.
Open a PowerShell command line, paste the following, and press enter to run it. This execution should only take a few seconds, as it is a very small file.
dotnet new install VintageStory.Mod.BasicTemplate
This is where everything comes together. Your dotnet installation will download the Vintage Story mod template from NuGet (an online package manager for .NET), and install the templates to be used with Visual Studio.
| Looking for the advanced modding template, or want to make a dll-only mod? |
Since May 2024, the template listed above will install only the basic mod template - Which automatically imports all relevant libraries. If you need to select which libraries to import, or you want to make a dll-only mod, you will need to install the advanced templates by entering the following command:dotnet new install VintageStory.Mod.Templates
|
Test your template installation
To ensure that the template has installed correctly, launch Visual Studio and select 'Create a new project'. In the furthest-right drop down list ('All project types'), find 'Vintage Story' in the list.
If it exists, and displays two projects, then your template has successfully installed and you are ready to start making code mods. Congratulations!
If 'Vintage Story' does not exist in the project types, or there are no projects listed under this category, try restarting your PC and looking again. If there is still nothing, run the above command again.
| Still can't find the project type? |
| You may have forgot to install the .NET desktop development workload through the Visual Studio installer. Launch the Visual Studio Installer, select modify, and tick the box labeled .NET desktop development (under the 'Desktop & Mobile' section). |
Next Steps
Now that you have completed this tutorial, you can begin creating as many code mods as you wish. Move on to Creating a Code Mod to setup and customize your first mod!
| Code Modding | |||||||
|---|---|---|---|---|---|---|---|
| Basics | Code Mods • Preparing For Code Mods • Creating A Code Mod | ||||||
| Tutorials |
|
||||||
| Advanced | Server-Client Considerations • Setting up your Development Environment • Advanced Blocks • Advanced Items • Block and Item Interactions • Block Behavior • Block Entity • Particle Effects • World Access • Inventory Handling • Commands • GUIs • Network API • Monkey patching (Harmony) | ||||||
| Data Management | VCDBS format • Savegame Moddata • ModConfig File • Chunk Moddata • Serialization Formats • TreeAttribute | ||||||
| Worldgen | WorldGen API • NatFloat • EvolvingNatFloat | ||||||
| Rendering | Shaders and Renderers | ||||||
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 | |
|---|---|
| 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 | Item • Entity • Entity Behaviors • Block • Block Behaviors • Block Classes • Block Entities • Block Entity Behaviors • Collectible Behaviors • World properties |
| Workflows & Infrastructure | Modding Efficiency Tips • Mod-engine compatibility • Mod Extensibility • VS Engine |
| Additional Resources | Community Resources • Modding API Updates • Programming Languages • List of server commands • List of client commands • Client startup parameters • Server startup parameters Example Mods • API Docs • GitHub Repository |
