tModLoader - Tutorial: [1] Getting started with tModLoader (2024)

Getting started with tModLoader
Last update: 9th of July, 2017

Table of contents

Table of contents
My tutorials
Other noteworthy tutorials and guides
Prerequisites
Introduction
I'm coming with tAPI/tConfig experience, what do I need to know?
Getting started
The Mod class
The build.txt file
The description.txt file
Let's continue: our first item
What next?
1. What do I need to know about 'Mods' and 'Mod Sources' in the in-game menu?
Tips
1. Always have an instance of your mod available
Notes

My tutorials

WIP

Getting Started with tModLoader
Recipes
Items
Projectiles

More to come..

Other noteworthy tutorials and guides

Please note that these tutorials may or may not be more advanced than mine. Most of these will be more of more intermediate difficulty and will often require more extensive understanding of c# and knowledge of the API.

Projectile Guide and Implementation (by @Sin Costan)
Custom Bosses - NPC AI and Server Syncing (by @blushiemagic) (note: this tutorial was written for tAPI)
Creating Simple UI: Custom Resource Bars (by @Subaro)

Prerequisites

Make sure you have....

...the latest tModLoader release installed
...the latest Microsoft .NET Framework installed
...the Microsoft XNA Framework Redistributable 4.0 installed (you have this if you are able to play Terraria)
...Microsoft Visual Studio (community = free) installed with the C# workspace
...at least some basic understanding of C# (c-sharp)

I'm not going to repeat these prerequisites in further tutorials. Any specialties will be listed if necessary, but otherwise omitted.

Introduction

In this tutorial I will cover how to get the basic template for a tModLoader mod, and getting to know various things about the API as well.
The tModLoader is an API (Application Programming Interface), quite literally a mod to make mods. It functions as a gateway between your mod and Terraria, and allows you to do many things with mostly indirect control, but managed. First and foremost, I'd like to cover a handful incredibly useful sites:

The tModLoader wikipedia

This site contains lots of useful information, including guides, references and links to open-source mods you can learn from.

The tModLoader documentation

This site contains documentation of the API source, generated by Doxygen. The docs are maintained through the source-code, meaning they are always up-to-date.

The old tConfig wikipedia

Even though this site is out-of-date, it still contains some useful (and applicable) information to date. This site should be approached with caution and information should be taken with a grain of salt due to its age.

Example Mod

ExampleMod is a mod that contains various code to 'showcase' what tModLoader is capable of. Please note that most of these are very blunt examples, they should be considered a base reference but nothing more.

There's also the old tAPI docs, but they're practically useless at this point.

Now, let's get to it already. Please note I like to write out things, a lot. If you're not about text, it might be better to watch a video guide instead.

I'm coming with tAPI/tConfig experience, what do I need to know?

Honestly, probably not much. tModLoader can be quite different in a lot of ways. Certain things are definitely similar though, such as things like ModItem, ModBuff etc. One thing you should know is that tML does not use JSON files (as handled previously) Furthermore, most communication is handled through our Discord server and Yorai/Skiphs are available there as well for more intermediate questions.

Getting started

To get started, you're going to need a so called: 'mod skeleton' These are simply the base files you will need to get started. It is recommended to use jopo's 'mod skeleton generator' which does most work for you, so let's go ahaid and do that.

The generator is located here: http://javid.ddns.net/tModLoader/generator/ModSkeletonGenerator.html
You will be greeted by a few textboxes, fill these in and hit the generate button. It is common to end your mod name with 'Mod' so for example if I'm considering "Jofairden's Mod" I should name it "JofairdensMod", you should delete all special characters.
Noteworthy: you should never use whitespaces for most of this stuff (as these are internal names), either don't use spaces at all or use hyphens. E.g. My Super Sword becomes MySuperSword or My_Super_Sword. The latter is considered ugly by most developers, so going with the former is your safest bet and the most common convention in mods. Also note that if you have installed Terraria in a different location (not in C:\ for example), the reference to Terraria.exe will be broken and you'll need to add it manually.

Upon downloading, you will find that it has generated a .zip file for you. You will need an application such as 7zip to unpack this, Windows 10 can also unpack natively, however. Within this .zip file lies your mod source. Unzip the zip to the Terraria 'Mod Sources' (the WHOLE folder, not the contents only) The location for this place is as follows:

