How to Make an Item Use Scripting

Difficulty:

: 10 to 30 minutes

Introduction

This tutorial will cover the concepts of adding more sophisticated effects on your items. It is broken into two parts; first, we will discuss how to create a custom potion that adds several buffs at once, and then we will show the steps needed to create a sword that drains life on each hit.

Note that regular items can only add one buff at a time via the ini files, thus you can already see why coding with C# is more powerful, as there are fewer restrictions.

Requirements

This tutorial assumes you've completed the following tutorials and are familiar with compiling your mods:

• Install Guide
• How to Make a Basic Item

Creating the Item

Create the Potion .ini File

As you should be familiar with creating an item, these steps will be rather brief. But, let's make a custom potion that applies several buffs!

To start:

• Create a folder for your mod inside ModPacks (Skip this step if you already have a folder to use). For this tutorial we will use the name "CustomMod".
• Create a folder INSIDE CustomMod called "Items", unless it already exists.
• Since this is a potion, let's copy the .ini of a Health Potion to this folder, and name it "Elixir of Power.ini". The .ini should look something like this (in the format of a text document):

[Stats]
width=14
height=24
type=-1
useStyle=2
useAnimation=17
useTime=17
maxStack=30
consumable=True
useTurn=True
scale=1
useSound=3
rare=1
value=2000
[Recipe]
Amount=1
needWater=False
Items=2 Lesser Healing Potion,1 Glowing Mushroom
Tiles=Bottle

• Find an appropriate picture somewhere and call it "Elixir of Power.png". You can reuse the healing potion's 
• picture, or even make your own! See Resources for some programs you can use.

Example picture of "Elixer of Power"

The big difference between this file and the Healing Potion that there is no "potion=True" attribute or "healLife=100" attribute. We want our item to add buffs, but not restore life, so we removed the ability for it to do so. If you want, you can always add it back, simply by adding the line "healLife=x" (where x is the heal amount) on any line below [Stats] and above [Recipie]. Also, "potion=true", is a bit misleading. It doesn't indiciate that the item is a potion or not, but rather, it has a 60 second cooldown that is shared with other items (Potion Sickness). This is why a Mana Potion does not have a cooldown, but a Mushroom does have one.

Giving the Potion Some Effects

As mentioned in the introduction, the ini file is limiting: you can only specify one buff. What if we wanted to add three? Well, we need to create a .cs file so we can tell the game very specifically to do what we want.

• Create a file called "Elixir of Power.cs"
• This should be beside the other two files, Elixir of Power.ini and Elixir of Power.png
• Put the following code in the .cs file:

public static void UseItem(Player player, int playerID) {

         player.AddBuff(3, 600, false);
         player.AddBuff(5, 600, false);
         player.AddBuff(17, 600, false);

}

