Modding:Getting Started

From Vintage Story Wiki
This page contains changes which are not marked for translation.
Other languages:

This page was last verified for Vintage Story version 1.19.

Vintage story has an extensive modding system built into the game, allowing any user to make their own changes and additions as they see fit.

Before you get started, it's important to understand what you would like to accomplish so you can know what to expect.

Searching the wiki

By default the wiki's search feature excludes the modding pages. To update your search preferences, click the "Search Modding" button below. The results page will show that the (Main), BlockJson, and Modding namespaces are checked. Check "Remember selection for future searches", then click search to save the changes.

What Mods can I make?

The current modding system for Vintage Story is incredibly flexible and quite easy to use even if you don't know how to program. You can add fully functional blocks, items and even entities into the game without ever opening an IDE. More complex changes and systems can be made using C# programming.

This is because nearly every feature of the game relies on the usage of JSONs, which are text documents that utilize a flexible, easy to read format. You can open these files with any text editor, and with just a little bit of practice you can learn how to format them to avoid errors. The best way to learn this is to study the existing JSONs that are visible to anybody who has the game installed. To do so you'll need to locate the Vintage Story Assets folder, which you can learn about at the Asset System page.
In addition, here is a 12 minute video that will teach you why json is used, and the basic syntax, making it easier to understand the rest of the documentation.

If you're looking to add more complex systems to Vintage story you can accomplish this as well, but you likely won't be able to do this with JSONs alone. Vintage Story is written in C#, and it is highly suggested you learn the basics of programming and of C# in general before moving onto more complex mods that can't be accomplished with just JSONs.

Types of Mods

In general there are 3 main types of mods one can create for Vintage Story, with each having different levels of complexity:

  • Theme Packs: These are mods that only affect visuals and don't add more content or change features significantly.
  • Content Mods: These are mods that add additional content (i.e. blocks, items, mobs) to the game but don't utilize C# code and are mostly limited to JSONs.
  • Code Mods: These are mods that add more complex features and systems that require the use of C# code to accomplish.

Moving Forward

If you're just starting out, it's best to begin with a content mod, as most code mods simply extend the features of blocks, items and entities made from a content mod anyway. Once you've mastered content mods you can move onto coding if you want to add some really special things to your Vintage Story experience.

More advanced programmers may be tempted to jump to code mods immediately, but it is still highly suggested you familiarize yourself with content mods first since you'll almost certainly be using them in tandem with any C# code you write.

The first thing to do while starting your first mod is to familiarize yourself with the Asset System. This is where most of the magic in Vintage Story is accomplished, and you'll be using these resources constantly while modding.

To move on with a content mod, head over to the Basic Block page or Basic Item page. To start with a theme mod, head over to the Theme Pack page.

Green Items require C# coding

Getting Started | Basic Examples | Theme Pack

Asset System | Textures | Items | Recipes | Blocks | Entities | Model Creator | Animation Basics | VTML & Icons | Packaging & Release | Modinfo | Debugging


JSON Patching | Advanced JSON Item | The Remapper | Server-Client Considerations | Compatibility with other mods

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

Savegame Data Storage | ModConfig File | Chunk Data Storage | TreeAttribute


WorldGen Concepts | Terrain | Ores | Trees | WorldGen API | NatFloat | EvolvingNatFloat | Json Random Generator


Shaders and Renderers

Property Overview

Item | Entity | Block | Block Behaviors | Block Classes | Block Entities | Block Entity Behaviors | World properties

Workflows & Infrastructure

Modding Efficiency Tips | Mod-engine compatibility | Mod Extensibility | VS Engine

Additional Resources

List of server commands | List of client commands | Client startup parameters | Server startup parameters | Creative Starter Guide | ServerBlockTicking | Bot System | WorldEdit | Cinematic Camera | Adjustable FPS Video Recording

Example Mods | API Docs | GitHub Repository