Modding:Content Tutorial Simple Recipe

This page was last verified for Vintage Story version 1.19.4.

Introduction

Objective

In this tutorial, you will create two new grid recipes for our previously made item and block! Recipes are a great way of allowing players to access your new content.

Assets

Before starting, it is recommended you download the workspace and assets for this tutorial. The completed files can also be found here.

This tutorial starts with the following assets:

• Mod Setup & Folder Structure
• Premade Blocktype file
• Premade Itemtype file
• Premade Lang file
• Texture & Shape Files
• Empty Grid Recipe Files

Prerequisites

This tutorial will assume you understand the following topics:

• Setting up a content mod and using an IDE.
• The functions of shape, texture and lang files.

Although not necessary, it is recommended to have completed the following tutorials:

• 2. Simple Item
  • The 'Simple Wand' item is included in the tutorial setup.
• 3. Simple Block
  • The 'Simple Gold Block' is included in the tutorial setup.

Navigating Assets

Browse the downloaded workspace. You should have an understanding of most of the files that currently exist, however there are two new files:

• assets/simplerecipe/recipes/grid/simplewandrecipe.json - An empty json file. This will be used to create a recipe for the 'Simple Wand' item.
• assets/simplerecipe/recipes/grid/simpleblockrecipe.json - An empty json file. This will be used to create a recipe for the 'Simple Gold Block'.

Recipe File Structure

As you may have noticed, recipes are all stored within the 'recipes' folder - However there is a list of subfolders that determine the type of recipe.

This tutorial uses the 'grid' folder, which tells the game that any files stored within that folder are recipes to be made in the grid.

The valid recipe types (and therefore folders) are:

• alloy - Allows creation of different alloyed metals in a crucible.
• barrel - Allows creation of objects within a barrel.
• clayforming - Allows creation of clay objects using the clayforming system.
• cooking - Allows creation of food in a cooking pot.
• grid - Allows creation of objects by using the crafting grid.
• knapping - Allows creation of stone objects using the knapping system.
• smithing - Allows creation of metal objects on an anvil.

Creating the Item Recipe

Unlike when creating items and blocks, recipes can be somewhat difficult to test before they are complete, as all the information is required before the recipe will be created.

When creating recipes, it is a good idea to visualize what you are creating. This is the recipe you will be creating for this section:

One clear quartz, on top of two sticks. It is, after all, a magic wand.

Recipe File

Open the 'simplewandrecipe.json' file inside 'recipes/grid'.

To create a new grid recipe, the game needs the following information:

• Ingredients - This defines what objects are used in the grid to create the output.
• Pattern - This defines how the ingredients are arranged in the grid, as well as the width and height of the recipe.
• Output - This defines what object will be given to the player when the recipe is complete.

You will notice that this information can be listed in any order in the json file.

Recipe Pattern

To begin, you need to define the recipe pattern inside your json file.

{
	"ingredientPattern": "Q,S,S",
	"width": 1,
	"height": 3,

These three properties will define the pattern and shape of our recipe.

The 'ingredientPattern' property defines a list of letters. Each unique letter defines a new ingredient. Note that although this uses Q for quartz and S for stick, you can pick whatever letter you want. Do not worry about the format of this property right now, as it will be discussed in the next recipe.

The 'width' property defines how many columns the recipe uses.

The 'height' property defines how many rows the recipe uses.

Recipe Ingredients

For your recipe to function correctly, each unique letter in the previous 'ingredientPattern' property needs to be registed as an 'ingredient'.

Add the following code to your file, below the height property.

"ingredients": {
		"Q": {
			"type": "item",
			"code": "game:clearquartz"
		},
		"S": {
			"type": "item",
			"code": "game:stick"
		}
	},

The 'ingredients' property is a little different to any properties used before in the tutorials, because it is a dictionary data type. In this case, it is simply a way of mapping each character in the pattern to an in-game object. There are two unique characters in the pattern, Q and S, so we need to add both of these to the list. When adding an ingredient, you need to include its type and code. The type is simple - either "item" or "block" depending on which one it is. The code is the item's unique identifier. A future tutorial will discuss multiple ways of finding an objects code, but for now we can use game:clearquartz and game:stick.

When all the unique characters have entires, you can move on.

Recipe Output

The recipe output determines what object this recipe will make. Add the final section of code to your file, below the 'ingredients' section.

"output": {
		"type": "item",
		"code": "simplewand"
	}
}

You may notice that the 'output' property is defined very similarly to an ingredient, using identical 'type' and 'code' properties inside of it. In this instance, to create the simplewand item, we fill in using the item type and simplewand code.

Finalized Recipe

Your first recipe should now be complete! You should be able to test it by going on the "simplewand" page in the in-game handbook, or trying to create your item in survival mode.

Here is the full recipe for comparison:

simplewandrecipe.json

{ "ingredientPattern": "Q,S,S", "width": 1, "height": 3, "ingredients": { "Q": { "type": "item", "code": "game:clearquartz" }, "S": { "type": "item", "code": "game:stick" } }, "output": { "type": "item", "code": "simplewand" } }

Creating the Block Recipe

This is the recipe you will be creating for this section:

The recipe should be able to use any hammer, on top of 6 gold ingots to make the gold brick block.

