Modding:Inbuilt ModMaker
This page was last verified for Vintage Story version 1.20.4.
The mod maker program is an essential modding tool included with a Vintage Story installation. To access it, navigate to your install location for the game, and open the 'ModMaker.exe' program.
The mod maker currently has 5 options to choose from, however its primary use is to create patches for vanilla assets.
It is recommended to have some knowledge of content mods before using the modmaker.
Create Patches (Option 1)
As you may be aware, much of Vintage Story is written using JSON files that are immediately accessible from installing the game. Due to this, you can make significant changes to the game just by modifying these assets. You can also directly add new JSON files to the folders that you desire to create new content. These modifications are not saved between versions, and cannot be used in multiplayer.
To save your changes into a publishable mod, you can use the modmaker program.
Run the ModMaker.exe program, and you're given a list of options. Select the first option by typing 1, and then pressing enter. The program will give some information, and then ask you what version you would like to use. In almost all circumstances, this version is automatically detected, and you can just press enter to continue.
Downloading Vanilla Assets
If you have not run the mod maker before for this version, it will now download the appropriate original assets to compare against. To do this, you will need an internet connection.
Please note that if you are using a pre-release or unstable Vintage Story version, this step cannot be completed without creating a local install temp folder. See the "Create Temp Folder from Local install" step below.
Checking Shapes Folder
After successfully downloading the vanilla assets, the mod maker will ask if you would like to ignore the shapes folder. The shapes folder contains 55% of assets, and can take a considerable amount of time to process these. Considering that most mods do not add new shapes, it can save time by ignoring this.
If you haven't made any changes to the shapes folder, enter 'y' and press enter to ignore shapes. Or, enter 'n' and press enter to look for differences in the shapes folders.
Note that the mod maker will not check any non-JSON assets. This includes textures, sound files, and music files.
Analysing Changes
The mod maker will now begin searching for differences in the files. It analyses differences in JSON properties; so minor changes (such as additional whitespace) are ignored. While doing so, the program will inform you on the different files it notices, as well as the number of files it has analysed.
Mod Info
After the files have been analysed, if any changes have been found, you will be asked for some info about your mod.
- Mod Name - Your mod name can be pretty much anything, though it should be readable and give a good idea about what your mod does. This can include spaces, punctuation, and capital letters.
- Mod ID - This needs to be a unique identifier for your mod. Your mod ID should be similar to your mod name. In general, anyone who reads your mod ID should know what mod it is associated with. It needs to be all lowercase (numbers are allowed), however it cannot contain uppercase letters or punctuation.
- Author Name - Whatever name you wish to go by. This is just for display purposes.
Packaging Your Mod
When the mod info values have been entered, your mod will now be created! The program will let you know where your mod exists, which will usually be in the VintageStoryData folder.
The packaged mod will be a zip file of a content mod. From here, you can either upload your mod to the Vintage Story ModDB, or unzip your mod and make further edits to it.
If your mod is now complete, it may be a good idea to restore the vanilla assets. See option 3 for how to do this.
Note that if you do not restore the vanilla assets, and your packaged mod is enabled, the changes you have made will actually be applied twice, which can cause unexpected behavior.
Convert Vanilla Assets to Standard JSON (Option 2)
Vintage Story loads all assets using JSON5. JSON5 is significantly more leniant with formatting when compared to standard JSON, however it can often cause issues with some IDEs or text editors. To allow editing to be easier, the mod maker can convert all the vanilla assets from JSON5, into JSON. This process may take a short while, but the program will inform you on how many files have been processed.
Note that this will increase the size of the assets folder from ~670MB to ~850MB, as of 1.20.3. This can cause a small increase in loading speeds, however it causes no difference in functionality to any mods.
| JSON5 | JSON |
|---|---|
{
...
creativeinventory: { "general": ["*"], "items": ["*"] },
heldTpIdleAnimation: "holdunderarm",
maxstacksize: 1,
combustibleProps: {
burnTemperature: 600,
burnDuration: 10,
},
...
}
|
{
...
"creativeinventory": {
"general": [
"*"
],
"items": [
"*"
]
},
"heldTpIdleAnimation": "holdunderarm",
"maxstacksize": 1,
"combustibleProps": {
"burnTemperature": 600,
"burnDuration": 10
},
...
}
|
Restore Vanilla Assets (Option 3)
After editing the assets folder, it can be important to revert the assets back to their original form. This can help reduce bugs when testing mods, and gives you a clean slate for a new modding environment. This process will delete all changes made to the assets, including new files, therefore it is recommended to backup your assets folder to not lose any changes! Any non-json assets will not be reverted, including textures, music, and sounds.
Please note that if you are using a pre-release or unstable Vintage Story version, this step cannot be completed without creating a local install temp folder. See the "Create Temp Folder from Local install" step below.
When prompted for a version, enter the appropriate version and press enter.
If you have run option 2 beforehand, you will need to redo that process to change your assets to standard JSON.
Delete Temp Files (Option 4)
The program has been made more robust in recent versions, however it can still sometimes have issues. If you are having any issues with the game not finding files, or detecting files as being changed which have not been, then your first step should be to delete the temp files. This will force the program to redownload the vanilla assets, and hopefully solve any issues.
(Experimental) Create Temp Folder from Local Install (Option 5)
This option is required if you wish to use the mod maker with pre-release or other unstable versions.
This allows you to create an assets folder based on a local installation of the game. To ensure it works correctly, you need to run this step before you modify any assets. If you have modified any assets already, you will need to create a clean install of the game, and repeat this step.
The program will ask for confirmation before completing this step. When it is complete, you will be able to use the mod maker with unstable versions of the game.
