Modding:Basic Item: Difference between revisions

From Vintage Story Wiki
No edit summary
No edit summary
(39 intermediate revisions by 8 users not shown)
Line 1: Line 1:
<languages/>
<translate>
<!--T:1-->
__FORCETOC__
__FORCETOC__
This tutorial should introduce you into the basic of adding an item to the game using JSON files. If you want to add a 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 known to you.
First, if you haven't done it already, please read the tutorial [[Getting Started with Advanced Modding#Domains|Getting Started]]. 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 =
== A Simple Item == <!--T:2-->
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.


So, the first thing we going to need is an idea. What does this game need. Wait i got it ... the game needs an overpowered wand.
== Workspace == <!--T:3-->
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 <code>assets/basicwand/</code>. ''Note'': the namespace does not need to be the same as the name of the mod.


== The Texture ==
<!--T:4-->
All mods that add content must be in the <assets folder> and their own namespace directory. The namespace, for us is <code>basicwand</code>. 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 <code>.edi</code>, you may notice that all the items in the game are prefixed with <code>game:</code>, which is the namespace for all the vanilla content.


This is the texture we gonna use [[File:Wand.png]]. In order to use it we need to place it inside the assets of the [[Vintagestory folder]]. Therefore the path should look like this: <code>assets/textures/items/tool/wand/wand.png</code>.
<!--T:5-->
After getting our workspace ready, we can move on to actually making the wand.


== The Json File ==
== Adding a Texture == <!--T:6-->
Let's start with the texture we will use: [[File:Wand.png]]


Now we need to let the game know if its existence. We can accomplish that by creating a json file and placing it inside <code>assets/itemtypes/tool/wand.json</code>.
<!--T:7-->
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 <code>textures/item/</code>. Remember, this is in our namespaced folder so the full path is <code>assets/basicwand/textures/item/</code>.


The content of this json file should look as it follows:
== Creating the Item File == <!--T:8-->
To create the actual wand item, we need to create a JSON file inside the <code>itemtypes/</code> folder. In this example we name it <code>wand.json</code>. This file contains the basic properties of our item.
 
<!--T:9-->
The most basic item requires two things:
* '''code''': A unique identifier for the item.
* '''texture''': What textures to apply to the item.
 
<!--T:10-->
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
 
<!--T:11-->
For now, our values for each property are simple:
* <code>code</code>: <code>wand</code>
* <code>texture</code>: <code>item/wand</code> (Note that the specified path does '''not''' include <code>texture</code> in the path.)
* <code>creativeinventory</code>: <code>general</code>
 
<!--T:12-->
''Finally'' the values in the actual JSON look like this:
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
{
{
code: "wand",
  code: "wand",
creativeinventory: { "default": ["*"] },
  creativeinventory: {
texture: { base: "tool/wand/wand" }
    "general": ["*"]
  },
  texture: {
    base: "item/wand"
  }
}
}
</syntaxhighlight>
</syntaxhighlight>


* '''code''': A unique identifier for your item. If you plan a larger mod, it is suggested to prefix your modname to the identifier.
<!--T:13-->
* '''creativeinventory''': The creative inventory tabs the itemshould be shown in (currently only 1 tab available)
You might have noticed that the <code>creativeinventory</code> and <code>texture</code> properties aren't as simple as the <code>code</code> values. The reason for the differences in <code>texture</code> and <code>creativeinventory</code> isn't something we'll cover in this tutorial, but is discussed in advanced tutorials.
* '''textures''': What textures to apply.
 
== Testing ==
 
Now we got everything ready to run our first test. You should be able to find the added item in the creative inventory.
 
[[File:2017-01-30 13-59-27.png|700px]]


== Naming the Item ==
== Naming the Item == <!--T:14-->
Now we've got almost everything ready, except for a proper name. To do this we create another JSON file: <code>lang/en.json</code>. The game uses this file to look up the name of the item. The language files have a very simple syntax: <code>"item-code": "Item Name"</code>.


To give the item a proper name, you currently have to manually add a line like this in the file <code>assets/lang/en.json</code>
<!--T:15-->
For our wand, this means our file should look something like this:
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
"item-wand": "Wand",
{
  "item-wand": "Wand"
}
</syntaxhighlight>
</syntaxhighlight>


A better way of handling naming and translation will be added once its desired.
== Conclusion == <!--T:16-->
 
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.
== 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:
 
[[File:MyWandMod.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 =
 
== Mining Properties ==
 
== Variants ==


== Texture Overlays ==
<!--T:17-->
{{Navbox/modding|Vintage Story}}
</translate>

Revision as of 11:32, 21 July 2020

Other languages:

First, if you haven't done it already, please read the tutorial Getting Started. 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.

Workspace

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: Wand.png

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 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 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:

  • 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 have noticed that the creativeinventory and texture properties aren't as simple as the code values. The reason for the differences in texture and 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:

{
  "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 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.

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.