Modding:Content Tutorial Simple Item: Difference between revisions

<languages/>

<translate>

{{GameVersion|1.19.4}}

__FORCETOC__

In this tutorial, you will create an item - A simple wand! Although this item will have no real functionality, it will demonstrate how to create assets in json, as well as how to use shapes, textures, and lang files.

Before starting, it is recommended you [https://github.com/Nateonus/vsmodexamples/releases/tag/SimpleItemTutorial 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

* Empty item file

* Item texture file

This tutorial will assume you understand the following topics:

* [[Modding:Developing a Content Mod|Setting up a content mod and using an IDE.]]

* [[Modding:Content Tutorial Basics|The functions of shape, texture and lang files.]]

Using the downloaded workspace, have a look at the files that currently exist.

* ''modinfo.json'' - The mod info file, which registers your mod with the ID 'simpleitem'.

* ''modicon.png'' - The mod icon file, which will be displayed on the mod manager menu.

* ''assets/simpleitem/textures/item/simplewand.png'' - A texture file for the wand.

In order to create an item, a file must be created inside the ''itemtypes'' folder. If using the provided workspace, there already exists an item file called simplewand. Open this file in your IDE.

The most important property when creating an asset is the code, also known as an ID. To begin, copy and paste this into the opened simplewand file.<syntaxhighlight lang="json">

{

</syntaxhighlight>Remember that json files are a set of keys to values. The key, in this example, is "''code''", and the value is "''simplewand''". Note that the item file starts and ends in curly brackets ('''{ }'''), meaning it is a single object.

Now that your itemtype file has a code, it will now be created and registered in game. However, you need a way of accessing the item. To do this, add a new property:<syntaxhighlight lang="json">

{

</syntaxhighlight>Notice that each property is seperated using a comma. The new property, ''"creativeinventory"'' tells the game what creative tab this item will be placed in. The syntax of this particular property is a little bit more complex, but don't worry about it for now. All this does is add the item into the "general" creative tab.

If you were to launch Vintage Story and enable your mod, you will see the item in the creative menu!  

[[File:Content Tutorial Simple Item No Texture Or Shape.png|frameless]]

Ideally, you do not want your item to be a large black box.

The shape and texture files exist in the assets, so why isn't the item being [[wikipedia:Software_rendering|rendered]] correctly?

If an asset wishes to use a certain shape or texture, then it must specify this within its json file. Replace your current itemtype json with the following:<syntaxhighlight lang="json">

{

</syntaxhighlight>Two new properties have been added - ''texture'' and ''shape.'' Remember that the shape is a 3D representation of our item, and the texture is a 2D image that is mapped onto our shape, and we should include both to ensure our item is rendered correctly. It may seem confusing that both the texture and shape values appear to be the same, but the game looks for these in different places. To find shapes, the game automatically looks in the mod's ''shapes'' folder, whereas for textures it looks in the mod's ''textures'' folder.  

If you run the game again, you'll notice some changes.

[[File:SimpleItemTutorialWandNoPositioning.png|frameless]]

Now, that certainly looks closer to what we wanted, but the position of the item is wrong.

Your item is nearly complete, however the 3d object does not have the correct transformation. A transformation, in 3d graphics, refers to an object's position, rotation, and scale.  

To allow modders to easily position items and blocks correctly, Vintage Story utilises a transform editor that can be accessed in game. When in game, hold the item you wish to position and use the command ''<nowiki/>'.tfedit' to open the transform editor.''

The transform editor allows you to select where the object is rendered, and adjust its transformation directly. The best part about this is the generated json code at the bottom of this editor, which you can copy and paste straight into your item file.

It is recommend to learn how to use the transform editor, since it is an invaluable tool for transforming items and blocks.

Changes made within the transform editor do not modify any files, and will therefore not save. For each item you create, it is recommended to set positions for ground, main hand, and gui. These use the properties ''groundTransform'', ''tpHandTransform,'' and ''guiTransform'' respectively.

To transform your wand correctly, add the following properties. Don't forget to add a comma after the final curly bracket on the previous shape element.<syntaxhighlight lang="json">

"guiTransform": {

</syntaxhighlight>To see if the changes are correct, you can simply reload the world. Hopefully, if everything worked correctly, you should find that your wand now fits better in the player's hand, as well as appearing in the gui more appropriately.

[[File:SimpleItemContentTutorialItemPositionButNoName.png|frameless]]

There is one final change before the item is complete.

Currently, every instance of the item is called ''<nowiki/>'simpleitem:item-simplewand'.'' To fix this, you need to add an entry to the lang file. Open up the provided ''en.json'' language file, found in ''assets/simpleitem/lang.''  

This sample lang file contains two premade translations, to show you how the file works. <syntaxhighlight lang="json">

{

</syntaxhighlight>Both sample translations are not used, and can be deleted if you want to.

To speed up testing, if you still have Vintage Story open, you can use the command '<nowiki/>''.reload lang''' to reload all lang files. Hovering over your item should show that our lang file has taken effect.

[[File:SimpleItemTutorialFinalImageWorking.png|frameless]]

Congratulations, you have now created your first item! This tutorial should have given you some understanding of items, textures, shapes and language files, as well as the basics of modding for Vintage Story!  

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

When you're ready, try out the next tutorial: [[Modding:Content Tutorial Simple Block|Simple Block]]. This will show you how to create a new block with a texture.

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

Change the color of the wand

{| class="wikitable mw-collapsible mw-collapsed"

|}

{{Navbox/contentmodding}}

</translate>