Modding:Asset System

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 loads most of its game content from asset JSONs. Many examples of these can be found inside the assets directory inside your Vintagestory folder. Things such as blocks, items, world generation, recipes, etc. are all loaded from assets during startup.

Finding the assets folder

All the functioning assets for Vintage Story are visible in the game's folder, allowing you to peruse them and learn to write your own. You can find these files using the following methods for each type of OS you're running Vintage Story on. If you're looking for source code (ie C# classes) your best option is to dive into the Vintage Story Github and peruse the vsapi, vssurvivalmod, vsessentialsmod and vscreativemod repositories for class references.

Windows

If you're running Vintage Story on Windows, and installed the game to the default location, you can navigate to this folder by typing %appdata% in desktop search bar, which will take you to your computer's roaming folder. Find the Vintagestory folder here and you'll immediately come across the assets folder, which contains assets for "creative", "game" and "survival".

  • creative contains assets for creative mode only.
  • game contains many universal assets, such as lang files, the player entity shape, and other essential assets to the game.
  • survival contains the bulk of the actual content most players will come across, and contains all the resources Vintage Story uses, such as textures sounds and world generation.

List of Asset Types

The following are the categories of assets you can expect to use while modding for Vintage Story. Each are easily modifiable and can be used to easily add your own content or changes without having to do any advanced coding. You can also read some examples to learn about what you can do with it.

Name Affects Gameplay Side Type Usage
AssetCategory
blocktypes
true universal Defines all the blocks that are in the game
config
true universal Used for generic data that does not fit into the other categories.
dialog
false client only Contains some of the dialog layouts
entities
true server only Creatures and other entities
itemtypes
true universal Defines all the items that are in the game
lang
false universal Translation
music
false client only The games music tracks and its configuration
patches
true universal Used to patch game data defined in other json files
worldproperties
true universal Contains some commonly used lists of properties
abstract
true universal
block
true universal
sounds
false universal Sounds
shapes
false universal Contains the 3d models for all the items, blocks and creatures
block
false universal Shapes for blocks
entity
false universal Shapes for entities
item
false universal Shapes for items
recipes
true server only The crafting, knapping, smithing and clay forming recipes
alloy
true server only How metals can be combined to create alloys
grid
true server only Recipes for 3x3 grid crafting
smithing
true server only Recipes for smithing on the anvil
worldgen
true server only Contains all the configuration for world generation
terrain
true server only Defines how the terrain should look and with what it should be decorated with
tree
true server only Defines the shapes of trees
shaders
false client only Contains GLSL source code, that defines how the game is rendered
shaderincludes
false client only Contains GLSL source code, that defines how the game is rendered
textures
false client only Contains all the graphics of the game
block
false client only Block textures
item
false client only Item textures
decal
false client only Decaltextures
entities
false client only Entities textures
environment
false client only Environment textures (Sky, Moon, Sun, etc.)
gui
false client only Gui textures
hud
false client only Hud textures
particle
false client only Particle textures

Domains

Domains are used to separate mod added content from the original one. Basically a domain is a prefix for any given code (identifier for item, block, etc.) or path (textures, sounds, etc.). VintageStory itself has its own prefix game for all its assets (game, survival and creative folders).

When packaging a mod you specify a domain by placing a directory inside the mod assets directory with all your mod assets inside. The name of your domain directory will be the "current domain" for all assets inside it. If no domain has been specified in an asset code the game will assume it is in the current domain, meaning you only have to add a domain prefix if you want to refer to something outside the current domain.

For example, if you want to create a new block which uses the original leather texture, you would have to specify the domain (since your block has a different one). Instead of using block/leather for assets/survival/textures/block/leather.png, you would have add the prefix for the domain game:block/leather.

Overwriting assets

There are no limitations to the system. So you can overwrite assets from Vintagestory itself by using the game domain folder.

To overwrite the bed blocktype you can put your own json file inside your mod zip archive with the following path: assets/game/blocktypes/wood/bed.json. So Vintagestory will load your json file instead of the original one.

Theme packs can only override assets that do not affect game mechanics, the other mod types can override any asset.

Accessing assets in code

To access assets in a code mod, you can use the AssetManager.

Moving Forward

Once you have an idea of what assets are and how they're organized, it's time to move onto your first content mod. Head over to the Basic Block page to learn how to make your first block, or go to the Basic Item page if you'd like to start by making an item. Both are great ways to learn how to make your first mod.


Content Modding
Basics Content Mods Developing a Content Mod Packaging & Release
Tutorials
Concepts Modding Concepts Modinfo Variants Domains Patching Remapping World Properties
Moddable Assets
Uncategorized
Icon Sign.png

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 ItemEntityEntity BehaviorsBlockBlock BehaviorsBlock ClassesBlock EntitiesBlock Entity BehaviorsCollectible BehaviorsWorld properties
Workflows & Infrastructure Modding Efficiency TipsMod-engine compatibilityMod ExtensibilityVS Engine
Additional Resources Community Resources Modding API Updates Programming Languages List of server commandsList of client commandsClient startup parametersServer startup parameters
Example ModsAPI DocsGitHub Repository