Modding:Basic Block

This tutorial should introduce you into the basic of adding a block to the game using JSON files. Down below you can find a complete list of all existing properties. If your block requires more than just a JSON file there is a tutorial for Advanced Blocks. There is a full list of all properties which can be defined inside the json file Block Json Properties.

A Simple Block

To get started let's start with something simple. In our example we will add an ordinary gold block (will be for decorative use only) to the game.

The Texture

First of all we need a texture. We will add a gold block to the game using this texture: .

Now we need to copy the texture to the game assets. Therefore navigate to the Vintagestory folder and place it in assets\textures\blocks\metal\. Eventually rename it to mygoldtexture.png

The JSON file

Now we need a json file which will determine the properties this block has. For now we keep it simple and only cover simple properties, but there are a lot of other things you can do with. Here is a full list of all Block Json Properties. So create a new json file in your editor (we recommend to use an editor with syntax highlighting, such as Notepad++ or Visual Studio) named mygoldblock.json.

{
	code: "mygoldblock",
	creativeinventory: { "default": ["*"] },
	shape: { base: "basic/cube" },
	blockmaterial: "Stone",
	drawtype: "cube",
	textures: {
		all: { base: "metal/mygoldtexture" }
	},
	resistance: 3.5,
	sounds: {
		"place": "block/anvil",
		"walk": "walk/stone"
	}
}

Short explanation of each line:

• code: A unique identifier for your block. If you plan a larger mod, it is suggested to prefix your modname to the identifier.
• creativeinventory: The creative inventory tabs the block should be shown in (currently only 1 tab available)
• shape: Which model the block should use
• drawtype: Determines the drawing system, use 'cube' for normal full cubes or 'json' for custom created shapes.
• textures: What textures to apply. For simple blocks you can define one single texture for 'all' faces or define one for every facing ('north', 'east', 'west', 'south', 'up', 'down')
• resistance: How many seonds of real time it takes to break the block without tools
• sounds: The sounds to be played when placing/breaking or walking on the block

Now navigate to the Vintagestory folder again and place the json file for example in assets\assets\blocktypes\metal\. The sub-folders in blocktypes are only for organisation purposes, the engine does not handle them in any special way.

Testing

Finally we got everything ready to run our first test. Therefore start Vintagestory as usual, you should be able to find your block inside the creative inventory.

.

Naming the Block

To give the block a proper name, you currently have to manually add a line like this in the file assets/lang/en.json

	"block-mygoldblock": "Block of Gold",

A better way of handling naming and translation will be added once its desired.

Distributing a mod

The current modding system does not yet support mod-specific asset folders. The current way of doing it is to create a zip file a user can extract into his game folder that will extract the files into the right folders. Example:

MyGoldBlockMod.zip

A proper mod manager will be added to the game once there is a few serious mods out there (go bug tyron about it ;-) ).

Advanced Properties

Now we do some more advanced stuff with our lovely gold block. We will add random textures, different variants and custom shapes. So let's get started.

Random Textures

So first of all we need some more textures. I have created some variants of the gold block . To keep the name of the textures simple I added a number to each texture name (mygoldtexture.png,mygoldtexture1.png,mygoldtexture2.png,mygoldtexture3.png)

Now we need to add those new textures to the json file.

	textures: {
		all: { 
			base: "metal/mygoldtexture",
			alternates: [{base: "metal/mygoldtexture1" }, {base: "metal/mygoldtexture2" }, {base: "metal/mygoldtexture3" }],
		},
	},

Eventually save it and run Vintagestory again. Now you should see a result like this:

Of course you can add more texture if you would like to.

Variants

Gold is the best, but iron is awesome too ... so what shall will do? Let's add another variant of this block, because we all love iron.

You could duplicate the blocktype file and rename silver to gold in all the places, or you can simply add another variant to the existing blocktype.

Variantgroup: Type

So first of all we need some new textures again:

Now we need to change a few things in our json file. We can add all kinds of different groups, but for now we keep it simple. We are adding group called type, with the states gold and iron. You can use any group code you want.

	variantgroups: [
		{ code: "type", states: ["gold", "iron"] }
	],

