Modding:Item Json Properties: Difference between revisions

From Vintage Story Wiki
Line 368: Line 368:
   </tr>
   </tr>
   <tr>
   <tr>
     <td colspan="5" style='font-size: 14pt; border-bottom: 2pt solid black; padding-left: 100px;'><b>Common</b></td>
     <td colspan="5" style='font-size: 14pt; border-bottom: 2pt solid black; padding-left: 100px;'><b>Attributes</b></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_creativeinventory" data-tt-parent="root">creativeinventory</div></td>
    <td>key: string, value: string[]</td>
    <td>-</td>
    <td>In which creative inventory tabs the item should be visible in.</td>
    <td>Any Item</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_creativeinventory_info" data-tt-parent="p_creativeinventory" data-invisible="true"></div></td>
    <td colspan="4">
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:
<syntaxhighlight lang="json">
creativeinventory: { "general": ["*"], "terrain": ["*"], "construction": ["*"] },
</syntaxhighlight>
 
'''<code>*</code>''' 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 '''<code>up</code>''', since the block uses a class to determine which direction it will be placed in regardless of the variant used:
<syntaxhighlight lang="json">
creativeinventory: { "general": ["*-up"], "decorative": ["*-up"] },
</syntaxhighlight>
</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_maxstacksize" data-tt-parent="root">maxstacksize</div></td>
    <td>integer</td>
    <td>64</td>
    <td>Determines the maximum amount you can stack the item in one slot.</td>
    <td> hide, nugget</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_attackpower" data-tt-parent="root">attackpower</div></td>
    <td>decimal number</td>
    <td>0.5</td>
    <td>The damage the item deals when hitting an entity.</td>
    <td>sword, spear</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_attackrange" data-tt-parent="root">attackrange</div></td>
    <td>decimal number</td>
    <td>1.5</td>
    <td>The maximum distance you can hit an entity with the item.</td>
    <td>sword, spear</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_materialdensity" data-tt-parent="root">materialdensity</div></td>
    <td>integer</td>
    <td>9999</td>
    <td>Determines on whether an object floats on liquids or not.</td>
    <td>ingot</td>
   </tr>
   </tr>
  <tr>
<tr>
     <td scope="row"><div class="tt" data-tt-id="p_materialdensity_info" data-tt-parent="p_materialdensity" data-invisible="true"></div></td>
     <td scope="row"><div class="tt" data-tt-id="p_attributes_list" data-tt-parent="root">attributes</div></td>
    <td colspan="4">
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.
</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_liquidselectable" data-tt-parent="root">liquidselectable</div></td>
    <td>boolean</td>
    <td>false</td>
    <td>If the item can select a liquid while holding it in hand.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_liquidselectable_info" data-tt-parent="p_liquidselectable" data-invisible="true"></div></td>
    <td colspan="4">
Used for buckets in order to fill it with water and to place waterlily on top of water.
</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_miningspeed" data-tt-parent="root">miningspeed</div></td>
    <td>key: string, value: decimal number</td>
    <td>-</td>
    <td>The mining speed for each block material.</td>
    <td>pickaxe, shovel</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_miningspeed_info" data-tt-parent="p_miningspeed" data-invisible="true"></div></td>
    <td colspan="4">
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:
 
<syntaxhighlight lang="json">
miningspeed: {
          "dirt": 5,
          "gravel": 4,
          "ice": 7,
          "metal": 3,
          "sand": 4,
          "snow": 3,
          "stone": 6,
        }
</syntaxhighlight>
</td>
  </tr>
    <td scope="row"><div class="tt" data-tt-id="p_miningtier" data-tt-parent="root">miningtier</div></td>
    <td>integer</td>
    <td>0</td>
    <td>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.</td>
    <td>pickaxe, sword</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_attributes" data-tt-parent="root">attributes</div></td>
     <td>key: string, value: object</td>
     <td>key: string, value: object</td>
     <td>-</td>
     <td>-</td>