• If this is your first time programming, your eyes probably glazed over, so here's a briefish explanation on what is happening here.
  • The very first line is called a function definition. The function is called UseItem. The section which reads "public static" means that any other code can call (execute) this function with no restrictions, and "void" means that the function does not return a value (so it takes input, but doesn't give an output).
  • The part in the round brackets that says "(Player player, int playerID)" is the input that is given to the function, or what it has to work with. We supply it a valid player, and an ID number of that player.
    • A side note: If you are using any of the functions defined in tConfig Classes, then you just copy the definition that is documented there as is, and the game will intelligently know what to do. When you get more advanced and write your own functions, you will be responsible for passing the correct information to and from it.
  • Finally, the meat of the function: Anything that is located in the curly braces { } is what the function actually does. We see three very similar commands: player.AddBuff, and a bunch of stuff in the brackets. These are function calls. What is happening here is that the player object (called player) has a function called "AddBuff", so when we do it, it adds a buff to the player. How does it know what buff to give the player? That's what the stuff in the brackets is for.
  • The first number is the buff type and the second in the duration in frames. Being that there are 60 frames in a second, each buff will last for 10 seconds (10 seconds has 600 frames because 60 frames per second is 10*60=600).

Testing it Out

• Once you have added these three files to the folder, save them, compile the mod, and test it out.
• When you use the item, you should be able to see the three buffs you added (Swiftness, Ironskin, and Hunter, all for the same 10 second timer).

Creating the Sword

CustomSword.ini

The first thing for any new item should be a .ini file. In general, different types of items have different .ini files. One example that can be used for this is:

[Stats]
width=24
height=28
type=-1
useStyle=1
useAnimation=19
useTime=19
maxStack=1
damage=20
knockBack=2
scale=1.05
useSound=1
value=9000
melee=True
[Recipe]
Amount=1
needWater=False
Items=10 Wood
Tiles=Furnace

This will allow you to create the sword at a furnace, provided you have 10 wood to spare. If you are interested in customizing the weapon further, a good reasource to edit the .ini files is located at the Item Attributes page. Just add the name and the value and it should modify your item as desired. Make sure to not use conflicting tags however or the item may not work properly and could crash your game (for example the legSlot/ headSlot/ accessory tags or the useAmmo/ Mana tags).

CustomSword.png

Next is a picture. The size of this picture will be modified in the .ini by the width/height tags, so the picture shouldn't be too much smaller or bigger than the tags (anything bigger than 64x64 is probably excessive). For weapons, the useStyle determines how the weapon is animated, so make sure you are using the right one in the .ini for your weapon by checking the list at the List of Use Styles.

CustomSword.cs

If we wanted to spice up the weapon a little bit with, for example, a life stealing effect, we could use the following code to give our sword some drain power:

public void DealtNPC(Player player, NPC npc, double damage)
{
	player.statLife += (int)damage/10;
}

public void DealtPVP(Player myPlayer, int damage, Player enemyPlayer)
{
	myPlayer.statLife += (int)(damage*2)/10;
}

This code has two main parts. The first is the DealthNPC() method, which is called when the weapon deals damage to an enemy who isn't a player. It says player.statLife (aka your life) += (additionally becomes) (int)damage/10; (10% of the damage that was just dealt). The second part is DealtPVP with mostly the same parts except 20% of the damage is added to your life.

Make sure to compile and activate the mod before testing!

For more basic information on how to make a weapon, check out this great tutorial:

How to Make a Custom Weapon

Final Words

While coding can seem complex at first, it is an excellent skill to learn, as it gives you the most control over your modding. If you were able to get everything working correctly, you might want to read up on How to Make a Custom Buff, since you can then have a potion apply buffs or a weapon that applies debuffs as a natural extension of this tutorial.

As a bonus, here are some other UseItem scripts you can use within the .cs file, to give you a good range of ideas to try:

Drop a meteor

Use caution with this one, since meteors can cause damage to your structures. Also, it may not spawn if there is an excessive amount of meteorite ore already in the world.

public void UseItem(Player player, int playerID) {
    WorldGen.dropMeteor();
}

Spawn Bunnies

Using the item lets you spawn bunnies like you're using a boss-summoning item. Bunny has awoken! Replacing Bunny can be used to spawn other mobs, including custom ones.

public void UseItem(Player player, int playerID) {
    NPC.SpawnOnPlayer(playerID, "Bunny");
}

Starfury-Like Effect

Makes a starfury star fall from the sky on use:

public void UseItem(Player player, int playerID) {

	// Set the variables
	float x = (float)(Main.mouseX + Main.screenPosition.X);
	float y = (float)(Main.mouseY + Main.screenPosition.Y);
	float speedX = (Main.rand.Next(80) - 40) / 10f;
	float speedY = 14.9f;
	int type = 12; // type of the projectile (you can change this)
	int damage = (int)(item.damage * player.magicDamage /* magicDamage! */);
	float knockback = 2.0f;
	int owner = playerID;

	
	// Adjust the position of the projectile
	x += Main.rand.Next(200) - 100f;
	y += -500f;
	
	
	// Actually spawn the projectile	
	int projID = Projectile.NewProjectile(
		x, y, speedX, speedY,
		type, damage, knockback, owner
		);
	
}