API Reference
Complete reference for tModLoader's C# API with examples and best practices
API Reference
All Levels
v2025.07.3.0
Quick Access
Core Classes
ModItem
The base class for creating custom items. Inherit from ModItem to create weapons, tools, accessories, and consumables.
Key Methods:
SetDefaults()
Set item properties like damage, size, rarity, and use style
AddRecipes()
Define crafting recipes for your item
UseItem(Player player)
Custom behavior when item is used
Example Implementation:
public class MagicSword : ModItem
{
public override void SetDefaults()
{
Item.damage = 80;
Item.DamageType = DamageClass.Magic;
Item.mana = 10;
Item.width = 44;
Item.height = 44;
Item.useTime = 25;
Item.useAnimation = 25;
Item.useStyle = ItemUseStyleID.Shoot;
Item.knockBack = 5;
Item.value = Item.buyPrice(gold: 5);
Item.rare = ItemRarityID.Pink;
Item.UseSound = SoundID.Item20;
Item.autoReuse = true;
Item.shoot = ProjectileID.MagicMissile;
Item.shootSpeed = 16f;
}
}ModNPC
Create custom NPCs including enemies, town NPCs, and bosses with custom AI and behavior.
Essential Methods:
SetDefaults()
Set NPC stats and properties
AI()
Custom AI behavior logic
ModifyNPCLoot()
Define drop tables and loot
OnKill()
Actions when NPC is killed
public class ExampleEnemy : ModNPC
{
public override void SetDefaults()
{
NPC.width = 40;
NPC.height = 56;
NPC.damage = 15;
NPC.defense = 6;
NPC.lifeMax = 100;
NPC.HitSound = SoundID.NPCHit1;
NPC.DeathSound = SoundID.NPCDeath2;
NPC.value = 60f;
NPC.knockBackResist = 0.5f;
NPC.aiStyle = NPCAIStyleID.Fighter;
AIType = NPCID.Zombie;
}
}Common Development Patterns
Creating Recipes
public override void AddRecipes()
{
Recipe recipe = CreateRecipe();
recipe.AddIngredient(ItemID.IronBar, 5);
recipe.AddIngredient(ItemID.Wood, 10);
recipe.AddIngredient(ModContent.ItemType<CustomItem>(), 1);
recipe.AddTile(TileID.WorkBenches);
recipe.AddCondition(Recipe.Condition.InGraveyard);
recipe.Register();
}Recipes are automatically synced in multiplayer and appear in recipe browsers.
Custom Projectiles
public class MagicBolt : ModProjectile
{
public override void SetDefaults()
{
Projectile.width = 16;
Projectile.height = 16;
Projectile.friendly = true;
Projectile.penetrate = 3;
Projectile.timeLeft = 600;
Projectile.light = 0.5f;
Projectile.DamageType = DamageClass.Magic;
}
public override void AI()
{
// Custom movement and visual effects
Projectile.rotation += 0.4f;
if (Main.rand.NextBool(3))
{
Dust.NewDust(Projectile.position, Projectile.width,
Projectile.height, DustID.Electric);
}
}
}Global Modifications
Modify existing game content using Global classes:
public class GlobalItemChanges : GlobalItem
{
public override void SetStaticDefaults()
{
// Modify all items of a specific type
}
public override void ModifyTooltips(Item item, List<TooltipLine> tooltips)
{
if (item.type == ItemID.TerraBlade)
{
tooltips.Add(new TooltipLine(Mod, "CustomTooltip",
"Enhanced by YourMod!"));
}
}
}Best Practices
Do's
- Use ModContent.ItemType<T>() for referencing custom items
- Implement proper null checking
- Use meaningful variable and class names
- Test in multiplayer environment
- Follow C# naming conventions
- Document your code with comments
Don'ts
- Don't hardcode item IDs - use constants
- Don't access Main.player directly in multiplayer
- Don't forget to handle edge cases
- Don't use heavy operations in AI() methods
- Don't modify vanilla content unnecessarily
- Don't ignore compiler warnings
Useful Utilities & Helpers
Common Helper Methods
// Get item type from mod item class
int itemType = ModContent.ItemType<MyCustomItem>();
// Check if mod is loaded
bool calamityLoaded = ModLoader.HasMod("CalamityMod");
// Create dust effects
Dust.NewDust(position, width, height, DustID.Electric);
// Spawn projectiles
Projectile.NewProjectile(source, position, velocity, type, damage, knockback);
// Play sounds
SoundEngine.PlaySound(SoundID.Item1, position);Networking Helpers
// Send data to server
ModPacket packet = Mod.GetPacket();
packet.Write((byte)MessageType.ExampleMessage);
packet.Write(someData);
packet.Send();
// Handle received packets
public override void HandlePacket(BinaryReader reader, int whoAmI)
{
MessageType msgType = (MessageType)reader.ReadByte();
switch (msgType)
{
case MessageType.ExampleMessage:
// Handle message
break;
}
}