|
|
| Line 1: |
Line 1: |
| __FORCETOC__ | | __FORCETOC__ |
|
| |
|
| Please read the tutorial [[Getting Started with Advanced Modding#Domains|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 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 familiar to you. | | Please read the tutorial [[Getting Started with Advanced Modding#Domains|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 = | | = 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 an overpowered wand. Let's call this mod '''MyWandMod'''. | | 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. Let's call this mod '''BasicWand''', because this is the Basic Item tutorial, and we're making a wand. |
|
| |
|
| == Workspace == | | == 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 <code>assets/basicwand/</code>. |
|
| |
|
| First of all I suggested to create a new folder to keep everything nice and clean. Inside this '''workspace''' we will create the mod itself and later on put it into a zip file, so we can test it and distribute it to other people.
| | All mods that add content must be in the assets folder and their own namespace directory. The namespace, for us is <code>basicwand</code>, prevents multiple mods with 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. |
| | |
| | After making sure our workspace is ready we can move on to actually making the wand. |
|
| |
|
| == The Texture == | | == The Texture == |
| | Let's start with the texture we will use: [[File:Wand.png]] |
|
| |
|
| This is the texture we gonna use: [[File: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 <code>textures/item/</code>. Remember, this is in our namespaced folder so the full path is <code>assets/basicwand/textures/item/</code>. |
|
| |
|
| In order to use the texture we need to put it at the right place. Therefore create the following folders in your workspace <code>assets/mywandmod/textures/item/</code>. Now rename the texture to <code>wand.png</code> and place it in there.
| | == The Item File == |
| | 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. |
|
| |
|
| == The Item File ==
| | 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. |
|
| |
|
| To create the actual wand need to create a json file inside <code>assets/mywandmod/itemtypes/</code> in your workspace. In this example we name it <code>wand.json</code>. This file contains the basic properties of your item.
| | For now, our values for each property are pretty 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> |
|
| |
|
| The content of this json file should look as it follows:
| | ''Finally'' the values in the actual JSON look like this: |
| <syntaxhighlight lang="json"> | | <syntaxhighlight lang="json"> |
| { | | { |
| code: "wand",
| | code: "wand", |
| creativeinventory: { "general": ["*"] },
| | creativeinventory: { |
| texture: { base: "item/wand" }
| | "general": ["*"] |
| | }, |
| | texture: { |
| | base: "item/wand" |
| | } |
| } | | } |
| </syntaxhighlight> | | </syntaxhighlight> |
|
| |
|
| * '''code''': A unique identifier for your item.
| | You might've noticed that the <code>creativeinventory</code> and <code>texture</code> properties aren't as simple as the <code>code</code> values. We will see why <code>texture</code> is like what it is. The reason why <code>creativeinventory</code> is like that isn't something we'll cover in this tutorial. |
| * '''creativeinventory''': The creative inventory tabs the itemshould be shown in (currently only 1 tab available)
| |
| * '''textures''': What textures to apply.
| |
|
| |
|
| == Naming the Block == | | == Naming the 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>. |
| Now we got almost everything ready, except of a proper name. Create another json file in your workspace <code>assets/mywandmod/lang/en.json</code> and give your item a proper name: | |
|
| |
|
| | 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> |
|
| |
|
| == Testing and Packaging == | | == Conclusion == |
| | | Together, the item and language files are technically enough to be a complete mod. But they don't add the overpowered 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. |
| There is only one thing left. We need to create a zip file of the assets folder inside your workspace. Either you use an external program, such as WinRAR or 7Zip, or you right-click the <code>assets</code> folder and compress it. Eventually you can rename the zip file to <code>MyWandMod.zip</code>. The zip file can be either used for testing purposes or you can send it to other people so they can use it as well.
| |
| | |
| Furthermore you need to add a <code>modinfo.json</code> file, check out [[Game Content Mod|this tutorial]].
| |
| | |
| [https://wiki.vintagestory.at/images/e/ec/MyWandMod.zip MyWandMod.zip]
| |
| | |
| To install the mod, navigate to the [[Vintagestory folder]] and place it inside the mods folder.
| |
| | |
| | |
| 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]]
| |
| | |
| '''Hint''': Use the client command <code>.tfedit</code> if you want to adjust the item position, rotation and scale in Hands, in GUI, when dropped on the ground or in third person mode. | |
| | |
| = Advanced Properties =
| |
| | |
| == Mining Properties ==
| |
| | |
| Our wand is still rather useless, so it might be a good idea to add our wand some mining functionality. How it works? We the property "miningspeedByType" we can define the mining speed for each material. Here is a list of all [[Block Materials|block materials]].
| |
| | |
| The number indicates how fast the tool is able to mine the block, while <code>1</code> is the default value. <code>time to mine = block resistance / miningspeed</code>. Meaning a speed of <code>2</code> is twice as fast the default speed of one. So our tool is seven times faster than using the hand.
| |
| | |
| A pickaxe looks like this:
| |
| <syntaxhighlight lang="json">
| |
| miningspeedByType: {
| |
| "*": {
| |
| "stone": 7,
| |
| "metal": 7
| |
| },
| |
| },
| |
| </syntaxhighlight>
| |
| | |
| Although the tool is working already, we should add some kind of durability. Therefore we need to define what can damage our tool and the durability itself.
| |
| | |
| Our tool can be damaged by breaking a block, or using it for an weapon. The property <code>damagedby</code> allows us to define all possible damage source. For now we will stick to <code>blockbreaking</code> and <code>attacking</code>.
| |
| | |
| <syntaxhighlight lang="json">
| |
| damagedby: ["blockbreaking", "attacking"],
| |
| </syntaxhighlight>
| |
| | |
| and the durability should be 2000:
| |
| | |
| <syntaxhighlight lang="json">
| |
| durabilityByType: {
| |
| "*": 2000,
| |
| },
| |
| </syntaxhighlight>
| |
| | |
| == Variants ==
| |
| | |
| Pretty basic so far, let's go more advanced. Let's add some variants to our wand, each of them should represent another tool (shovel, pickaxe, axe).
| |
| | |
| So first of all we have to add a new variantgroup. The name of your group is <code>tooltype</code> and possible values are <code>"shovel"</code>, <code>"pickaxe"</code>, <code>"axe"</code>:
| |
| <syntaxhighlight lang="json">
| |
| variantgroups: [
| |
| { code: "tooltype", states: ["shovel", "pickaxe", "axe" ] },
| |
| ],
| |
| </syntaxhighlight>
| |
| | |
| Now we need to change our <code>miningspeedByType</code> property to set the speed of each material for each type:
| |
| <syntaxhighlight lang="json">
| |
| miningspeedByType: {
| |
| "*-shovel": {
| |
| "soil": 7,
| |
| "sand": 7,
| |
| "gravel": 4.4
| |
| },"*-pickaxe": {
| |
| "stone": 7,
| |
| "metal": 7
| |
| },"*-axe": {
| |
| "wood": 6,
| |
| "leaves": 4
| |
| },
| |
| },
| |
| </syntaxhighlight>
| |
| | |
| Every group will be added after each other to the item name <code>item-myitemname-mygroup-mysecondgroup</code>. In total, our wand has 3 types and their full names are:
| |
| *item-wand-shovel
| |
| *item-wand-pickaxe
| |
| *item-wand-axe
| |
| | |
| Each of our selectors starts with a <code>*</code> which is a custom symbol and means it can be anything. Through that way you can select specific variants of your item.
| |
| | |
| If we would add another variant called <code>material</code> (values are <code>magic</code>, <code>air</code>, <code>death</code>) and wanted to select all shovels we would have to do it like that: <code>*-shovel-*</code>. Meaning it can be anything before, but it has to be a shovel and it can be any type of a shovel.
| |
| | |
| We can also change the durability for each type individually.
| |
| <syntaxhighlight lang="json">
| |
| durabilityByType: {
| |
| "*-shovel": 4000,
| |
| "*-pickaxe": 3000,
| |
| "*-axe": 2000,
| |
| },
| |
| </syntaxhighlight>
| |
| | |
| == Variant Textures ==
| |
| | |
| Using the same way we specified the mining speed for each type we can also specify a texture for each type.
| |
| | |
| <syntaxhighlight lang="json">
| |
| textureByType: {
| |
| "*-shovel": {
| |
| base: "item/wand-shovel",
| |
| },
| |
| "*-pickaxe": {
| |
| base: "item/wand-pickaxe",
| |
| },
| |
| "*-axe": {
| |
| base: "item/wand-axe",
| |
| },
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| But we can accomplish the same thing with an easier way:
| |
| <syntaxhighlight lang="json">
| |
| texture: {
| |
| base: "item/wand-{tooltype}",
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| <code>{tooltype}</code> will be replaced by either shovel, pickaxe or axe.
| |
| | |
| == Texture Overlays ==
| |
| | |
| As everybody knows programmers are lazy, so instead of drawing a texture for each variant of our item, we can use overlays instead, which will make it a lot easier.
| |
| | |
| These are the overlays for each type: [[File:Wand-overlay-axe.png]] [[File:Wand-overlay-pickaxe.png]] [[File:Wand-overlay-shovel.png]]. All we have to do now is to change the base texture to back to the original wand texture and add an overlay texture.
| |
| | |
| <syntaxhighlight lang="json">
| |
| texture: {
| |
| base: "wand",
| |
| overlays: [ "item/wand-overlay-{tooltype}" ],
| |
| },
| |
| </syntaxhighlight>
| |
| | |
| and this is the result:
| |
| | |
| [[File:2017-02-09 17-30-34.png|700px]]
| |
| | |
| = Mod Download =
| |
| | |
| You can download the mod to test it out yourself:
| |
| | |
| [https://wiki.vintagestory.at/images/e/ec/MyAdvancedWandMod.zip MyAdvancedWandMod.zip]
| |
| | |
| = Moving Forward =
| |
| | |
| The example shown here is a rather simple item, and barely covers all the unique things that can be added in Vintage Story. It's highly suggested that you experiment with or at least familiarize yourself with all the known item properties before moving onto code mods. The best way to do this is to peruse the '''[[Modding:Item Json Properties | Item Properties]]''' page, which contains an ongoing list of all the usable JSON item properties currently incorporated into the game. Most properties in the list also have referenced files you can search for in the Vintage Story Assets folder. If you don't know where this is, you can find tutorials for each operating system at the [[Modding:The Asset System | Asset System]] page.
| |
| | |
| If you haven't yet, it's suggested you also check out the '''[[Modding:Basic Block| Basic Block]]''' and '''[[Modding:Basic Entity | Basic Entity]]''' pages to learn how simple JSON items and entities are added to the game.
| |
| | |
| However, if you're feeling like making the jump to code mods then you'll want to start by setting up your '''[[Modding: Setting up your Development Environment | Development Environment]]'''.
| |
| | |
| {{Navbox/modding|Vintage Story}}
| |
