Mod Development Guide
Learn how to create amazing Terraria mods with tModLoader's C# API
Prerequisites
Development Environment
- • Visual Studio 2022 (recommended)
- • JetBrains Rider
- • Visual Studio Code with C# extension
- • .NET 6.0 SDK or later
Knowledge Requirements
- • Basic C# programming
- • Object-oriented concepts
- • Familiarity with Terraria gameplay
- • Basic understanding of game development
Development Setup
1 Install Development Tools
Choose your preferred C# development environment:
2 Create Your First Mod
Use tModLoader's built-in tools to create a mod template:
- Launch tModLoader and go to "Workshop" → "Develop Mods"
- Click "Create Mod" and enter your mod details
- Choose a unique mod name (no spaces or special characters)
- Click "Create" to generate the mod template
This creates a basic mod structure in your ModSources folder with all necessary files.
Basic Mod Structure
Every tModLoader mod follows a standard structure:
YourModName/
├── build.txt # Mod metadata and dependencies
├── description.txt # Mod description for the browser
├── icon.png # Mod icon (64x64 recommended)
├── YourModName.cs # Main mod class
├── Items/ # Custom items
├── NPCs/ # Custom NPCs
├── Projectiles/ # Custom projectiles
├── Tiles/ # Custom tiles/blocks
├── Walls/ # Custom walls
├── Buffs/ # Custom buffs/debuffs
└── Sounds/ # Custom audio filesExample Mod Class
Here's a basic mod class structure:
using Terraria.ModLoader;
namespace YourModName
{
public class YourModName : Mod
{
public override void PostSetupContent()
{
// Code that runs after all mods are loaded
}
public override void PostUpdateInput()
{
// Code that runs every frame
}
public override void Unload()
{
// Cleanup code when mod is unloaded
}
}
}build.txt Configuration
The build.txt file contains important metadata about your mod:
displayName = Your Mod Name
author = Your Name
version = 1.0.0
modReferences =
buildIgnore = *.csproj, *.user, *.suo, bin/, obj/, .vs/
homepage = https://github.com/yourusername/yourmod
description = A brief description of what your mod doesCreating Your First Item
Let's create a simple custom sword as your first item:
Create the Item Class
Create a new file: Items/ExampleSword.cs
using Terraria;
using Terraria.ID;
using Terraria.ModLoader;
namespace YourModName.Items
{
public class ExampleSword : ModItem
{
public override void SetDefaults()
{
// Basic item properties
Item.damage = 50;
Item.DamageType = DamageClass.Melee;
Item.width = 40;
Item.height = 40;
Item.useTime = 20;
Item.useAnimation = 20;
Item.useStyle = ItemUseStyleID.Swing;
Item.knockBack = 6;
Item.value = Item.buyPrice(gold: 1);
Item.rare = ItemRarityID.Green;
Item.UseSound = SoundID.Item1;
Item.autoReuse = true;
}
public override void AddRecipes()
{
Recipe recipe = CreateRecipe();
recipe.AddIngredient(ItemID.IronBar, 10);
recipe.AddIngredient(ItemID.Wood, 5);
recipe.AddTile(TileID.Anvils);
recipe.Register();
}
}
}Add Item Texture
Create a 40x40 pixel PNG image and save it as:
Items/ExampleSword.png
The file name must match your class name exactly.
Build and Test Your Mod
Build + Reload Workflow
tModLoader's powerful development feature allows you to test changes instantly:
- In tModLoader, go to "Workshop" → "Develop Mods"
- Find your mod in the list and click "Build + Reload"
- Wait for compilation to complete
- Your mod will automatically reload with changes
- Test your new item in-game
Pro Tip: Use "Build + Reload" frequently during development. It's much faster than restarting the game!
Common Build Errors
- Missing texture: Ensure PNG file matches class name exactly
- Compilation errors: Check syntax and using statements
- Missing references: Verify ModLoader references are correct
- Build.txt errors: Check mod metadata formatting
Advanced Development Topics
Publishing Your Mod
Publishing to Steam Workshop
- Ensure your mod builds without errors
- Go to "Workshop" → "Develop Mods"
- Click "Publish" next to your mod
- Fill out the Steam Workshop form with description and tags
- Upload screenshots and set visibility
- Click "Publish" to make it live
Your mod will be available in the mod browser within a few minutes of publishing.
Best Practices for Publishing
Content Guidelines
- Write clear, detailed descriptions
- Include high-quality screenshots
- Test thoroughly before publishing
- Document known issues
Technical Requirements
- No compilation errors or warnings
- Proper null checking
- Multiplayer compatibility testing
- Performance optimization