Line 495: Line 378:
   </tr>
   </tr>
   <tr>
   <tr>
     <td scope="row"><div class="tt" data-tt-id="p_attributes_info" data-tt-parent="p_attributes" data-invisible="true"></div></td>
     <td scope="row"><div class="tt" data-tt-id="p_attributes_info" data-tt-parent="p_attributes_list" data-invisible="true"></div></td>
     <td colspan="4">
     <td colspan="4">
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.
Attributes constitute a large number of custom properties that an item can have, many of which are specific to unique items that rely on a C# class for additional functionality. If you wish to add your own JSON attributes to an item generally you must also have a class to utilize them.


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:
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 you could define them here:


<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
Line 509: Line 392:


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.  
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.  
  </tr>
  <tr>
  <td scope="row"><div class="tt" data-tt-id="p_attributes_list" data-tt-parent="p_attributes">Attribute List</div></td>
    <td colspan="4">
A complete list of existing properties are contained here:</td>
   </tr>
   </tr>
   <tr>
   <tr>
Line 662: Line 540:
</syntaxhighlight>
</syntaxhighlight>


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.  
Here we can see that the pigment will be named "Tyrian Purple", and is made with the three RGB values (found from a Wikipedia article in this case).
</tr>
<tr>
  <td scope="row"><div class="tt" data-tt-id="p_alist_reinforcestr" data-tt-parent="p_attributes_list">reinforcementStrength</div></td>
  <td>number</td>
  <td>-</td>
  <td>Allows an item to be used by the plumb and square tool to reinforce a block. A higher value indicates more times a block must be broken before it's removed.


Example: Igneous stones = 50, Iron Ingot = 400</td>
  <td>stone, ingot</td>
</tr>
<tr>
  <td scope="row"><div class="tt" data-tt-id="p_alist_sentity" data-tt-parent="p_attributes_list">spearEntityCode</div></td>
  <td>Entity</td>
  <td>-</td>
  <td>Assigns an spear entity to be made when a spear is thrown.</td>
  <td>spear</td>
</tr>
<tr>
  <td scope="row"><div class="tt" data-tt-id="p_alist_worktemp" data-tt-parent="p_attributes_list">workableTemperature</div></td>
  <td>number</td>
  <td>-</td>
  <td>The temperature required for an item (an ingot) to be worked on an anvil. A value of 0 means it can be worked cold without heating.</td>
  <td>ingot</td>
</tr>
</tr>
  <tr>
    <td colspan="5" style='font-size: 14pt; border-bottom: 2pt solid black; padding-left: 100px;'><b>Common</b></td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_creativeinventory" data-tt-parent="root">creativeinventory</div></td>
    <td>key: string, value: string[]</td>
    <td>-</td>
    <td>In which creative inventory tabs the item should be visible in.</td>
    <td>Any Item</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_creativeinventory_info" data-tt-parent="p_creativeinventory" data-invisible="true"></div></td>
    <td colspan="4">
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:
<syntaxhighlight lang="json">
creativeinventory: { "general": ["*"], "terrain": ["*"], "construction": ["*"] },
</syntaxhighlight>
'''<code>*</code>''' 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 '''<code>up</code>''', since the block uses a class to determine which direction it will be placed in regardless of the variant used:
<syntaxhighlight lang="json">
creativeinventory: { "general": ["*-up"], "decorative": ["*-up"] },
</syntaxhighlight>
</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_maxstacksize" data-tt-parent="root">maxstacksize</div></td>
    <td>integer</td>
    <td>64</td>
    <td>Determines the maximum amount you can stack the item in one slot.</td>
    <td> hide, nugget</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_attackpower" data-tt-parent="root">attackpower</div></td>
    <td>decimal number</td>
    <td>0.5</td>
    <td>The damage the item deals when hitting an entity.</td>
    <td>sword, spear</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_attackrange" data-tt-parent="root">attackrange</div></td>
    <td>decimal number</td>
    <td>1.5</td>
    <td>The maximum distance you can hit an entity with the item.</td>
    <td>sword, spear</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_materialdensity" data-tt-parent="root">materialdensity</div></td>
    <td>integer</td>
    <td>9999</td>
    <td>Determines on whether an object floats on liquids or not.</td>
    <td>ingot</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_materialdensity_info" data-tt-parent="p_materialdensity" data-invisible="true"></div></td>
    <td colspan="4">
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.
</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_liquidselectable" data-tt-parent="root">liquidselectable</div></td>
    <td>boolean</td>
    <td>false</td>
    <td>If the item can select a liquid while holding it in hand.</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_liquidselectable_info" data-tt-parent="p_liquidselectable" data-invisible="true"></div></td>
    <td colspan="4">
