Modding:Advanced JSON Item: Difference between revisions

From Vintage Story Wiki
m (VeryGoodDog moved page Modding:Advanced Item to Modding:Advanced JSON Item: theres a page called Modding:Advanced Items about code mod items.)
m (→‎Variant Groups: fix typo)
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
WIP ask VeryGoodDog if you really want this done
This tutorial introduces some more advanced properties of the JSON modding system including item variant, and property groups.
 
== Basic Properties ==
 
Revisiting our wand from the basic tutorial. Currently, it's only a stick, which is still rather useless Using this tutorial, we will now add mining functionality.
How does this work? By adding a property to our wand using <code>miningspeed</code> we can define the mining speed when using the wand. We also need to define how fast the wand will mine each block type. (Use this list of all [[block materials]].)
 
The number indicates how fast the tool is able to mine a specific block type, with <code>1</code> as the default value. <code>time to mine = block resistance / miningspeed</code>. A speed of <code>2</code> is twice as fast the default speed of one. So using the code below, we make our wand mine seven times faster than using any default tool.
 
Our wand looks like this:
<syntaxhighlight lang="json">
miningspeed: {
"stone": 7,
"metal": 7
},
</syntaxhighlight>
 
Although the tool is already working, we should add some kind of durability. Next, we need to define the durability of our wand and what can cause damage to our wand.
The property <code>damagedby</code> allows us to define what damages an item. For now we will stick to <code>blockbreaking</code> and <code>attacking</code>.
 
Using the code below, our wand will take damage when we use it to break a block, or when using our wand as a weapon.
 
<syntaxhighlight lang="json">
damagedby: ["blockbreaking", "attacking"],
</syntaxhighlight>
 
We also define the durability as 2000:
 
<syntaxhighlight lang="json">
durability: 2000,
</syntaxhighlight>
 
== Variant Groups ==
 
So far we have stayed pretty basic, but we can define go more advanced properties as well. Let's add some variants to our wand, and make each of these new wand types replace another tool (shovel, pickaxe, axe).
 
First, we add a new variant group with a set of possible variants. The name of the new group is <code>tooltype</code> and possible values are <code>"shovel"</code>, <code>"pickaxe"</code>, <code>"axe"</code>:
And within the group, we include this bit of code to tell the game to actually create three wand variants:
* <code>item-wand-shovel</code>
* <code>item-wand-pickaxe</code>
* <code>item-wand-axe</code>
 
We do this like so:
<syntaxhighlight lang="json">
variantgroups: [
{ code: "tooltype", states: ["shovel", "pickaxe", "axe" ] },
],
</syntaxhighlight>
 
Every variant will be added after the previous variant to the item name <code>item-myitemname-mygroup-mysecondgroup</code>. You can add as many variants as you want.
 
Now, in order to actually utilize our new variants, we will need to change our <code>miningspeed</code>, and <code>durability</code> to <code>miningspeedByType</code> and <code>durabilityByType</code>, as we want to make these wands have the properties of the tools we intend to replace. Most properties can have <code>...ByType</code> added to the end, and they will utilize the variant system.
 
For the new mining speeds, we change the property name to <code>miningspeedByType</code> and added wild card selectors (*). These wild card selectors are where modders can really use the power of the variant system.
<syntaxhighlight lang="json">
miningspeedByType: {
"*-shovel": {
"soil": 7,
"sand": 7,
"gravel": 4.4
},"*-pickaxe": {
"stone": 7,
"metal": 7
},"*-axe": {
"wood": 6,
"leaves": 4
},
},
</syntaxhighlight>
The wand name <code>*-shovel</code> matches any variant ending in <code>-shovel</code>, and likewise applies for the other variants. Using these selectors, we can target specific item types easily.
 
We can also change the durability for each type individually.
<syntaxhighlight lang="json">
durabilityByType: {
"*-shovel": 4000,
"*-pickaxe": 3000,
"*-axe": 2000,
},
</syntaxhighlight>
 
== Variant Textures ==
 
Using the same method we applied to specify the mining speed for each type, we can also specify a texture for each type.
<syntaxhighlight lang="json">
textureByType: {
"*-shovel": {
base: "item/wand-shovel",
},
"*-pickaxe": {
base: "item/wand-pickaxe",
},
"*-axe": {
base: "item/wand-axe",
},
}
</syntaxhighlight>
 
