Skip to content

Saving Data

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

Anything your mod keeps in a field is lost when the game closes, unless it is saved. Items, players and the world can each save their own data with SaveData and LoadData, using tModLoader's TagCompound. Bunny Loader keeps that data in files of its own next to the game's saves, so a character or a world still opens after the mod is removed. Data that belongs to the whole world, saved by a ModSystem, is explained on Systems.

Saving: SaveData and LoadData

using Terraria.ModLoader.IO;

public class ShinyRock : ModItem
{
    public int Polish;

    public override void SaveData(TagCompound tag) => tag["polish"] = Polish;

    public override void LoadData(TagCompound tag) => Polish = tag.GetInt("polish");
}

The item's data goes with the item wherever the game saves it: the player's inventory, equipment (armor, accessories, dyes), piggy bank, safe and the other banks (in <player>.plr.bl, next to the .plr) and chests (<world>.wld.bl). Items on the ground are not saved, as in the game. Bunny Loader stores each item by its name, so the data survives other mods being added or removed; an item of a mod that is not loaded keeps its data until the mod comes back.

TagCompound is tModLoader's:

Call Does
tag["key"] = value sets (or replaces) a value
tag.Add("key", value) sets; throws if the key is already there
tag.GetInt("key"), GetFloat, GetBool, GetString, GetByteArray, GetIntArray, GetCompound, GetList<T> reads; a missing key gives 0, "", an empty list or an empty TagCompound
tag.Get<T>("key") reads as T (numbers convert); a value of another kind throws
tag.TryGet("key", out T value) false instead of throwing
tag.ContainsKey("key"), tag.Remove("key") as in a dictionary

What can go in: bool, the number types, string, byte[], int[], lists of these, and other TagCompounds. For a Vector2 or a Color, save their fields.

  • If LoadData throws, the error goes to the log, and the saved data is kept as it was: the next save writes it back untouched instead of losing it.
  • The data is stored as JSON in the item sidecars, next to the game's save.
  • TagIO.ToFile(tag, path) and TagIO.FromFile(path) write and read a TagCompound to a file of your own, in tModLoader's binary format (compressed by default).

A GlobalItem with InstancePerEntity saves its data the same way, with SaveData(item, tag) and LoadData(item, tag) (Global classes).


← Systems  ·  Mod configs →

Clone this wiki locally