Modding:Code Tutorial Simple Item

This page is in progress. Please come back later!

Introduction

Objective

In this tutorial, you will be creating an item with basic custom functionality. You will find out how item classes are registered, and how to interact further with entities. The item you will be creating is a new 'thorny' sword, which will slightly hurt the player when used to attack.

Prerequisites

It is recommended to use the same project for all newer code tutorials, with the project name "VSTutorial". If you have not yet done this, please follow the following tutorials:

1. Preparing For Code Mods
2. Creating A Code Mod

This tutorial also assumes that you have read:

• Code Tutorial Essentials

It is also highly recommended to have completed previous tutorial in the code series:

• Simple Block Class

Assets

This tutorial uses the finished project from the previous tutorial. If you need to, you can download the finished version of the previous tutorial from GitHub here.

As usual, you need the required assets for this tutorial. These can be downloaded from GitHub here, and should replace the entirety of your assets folder as it also contains the previous tutorial's assets. When these files are added, you should have new itemtype, shape, and texture files.

Run the game, launch a world, and check the creative menu. You should be able to find the "Thorns Blade".

Playing Vintage Story in fullscreen mode?

It is highly recommended to run the game in windowed mode when making code mods. If your code results in an error, Visual Studio will attempt to gain focus, and Vintage Story will stop responding. You can press F11 to easily switch between the fullscreen and windowed modes.

Item Class

Close the game and go back to Visual Studio. To add custom functionality to the item, you'll need to create an item class.

An item class is a script that offers custom functionality for any specific itemtype assets. Note that each itemtype can only have a single attached item class.

Creating an item class is extremely similar to creating a block class.

Creating an Item Class

To keep the code organized, you should create a new folder called "Items". Right click on your project, hover over add, and select New Folder.

You also need a name for the new item class. These follow the same convention as the Blocks, and most other types. In this case, our thorny blade item class, you should name this class "ItemThornsBlade".

Create your new class. Right click the new folder, hover over Add, and select Class. Ensure you have the standard Class selected in the template list, enter your class name, and click create.

The class you created needs to extend the 'Item' class. This will allow you to use many of the available functions for items. Change the class definition to now be:

internal class ItemThornsBlade : Item

Most of the time, Visual Studio will automatically add 'using' statements. However, if this errors, click on "Item", press Alt+Enter, and select the "using Vintagestory.API.Common" option.

The ItemThornsBlade class now exists, but it does nothing. Time to override a function, I suppose.

Inside the empty class, type "override " and a list of methods we can use will be displayed. In this instance, you will want to override the 'OnAttackingWith' function. This function is called whenever our item is used to attack an entity. Search for this in the list and double click on it to automatically add the required code sample.

Your class should now look like this:

ItemThornsBlade.cs

using Vintagestory.API.Common; using Vintagestory.API.Common.Entities; namespace VSTutorial.Items { internal class ItemThornsBlade : Item { public override void OnAttackingWith(IWorldAccessor world, Entity byEntity, Entity attackedEntity, ItemSlot itemslot) { base.OnAttackingWith(world, byEntity, attackedEntity, itemslot); } } }

Note that the the sample code in 'OnAttackingWith' contains a function called 'base.OnAttackingWith'. This essentially runs any default behavior for the function. If you were to remove this line then any default behavior would not happen, and, in this case, the item will not lose any durability when used for attacking.

In the OnAttackingWith function, you are given access to the world, the entity who is attacking, the entity who is being attacked, and the itemslot that this item exists in. For testing purposes, add some code that outputs a message to the console when we attack an entity. You'll need to add the following code below the 'base' line:

world.Api.Logger.Event("Got attack with thorns blade!");

You can access the current game API from a lot of places. This particular line accesses the API through the world, however it can also be accessed through any entity with very similar code. You should be aware that this will create a message to the console when we attack an entity with the new item.

Registering the Item Class

The class for the thorns blade is created, however before it can be used it needs to be registered through the game API. In your mod system, which you used in the previous tutorial, you need to register an item class for both the client and server.

In the Start function, make a call to the RegisterItemClass function in the API. Add the following code on a new line inside of the Start function's block:

api.RegisterItemClass();

Similarly to the previous tutorial, this will result in an error. You'll need to add some parameters to the function. Don't forget, you can hover over the function with your mouse and the required parameters will be shown. In this case, we once again need a class name, and a type. Your class name argument should be fully lowercase, and should generally be your mod ID, joined with the name of the class you just made. The itemType will be the class you just made. Replace the function with the following:

api.RegisterItemClass(Mod.Info.ModID + ".thornsblade", typeof(ItemThornsBlade));

This will register the ItemThornsBlade class with the name "vstutorial.thornsblade".

Why include the mod id here?

If you've made code mods before the introduction of these new tutorials, you probably haven't included your mod ID when registering classes. As more and more mods are being made, there are occasional collisions in regards to class names. Say, for example, two mods both add in a 'trampoline' block class. Only one instance of the trampoline class will exist, which can cause issues if they had slightly different functionality. So, including your mod ID when registering classes will ensure that these 'collisions' do not occur.

Adding Item Class to Asset

Before your item will work, you need to add the class to the asset file. Open the file in assets/vstutorial/itemtypes/thornsblade.json.