Used for buckets in order to fill it with water and to place waterlily on top of water.
</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_miningspeed" data-tt-parent="root">miningspeed</div></td>
    <td>key: string, value: decimal number</td>
    <td>-</td>
    <td>The mining speed for each block material.</td>
    <td>pickaxe, shovel</td>
  </tr>
  <tr>
    <td scope="row"><div class="tt" data-tt-id="p_miningspeed_info" data-tt-parent="p_miningspeed" data-invisible="true"></div></td>
    <td colspan="4">
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:
<syntaxhighlight lang="json">
miningspeed: {
          "dirt": 5,
          "gravel": 4,
          "ice": 7,
          "metal": 3,
          "sand": 4,
          "snow": 3,
          "stone": 6,
        }
</syntaxhighlight>
</td>
  </tr>
    <td scope="row"><div class="tt" data-tt-id="p_miningtier" data-tt-parent="root">miningtier</div></td>
    <td>integer</td>
    <td>0</td>
    <td>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.</td>
    <td>pickaxe, sword</td>
  </tr>
   <tr>
   <tr>
     <td scope="row"><div class="tt" data-tt-id="p_combustibleprops" data-tt-parent="root">combustibleprops</div></td>
     <td scope="row"><div class="tt" data-tt-id="p_combustibleprops" data-tt-parent="root">combustibleprops</div></td>

Revision as of 20:59, 18 April 2020

Overview

A complete list of all available properties

Property Type Default Usage Reference
json
Core (no byType available)
code
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.

enabled
boolean true If the item will be loaded or not. Can be used to temporarily remove the item. -
variantgroups
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): The world properties are stored in the assets/survival/worldproperties folder. They are used to help fill in the variantgroups field. Instead of directly specifying every state in the variant group, the states can be loaded from a world property through the loadFromProperties key. The states from multiple world properties can be added with the loadFromPropertiesCombine key, which takes an array of strings. The states key can still be optionally added to the variant group to specify additional states.

For example, the following creates a variant group named orientation. It contains 5 states. north, east, south, and west are loaded from the abstract/horizontalorientation world property. up is added to the list of states.

	variantgroups: [
		{ code: "orientation", states: ["up"], loadFromProperties: "abstract/horizontalorientation" }
	],

Unwanted variant states can be filtered out with the skipVariants property. Or all states that do not match an expression can be filtered out with the allowedVariants property.