But we can accomplish the same texture change an easier way:
<syntaxhighlight lang="json">
texture: {
base: "item/wand-{tooltype}",
}
</syntaxhighlight>
 
<code>{tooltype}</code> will be replaced by either shovel, pickaxe or axe. This is another extremely useful part of the variant group system. For example, VS has a lot of different kinds of rocks. Defining all the drops when using our wand could be done by specifying each block drop:
<syntaxhighlight lang="json">
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 }
}],
}
</syntaxhighlight>
But as you can see, using this method would get extremely long (quickly!). Instead, defining all these things can be done using an abbreviated code:
<syntaxhighlight lang="json">
dropsByType: {
"*": [{
"type": "item",
"code": "stone-{rock}",
"quantity": { "avg": 2.5, "var": 0.5 }
}]
}
</syntaxhighlight>
 
== 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: [[File:Wand-overlay-axe.png]] [[File:Wand-overlay-pickaxe.png]] [[File:Wand-overlay-shovel.png]]. All we have to do now is to change the base texture to back to the original wand texture and add an overlay texture.
 
<syntaxhighlight lang="json">
texture: {
base: "item/wand",
overlays: [ "item/wand-overlay-{tooltype}" ],
},
</syntaxhighlight>
 
and this is the result:
 
[[File:2017-02-09 17-30-34.png|700px]]
 
= Mod Download =
 
You can download the mod to test it out yourself:
 
[https://wiki.vintagestory.at/images/e/ec/MyAdvancedWandMod.zip 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 '''[[Modding:Item Json Properties | 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 [[Modding:The Asset System | Asset System]] page.
 
If you haven't check out the '''[[Modding:Basic Block| Basic Block]]''' and '''[[Modding:Basic Entity | Basic Entity]]''' pages to learn how simple JSON items and entities are added to the game, we suggest you start there.
 
However, if you're feeling like making the jump to code mods then you'll want to start by setting up your '''[[Modding: Setting up your Development Environment | Development Environment]]'''.
'''Hint''': Use the client command <code>.tfedit</code> 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.
 
{{Navbox/modding|Vintage Story}}

Revision as of 22:17, 20 July 2020

This tutorial introduces some more advanced properties of the JSON modding system including item variant, and property groups.

Basic Properties

Revisiting our wand from the basic tutorial. Currently, it's only a stick, which is still rather useless Using this tutorial, we will now add mining functionality. How does this work? By adding a property to our wand using miningspeed we can define the mining speed when using the wand. We also need to define how fast the wand will mine each block type. (Use this list of all block materials.)

The number indicates how fast the tool is able to mine a specific block type, with 1 as the default value. time to mine = block resistance / miningspeed. A speed of 2 is twice as fast the default speed of one. So using the code below, we make our wand mine seven times faster than using any default tool.

Our wand looks like this:

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

Although the tool is already working, we should add some kind of durability. Next, we need to define the durability of our wand and what can cause damage to our wand. The property damagedby allows us to define what damages an item. For now we will stick to blockbreaking and attacking.

Using the code below, our wand will take damage when we use it to break a block, or when using our wand as a weapon.

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

We also define the durability as 2000:

	durability: 2000,

Variant Groups

So far we have stayed pretty basic, but we can define go more advanced properties as well. Let's add some variants to our wand, and make each of these new wand types replace another tool (shovel, pickaxe, axe).

First, we add a new variant group with a set of possible variants. The name of the new group is tooltype and possible values are "shovel", "pickaxe", "axe": And within the group, we include this bit of code to tell the game to actually create three wand variants:

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

We do this like so:

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

Every variant will be added after the previous variant 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, as we want to make these wands have the properties of the tools we intend to replace. Most properties can have ...ByType added to the end, and they will utilize the variant system.

For the new mining speeds, we change the property name to miningspeedByType and added wild card selectors (*). These wild card selectors are where modders can really use the power of the variant system.

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

The wand name *-shovel matches any variant ending in -shovel, and likewise applies 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 method we applied to specify 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 texture change an easier way:

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

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

	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, using this method would get extremely long (quickly!). Instead, defining all these things can be done using an abbreviated code:

	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: Wand-overlay-axe.png Wand-overlay-pickaxe.png Wand-overlay-shovel.png. 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:

2017-02-09 17-30-34.png

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 check out the Basic Block and Basic Entity pages to learn how simple JSON items and entities are added to the game, we suggest you start there.

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.

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.