You need to add the following property to the file:

"class": "vstutorial.thornsblade",

Generally, this element is placed as the second property in your json file, immediately below the code property.

Note that the value of this property is identical to the value we used in the RegisterItemClass function. This is how the game links the JSON asset files to your code's registered classes.

Testing the Item Class

Press F5 again to run the game with the mod. Remember to set the game to windowed mode by pressing F11. Find the thorns blade in the creative menu, and use it to attack an entity.After doing so, take a look at the console that opened when launching the game. You should be able to see the following logs:

[Client Event] Got attack with thorns blade!
[Server Event] Got attack with thorns blade!

Remember what's going on here? Although you only attacked the entity once, there are two entries. One of these is sent to the console by the client, and the other is sent by the server. You should start to become aware that a lot of the code you write is going to happen on both the client and server. You'll be shown ways of controlling this later.

The thorns blade class and function are working, so close the game and go back to the ItemThornsBlade class.

Thorns Blade Functionality

You now need to add the real functionality for the thorns blade. Remove the line of code that logs the attack event, since you don't need that anymore. Your code should look like the following. Feel free to copy and paste this, as it contains some useful code comments too.

ItemThornsBlade.cs

using Vintagestory.API.Common; using Vintagestory.API.Common.Entities; namespace VSTutorial.Items { /* * As this is an item, you need to inherit the Item class. This gives access to functions within Item, and CollectibleObject. * Take a look at https://apidocs.vintagestory.at/api/Vintagestory.API.Common.Item.html#methods and * https://apidocs.vintagestory.at/api/Vintagestory.API.Common.CollectibleObject.html#methods for all the methods that can be overriden. */ internal class ItemThornsBlade : Item { /* * This function is called whenever this item is used by an entity to attack another entity. * You have access to the world, the entity who is attacking, the entity who is being attacked, and the held item's data. */ public override void OnAttackingWith(IWorldAccessor world, Entity byEntity, Entity attackedEntity, ItemSlot itemslot) { base.OnAttackingWith(world, byEntity, attackedEntity, itemslot); } } }

Note that any further code in this function can be placed above or below the 'base' call. In this case, the order does not matter.

Reflecting Damage

To inflict damage on an entity, there are two small steps:

1. A DamageSource instance must be created.
2. The damage source must be inflicted on the entity using the Entity.ReceiveDamage function.

Before you can inflict damage on an entity, you must create a damage source. This includes the type of damage, and can contain information about where the damage has come from. Note that it does not contain the amount of damage.

DamageSource damage = new DamageSource()
{
    Type = EnumDamageType.PiercingAttack,
    CauseEntity = byEntity
};

This creates a new instance of damage source called 'damage'. Type can be any instance of EnumDamageType, but for this purpose you should use PiercingAttack. CauseEntity is the entity that caused the damage, which should be whatever is using our sword.

Now the damage source is created, you need to inflict it upon the entity. The entity that used the item is 'byEntity', so you'll want to damage them:

byEntity.ReceiveDamage(damage, 0.25f);

This will inflict 0.25 points of damage onto the entity, using our 'damage' instance we just created.And that's it. When the item is used to attack, 0.25 points of damage will be inflicted on the player using the weapon.

The full code should be as follows:

ItemThornsBlade.cs

using Vintagestory.API.Common; using Vintagestory.API.Common.Entities; namespace VSTutorial.Items { /* * As this is an item, you need to inherit the Item class. This gives access to functions within Item, and CollectibleObject. * Take a look at https://apidocs.vintagestory.at/api/Vintagestory.API.Common.Item.html#methods and * https://apidocs.vintagestory.at/api/Vintagestory.API.Common.CollectibleObject.html#methods for all the methods that can be overriden. */ internal class ItemThornsBlade : Item { /* * This function is called whenever this item is used by an entity to attack another entity. * You have access to the world, the entity who is attacking, the entity who is being attacked, and the held item's data. */ public override void OnAttackingWith(IWorldAccessor world, Entity byEntity, Entity attackedEntity, ItemSlot itemslot) { DamageSource damage = new DamageSource() { Type = EnumDamageType.PiercingAttack, CauseEntity = byEntity }; byEntity.ReceiveDamage(damage, 0.25f); base.OnAttackingWith(world, byEntity, attackedEntity, itemslot); } } }

Go ahead and test the new sword. You'll need to be in survival mode, but you should find that hitting an entity will also inflict damage on yourself.

Conclusion

Congratulations, you've created, registered and tested a new item class!

Next Steps...

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

When you're ready, take a look at the next tutorial. This will show you how to register and add commands into the game!

Going Further

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

Currently, the sword will damage you even if it is used on mobs that are dead. Make it inflict damage only if the entity being attacked is alive.

To achieve this...

Check the 'Alive' field on 'attackedEntity' is true before inflicting damage. if (attackedEntity.Alive) { byEntity.ReceiveDamage(damage, 0.25f); }

Using the revive function in the Entity class, make the sword revive any dead entities hit by it.

To achieve this...

Check the 'alive' field is false, and then call the Revive function on 'attackedEntity'. if (!attackedEntity.Alive) { attackedEntity.Revive(); }

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.