Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Basic tModLoader Modding Guide
This guide will get you familiar with tModLoader modding and will help you make your first mod. Please read and follow Basic Prerequisites first so you have access to a capable text editor.
Your First Mod
To start, we will make a very simple mod to get you familiar with how mods are created for tModLoader. To begin, please visit the Mod Skeleton Generator and fill out the input boxes. I suggest TutorialMod, Tutorial Mod, TutorialSword, and NewbieModder.
Generate Mod Skeleton button and you should see a .zip file download. Next, open up
Documents\My Games\Terraria\ModLoader\Mod Sources or equivalent. If you do not have the Mod Sources folder, make a folder of that name. Next, we will take the folder contained within the .zip file we just downloaded and place it in the Mod Sources folder.
You should now have a
Documents\My Games\Terraria\ModLoader\Mod Sources\TutorialMod\ folder.
Mod Skeleton Contents
The Skeleton contains 7 files. Here is an explanation of each:
[ModName].cs - This is the
Modclass. It is the central file to any mod. One and only one
Modclass can exist in every mod. For simple mods this file will be very sparse, but in this class various global things can happen such as modifying music.
description.txt - Contains text for the description of the mod. Click the
More Infobutton in the Mod menu to view in game.
- build.txt - Contains the version, author, and display name of your mod. Can contain other values. Necessary.
- [ModName].csproj - A project file for Visual Studio set up for debugging your Mod. Debugging is extremely useful but a takes a bit of learning, don't delete.
[ModName].csproj.user - Related to
[ModName].csproj, contains the path to Terraria.exe for debugging. Don't remove, you'll want it later as you gain experience.
- Items/[ItemName].cs - A simple Sword item. Use this as an example as you learn to make additional ModItem classes.
- Items/[ItemName].png - The corresponding sprite.
Learn how to Build the Mod
We now have a ready-made mod ready to be built. Start up tModLoader and click on the Mod Sources menu item. Now click the build and reload button.
Now go in game, make a workbench and mine 10 dirt blocks, and you should see that you can craft a new sword!
Wow! Amazing. But 50 damage isn't enough. We will now do our first actual programming. Open up the
Mod Sources\TutorialMod\Items\TutorialSword.cs file in Notepad++. Find the line with
item.damage = 50; and change 50 to 100. Also at this time, let's change
Tooltip.SetDefault("This is a modded sword."); just for fun. Remember not to mess up the syntax that you learned in the Basic Prerequisites lesson. Now, save the file! Next, go in game, once again build and reload the mod and acquire the sword again. You should see the new damage and the new tooltip.
Experiment a little
You can now experiment a little more by changing some of the other item values. Remember, you have to save your changes and build and reload to see your changes in-game.
Now that you have a simple mod with a simple sword, it is time to branch out an learn other skills. Take it slow and experiment with something you want to learn. If you are seeking help from other modders on the Forum or Discord, it is best to phrase your question in terms of Vanilla things. For example, if you are curious how the Molten Fury changes Wooden Arrows to Flaming Arrows, it would be wise to ask "How does the Molten Fury change the projectile it shoots only when Wooden Arrows are used as ammo?" Phrasing your questions in this manner is most effective.
Continue reading to learn more about tModLoader and how to get better.
How do tModLoader 'hooks' work?
Firstly, they are technically not hooks. We simply call them hooks because it is easy. A 'hook' is a function you can use as a modder. Which hooks are available depends on the class you're working in. For example your Mod class has a Load Hook, which is a function special to the Mod class. Every one of these functions is
virtual, this means the function has a basic implementation but can be overridden by the modder if desired. This means when you want to use a hook, you override it, this is why the word
virtual is replaced with
override. Since the virtual (partial) implementation is overridden, that implementation will be lost. To see the standard implementation of hooks you should see the source documentation.
How are modded classes setup?
tModLoader provides a number of classes you can use to create your own mod content. You will base your own classes off of these by using what's called
class derivation or
class inheritance. To keep this simple, it basically means your class will use one of ours as its base. For example, your items will be based on ModItem:
MyItemClass : ModItem, where the
: ModItem denotes it inherits from the ModItem class, which is present in the Terraria.ModLoader namespace. (if you come from Java, this is the same as
extends ModItem)This means everything we made for ModItem becomes available to you in your class, such as the SetDefaults hook. Note that you can only derive from one class, so a ModItem cannot be a ModProjectile and so forth.
Learning from Example Mod
Example Mod is a mod made by the tModLoader developers to show off various modding capabilities. It would be wise to enable Example Mod and play around with it for a while. Use a mod like Cheat Sheet to spawn in its various items and find something it does that you want to learn. Next, download the Example Mod sourcecode and place it in the Mod Sources folder as you did with TutorialMod. Find the thing you are interested and try to understand it. Hopefully it is easy to understand. You can also change things in Example Mod and build Example Mod in game.
If you can handle modifying simple things in Example Mod or Tutorial Mod, you should be comfortable with the mod building process. Feel free to explore other guides or help for the next steps.
Learning in steps
If you are new to modding, you are probably also new to programming itself and possibly the c# language. It is recommended to start with easy things and work your way up the ladder of difficulty. One of the easiest things to do would be a sword that can be swung to deal damage as shown above, and one of the hardest would be to create a fully functional boss fight. Here is a few suggestions to get started:
- First, try to familiarize yourself with how tModLoader works. Read the section 'How do tModLoader 'hooks' work?'
- Next, try modifying the tutorial sword to deal more damage, have more knockback, faster speed etc. You can also make it shoot things by setting
item.shoot, and control the speed with
- You need to understand that modding is programming, it is c# and it is being familiar with the vanilla code. This means you should definitely follow free online courses to get a better understanding of the c# language or programming itself. A useful resource might also be the Quick Terraria-specific C# crash course. To get more familiar with the vanilla code, use our Advanced Vanilla Code Adaption guide.
- If you feel confident enough, try making your own projectile and having your sword interact with it.
- With more confidence, you can start trying other things, such as making an enemy NPC.
Here is a few things that would be considered difficult for most modders, and it is advised you start with easier things before attempting these:
- A fully functional boss
- Comprehensive UI
- Code abstraction
- Modding info for entities, and interacting with it
- Completely custom AI for a projectile, NPC, pet... etc.
There is many resources available so you can become a better modder. First of all, this wiki. On the right side of this page you can find the wiki menu, which houses links to various different tutorials and guides that you can use. These are all separated into their own difficulty level, from basic being the easiest and expert being the hardest. Secondly, a great source of information is the modding section on TCF. And lastly, a variety of helpful tools and guides is available on the homepage of this wiki.
Modding tips and guidelines
Internal names do not support whitespaces, this means you need to name
My Super Sword without spaces. People commonly just omit the spaces:
MySuperSword but sometimes you'll also see
My_Super_Sword. The former is called
pascal case and the latter is called
snake case Remember to use short and descriptive names; if you are making a sword it is likely you should use 'Sword' in the name. Naming convention mostly depends on who your work with/for (if you are employed etc.), if you work on your own it is obviously down to your personal preference. Good to note that
camel case is similar to
pascal case, but often you'll find with camel case that the first letter may be lowercase or capitalized and each subsequent concatenated word is capitalized such as backColor and timeUtc.
Keeping code tidy and organized
Though this is a more advanced topic (part of design patterns, which might be covered in expert tutorials later), it is useful to make sure you abstract your code properly. More on this in the code abstraction guide. For beginners, take this tip: after you've programmed something and it is finished, look at your code and ask yourself what is happening in every place. Now you should ask if the code is tidy. Try to find repeating parts of code and give it a dedicated method. Next, try to separate parts of your code by their logic and give them their own method as well, providing a useful descriptive name (see the previous tip) so it becomes easy to identify what that part of code is doing. This is a brief summary of a part of code abstraction.
Comment your code
It is not always obvious what code is doing, or sometimes you wish to make a note for yourself or other modders working with your code. You can make single line comments like this
// this is a comment, or you can make entire comment blocks like this:
/* * This is a comment block * And spans multiple lines! */
For beginners, it is highly advised to add as many comments as possible, even for things you think you already understand well. This will help you in the long run, you might come back to code months later and have forgotten how it works. For experienced modders, the challenge is to use as little comments as possible; your code should be evident in its behavior for others just by looking at it. Note many languages use different notations for comments, such as
#, for c# use what's shown above.