tModLoader API Tutorial for Developers 2025

Core API Classes Overview

ModItem

Create custom weapons, tools, accessories, and consumables

• SetDefaults() - Define item properties
• AddRecipes() - Create crafting recipes
• UseItem() - Custom use behavior

ModNPC

Create enemies, town NPCs, and bosses with custom AI

• SetDefaults() - NPC stats and behavior
• AI() - Custom artificial intelligence
• ModifyNPCLoot() - Define drop tables

Example: Creating an Advanced Magic Weapon

public class AdvancedStaff : ModItem
{
    public override void SetDefaults()
    {
        Item.damage = 75;
        Item.DamageType = DamageClass.Magic;
        Item.mana = 15;
        Item.width = 40;
        Item.height = 40;
        Item.useTime = 30;
        Item.useAnimation = 30;
        Item.useStyle = ItemUseStyleID.Shoot;
        Item.knockBack = 5;
        Item.value = Item.buyPrice(gold: 10);
        Item.rare = ItemRarityID.Pink;
        Item.UseSound = SoundID.Item20;
        Item.autoReuse = true;
        Item.shoot = ModContent.ProjectileType<MagicBolt>();
        Item.shootSpeed = 16f;
    }

    public override bool Shoot(Player player, EntitySource_ItemUse_WithAmmo source,
                              Vector2 position, Vector2 velocity, int type, int damage, float knockback)
    {
        // Shoot 3 projectiles in a spread
        for (int i = 0; i < 3; i++)
        {
            Vector2 newVelocity = velocity.RotatedByRandom(MathHelper.ToRadians(15));
            Projectile.NewProjectile(source, position, newVelocity, type, damage, knockback, player.whoAmI);
        }
        return false; // Don't shoot the default projectile
    }
}

This creates a staff that shoots 3 magic bolts in a spread pattern, demonstrating advanced projectile mechanics.

API Best Practices 2025

✅ Do's

• Use ModContent.ItemType<T>() for item references
• Implement proper null checking
• Follow C# naming conventions
• Test in multiplayer environment
• Document your code with comments

❌ Don'ts

• Don't hardcode item IDs
• Don't access Main.player directly in MP
• Don't ignore compiler warnings
• Don't use heavy operations in AI()
• Don't modify vanilla content unnecessarily

Continue Learning

This tutorial covers the basics. For comprehensive API documentation and advanced examples, check out these resources:

Full API Reference Official Docs