Name States
abstract/alloy -
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
abstract/fertility verylow, low, medium, compost, high
abstract/grasscoverage none, verysparse, sparse, normal
abstract/horizontalorientation north, east, south, west
abstract/rockgroup -
abstract/verticalorientation up, down
block/flower catmint, cornflower, forgetmenot, edelweiss, heather, horsetail, orangemallow, wilddaisy, westerngorse, cowparsley, goldenpoppy, lilyofthevalley, woad, redtopgrass
block/fruit blueberry, cranberry, redcurrant, whitecurrant, blackcurrant, saguaro, pineapple, redapple, pinkapple, yellowapple, cherry, peach, pear, orange, mango, breadfruit, lychee, pomegranate
block/grass -
block/herb basil, chamomile, cilantro, lavender, marjoram, mint, saffron, sage, thyme
block/metal bismuth, bismuthbronze, blackbronze, brass, chromium, copper, cupronickel, electrum, gold, iron, meteoriciron, lead, molybdochalkos, platinum, nickel, silver, stainlesssteel, steel, tin, tinbronze, titanium, uranium, zinc
block/mushroom flyagaric, fieldmushroom, almondmushroom, bitterbolete, blacktrumpet, chanterelle, commonmorel, deathcap, devilstooth, devilbolete, earthball, elfinsaddle, golddropmilkcap, greencrackedrussula, indigomilkcap, jackolantern, kingbolete, lobster, orangeoakbolete, paddystraw, puffball, redwinecap, saffronmilkcap, violetwebcap, witchhat, beardedtooth, chickenofthewoods, dryadsaddle, pinkoyster, tinderhoof, whiteoyster, reishi, funeralbell, deerear, livermushroom, pinkbonnet, shiitake
block/ore-gem-cut diamond, emerald, peridot
block/ore-gem-rough diamond,emerald,olivine_peridot
block/ore-graded nativecopper,limonite,quartz_nativegold,galena,cassiterite,chromite,ilmenite,sphalerite,quartz_nativesilver,galena_nativesilver,bismuthinite,magnetite,hematite,malachite,pentlandite,uranium,wolframite,rhodochrosite
block/ore-nugget nativecopper,limonite,nativegold,galena,cassiterite,chromite,ilmenite,sphalerite,nativesilver,bismuthinite,magnetite,hematite,malachite,pentlandite,uranium,wolframite,rhodochrosite
block/ore-ungraded alum,lapislazuli,corundum,anthracite,borax,cinnabar,lignite,bituminouscoal,sylvite,quartz,olivine,sulfur,fluorite,graphite,kernite,phosphorite
block/painting howl,elk,underwater,prey,forestdawn,fishandtherain,bogfort,castleruin,cow,hunterintheforest,seraph,sleepingwolf,sunkenruin,traveler,oldvillage,lastday,sodhouse
block/rock andesite,chalk,chert,conglomerate,limestone,claystone,granite,sandstone,shale,basalt,peridotite,phyllite,slate,bauxite
block/rockwithdeposit andesite,chalk,chert,conglomerate,limestone,claystone,granite,sandstone,shale,basalt,peridotite,phyllite,slate,obsidian,kimberlite,scoria,tuff,bauxite,halite,suevite,whitemarble,redmarble,greenmarble
block/tallgrass veryshort,short,mediumshort,medium,tall,verytall,eaten
block/toolmetal bismuth,bismuthbronze,blackbronze,brass,copper,gold,iron,meteoriciron,lead,molybdochalkos,silver,steel,tinbronze
block/wood birch,oak,maple,pine,acacia,kapok,baldcypress,larch,redwood,ebony,walnut,purpleheart
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.



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" } 
	},
allowedVariants
array - Used to trim unnecessary items generated by combined variants. crystalizedore-graded, ore-graded, ore-ungraded
skipVariants
array - Similar to allowedVariants, but instead skips the creation of listed variants rather than assigning which are allowed. armor
Specific
class
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.

durability
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
damagedby
array of string - From which damage sources does the item takes durability damage. pickaxe
blockbreaking
0 Mining a block. pickaxe
attacking
1 Hitting an entity. sword
fire
2 Currently not used. -
tool
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
Knife
0 Can harvest items from grass. knife, scythe
Pickaxe
1 Can mine rock and other stone materials pickaxe
Axe
2 Can chop down trees and other wood materials. axe-metal, axe-stone
Sword
3 No special abilities yet. sword
Shovel
4 Can dig soil, gravel and sand quickly. shovel
Hammer
5 No special abilities yet. hammer
Mallet
6 No special abilities yet. -
Spear
7 No special abilities yet. spear
Bow
8 No special abilities yet. bow
Sickle
9 No special abilities yet. -
Hoe
10 No special abilities yet. hoe
Saw
11 No special abilities yet. saw
Attributes
attributes
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 a C# class for additional functionality. If you wish to add your own JSON attributes to an item generally you must also have a class to utilize them.

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 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.

