Modding:Tutorial Template: Difference between revisions

From Vintage Story Wiki
(Creating tutorial template page for editing.)
 
(Modding Tutorial Template Page)
Line 2: Line 2:
<translate>
<translate>
<!--T:1-->
<!--T:1-->
{{GameVersion|1.19}}
{{GameVersion|1.19.4}}
__FORCETOC__
__FORCETOC__
First, if you haven't done it already, please read about {{ll|Modding:Asset System|nsp=1}}. 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 == <!--T:2-->
This page is a template for modding tutorials. To enhance readability and make modding a smoother experience, each tutorial should use the same or similar headings based on this page. Copy and paste this page's source in order to clone it.
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 == <!--T:3-->
== Introduction ==
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.


<!--T:4-->
=== Objective ===
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.
In this tutorial, you will '''(Add objective. Tutorials should only achieve one topic at a time, and not be too complex. If you have multiple complexities, split these into multiple tutorials.)'''


<!--T:5-->
=== Assets ===
After getting our workspace ready, we can move on to actually making the wand.
'''(Add Links)'''


== Adding a Texture == <!--T:6-->
Before starting, it is recommended you download the workspace and assets for this tutorial.  
Let's start with the texture we will use: [[File:Wand.png]] <br>
(To create your own textures, you can use programs like [https://www.dotpdn.com/downloads/pdn.html/ PaintDotNet(free)], [https://www.piskelapp.com/ Piskel(free)], [https://www.gimp.org/ GIMP(free)], or [https://github.com/aseprite/aseprite/ Aseprite(free open source, or pay for precompiled)])


<!--T:7-->
This tutorial starts with the following assets: '''(Edit as needed.)'''
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>.


== Creating the Item File == <!--T:8-->
* Mod Setup & Folder Structure
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. (we recommend to use an editor with syntax highlighting, such as [https://notepad-plus-plus.org/ Notepad++] or [https://www.sublimetext.com/ Sublime Text]. If you are going to have many json files or some C#, then [https://code.visualstudio.com/ Visual Studio Code] is also a good pick).
* Empty item file
* Template lang file
* Item shape file
* Item texture file


<!--T:9-->
The finished tutorial files can be found here.  
The most basic item requires two things:
* '''code''': A unique identifier for the item.
* '''texture''': What textures to apply to the item.


<!--T:10-->
=== Prerequisites ===
We also need to include this property to allow us access to our item in the creative inventory:
'''(Add prerequisite knowledge and links if appropriate.)'''
* '''creativeinventory''': defines the creative inventory tabs where the item should be shown


<!--T:11-->
This tutorial will assume you understand the following topics:
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-->
== Adding an Item ==
''Finally'' the values in the actual JSON look like this:
'''(The above heading is counted as a 'step'. I recommend following a method of 'do', 'analyse', 'experiment' for each step to improve modder's knowledge and understanding.)'''
<syntaxhighlight lang="json">
{
  code: "wand",
  creativeinventory: {
    "general": ["*"]
  },
  texture: {
    base: "item/wand"
  }
}
</syntaxhighlight>


<!--T:13-->
=== Creating our Item ===
You might have noticed that the <code>creativeinventory</code> and <code>textures</code> properties aren't as simple as the <code>code</code> values. The reason for the differences in <code>textures</code> and <code>creativeinventory</code> isn't something we'll cover in this tutorial, but is discussed in advanced tutorials.


== Naming the Item == <!--T:14-->
=== Testing our Item ===
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>.


<!--T:15-->
=== Try it out... ===
For our wand, this means our file should look something like this:
<syntaxhighlight lang="json">
{
  "item-wand": "Wand"
}
</syntaxhighlight>


== Conclusion == <!--T:16-->
== Conclusion ==
Congratulations, you have now '''(created your first item...)'''! This tutorial should have given you some understanding of '''(blah blah blah)'''.
 
=== Next Steps... ===
Try out the next tutorial, '''(link).''' This will show you how to create a '''(...)'''! <!--T:16-->


{{Navbox/contentmodding}}
{{Navbox/contentmodding}}
</translate>
</translate>

Revision as of 14:56, 21 March 2024

Other languages:
  • English

This page was last verified for Vintage Story version 1.19.4.


This page is a template for modding tutorials. To enhance readability and make modding a smoother experience, each tutorial should use the same or similar headings based on this page. Copy and paste this page's source in order to clone it.

Introduction

Objective

In this tutorial, you will (Add objective. Tutorials should only achieve one topic at a time, and not be too complex. If you have multiple complexities, split these into multiple tutorials.)

Assets

(Add Links)

Before starting, it is recommended you download the workspace and assets for this tutorial.

This tutorial starts with the following assets: (Edit as needed.)

  • Mod Setup & Folder Structure
  • Empty item file
  • Template lang file
  • Item shape file
  • Item texture file

The finished tutorial files can be found here.

Prerequisites

(Add prerequisite knowledge and links if appropriate.)

This tutorial will assume you understand the following topics:

Adding an Item

(The above heading is counted as a 'step'. I recommend following a method of 'do', 'analyse', 'experiment' for each step to improve modder's knowledge and understanding.)

Creating our Item

Testing our Item

Try it out...

Conclusion

Congratulations, you have now (created your first item...)! This tutorial should have given you some understanding of (blah blah blah).

Next Steps...

Try out the next tutorial, (link). This will show you how to create a (...)!


Content Modding
Basics Content Mods • Developing a Content Mod • Packaging & Release
Tutorials
Concepts Modding Concepts • Modinfo • Variants • Domains • Patching • Remapping • World Properties
Moddable Assets
Uncategorized
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.

Modding
Modding Introduction Getting Started • Theme Pack
Content Modding Content Mods • Developing a Content Mod • Basic Tutorials • Intermediate Tutorials • Advanced Tutorials • Content Mod Concepts
Code Modding Code Mods • Setting up your Development Environment
Property Overview Item • Entity • Entity Behaviors • Block • Block Behaviors • Block Classes • Block Entities • Block Entity Behaviors • Collectible Behaviors • World properties
Workflows & Infrastructure Modding Efficiency Tips • Mod-engine compatibility • Mod Extensibility • VS Engine
Additional Resources Community Resources • Modding API Updates • Programming Languages • List of server commands • List of client commands • Client startup parameters • Server startup parameters
Example Mods • API Docs • GitHub Repository


Retrieved from "https://wiki.vintagestory.at/index.php?title=Modding:Tutorial_Template&oldid=174096"