Mac: /Users/account/Library/Application Support/Terraria/ModLoader/Mod Sources
Linux: ~/.local/share/Terraria/ModLoader/Mod Sources OR $XDG_DATA_HOME/Terraria/ModLoader/Mod Sources
Windows: %UserProfile%/Documents/My Games/Terraria/ModLoader/Mod Sources

E.g. if my mod was 'JofairdensMod' then the 'JofairdensMod' folder should now reside in /Mod Sources, so the path is as follows: /Mod Sources/JofairdensMod

Upon first inspection you will find multiple files, and a folder. Amongst these files resides a .csproj file, this is your 'c-sharp' project file. Open this file. You will need Visual Studio for this. We will look at all the files in just a bit, first let's take a look at the main entry point of your mod: your mod class.

The Mod class

To open the previously mentioned file, navigate to your Solution Explorer and open <ModName>.cs (E.g. mine would be JofairdensMod.cs)
Noteworthy: it is common convention to name the file after your classname

Your file should look something like this:

Code:

using Terraria.ModLoader;namespace JofairdensMod{ class JofairdensMod : Mod { public JofairdensMod() { Properties = new ModProperties() { Autoload = true, AutoloadGores = true, AutoloadSounds = true }; } }}

For newcomers, here is a neat image (by jopojelly) to quickly show the general structure of a c-sharp file. Note the .cs file extension, this stands for c-sharp (the programming language)

This is your 'Mod' class, notice how it derives from the 'Mod' class which lies within tML. Your mod project should have only one 'Mod' class.
More information about class inheritance and derived classes can be found here. In general, deriving from 'Mod' allows tML to pick up on your mod, and allows you (`the modder`) to access various methods to work with. (these are often called 'hooks') You will later notice that almost all of your classes for your mod will derive from some class that lies within tML.

Your mod skeleton has only one method, in this case it's actually not really a method (but it certainly looks like one)
The method you see is actually your class constructor, it is called when a new instance of your class is created. In this case, we can change various properties of our mod in it, which will then be set when tML creates a new instance of your mod. More information about class constructors can be found here. In the generated skeleton, various 'Autoload' properties are set to true. It is recommended to keep Autoloading on, as it saves you from writing a lot of unnecessary code.

Next, we're going to look at another file in your mod's root directory: build.txt

The build.txt file

So, what is this build file for? The build file contains various other information about your mod, for when it gets built to a .tmod by tML. Your generated build file should look something like this:

Code:

author = Jofairdenversion = 0.1displayName = JofairdensMod

I think the build file is pretty self explanatory, as it follows .ini (initialization) file format, In general all you do is follow the rule of: property = value

More information about the build file and its various properties can be found here.

Noteworthy: it's common convention to follow the following version format: <major>.<minor>.<build>.<revision>
In fact, the build file won't even allow for much other format, so go along with it I'd say. You should almost never increment your major version number, in fact tML is not even on major release 1 itself. You can also look at Terraria itself for example: the initial release was 1.0.0.0, right now we have only hit 1.3, many years after initial release!

The description.txt file

This file is also pretty self explanatory. The information in this file will be used when you publish your mod to the mod browser.

Let's continue: our first item

Now that we've covered the files in our root directory, let's have a look at that 'Items' directory. This directory is however, not so different from our root directory. In this case, it contains a .cs file for our sword and a sprite that goes along with it. Please note that the sprite and .cs file are in the same directory and share the same filename, this is very important when autoloading! This is because tML will look for the item's sprite in that same directory, using the same name. The directory tML will look for is dictated by the namespace your class is in (notice how the sword's namespace goes along with the directory path: namespace JofairdensMod.Items in path JofairdensMod/Items) Also note that sprites should always be in .PNG format. Even animated sprites, which use .png spritesheets (and not .gifs) More on this at a later stage.

You can open the sword file the same way you did for your mod file. You will notice, there's quite a bit more code to this than our skeleton mod class. Your code should look similar to the following:

Code:

