Modding:Item Json Properties
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 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 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: Additionally it is possible to refer to external lists (used for blocks) that are found in the worldproperties folder, such as variantgroups: [
{ loadFromProperties: "block/rock" },
],
Here is a full list of all groups and their variants (you can also find them in the For example, the following creates a variant group named orientation. It contains 5 states. variantgroups: [
{ code: "orientation", states: ["up"], loadFromProperties: "abstract/horizontalorientation" }
],
Unwanted variant states can be filtered out with the
Wondering where some links have gone?
Furthermore there are other ways of combining groups together. So far we covered the default combination mode, which is Let's take a look at the 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
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 The third combination mode 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 Using this will result items called |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
(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 Furthermore this opens up even more possbilities for more advanced selectors like this one for doors:
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
Rock adds all of it's variations to general, terrain and construction: creativeinventory: { "general": ["*"], "terrain": ["*"], "construction": ["*"] },
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 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 material. | pickaxe | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Materials types are hardcoded 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 blocks it can break. If the required miningtier is above the defined one there will be no drop from it. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
attributes |
key: string, value: object | - | Custom Attributes associated with this item. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Extra attributes added to a item or block. Those are final and cannot be modified. It's a good way to keep things organized and and modifiable. The oreblastingbomb for example has attributes, which define its radius and type. These can be used by behaviors and blockentities: attributes: {
"blastRadius": 4,
"blastType": 0,
},
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. |
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 | Item • Entity • Block • Block Behaviors • Block Classes • Block Entities • Block Entity Behaviors • World properties |
Workflows & Infrastructure | Modding Efficiency Tips • Mod-engine compatibility • Mod Extensibility • VS Engine |
Additional Resources | Community Resources • Modding API Updates • Programming Languages • List of server commands • List of client commands • Client startup parameters • Server startup parameters Example Mods • API Docs • GitHub Repository |