Modding:Advanced JSON Item

This tutorial introduces some more advanced abilities of the JSON modding system. Particularly variant, and property groups for items.

Basic Properties

Our wand is still rather useless, so it's be a good idea to add some mining functionality. How this works? With the property miningspeed we can define the mining speed for an item. Here is a list of all block materials.

The number indicates how fast the tool is able to mine the block, while 1 is the default value. time to mine = block resistance / miningspeed. Meaning a speed of 2 is twice as fast the default speed of one. So our tool is seven times faster than using the hand.

Our wand looks like this:

	miningspeed: {
		"stone": 7,
		"metal": 7
	},

Although the tool is working already, we should add some kind of durability. Therefore we need to define what can damage our tool and the durability itself.

Our tool can be damaged by breaking a block, or using it for as a weapon. The property damagedby allows us to define what an item is damaged by. For now we will stick to blockbreaking and attacking.

	damagedby: ["blockbreaking", "attacking"],

and the durability should be 2000:

	durability: 2000,

Variant Groups

Pretty basic so far, let's go more advanced. Let's add some variants to our wand, each of them should represent another tool (shovel, pickaxe, axe).

So first of all we have to add a new variant group. The name of your group is tooltype and possible values are "shovel", "pickaxe", "axe":

	variantgroups: [
		{ code: "tooltype", states: ["shovel", "pickaxe", "axe" ] },
	],

This bit of code tells the game to create three variants:

• item-wand-shovel
• item-wand-pickaxe
• item-wand-axe

Every group will be added after each other to the item name item-myitemname-mygroup-mysecondgroup. You can add as many variants as you want.

Now, in order to actually utilize our new variants, we will need to change our miningspeed, and durability to miningspeedByType and durabilityByType. Most properties can have ...ByType stuck on the end and they will utilize the variant system.

For the new mining speeds, we changed the property name to miningspeedByType and added wild card selectors. These wild card selectors are where the power of the variant system shows.

	miningspeedByType: {
		"*-shovel": {
			"soil": 7,
			"sand": 7,
			"gravel": 4.4
		},"*-pickaxe": {
			"stone": 7,
			"metal": 7
		},"*-axe": {
			"wood": 6,
			"leaves": 4
		},
	},

The name *-shovel matches any variant ending in -shovel, and like wise for the other variants. Using these selectors we can target specific item types easily.

We can also change the durability for each type individually.

	durabilityByType: {
		"*-shovel": 4000,
		"*-pickaxe": 3000,
		"*-axe": 2000,
	},

Variant Textures

Using the same way we specified the mining speed for each type we can also specify a texture for each type.

	textureByType: {
		"*-shovel": {
			base: "item/wand-shovel",
		},
		"*-pickaxe": {
			base: "item/wand-pickaxe",
		},
		"*-axe": {
			base: "item/wand-axe",
		},
	}

But we can accomplish the same thing with an easier way:

	texture: {
		base: "item/wand-{tooltype}",
	}

{tooltype} will be replaced by either shovel, pickaxe or axe. This is another extremely powerful part of the variant group system. For example, VS has a lot of different kinds of rocks. Defining all the drops could be done by specifying each blocks drops:

	dropsByType: {
		"*-andesite": [{
			"type": "item",
			"code": "stone-andesite",
			"quantity": { "avg": 2.5, "var": 0.5 }
		}],
		"*-chalk": [{
			"type": "item",
			"code": "stone-chalk",
			"quantity": { "avg": 2.5, "var": 0.5 }
		}],
	}

But as you can see this would quickly get extremely long. Instead, defining all these things is done with:

	dropsByType: {
		"*": [{
			"type": "item",
			"code": "stone-{rock}",
			"quantity": { "avg": 2.5, "var": 0.5 }
		}]
	}

Texture Overlays

As everybody knows programmers are lazy, so instead of drawing a texture for each variant of our item, we can use overlays instead, which will make it a lot easier.

These are the overlays for each type: . All we have to do now is to change the base texture to back to the original wand texture and add an overlay texture.

	texture: {
		base: "item/wand",
		overlays: [ "item/wand-overlay-{tooltype}" ],
	},

and this is the result:

Mod Download

You can download the mod to test it out yourself:

MyAdvancedWandMod.zip

Moving Forward

The example shown here is a rather simple item, and barely covers all the unique things that can be added in Vintage Story. It's highly recommended that you experiment with or at least familiarize yourself with all the known item properties before moving onto code mods. The best way to do this is to peruse the Item Properties page, which contains an ongoing list of all the usable JSON item properties currently incorporated into the game. Most properties in the list also have referenced files you can search for in the Vintage Story Assets folder. If you don't know where this is, you can find tutorials for each operating system at the Asset System page.

If you haven't yet, it's suggested you also check out the Basic Block and Basic Entity pages to learn how simple JSON items and entities are added to the game.

However, if you're feeling like making the jump to code mods then you'll want to start by setting up your Development Environment. Hint: Use the client command .tfedit if you want to adjust the item position, rotation and scale in Hands, in GUI, when dropped on the ground or in third person mode.

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.