Recipe File

Open the 'simpleblockrecipe.json' file inside 'recipes/grid'.

Same as before, this grid recipe needs to define its ingredients, pattern, and output.

Recipe Pattern

Firstly, define the recipe pattern inside your json file.

{
	"ingredientPattern": "_H_,GGG,GGG",
	"width": 3,
	"height": 3,

The properties here are the same as the previous recipe, however you are now using the grid to its maximum capacity.

Understanding the IngredientPattern Property

The 'ingredientPattern' property is a lot easier to explain in this recipe. Each letter in the pattern determines a unique ingredient, however there are a couple of unique characters too. Each section, determined by commas, represent a row in the crafting grid. In the pattern above, the rows are: "_H_", "GGG", "GGG". Each character then represents its own space in the crafting grid. An underscore ( _ ) tells the game that this is a blank space and unused in this recipe.

Look back on the previous recipe, and make sure you understand the ingredient pattern there. It is a 1 by 3 recipe, where each row is seperated by a comma.

Recipe Ingredients

This recipe uses two ingredients - A hammer and a gold block.

Add the following code to your file, below the height property.

"ingredients": {
		"H": {
			"type": "item",
			"code": "game:hammer-*",
			"isTool": true
		},
		"G": {
			"type": "item",
			"code": "game:ingot-gold"
		}
	},

The ingredients here follow the exact same format as the previous recipe, however there is a new concept to introduce.

Asset Location Wildcards

So far in the tutorials, you will have used a lot of asset locations without much explanation about how they work. This is a very substantial topic, and will be explained more in a future tutorial. For now, however, it is important to understand the use of wildcards within a code property.

In Vintage Story, there can exist variants of each item, block, or entity. These variants are used to create a large amount of new objects that all share very similar properties, all within a single file. One such example of an item with variants is the hammer item. There exists a total of 9 hammers with near-identical functionality, however each one uses a different 'metal' variant to determine its material. Every object in the game has to have a unique code, so variants are appended to the end of the item code. This means that the full codes for all 9 hammers are:

• hammer-copper
• hammer-tinbronze
• hammer-bismuthbronze
• hammer-blackbronze
• hammer-gold
• hammer-silver
• hammer-iron
• hammer-meteoriciron
• hammer-steel

When it comes to creating recipes, you do not want to have to create 9 seperate recipes where each one accepts a different hammer, so you can use a wildcard. A wildcard allows a modder to group all these objects together using an asterisk ( * ) in its code property. By using "hammer-*", the game allows any object who's code begins with "hammer-" to be valid for this recipe. Note that you should still include the hyphen in the code, as using "hammer*" will result in being able to use any hammer and also any hammerhead items.

You will learn how to create your own object variants in future intermediate tutorials.

IsTool Property

There are a number of extra properties that can be included within recipes to make them slightly more complex. One such property is the 'isTool' property. Without this property, the hammer will disappear when the block is created. By marking the hammer as a tool, the recipe simple uses a single durability point, but the hammer remains.

Recipe Output

The final section of our recipe is the output. Add the final section of code to your file, below the 'ingredients' section.

"output": {
		"type": "block",
		"code": "simplegoldblock"
	}
}

As before, we just set this to our block's code. Note that the type has been changed to block in this instance.

Finalized Recipe

Your second recipe should now be complete! You should be able to test it by going on the "simplegoldblock" page in the in-game handbook, or trying to create your item in survival mode.

Here is the full recipe for comparison:

simpleblockrecipe.json

{ "ingredientPattern": "_H_,GGG,GGG", "width": 3, "height": 3, "ingredients": { "H": { "type": "item", "code": "game:hammer-*", "isTool": true }, "G": { "type": "item", "code": "game:ingot-gold" } }, "output": { "type": "block", "code": "simplegoldblock" } }

Conclusion

Congratulations, you have now created two recipes for your new item and block! This tutorial should have given you the ability to make simple recipes, as well as a brief understand of variants and wildcards.

Next Steps...

If you want to test your knowledge, consider doing the tasks under the Going Further section below.

This is the final tutorial in the 'Basic Tutorial' section. Take a look at starting the intermediate content mod tutorials, where you will learn more about variants and error-checking, as well as developing complex blocks, items, entities, and many more.

Going Further

Want to make some additional changes to this mod? Try and achieve the following things!

Gold ingots are too expensive... change the block recipe to use gold bits instead. Note that the code for gold bits is "game:metalbit-gold".

To achieve this...

In 'simpleblockrecipe.json', modify "game:ingot-gold" to "game:metalbit-gold".

Create another grid recipe that uses a simple wand and a single charcoal to make a diamond. The codes are "simplewand", "game:charcoal", and "game:gem-diamond-rough" respectively. Note that the wand should be consumed on use - Using the "onTool" property will cause your recipe to not work as the simple wand is not defined as a tool.

To achieve this...

Create a new charcoaltodiamond.json recipe inside recipes/grid. Your file may look similar to this: { "ingredientPattern": "W,C", "width": 1, "height": 2, "ingredients": { "W": { "type": "item", "code": "simplewand" }, "C": { "type": "item", "code": "game:charcoal" } }, "output": { "type": "item", "code": "game:gem-diamond-rough" } }

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.