Modding:Item Json Properties

From Vintage Story Wiki
Jump to navigation Jump to search


A complete list of all available properties

Property Type Default Usage Reference
Core (no byType available)
string required A unique identifier for the item. Reference JSONs that use this property.

A domain prefix will be added dynamically depending on the location of the file. Every mod and VintageStory itself have a unique prefix.

For example the code stone turns into game:stone. To refer to items outside your mod (IE with item patches) you would use the following format: yourmod:youritem

The code identifier has to be unique inside its domain. In theory there could be equal identifiers with different domain prefixes. Find out more about Domains.

boolean true If the item will be loaded or not. Can be used to temporarily remove the item. -
array of object - Allows you define multiple variants of the same item. armor, ore-graded, plank,

The variantgroups property allows you to define multiple variants of this item. All of them will have their unique pattern, which will be added to the item code.

An easy example would be a bowl, which can either be raw or burned:

	variantgroups: [
		{ code:"type", states: ["raw", "burned"] },

Meaning there will be two variants bowl-raw and bowl-burned.

It's also possible to define multiple groups.

	variantgroups: [
		{ code:"state", states: ["closed", "opened"] },
		{ code:"contents", states: ["empty", "cabbage"] },

As a result you will have 2x2 groups, which will be added one after each other: barrel-closed-empty, barrel-closed-cabbage, barrel-opened-empty and barrel-opened-cabbage.

Additionally it is possible to refer to external lists (used for blocks) that are found in the worldproperties folder, such as block/rock, which contains all states of all rock types. This used for gravel, sand and rock. It's a good way to keep everything organized:

	variantgroups: [
		{ loadFromProperties: "block/rock" },

Here is a full list of all groups and their variants (you can also find them in the assets/worldproperties folder):

Name States
block/grass -
block/mushroom flyagaric, bolete, fieldmushroom
block/herb basil, chamomile, cilantro, lavender, marjoram, mint, saffron, sage, thyme
block/flower catmint, forgetmenot, edelweiss, heather, horsetail, orangemallow, wilddaisy, westerngorse, cowparsley, californiapoppy
block/metal bismuth, bismuthbronze, blackbronze, brass, chromium, copper, gold, iron, lead, platinum, rhodium, silver, stainlesssteel, steel, tin, tinbronze, titanium, uranium, zinc
block/ore lignite, bituminouscoal, nativecopper, limonite, quartz_nativegold, galena, cassiterite, chromite, platinum, ilmenite, sphalerite, rocksalt_sylvite, quartz_nativesilver, lapislazuli, diamond, emerald, bismuthinite, quartz, rocksalt, sulfur, magnetite
block/tallgrass veryshort, short, mediumshort, medium, tall, verytall, eaten
block/rock andesite, chalk, claystone, granite, sandstone, shale
block/woodwithaged birch, oak, maple, pine, acacia, kapok, aged
block/wood birch, oak, maple, pine, acacia, kapok
block/painting acitasluna, dandelionnight, distantpath, forestpath, night, papiliorumanzovia, stillmomentsbeforesunrise, thedreamprojection, troidesaeacus, winterflowers
abstract/rockgroup -
abstract/alloy -
abstract/fertility verylow, low, medium, high
abstract/grasscoverage none, verysparse, sparse, normal
abstract/horizontalorientation north, east, south, west
abstract/verticalorientation up, down
abstract/coating n, e, s, w, u, d, ud, ns, ew, nd, ed, sd, wd, su, wu, nu, eu, es, sw, nw, ne, nwd, ned, esd, swd, nwu, neu, esu, swu, nsd, ewd, sud, wud, nud, eud, nsu, ewu, nes, esw, nsw, new, newd, nesd, eswd, nswd, eswu, nswu, newu, nesu, nesw, ewud, nsud, neud, esud, swud, nwud, neswd, neswu, newud, nesud, eswud, nswud, neswud

Furthermore there are other ways of combining groups together. So far we covered the default combination mode, which is multiplicative (the total count of variants is the product of all states). There are two other methods, Additive and SelectiveMultiply.

Let's take a look at the additive combination mode used in the flowerpot block:

	variantgroups: [
		{ code: "type", states: ["raw"] },
		{ code: "empty", states: ["empty"], combine: "additive" },
		{ code: "flower", loadFromProperties: "block/flower", combine: "additive" },
		{ code: "mushroom", loadFromProperties: "block/mushroom", combine: "additive" },
		{ code: "sapling", loadFromProperties: "block/wood", combine: "additive" },

The variants are flowerpot-raw, flowerpot-empty, flowerpot-{all flowers}, flowerpot-{all mushrooms} and flowerpot-{all saplings}.

Additive mode could also be called separate, since it defines a variant separate from all the other groups:

	variantgroups: [
		{ code: "something", states: ["same", "different"] },
		{ code: "type", states: ["raw", "baked"] },
		{ code: "empty", states: ["red", "green"], "combine": "additive" },

In this case, the result would be same-raw, same-baked, different-raw, different-baked, red and green

The third combination mode "SelectiveMultiply" which allows you to specify which variant groups you want to combine multiplicatively with. There are many examples of this in the clothing item JSONS, as shown below with the lowerbody asset:

    code: "clothes",	
    variantgroups: [
	{ code: "category",  states: ["lowerbody"] },
	{ code: "lowerbody", combine: "SelectiveMultiply", onVariant: "category", states: [
"aristocrat-leggings", "dirty-linen-trousers", "fine-trousers", "jailor-pants", "lackey-breeches", "merchant-pants", "messenger-trousers", "minstrel-pants", "noble-pants", "prince-breeches", "raindeer-trousers", "raw-hide-trousers", "shepherd-pants", "squire-pants", "steppe-shepherds-trousers", "tattered-peasent-gown", "torn-riding-pants", "warm-woolen-pants", "woolen-leggings", "workmans-gown" 
         ] },

The function onVariant specifies which variant group to selectively combine with, ignoring all other variants without it (in case some are combined additively).

Using this will result items called clothes-lowerbody-aristocrat-leggings, clothes-lowerbody-dirty-linen-trousers, etc.

(any) bytype
key: string; value: object - You can create properties for certain variants of the item.

In order to define properties for specific variants you can add byType to the property name. This allows you to define it depending on the type and always follows the same syntax:

	(property)ByType: {
		"selector": property,
		"selector2": property2,

If the selector matches the name of the variant the given property will be used. Keep in mind that only the first matching one will be used (everything below will be ignored).

A slab for example has two variants (up, down), which have different collision boxes:

	collisionboxByType: {
		"*-down": { x1: 0, y1: 0, z1: 0,   x2: 1, y2: 0.5, z2: 1 },
		"*-up": { x1: 0, y1: 0.5, z1: 0,   x2: 1, y2: 1, z2: 1 }

The char * stands for anything. In this case it ignores the code of the item.

Furthermore this opens up even more possbilities for more advanced selectors like this one for doors: *-north-*-opened-left. This will ignore the second variantgroup. Additionally ByType can also be used for child properties:

	collisionboxnbox: { 
		x1: 0, y1: 0, z1: 0.875, x2: 1, y2: 1, z2: 1,
		rotateYByType: {
			"*-north-*-opened-left": 90,
			"*-north-*-closed-left": 0,
			"*-west-*-opened-left": 180,
			"*-west-*-closed-left": 90,

			"*-east-*-opened-left": 0,
			"*-east-*-closed-left": 270,
			"*-south-*-opened-left": 270,
			"*-south-*-closed-left": 180,

			"*-north-*-opened-right": 270,
			"*-north-*-closed-right": 0,
			"*-west-*-opened-right": 0,
			"*-west-*-closed-right": 90,

			"*-east-*-opened-right": 180,
			"*-east-*-closed-right": 270,
			"*-south-*-opened-right": 90,
			"*-south-*-closed-right": 180

Since Vintagestory v1.8 it is also possible to use the variantgroup as a placeholder:

	variantgroups: [
		{ code: "metal", states: ["copper", "tinbronze", "bismuthbronze", "blackbronze", "gold", "silver", "iron" ] },
	textures: {
		"metal": { base: "block/metal/ingot/{metal}" },
		"wood": { base: "item/tool/material/wood" } 
array - Used to trim unnecessary items generated by combined variants. crystalizedore-graded, ore-graded, ore-ungraded
array - Similar to allowedVariants, but instead skips the creation of listed variants rather than assigning which are allowed. armor
string "item" The class an item should use if it has additional C# functionalities that can't be accomplished with JSONS. axe-metal, hoe, spear

It can be used to open guis or adding other extra functionality to the item. A complete tutorial of how to add your own class to the game can be found here.

integer 0 The maximum uses of the item. Items that reach 0 uses disappear. NOTE: The actual current durability of the item is stored as a treeAttribute, this is only a max value. pickaxe
array of string - From which damage sources does the item takes durability damage. pickaxe
0 Mining a block. pickaxe
1 Hitting an entity. sword
2 Currently not used. -
string - Classifies the item as the given tool, which gives it the ability to harvest resources from certain blocks. axe-metal, pickaxe, knife, scythe, shovel
0 Can harvest items from grass. knife, scythe
1 Can mine rock and other stone materials pickaxe
2 Can chop down trees and other wood materials. axe-metal, axe-stone
3 No special abilities yet. sword
4 Can dig soil, gravel and sand quickly. shovel
5 No special abilities yet. hammer
6 No special abilities yet. -
7 No special abilities yet. spear
8 No special abilities yet. bow
9 No special abilities yet. -
10 No special abilities yet. hoe
11 No special abilities yet. saw
key: string, value: string[] - In which creative inventory tabs the item should be visible in. Any Item

There are several to which you can add content from your mod. Note that general should always be included, since it should contain everything.

  • general
  • terrain
  • flora
  • construction
  • decorative
  • items

Rock adds all of it's variations to general, terrain and construction:

	creativeinventory: { "general": ["*"], "terrain": ["*"], "construction": ["*"] },

* represents the variants which will be added. You can specify multiple and separate them with a comma. It follows the same way as the byType property.

However, sometimes you may only want to show a single variant of your block or item (such as one that has multiple directional variants). In this case, you can set a specific variant to show up, once again using similar syntax to the variant code.

For example, a Torch only adds the variation up, since the block uses a class to determine which direction it will be placed in regardless of the variant used:

	creativeinventory: { "general": ["*-up"], "decorative": ["*-up"] },
integer 64 Determines the maximum amount you can stack the item in one slot. hide, nugget
decimal number 0.5 The damage the item deals when hitting an entity. sword, spear
decimal number 1.5 The maximum distance you can hit an entity with the item. sword, spear
integer 9999 Determines on whether an object floats on liquids or not. ingot

Water has a density of 1000, meaning everything below or equal will float on water. The same goes for lava which has a density of 5000.

Vintage story uses real world densities for each material (where 1000 = 1 g/cm^3). To give an idea of the current range of densities, gold has a density of 19300, iron's is 7870, and a feather is 20.

boolean false If the item can select a liquid while holding it in hand.

Used for buckets in order to fill it with water and to place waterlily on top of water.

key: string, value: decimal number - The mining speed for each block material. pickaxe, shovel

Materials types are hard-coded into blocks, and include the following types:

soil, gravel, sand, wood, leaves, stone, liquid, snow, ice, metal, mantle, plant, glass, ceramic, cloth, lava, brick, fire, other

An item is not limited to a single material that it can mine, so if you wanted to make a tool (such as a mattock) that could mine many materials you could do the following:

	miningspeed: {
          "dirt": 5,
          "gravel": 4,
          "ice": 7,
          "metal": 3,
          "sand": 4,
          "snow": 3,
          "stone": 6,
integer 0 Determines which tier of blocks the item can break. If the block tier is above the one defined here nothing will be dropped from it when broken. Also determines the damage tier of a weapon, which is contested against armor tiers. pickaxe, sword
key: string, value: object - Custom Attributes associated with this item. armor, ingot

Attributes constitute a large number of custom properties that an item can have, many of which are specific to unique items that rely on classes for their functionality. If you wish to utilize your own custom attributes generally you must have an accompanying class with the item.

Values placed here are final and cannot be modified. For example, if you made a new type of weapon, say a mace that had additional weapon properties (used in an ItemMace class) you could define them here:

    attributes: {
		"armorDamage": 10,
		"stunChance": 0.1,

Here we have made two new attributes called "armorDamage" and "stunChance" and have given them their own static values to be used in code. As is, these cannot do anything without the usage of C# code in a class. Regardless, we can see that this is a convenient way to create extra properties that can be manipulated using variant combinations if desired.

Attribute List

A complete list of existing properties are contained here:

value, decimal - Determines how often a projectile will break when shot.

Flint arrow = 0.5 (50%, iron arrow = 0.20 (20%).

array - Creates a list of block prefixes a tool can interact with using special features (such as how a scythe cuts large swathes of grass). scythe
- - Allows an item to be traded as a universal currency. gear (rusty)
value - Assigns a value to the currency, a rusty gear is valued at 1. gear (rusty)
value - The ranged damage of a thrown weapon (such as a spear). spear
boolean false If true, will make an item disappear when dropped into a water block. flour, lime, salt
boolean false If true, allows an item to be used to construct a firepit. firewood, bamboostakes
n: value, p: value, k: value - Sets the item as a fertilizer and assigns it nitrogen(N), phosphorous(P) and potassium(K) values. bonemeal, potash

As an example, we can make a "universal fertilizer" that contributes a decent amount to each element:

	fertilizerProps: {n: 20, p: 20, k: 20},
health: value - If the item is a poultice, this is the amount it will heal (requires ItemPoultice class). poultice
boolean false If true, will be playable on the echo chamber block. Requires a track to be set using the musicTrack property. resonancearchive
boolean false Allows an item to be "knapped" into primitive toolheads. flint, stone
boolean false If true, will allow the item to be used for microblock chiseling.

NOTE: Microblock chiseling must also be active in the world settings.

number - Assigns the units of metal the item contributes when it is smelted.

NOTE: An item must be smeltable for this property to be of any use, make sure to check the combustableProps section for more info.

path to ogg file - Assigns a path to the ogg file of the music track associated with an item that can be played on the echo chamber block. Will only function if the isPlayableDisc property is set to true. resonancearchive
- - Allows an item to be used as a pigment for coloring. resonancearchive
string - Assigns a name to the color of the pigment. charcoal
red:value, green: value, blue: value - The RGB values of the pigment, which can be found using any generic color picker. charcoal

As an example, let's say you wanted to make a valuable purple pigment from the shell of a rare rock snail:

	"pigment": {
           "name": "Tyrian Purple",
           "color": {
             "red": 102,
             "green": 2,
             "blue": 60

Here we can see that the pigment will be named "Tyrian Purple", and is made with the three RGB values we found from a wikipedia entry.

object - Information about the items burnable states.
integer - The temperature at which it burns in degrees celsius.
decimal number - For how long it burns in seconds.
integer 500 How many degrees celsius it can resists before it ignites (not implemented yet).
integer - How many degrees celsius it takes to smelt/transform this into another. Only used when put in a stove and Melted is set.
decimal number - For how many seconds the temperature has to be above the melting point until the item is smelted.
decimal number 1 How much smoke this item produces when being used as fuel.
integer 1 How many ores are required to produce one output stack.
object - If set, the block/item is smeltable in a furnace and this is the resulting itemstack once the MeltingPoint has been reached for the supplied duration.
boolean true If set to true, the block/item requires a smelting/cooking/baking container such as the Crucible. If false, it can be directly baked/melted without smelting/cooking/baking container.

This property can be used to define a burning material. Plank for example can get on fire:

    combustibleProps: {
        burnTemperature: 800,
        burnDuration: 12,

Furthermore it can be used to define smelting processes. An example would be an ingotmold which turns into an ingotmold-burned:

    combustiblePropsByType: {
        "ingotmold-raw": {
            meltingPoint: 600,
            meltingDuration: 30,
            smeltedRatio: 1,
            smeltedStack: { type: "block", code: "ingotmold-burned" },
            requiresContainer: false
object - Information about the items nutrients.
string - Defines the type of food. It can be fruit, vegetable, protein, grain and dairy.
decimal number 0 How much saturation it can restore.
decimal number 0 How much health it can restore.
string required The texture definitions for the item held in hand or dropped on the ground.
object - The items shape. Empty for automatic shape based on the texture.
object - The items shape in inventory.
object item default Used for scaling, rotation or offseting the item when rendered in guis.
object item default Used for scaling, rotation or offseting the item when rendered in the first person mode hand.
object item default Used for scaling, rotation or offseting the item when rendered in the third person mode hand.
object item default Used for scaling, rotation or offseting the rendered as a dropped item on the ground.

Vintage Story: Modding
Basics Mod Types | Asset System | Textures | Items | Recipes | Blocks | Model Creator | Release
Advanced Setup(Windows,Linux) | Items (Code, JSON) | Blocks | Item-Block interactions | Block Behaviors | Block Entities | Particles | World Access
Worldgen Terrain | Ores | Trees | WorldGen API
Rendering Shaders and Renderers
Property Overview Item | Block | Block Behaviors | Block Classes | Block Entities | Block Entity Behaviors