First, if you haven't done it already, please read about Asset System. This tutorial should introduce you to the basics of using JSON files to add an item to the game. If you want to add an item with functionality, you should check out the tutorial for Advanced Items. That page contains a full list of all properties that can be defined inside the json file Item Json Properties. Adding a block to the game is similar to adding an item, so if you have already learned how to do that, most of the following steps should be familiar.
A Simple Item
The first thing we need is an idea. What does this game need? Wait! I got it ... the game needs a cool wand. Let's call this mod BasicItem, because this is the Basic Item tutorial, and we're making a wand.
First create a folder to put the mod files in, which will become your workspace where we will create the mod itself. We will have to add several folders inside the main folder to keep our files organized. The Vintage Story mod loader requires some files to be placed in specific folders so the loader can find what it needs to load. For this mod, everything will go in our namespaced assets folder. For us, this folder is
assets/basicwand/. Note: the namespace does not need to be the same as the name of the mod.
All mods that add content must be in the <assets folder> and their own namespace directory. The namespace, for us is
basicwand. This convention prevents multiple mods that use the same item code from causing issues. For example, if you enable extended debug info with the command
.edi, you may notice that all the items in the game are prefixed with
game:, which is the namespace for all the vanilla content.
After getting our workspace ready, we can move on to actually making the wand.
Adding a Texture
Let's start with the texture we will use:
(To create your own textures, you can use programs like PaintDotNet(free), Piskel(free), GIMP(free), or Aseprite(free open source, or pay for precompiled))
In order to use the texture, we need to put it in the right place (so the mod loader can find it). To do this we will create the folder
textures/item/. Remember, this is in our namespaced folder so the full path is
Creating the Item File
To create the actual wand item, we need to create a JSON file inside the
itemtypes/ folder. In this example we name it
wand.json. This file contains the basic properties of our item. (we recommend to use an editor with syntax highlighting, such as Notepad++ or Sublime Text. If you are going to have many json files or some C#, then Visual Studio Code is also a good pick).
The most basic item requires two things:
- code: A unique identifier for the item.
- texture: What textures to apply to the item.
We also need to include this property to allow us access to our item in the creative inventory:
- creativeinventory: defines the creative inventory tabs where the item should be shown
For now, our values for each property are simple:
item/wand(Note that the specified path does not include
texturein the path.)
Finally the values in the actual JSON look like this:
You might have noticed that the
textures properties aren't as simple as the
code values. The reason for the differences in
creativeinventory isn't something we'll cover in this tutorial, but is discussed in advanced tutorials.
Naming the Item
Now we've got almost everything ready, except for a proper name. To do this we create another JSON file:
lang/en.json. The game uses this file to look up the name of the item. The language files have a very simple syntax:
"item-code": "Item Name".
For our wand, this means our file should look something like this:
Together, the item and language files are technically enough to be a complete mod. But they don't add the cool wand I said we would make at the beginning of this tutorial. In order to add more properties, we have to head over to the Modding:Advanced Item tutorial where I explain how we can do way cooler things with items than just create a measly stick.
|Green Items require C# coding
Advanced Blocks | Advanced Items | Block and Item Interactions | Block Behavior | Block Entity | Particle Effects | World Access | Inventory Handling | Commands | GUIs | Network API | Monkey patching (Harmony)
|Workflows & Infrastructure
List of server commands | List of client commands | Client startup parameters | Server startup parameters | Creative Starter Guide | ServerBlockTicking | Bot System | WorldEdit | Cinematic Camera | Adjustable FPS Video Recording