The next thing we need to do is set textures by type. So we remove our texture property and replace it with a new property texturesbytype, which will allow us to set different textures for each type.

	texturesbytype: {
		"*-gold": {
			all: { 
				base: "metal/mygoldtexture",
				alternates: [{base: "metal/mygoldtexture1" }, {base: "metal/mygoldtexture2" }, {base: "metal/mygoldtexture3" }],
			},
		},
		"*-iron": {
			all: { 
				base: "metal/myirontexture",
				alternates: [{base: "metal/myirontexture1" }, {base: "metal/myirontexture2" }, {base: "metal/myirontexture3" }],
			},
		}
	},

Every group will be added after each other to the blocks name myblockname-mygroup-mysecondgroup. In our example the block name is ignorable so its replaced by *.

You can also use a more compact definition. Due to way we named our textures we can use the placeholder {type} to determine the texture name, so instead of taken care of every case we can do it like this:

	textures: {
		all: { 
			base: "metal/my{type}texture",
			alternates: [{base: "metal/my{type}texture1" }, {base: "metal/my{type}texture2" }, {base: "metal/my{type}texture3" }],
		},
	},

Eventually your file should look like this:

{
	code: "myshinyblock",
	creativeinventory: { "default": ["*"] },
	variantgroups: [
		{ code: "type", states: ["gold", "iron"] }
	],
	shape: { base: "basic/cube" },
	blockmaterial: "Stone",
	drawtype: "cube",
	textures: {
		all: { 
			base: "metal/my{type}texture",
			alternates: [{base: "metal/my{type}texture1" }, {base: "metal/my{type}texture2" }, {base: "metal/my{type}texture3" }],
		},
	},
	resistance: 3.5,
	sounds: {
		"place": "block/anvil",
		"walk": "walk/stone"
	}
}

Variantgroup: Condition

Let's at another group to our block, which will determine the condition of this block. There will be two states good and used. We can add this group by adding another property inside variantgroups[].

	variantgroups: [
		{ code: "type", states: ["gold", "iron"] },
		{ code: "condition", states: ["good", "used"]}
	],

To finish implementing this second group we need to take care of every case. We want the good blocks to only use the base texture and the used blocks to also use their random textures:

	texturesbytype: {
		"*-good": {
			all: { 
				base: "metal/my{type}texture",
			},
		},
		"*-used": {
			all: { 
				base: "metal/my{type}texture",
				alternates: [{base: "metal/my{type}texture1" }, {base: "metal/my{type}texture2" }, {base: "metal/my{type}texture3" }],
			},
		},
	},

The blocks in a good condition or on the left side, while the used ones are on the right:

Custom Shapes

In order to use a custom shape we need to create one first. Therefore we can use the VS Model Creator.

Once you have created your own shape you need to export it as a json file and move it to assets/shapes/blocks/. In our example we will use this model Myshinymodel.json and move it to assets/shapes/blocks/metal/myshinymodel.json. Now we need to specify the model inside our block type json file (assets/blocktypes/metal/myshinyblock.json).

Therefore we will change the drawtype from cube to json:

	drawtype: "json",

and the shape to metal/myshinymodel

	shape: { base: "metal/myshinymodel" },

Although this would be enough theoretically, we also should determine this block as being non-solid, to prevent graphical glitches.

	sidesolid: {
		all: "false"
	},
	sideopaque: {
		all: "false"
	},

So let's run the game. This is how it should look like:

Variants of Custom Shapes

I created another model for the blocks in good condition (myshinymodel1.json), because they should look more awesome, than the ones in used conditions. Therefore we need to copy the json file to assets/shapes/block/metal/ as well.

In order to specify the shape by type we need to remove the property shape and replace it with shapebytype:

	shapebytype: {
		"*-good": {
			base: "metal/myshinymodel1",
		},
		"*-used": {
			base: "metal/myshinymodel",
		},
	},

MyShinyBlockMod

There are a lot of more things you can do with the system. It is always recommend to take a look at the files created by Vintage Story itself to understand how the system is working. I hope I could introduce you into the basic of adding blocks the game. Advanced Blocks will teach you how to add more functionality to your block.