Skip to content

Content Loading

JonataOliveiraa edited this page Nov 14, 2026 · 1 revision
Intermediate

Hooks change what the game already has; content classes add new things. A class that extends ModItem becomes a new item, one that extends ModNPC a new NPC, and so on, with the same names, in the same namespace (Terraria.ModLoader) and loaded in the same order as in tModLoader. You never register them by hand. This page explains what Bunny Loader does for you: which classes it loads, in what order, how one class becomes many items in the world, and how to find any content by its name.

What gets loaded

Every class in your .dll that implements ILoadable (every ModType, like ModItem, does) is loaded on its own, in the order of its full name, when it:

  • is not abstract and has a constructor without parameters;
  • has no [Autoload(false)], on itself or on a base class;
  • has no [Autoload(Side = ModSide.Server)] (the phone has no dedicated server, so server-only content never loads);
  • returns true from IsLoadingEnabled(mod) (the default).
// Only when the option is on.
public override bool IsLoadingEnabled(Mod mod) => MyOptions.ExtraItems;

A class left out of the autoload can still be loaded from Mod.Load:

[Autoload(false)]
public class SecretItem : ModItem { /* ... */ }

public class MyMod : Mod
{
    public override void Load()
    {
        AddContent<SecretItem>();
    }
}

To turn the autoload off for the whole mod, set ContentAutoloadingEnabled = false in the mod's constructor and call AddContent for each class. AddContent only works while the mod loads: from PostSetupContent on, it throws.

Your own classes can join the load too: implement ILoadable and its Load(Mod mod) runs with the content's, and ModContent.GetInstance<T>() finds the instance.

The order

When What runs Thread
1. The mod loads (the game is opening) each content class: IsLoadingEnabled, then its Load(); then your Mod.Load(), then each ModSystem's OnModLoad() the loader's
2. The game knows the new types each ModSystem's ResizeArrays() and OnLocalizationsLoaded(), then each item's and each ModSystem's SetStaticDefaults() the game's
3. All mods' content is in the game Mod.PostSetupContent(), then each ModSystem's the game's
4. Mod.AddRecipeGroups(), then each ModSystem's the game's
5. Mod.AddRecipes(), each ModSystem's, each item's and each GlobalItem's AddRecipes() the game's
6. Mod.PostAddRecipes(), then each ModSystem's the game's
7. each ModSystem's PostSetupRecipes() the game's

Each of steps 3 to 6 runs in every C# mod (in load order) before the next one starts, as in tModLoader: in AddRecipes you can use any mod's items. An exception in one mod's step goes to the log and the error panel, and the other mods go on.

Two differences from tModLoader:

  • Unload() exists (on Mod, ModType and ILoadable) but is never called: Bunny Loader does not unload mods while the game runs; changing mods restarts the game.
  • ModSystem has, for now, only these steps (SetStaticDefaults, PostSetupContent, AddRecipeGroups, AddRecipes, PostAddRecipes); its other hooks come later.

The template and its instances

The object Bunny Loader creates and registers is the template. In Load and SetStaticDefaults it has no game item yet: Item.IsNull is true. Each time the game fills in an item of your type (Item.SetDefaults), your SetDefaults runs in a new instance, with Item set to that item and Type and Mod copied from the template.

By default the new instance is created by your class's constructor, so fields have their initial values, not the template's. To copy the template instead (the fields you set in Load, for example), override CloneNewInstances:

protected override bool CloneNewInstances => true;

The copy is shallow: a list or array in a field is shared with the template. Override Clone(Item newEntity) to copy it deeper:

public List<int> Charges = new();

public override ModItem Clone(Item newEntity)
{
    var copy = (ShinyRock)base.Clone(newEntity);
    copy.Charges = new List<int>(Charges);
    return copy;
}

Item.ModItem

The instance stays with its item: item.ModItem gives it back, the same object every time, so its fields are per item.

if (Main.LocalPlayer.HeldItem.ModItem is ShinyRock rock)
    rock.Polish++;
  • item.ModItem is null for an item of the game, and becomes null again when SetDefaults turns the item into a vanilla one.
  • Item.Clone() gives the copy a Clone of the instance (with your Clone override, if there is one), so the data follows the item into the copy.
  • An item that became your type without SetDefaults (its type written by hand) gets a new instance the first time item.ModItem is read.
  • The data lives as long as the game keeps the item: Bunny Loader holds no item alive. To keep it across sessions, save it (next section); to send it to the other players, override NetSend and NetReceive (Networking).

Finding content by name

The full name of a content class is <mod>/<Name>: the mod's internal name (the name of its assembly) and the class name. Any mod can find any other mod's content by it:

ModItem rock = ModContent.Find<ModItem>("MyMod/ShinyRock");
if (ModContent.TryFind("OtherMod/Ruby", out ModItem ruby))
    Mod.Logger.Info($"OtherMod is here, and its ruby is item {ruby.Type}");

ModItem mine = Mod.Find<ModItem>("ShinyRock");   // in this mod

Find throws when there is no such content; TryFind returns false.


Systems →

Clone this wiki locally