Difference between revisions of "Modding:Item Json Properties"

From Vintage Story Wiki
Jump to navigation Jump to search
Line 582: Line 582:
Attributes primarily used with equipment and armor.
Attributes primarily used with equipment and armor.
  <td scope="row"><div class="tt" data-tt-id="p_alist_atshape" data-tt-parent="p_attributes_equip">attachShape</div></td>
  <td>Path to Shape</td>
  <td>Assigns a shape to a bag to be shown on the player when worn in a bag slot.</td>
  <td scope="row"><div class="tt" data-tt-id="p_alist_backpack" data-tt-parent="p_attributes_equip">backpack</div></td>
  <td>Gives an item bag properties, allowing it to be placed in the bag slot to increase inventory space.</td>
  <td scope="row"><div class="tt" data-tt-id="p_alist_bpquantity" data-tt-parent="p_alist_backpack">quantitySlots</div></td>
  <td>How many additional slots the bag provides.</td>
  <td scope="row"><div class="tt" data-tt-id="p_alist_bpsflags" data-tt-parent="p_alist_backpack">storageFlags</div></td>
  <td>number (storage flag ID)</td>
  <td>Limits what type of item can be placed into the bag by assigning it a storage flag. (Need a list of storage flags)</td>
  <td scope="row"><div class="tt" data-tt-id="p_alist_slotcolor" data-tt-parent="p_alist_backpack">slotBgColor</div></td>
  <td>Color value (HEX)</td>
  <td>Changes the background color of the additional slots provided by the bag. Requires a HEX color code, which you can find with any generic color picker</td>
<td scope="row"><div class="tt" data-tt-id="p_attributes_misc" data-tt-parent="root">(Misc Attributes)</div></td>
<td scope="row"><div class="tt" data-tt-id="p_attributes_misc" data-tt-parent="root">(Misc Attributes)</div></td>

Revision as of 01:46, 19 April 2020


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

(Container Attributes)

Attributes that change how items interact with containers.

boolean - If set to true, converts an item placed into a barrel to a "liquid" state that can be used for barrel recipes (EX: how salt is used to cure meat). salt
boolean - If set to true, can be placed into a crock from another container (Keep in mind that doing so also turns the item into a meal, which cannot be undone). pickledvegetable
boolean - If set to true, allows an item to be placed into a display case. ingot, ore-graded, ore-ungraded, stone
boolean - A bit of a misnomer, this indicates that an item can be placed into and heated in a forge, not that it can or can't be forged on an anvil. ironbloom
Path to texture - Pathway to the texture shown when an item is placed into a barrel. This can include a liquid or solids. waterportion, salt
- - Gives an item additional rendering properties when placed in a fire pit. redmeat, poultry
- - If the model type shows the item, it can be transformed using this property. redmeat, poultry
- - Tell the firepit which model to use when this item is placed into it. redmeat, poultry

Here's an example of how the firepit transformation is used by the different meat items:

inFirePitProps: {
  transform: {
    scale: 0.85,
    origin: { x: 0.5, y: 0.0625, z: 0.5 },
    translation: { x: -0.03125, y: 0.0625, z: 0.046875 },
    rotation: { x: 0, y: 0, z: 90 }
  useFirepitModel: "Spit"

If you're familiar with the other transformation code, this is nothing unusual and works on the same principles by changing the scale, position and rotation of the model with respect to the origin of rotation.

At the moment spit is the only model used with single food items. The other option wide is used with the cooking pot.

boolean - If true, allows the item to be placed on shelves. redmeat, stone
boolean - If true, allows the item to be placed on a tool rack. To look right the item also requires additional transformations using the toolrackTransform property (see rendering section). pickaxe, scythe, sword
- - This contains all the liquid properties of an item, generally determining how it is stored and used with a bucket. waterportion, limewaterportion
true - IF true, the liquid can be placed into liquid containers, such as barrels and buckets. waterportion, limewaterportion
number - The number of itemstack items required to make a litre of liquid. Generally this value is 1:1, but concentrated items like honey can be 4:1. waterportion, honeyportion
Path to Texture - A "block" texture given to a liquid when it's rendered in containers or other items. waterportion, honeyportion
boolean - If true, allows the player to use the Ctr + Right Click function to "spill" the liquid from a container. The whenSpilled property determines what happens if this is true. waterportion, limewater
number (0,1 or 2) - An optional liquid property that tints the color of a liquid when in a container. Available options are 0(red), 1(green) and 2(blue). waterportion, limewater
- - Determines what happens when the "spill" interaction is used. Only works if the allowSpill property is set to true. waterportion, limewater
string - Code identifier that determines what happens when the liquid is spilled from a container. waterportion, limewater
- - Places a block at the spilled location. waterportion
- - Drops an item at the location. If the item is a liquid it will disappear immediately with a "splash" particle effect. limeportion
string - The block or item dropped when spilled. if the "PlaceBlock" action is chosen a block is placed, if "DropContents" is used an item is generated. waterportion, limewater
- - Allows for different blocks or items to be placed based on the level of the liquid in the container. waterportion, limewater
(Equipment Attributes)

Attributes primarily used with equipment and armor.

Path to Shape - Assigns a shape to a bag to be shown on the player when worn in a bag slot. backpack
- - Gives an item bag properties, allowing it to be placed in the bag slot to increase inventory space. backpack
number - How many additional slots the bag provides. backpack
number (storage flag ID) - Limits what type of item can be placed into the bag by assigning it a storage flag. (Need a list of storage flags) miningbag
Color value (HEX) - Changes the background color of the additional slots provided by the bag. Requires a HEX color code, which you can find with any generic color picker miningbag
(Misc Attributes)

Uncategorized attributes used in various items.

value, decimal - Determines how often a projectile will break when shot. Flint arrow = 0.5 (50%, iron arrow = 0.20 (20%). arrow
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},
- - Gives the item a grinding recipe in a quern. ore-ungraded
object - Type of stack produced, either a block or item. ore-ungraded
string - Name of the item or block produced by the recipe. ore-ungraded
number - The amount of the output produced after grinding. ore-ungraded
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
- - Changes the nutrition of a food item when it is cooked into a meal, otherwise the default nutrition property is used. egg, vegetable
number - Numerical value of saturation added. egg, vegetable
string - Category it adds to in the meal: Dairy(unused), Fruit, Grain, Protein and Vegetable egg, vegetable
- - 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 (found from a Wikipedia article in this case).

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
Entity - Assigns an spear entity to be made when a spear is thrown. spear
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
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
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