tModLoader Tutorial: [1] Getting started with tModLoader

Discussion in 'General Mod Discussion' started by Jofairden, Jun 8, 2016.

  1. Jofairden

    Jofairden Golem

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

    Table of contents

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


    1. Getting Started with tModLoader
    2. Recipes
    3. Items
    4. 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.


    Make sure you have....

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

    Back to top


    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:
    This site contains lots of useful information, including guides, references and links to open-source mods you can learn from.​
    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.​
    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.​
    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.

    Back to top

    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.

    Back to top

    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:
    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.

    Back to top

    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:
    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

    Back to top

    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:
    author = Jofairden
    version = 0.1
    displayName = 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, right now we have only hit 1.3, many years after initial release!

    Back to top

    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.

    Back to top

    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:
    using Terraria.ID;
    using Terraria.ModLoader;
    namespace JofairdensMod.Items
        public class JofairdensSword : ModItem
            public override void SetStaticDefaults()
                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);
    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:
    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:
    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:
    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:
            public override void AddRecipes()
                ModRecipe recipe = new ModRecipe(mod);
                recipe.AddIngredient(ItemID.DirtBlock, 10);
    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:
                recipe = new ModRecipe(mod); // Same object, new instance
                recipe.AddIngredient(Some other ingredient);
    More on recipes in a later tutorial.

    Back to top
    What next?

    Right now you have the barebones set up for your mod. If you go in-game and try to build the mod, it should work.

    What do I need to know about 'Mods' and 'Mod Sources' in the in-game menu?
    'Mods' refers to your 'Mods' folder in your documents. This is where all of your .tmod files are located. These files are the required files for you to be able to play mods. You either get them from creating your own mod(s), or by downloading others.

    Let's take a look at the 'Mods' section. This section holds all .tmod files (mods) you have downloaded. (or your own built mods)

    Right under the mod's name, it'll either say 'Disabled' or 'Enabled. Disabled mods will not be part of your Terraria.
    If you want to enable a mod, either click 'Click to enable' or click 'Enable All'.
    Make sure to click 'Reload mods' when you've changed enabled/disabled statuses.
    The 'More info' button shows an information tab about the mod.

    'Mod Sources' refers to your 'Mod Sources ' folder in your documents. This is where all your source files for your mods are located, which for me would be 'JofairdensMod'. In this menu you see several buttons, showcased in the following image.

    • The 'Build' button button under a Mod's name will then proceed to build the mod into a .tmod file. You shouldn't get any errors if everything in your source-code (src) is correct.
    • The 'Build + Reload' button does the exact same thing, but also reloads all your mods. Reloading basically implements all your enabled mods in the 'Mods' section into Terraria.
    • The 'Publish' button allows you to publish your mod to the mod browser, more on that later.
    • The buttons below all your mod sources should speak for themselves, manage published is for 'managing' mods you've published on the mod browser.
    • The Mod Browser allows you to browse and easily download mods that are published on there. The browser should be self explanatory.


    Back to top


    Always have an instance of your mod available
    As I said earlier, sometimes you will have a 'mod' object available but not always. You can make your own mod instance object so you always have access to your mod instance for these scenarios. This can be done as follows:
    • Declare a new static object for your instance (in your mod class)
    public static JofairdensMod instance;
    • Next, override the Load() hook and set your object instance here
    public override void Load()
       instance = this;

    Now you can access <YourMod>.instance (e.g. JofairdensMod.instance) when the mod object is not available.

    Back to top



    Back to top
    Last edited: Jul 10, 2017
    Vedomir, leechheart, Ori and 14 others like this.
  2. Scourge of light

    Scourge of light Terrarian

    What do I do if I get this Capture.PNG
  3. Jofairden

    Jofairden Golem

    You fully install tML, which you didn't. One of the files can't be found
  4. Scourge of light

    Scourge of light Terrarian

    what should I do
    reinstall it?
  5. Kitten9997

    Kitten9997 Terrarian

    Scourge of light, I had the same error. I found out it was because my antivirus wrongly detected tModLoaderMac.exe as malicious software. You might need to add the terraria steam folder (or whereever terraria is installed) to the exceptions for your antivirus. That fixed the problem with me, and the antivirus stopped trying to delete tModLoaderMac.exe
    Enoki The Truffle likes this.
  6. Spiked Penguin

    Spiked Penguin Terrarian

    Well, so much for my idea lmao. Great job explaining and I have over looked some of your other guides very well done.
  7. Danstr

    Danstr Terrarian


    Attached Files:

  8. Kazzymodus

    Kazzymodus Lunatic Cultist

    Find the Steamworks.NET.dll file in your Terraria Steam folder and delete it.
  9. Danstr

    Danstr Terrarian

    Really? Can I ask Why? (I'm a Noob LOL)
  10. Kazzymodus

    Kazzymodus Lunatic Cultist

    Essentially because you have two of those, and the program doesn't know which one to use.
  11. Danstr

    Danstr Terrarian

    Ah, well that makes sense. Thanks!
    Kazzymodus likes this.
  12. baileydog41

    baileydog41 Terrarian

    Guys pls help I got tmod loader and I installed a mod that whenever I open Terraria with mods it crashes, so I cant acess the mod folder to delete the mod, HOW DO I GET TO MY MODS FOLDER ON MAC WITHOUT GOING THROUGH ON TERRARIA!! Pls Help
  13. AndreasNylleriMoon

    AndreasNylleriMoon Terrarian

    Okay First what kind of computer do you use? (Mac,linux,PC,etc.)
  14. SnowLeopard Games

    SnowLeopard Games Terrarian

    on mac there is a bar at the top of the screen that has the name of the applications and some other text E.G: window, file, edit, etc.
    click on finder and click go then hold option/alt and a file called library will appear click that and then click Application Support next scroll down and find the Terraria folder DO NOT GO INTO STEAM next click ModLoader and then go into mods and delete the mod that is stuffing your game up.
    --- Double Post Merged, Feb 25, 2017, Original Post Date: Feb 25, 2017 ---
    *facepalm read the post again
  15. Piggy0007

    Piggy0007 Terrarian

    I got this..
    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(3,17) : error CS1010: Newline in constant

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(3,17) : error CS1012: Too many characters in character literal

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(5,14) : error CS1010: Newline in constant

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(5,14) : error CS1012: Too many characters in character literal

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(7,16) : error CS1010: Newline in constant

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(7,16) : error CS1012: Too many characters in character literal

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(3,17) : error CS1514: { expected

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(5,14) : error CS1514: { expected

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(5,14) : error CS1519: Invalid token ''\u0073'' in class, struct, or interface member declaration

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(7,16) : error CS1519: Invalid token ''\u0073'' in class, struct, or interface member declaration

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(9,15) : error CS1519: Invalid token '=' in class, struct, or interface member declaration

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(9,21) : error CS1520: Method must have a return type

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(14,5) : error CS1597: Semicolon after method or accessor block is not valid

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Piglet'sExpansion.cs(17,1) : error CS1022: Type or namespace definition, or end-of-file expected

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Items\Pigifier.cs(4,17) : error CS1010: Newline in constant

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Items\Pigifier.cs(4,17) : error CS1012: Too many characters in character literal

    c:\Users\bhewett\Documents\My Games\Terraria\ModLoader\Mod Sources\Piglet'sExpansion\Items\Pigifier.cs(4,17) : error CS1514: { expected

    And this http://images.akamai.steamuserconte...847/C7777D8E63AF80A32537869C0D2A3B4D5990243A/
  16. Jofairden

    Jofairden Golem

    You're going to need to show your code of Pigifier.cs before anyone can help, use
    Piggy0007 likes this.
  17. Piggy0007

    Piggy0007 Terrarian

    Thanks. Also, is this good?
    author = Piggy0007
    *Inside of Build*
    version = 0.1

    *Inside of Items
    Pigifier.cs Pigifier (Image)
    *Outside of Items*
    *Inside of Build*
    version = 0.1
    displayName = Piglet's Expansion
    homepage =
    hideCode = false
    hideResources = false
    includeSource = true
    buildIgnore = *.csproj, *.user, obj\*, bin\*, .vs\*
    includePDB = true[/QUOTE]
    *Outside of build*
    *Inside of description*
    Piglet's Expansion, a WIP.
    *Outside of description*

    Last edited: 9 minutes ago
    --- Double Post Merged, Mar 7, 2017, Original Post Date: Mar 7, 2017 ---
    Never mind, i just fixed it by deleting the cs pigifier and cs Piglet's Expansion...
  18. Fluffertop

    Fluffertop Terrarian

    --- Double Post Merged, Mar 27, 2017, Original Post Date: Mar 27, 2017 ---
    I got an error that said: error CS1514: { expected. I DON'T KNOW WHAT IT MEANS. PLS HELP!!!
  19. silverninja510

    silverninja510 Terrarian

    When I try to build the testmod I get this error 20170410074024_1.jpg Any advice?
  20. OverlordCMD

    OverlordCMD Skeletron Prime

    I cant find mod sources.
    JustInsane3014 likes this.