How to Create Your First Terraria Mod in 2025

What You'll Learn

• Setting up your development environment
• Creating a custom sword with unique properties
• Understanding tModLoader's C# API
• Testing and debugging your mod
• Publishing to Steam Workshop

Prerequisites

Required Knowledge

• Basic C# programming (variables, methods, classes)
• Familiarity with Terraria gameplay
• Basic understanding of object-oriented programming

Required Software

• tModLoader installed and working
• Visual Studio 2022 (recommended) or VS Code
• .NET 6.0 SDK or later

Step 1: Development Environment Setup

Creating Your Mod Template

Launch tModLoader and go to "Workshop" → "Develop Mods"
Click "Create Mod"
Enter your mod name (e.g., "MyFirstMod" - no spaces!)
Fill in author name and description
Click "Create"

This creates a mod template in your ModSources folder with all necessary files.

Step 2: Creating a Custom Sword

Let's create a simple but effective custom sword. This will teach you the basics of item creation.

Create the Item Class

Create a new file: Items/BeginnerSword.cs

using Terraria;
using Terraria.ID;
using Terraria.ModLoader;

namespace MyFirstMod.Items
{
    public class BeginnerSword : ModItem
    {
        public override void SetDefaults()
        {
            // Basic item properties
            Item.damage = 45;                    // Damage value
            Item.DamageType = DamageClass.Melee; // Damage type
            Item.width = 40;                     // Hitbox width
            Item.height = 40;                    // Hitbox height
            Item.useTime = 20;                   // Use speed
            Item.useAnimation = 20;              // Animation speed
            Item.useStyle = ItemUseStyleID.Swing;// How it's used
            Item.knockBack = 6;                  // Knockback strength
            Item.value = Item.buyPrice(gold: 2); // Sell value
            Item.rare = ItemRarityID.Green;      // Rarity color
            Item.UseSound = SoundID.Item1;       // Use sound
            Item.autoReuse = true;               // Can auto-swing
        }

        public override void AddRecipes()
        {
            Recipe recipe = CreateRecipe();
            recipe.AddIngredient(ItemID.IronBar, 15);
            recipe.AddIngredient(ItemID.Wood, 10);
            recipe.AddTile(TileID.Anvils);
            recipe.Register();
        }
    }
}

Understanding the Code

SetDefaults(): Defines all the item's properties like damage, size, and behavior
AddRecipes(): Creates crafting recipes for your item
DamageClass.Melee: Makes it scale with melee damage bonuses
ItemRarityID.Green: Sets the rarity color (affects item name color)

Step 3: Build and Test

Using Build + Reload

tModLoader's best feature for developers is the "Build + Reload" system that lets you test changes instantly:

In tModLoader, go to "Workshop" → "Develop Mods"
Find your mod and click "Build + Reload"
Wait for compilation (should take 5-10 seconds)
Your mod reloads automatically with changes
Test your new sword in-game!

Testing Your Sword

To test your new sword:

1. Open your inventory and check if you can craft it (you'll need iron bars and wood)
2. Craft the sword and test its damage on enemies
3. Check that the sound effect and animation work correctly
4. Verify the auto-swing functionality

Adding Advanced Features

Custom On-Hit Effects

Let's add a special effect when your sword hits an enemy:

public override void OnHitNPC(Player player, NPC target, NPC.HitInfo hit, int damageDone)
{
    // 20% chance to inflict fire debuff
    if (Main.rand.NextBool(5))
    {
        target.AddBuff(BuffID.OnFire, 180); // 3 seconds of fire
    }

    // Spawn some visual effects
    for (int i = 0; i < 10; i++)
    {
        Dust.NewDust(target.position, target.width, target.height, DustID.Fire);
    }
}

This adds a 20% chance to set enemies on fire and creates fire particle effects on hit.

Custom Tooltip

Add custom text to your item's tooltip:

public override void ModifyTooltips(List<TooltipLine> tooltips)
{
    TooltipLine line = new TooltipLine(Mod, "CustomTooltip", "A sword forged by a beginner modder!");
    line.OverrideColor = Color.Orange;
    tooltips.Add(line);
}

Publishing Your Mod

Publishing to Steam Workshop

Ensure your mod builds without errors
Add an icon.png file (64x64 pixels) to your mod folder
Write a good description.txt explaining what your mod does
In "Develop Mods", click "Publish" next to your mod
Fill out the Steam Workshop form with tags and description
Upload screenshots showing your mod in action
Click "Publish" to make it live!

Tips for Successful Publishing

• Write clear, detailed descriptions
• Include high-quality screenshots
• Use relevant tags for discoverability
• Test thoroughly before publishing
• Respond to user feedback and comments

Congratulations! You're Now a Mod Developer!

You've created your first Terraria mod! This is just the beginning - tModLoader's API can do incredible things. Explore NPCs, projectiles, tiles, and world generation next.

Advanced Development API Reference