Modding:Basic Item

From Vintage Story Wiki
Revision as of 15:57, 26 May 2020 by VeryGoodDog (talk | contribs) (rename some sections and call it a "cool" wand (screenshots needed))

Please read the tutorial Getting Started first, if you haven't done it already. This tutorial should introduce you into the basic of adding an item to the game using JSON files. If you want to add an item with functionality you should check out the tutorial for Advanced Items. There is a full list of all properties which can be defined inside the json file Item Json Properties. Adding a block to the game is rather similar, so if you have done that already most of the following steps should be familiar to you.

A Simple Item

So, the first thing we going to need is an idea. What does this game need? Wait! I got it ... the game needs a cool wand. Let's call this mod BasicWand, because this is the Basic Item tutorial, and we're making a wand.

Workspace

First of all, we need a folder to the mod's files in. Inside this workspace we will create the mod itself. In side of this we will have to add several folders to keep organized. The Vintage Story mod loader requires some files to be 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 is assets/basicwand/.

All mods that add content must be in the assets folder and their own namespace directory. The namespace, for us is basicwand, prevents multiple mods with 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 making sure our workspace is ready we can move on to actually making the wand.

Adding a Texture

Let's start with the texture we will use: Wand.png

In order to use the texture we need to put it at the right place. To do this we will create the folder textures/item/. Remember, this is in our namespaced folder so the full path is assets/basicwand/textures/item/.

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.

The most basic item requires two things:

  • code: A unique identifier for the item.
  • texture: What textures to apply.

We also need to include this property so we can see our item in the creative inventory:

  • creativeinventory: The creative inventory tabs the item should be shown in.

For now, our values for each property are pretty simple:

  • code: wand
  • texture: item/wand (Note that the specified path does not include texture in the path.)
  • creativeinventory: general

Finally the values in the actual JSON look like this:

{
  code: "wand",
  creativeinventory: {
    "general": ["*"]
  },
  texture: {
    base: "item/wand"
  }
}

You might've noticed that the creativeinventory and texture properties aren't as simple as the code values. We will see why texture is like what it is. The reason why creativeinventory is like that isn't something we'll cover in this tutorial.

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:

{
  "item-wand": "Wand"
}

Conclusion

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 get to that 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 a measly stick.