Modding:Asset System

This page was last verified for Vintage Story version 1.19.8.

Vintage Story loads most of its game content from asset JSON files. Many examples of these can be found inside the assets directory inside your Vintagestory folder. Things such as blocks, items, world generation, recipes, and more are all loaded from the assets folder during startup.

Asset Folder Location and Structure

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 (i.e. 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.

Finding the Assets Folder

Windows

Press the Windows key + R. Type "%appdata%" and press enter. This will take you to your computer's roaming folder. A folder labelled Vintagestory will contain the assets folder.

If you use a non-default installation place, then the path is [Installation folder]/assets

Linux

The location of the assets folder varies based on the method used to install the game. The official installation documentation recommends a user-wide install using Flatpak. Below are the two locations where the assets folder may be installed using Flatpak:

User-wide Installation: ~/.local/share/flatpak/app/at.vintagestory.VintageStory/current/active/files/extra/vintagestory/assets

System-wide installation: /usr/lib/flatpak/app/at.vintagestory.VintageStory/current/active/files/extra/vintagestory/assets

Users that have used a distro-specific package manager should consult the documentation of said manager for information as to where applications are stored.

Folder Structure

The assets folder contains three folders: "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 Vintage Story. Each are easily modifiable and can be used to add your own content or changes without having to do any advanced coding. There are many examples and tutorials on the wiki, such as those on Developing a Content Mod . For a more detailed description of each asset type, you should view the Asset Types category.

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

A domain is a prefix for any given code (identifier for item, block, etc.) or path (textures, sounds, etc.). Practically, a domain is used to separate and signify what content belongs to a given mod, or the base game.

Vintage Story uses its own prefix, game, for all vanilla assets (meaning all assets under the game, survival and creative folders). For example, if you wanted to create a new block that uses the original leather texture, instead of using block/leather for assets/survival/textures/block/leather.png, you instead add the prefix: game:block/leather to reference the texture.

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.

Overwriting Assets

You can overwrite vanilla assets yourself by providing your own game domain folder. This is useful for modifying the game's vanilla behavior.

For example, 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. Vintage Story 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.