Modding:Mod Packaging

From Vintage Story Wiki
Jump to navigation Jump to search
If your mod changes only visuals, sounds, and other "theming" assets, refer also to the Theme Pack page.

Zip Files

To make your mod easy to install and use, it should be packed into a zip file. Any assets (images, .json files, etc) go in a "assets" directory in the root of the zip, any source files into the "src" folder and any DLLs (and optionally, PDB files) go directly into the zip file root folder.

Please note that if you have a code mod that has no assets (AKA, your mod is a single C# DLL), it is possible to ship the bare DLL without packing it into a zip. This is not really a good idea though, as when distributed this way it is hard to include a PDB file and downloading DLLs directly in Windows can lead to issues with your mod failing to load due to security policies applied to files downloaded from the internet.

Zip File Structure
asset files (tree overview)
compiled sources files (*.dll and *.pdb)
source code files - folders allowed (*.cs)

Info file

Every zip-file mod requires a modinfo.json inside the root directory of the archive. Otherwise the entire mod will be ignored. This info file specifies what kind of mod it is, its name, author, etc.

An example of a theme pack info file (modinfo.json):

  "type": "content",
  "modid": "creativemdexamplemod",
  "name": "My Example Content Mod",
  "description" : "This is an example mod, which does nothing",
  "authors": ["CreativeMD"],
  "version": "1.0",
  "dependencies": { 
	"game": "",
	"survival": ""
  "website": ""

  "type": "content",

Besides "type": "content", there is also "type": "theme" and "type": "code".

  • "type": "content": Defines this mod as being a Content Mod. Content Mods cannot contain any C# code (if it does they will be ignored).
  • "type": "theme": Defines this mod as being a Theme Pack. Theme Packs cannot override gameplay affecting assets categories (such as blocktypes, itemtypes and so on) and no C# code will be loaded.
  • "type": "code": Defines this mod as being a Code Mod. Code Mods are the same as a Content Mods, except they can also load C# code to do things that are not possible with JSON.
  "dependencies": {
    "game": "1.5.3"

Means it requires at least VintageStory v1.5.3 or a newer version. For more info see Modinfo.


Note: Mod icons do not appear to be supported as of game version 1.14.10. However, this feature might be supported in future versions.

The file modicon.png (if it exists) will be used and shown in the mod manager menu.

Example Mod.png

Distribution and Installation

To install a mod simply place the zip file in the Mods directory in your Vintagestory directory.

You can upload your mod to the Vintage Story Mod Database so people can find it.

Main Page: Modding
Green Items require C# coding

Getting Started | Mod Types | Simple Examples

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


JSON Patching | Advanced JSON Items | The Remapper | Server-Client Considerations

Setting Up Your Development Environment (General - Windows - Linux)

Advanced Blocks | Advanced Items | Item-Block Interactions | Block Behavior | Block Entities | Particle Effects | World Access | Inventory Handling | Chat Commands | GUIs | Server-Client Networking | Monkey patching (Harmony)

Data Management

Savegame Data Storage | ModConfig File | Chunk Data Storage | Tree Attribute


WorldGen Concepts | Terrain | Ores | Trees | WorldGen API


Shaders and Renderers

Property Overview

Item | Entity | Block | Block Behaviors | Block Classes | Block Entities | Block Entity Behaviors

Workflows & Infrastructure

Modding Efficiency Tips | Mod Extensibility | Load Order

Additional Resources

List of server commands | List of client commands | Client startup parameters | Creative Starter Guide | ServerBlockTicking | Bot System | WorldEdit | Cinematic Camera

Example Mods | API Docs | GitHub Repository