using Terraria.ID;using Terraria.ModLoader;namespace JofairdensMod.Items{ public class JofairdensSword : ModItem { public override void SetStaticDefaults() { DisplayName.SetDefault("JofairdensSword"); Tooltip.SetDefault("This is a modded sword."); } public override void SetDefaults() { item.damage = 50; item.melee = true; item.width = 40; item.height = 40; item.useTime = 20; item.useAnimation = 20; item.useStyle = 1; item.knockBack = 6; item.value = 10000; item.rare = 2; item.UseSound = SoundID.Item1; item.autoReuse = true; } public override void AddRecipes() { ModRecipe recipe = new ModRecipe(mod); recipe.AddIngredient(ItemID.DirtBlock, 10); recipe.AddTile(TileID.WorkBenches); recipe.SetResult(this); recipe.AddRecipe(); } }}

Notice that there are 3 methods going on. Let's go over them and see what they do.

Just recently, SetDefaults got separated with SetStaticDefaults, and this new method was introduced together with language support for mods. Most 'static' stuff (that is not directly tied to the item object) will go in this method, such as setting the displayed name and tooltip(s). In my example, I want my sword to show as "Jofairden's Sword" and not as "JofairdensSword", so let's go ahaid and change that:

Code:

DisplayName.SetDefault("Jofairden's Sword");

I will also program this sword to kill anything it hits, so I will change the tooltip to reflect this:

Code:

Tooltip.SetDefault("This sword kills anything it hits");

Next, we will look at the 'regular' SetDefaults() method. Here we can set various properties related to the item object, such as the damage and knockback. You can change these properties to your liking, and there are more properties available than you will see in the generated skeleton. This is the part where you'll want to have Visual Studio, as it contains 'Intellisense' which will show you all the properties available on the item object.

For my sword, I'm going to define custom behaviour, so let's set the damage to 1 and the knockback to nothing for the sake of exampleness:

Code:

item.damage = 1;

To remove the knockback, I can set it to 0, but I can also simply omit the line of setting it, as the default knockback is always 0.
Notice that the knockback is a float and not an integer, meaning floating numbers are possible, such as 6.5f knockback. Also notice how the type is denoted by appending the 'f' after the number, e.g: item.knockback = 6.5f (also note that simply noting 6.5 will result in an error, as this is a double and not a float (which can also be denoted by appending a 'd' after the number))
It is very important that you understand the various different built-in data types in c-sharp, more information on this is available here.

The last method is AddRecipes(), in which we can create new recipes for our sword. Of course, we could create any kind of recipe we want here. But restraining the recipes created to the actual item itself is good in terms of code organization. The generated code should look something like this:

Code:

 public override void AddRecipes() { ModRecipe recipe = new ModRecipe(mod); recipe.AddIngredient(ItemID.DirtBlock, 10); recipe.AddTile(TileID.WorkBenches); recipe.SetResult(this); recipe.AddRecipe(); }

This code creates a new ModRecipe object, with our mod as the source of the recipe. Note that 'mod' (in new ModRecipe(mod)) is simply a mod object (of our mod) available in the current scope. Not all times is this object available, more on this in the tips section.

Next, we add 'DirtBlock' (a block of dirt) as a required ingredient, with the requirement of having at least 10 (`ten`). Note that the value passed here for the item is an integer, an item type or `ID` if you will. Almost all vanilla item types can be found in the Terraria.ID.ItemID namespace. Since the Terraria.ID namespace is included at the top of our file, we can simply call the ItemID class as shown. There are various ways to require modded items as an ingredient, more on this at a later stage.

Next, we add 'WorkBenches' as a required tile. This means the player will need to stand at any workbench for the recipe to be available. This TileID class comes from the same namespace as `ItemID`, so from the Terraria.ID namespace.

Next, we set the result to 'this', which is a reference to our current class, our 'ModItem' in this case. At the end, we call the method AddRecipe() on the ModRecipe object to add the recipe to the game. Note that if you want to create another recipe for the sword (say, with some other ingredients), you can reuse the same object and simply construct a new ModRecipe instance:

Code:

 recipe = new ModRecipe(mod); // Same object, new instance recipe.AddIngredient(Some other ingredient); recipe.SetResult(this); recipe.AddRecipe();