breakChanceOnImpact
value, decimal - Determines how often a projectile will break when shot. Flint arrow = 0.5 (50%, iron arrow = 0.20 (20%). arrow
codePrefixes
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
currency
- - Allows an item to be traded as a universal currency. gear (rusty)
value
value - Assigns a value to the currency, a rusty gear is valued at 1. gear (rusty)
damage
value - The ranged damage of a thrown weapon (such as a spear). spear
dissolveInWater
boolean false If true, will make an item disappear when dropped into a water block. flour, lime, salt
firepitConstructable
boolean false If true, allows an item to be used to construct a firepit. firewood, bamboostakes
fertilizerProps
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
health: value - If the item is a poultice, this is the amount it will heal (requires ItemPoultice class). poultice
isPlayableDisc
boolean false If true, will be playable on the echo chamber block. Requires a track to be set using the musicTrack property. resonancearchive
knappable
boolean false Allows an item to be "knapped" into primitive toolheads. flint, stone
microBlockChiseling
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.

chisel
metalUnits
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.

resonancearchive
musicTrack
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
pigment
- - Allows an item to be used as a pigment for coloring. resonancearchive
name
string - Assigns a name to the color of the pigment. charcoal
color
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 (found from a Wikipedia article in this case).

reinforcementStrength
number - Allows an item to be used by the plumb and square tool to reinforce a block. A higher value indicates more times a block must be broken before it's removed. Example: Igneous stones = 50, Iron Ingot = 400 stone, ingot
spearEntityCode
Entity - Assigns an spear entity to be made when a spear is thrown. spear
workableTemperature
number - The temperature required for an item (an ingot) to be worked on an anvil. A value of 0 means it can be worked cold without heating. ingot
Common
creativeinventory
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"] },
maxstacksize
integer 64 Determines the maximum amount you can stack the item in one slot. hide, nugget
attackpower
decimal number 0.5 The damage the item deals when hitting an entity. sword, spear
attackrange
decimal number 1.5 The maximum distance you can hit an entity with the item. sword, spear
materialdensity
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.

liquidselectable
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.

miningspeed
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,
        }
miningtier
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
combustibleprops
object - Information about the items burnable states.
burntemperature
integer - The temperature at which it burns in degrees celsius.
burnduration
decimal number - For how long it burns in seconds.
heatresistance
integer 500 How many degrees celsius it can resists before it ignites (not implemented yet).
meltingpoint
integer - How many degrees celsius it takes to smelt/transform this into another. Only used when put in a stove and Melted is set.
meltingduration
decimal number - For how many seconds the temperature has to be above the melting point until the item is smelted.
smokelevel
decimal number 1 How much smoke this item produces when being used as fuel.
smeltedratio
integer 1 How many ores are required to produce one output stack.
smeltedstack
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.
requirescontainer
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
        }
    },
nutritionprops
object - Information about the items nutrients.
foodcategory
string - Defines the type of food. It can be fruit, vegetable, protein, grain and dairy.
saturation
decimal number 0 How much saturation it can restore.
health
decimal number 0 How much health it can restore.
Rendering
textures
string required The texture definitions for the item held in hand or dropped on the ground.
shape
object - The items shape. Empty for automatic shape based on the texture.
shapeinventory
object - The items shape in inventory.
guiTransform
object item default Used for scaling, rotation or offseting the item when rendered in guis.
fphandtransform
object item default Used for scaling, rotation or offseting the item when rendered in the first person mode hand.
tphandtransform
object item default Used for scaling, rotation or offseting the item when rendered in the third person mode hand.
groundtransform
object item default Used for scaling, rotation or offseting the rendered as a dropped item on the ground.


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.