Skip to content

Mod Structure

JonataOliveiraa edited this page Nov 14, 2026 · 1 revision
Getting started

A mod is a folder with a fixed shape: a manifest that says what the mod is, the code, and folders for textures, sounds and translations. Bunny Loader packs that folder into a package, a .bl or .zip file, when you share it or install it. This page goes through each part: the folder, the manifest, the code, and how your code finds its textures and other files.

The folder

Here is a mod with one item, as Your first mod leaves it:

FirstMod/
  manifest.json                         what the mod is
  FirstMod.cs                           the mod class
  Content/Items/FirstSword.cs           a ModItem
  Content/Items/FirstSword.png          its picture
  Localization/en-US_Mods.FirstMod.hjson   its name, in English
  icon.png                              the mod's picture in the list (optional)
  description.md                        the text of the mod's page (optional)

The name of the folder is the mod's ID, its internal name, and so is the name of the mod class and of its file. Other mods find yours by this ID, its translation keys start with Mods.FirstMod., and the compiled code is named after it (FirstMod.dll). The ID may have letters, numbers and _, and must start with a letter. BL Editor only uses lowercase IDs, such as firstmod; Bunny Loader accepts both.

The Assets/, Common/, Content/ and Localization/ folders follow tModLoader's habit: new content in Content, code that changes what exists in Common, loose sounds and textures in Assets, translations in Localization. Bunny Loader does not require any of them: a texture is found through the namespace of its class (see below), and translation files anywhere in the mod (Localization). They are there to keep big mods tidy, and you can organize your code as you like. Folders named bin/ and obj/, and .csproj files, never go into a package.

The manifest

manifest.json is the mod's card. Bunny Loader reads it before it loads a single line of code, to show the mod in the list and to know which files to load.

{
  "uid": "24f03eb3-c4c8-44cf-bddf-9e62105abe24",
  "id": "FirstMod",
  "name": "First Mod",
  "version": "1.0.0",
  "authors": [{ "name": "You" }],
  "type": "mod",
  "category": "Armas",
  "summary": "My first sword.",
  "blVersion": 3
}

The uid is the mod's identity: a lowercase UUID that is also the name of its folder once installed. Two packages with the same uid are the same mod, so installing one replaces the other, which is how updates work. Generate your own once (BL Editor does it for you; on a PC, New-Guid in PowerShell) and never change it after you share the mod. The id is the ID described above.

The other fields are reference data, so here they are in a table:

Field
uid Required. The identity, as above.
id Required. The internal name.
name, version What the list shows.
authors Plain names, or objects with a photo (from authors/), a role, a color and a link.
type mod for a mod; texture and font packs use texture and font.
category Free text. Textura, Armas, Jogabilidade, Cheat, Utilidade and Itens get their own color and icon.
summary, updated The line on the mod's card and the date of the latest version (YYYY-MM-DD). The long description goes in description.md.
license, links, pages, theme Optional: the license, link buttons, extra tabs and the colors and background of the mod's page.
dependencies Optional: the mods (by id or uid) that must load before this one; if one of them is not turned on, this one does not load.
blVersion The package format: 3.

The code: sources or a compiled .dll

A package can carry its code in two ways, and Bunny Loader handles both. If the folder has FirstMod.dll, built on a PC as in Setup on PC, Bunny Loader loads it as it is. If there is no .dll, only .cs files, as in a project from BL Editor, Bunny Loader compiles them itself: every .cs file in the folder and its subfolders becomes part of one assembly named after the mod. A .dll that sits next to the sources, such as a library you ship, is a reference for that compilation and is found again when the mod runs.

Compiling on the phone happens once. Bunny Loader writes the result to bin/ with a stamp, bin/FirstMod.build.json, that holds a hash of every source file and shipped library, the version of Bunny Loader's API and the hash of the .dll. Each time the game starts, it compares the stamp with the sources, which takes a few milliseconds, and only compiles again when something changed: a source file you edited, or an update of Bunny Loader that changed the API. The first compilation is the slow one, because the compiler itself has to warm up: from several seconds for a small mod to minutes for one with hundreds of files. The compiler is deterministic, so the same sources give the same .dll, byte for byte, on the phone and on a PC.

The sources are compiled with the same options as the .csproj in Setup on PC: the newest C#, nullable on, unsafe allowed and no implicit using lines, against BunnyLoader.dll and the .NET libraries on the phone. If the code does not compile, the mod stays off and the log names each error with its file and line:

E [mod] mod 24f03eb3-...: Content/Items/FirstSword.cs(14,23): CS0103: The name 'Damag' does not exist in the current context
E [mod] mod 24f03eb3-...: FirstMod.cs did not compile (1 error(s))

Which way is better depends on what you want. Sources are the easiest to share, since anyone can read the mod and change it on the phone. A .dll built on a PC is what you want while writing a big mod, because the IDE checks the code as you type and NuGet packages are one line in the .csproj. You can also do both: ship the .dll and keep the sources in the package for others to read.

Textures and files

Textures come as Asset<Texture2D> (using ReLogic.Content; and using Microsoft.Xna.Framework.Graphics;), as in tModLoader:

// A PNG of this mod, by its path in the mod folder (no extension).
Asset<Texture2D> glow = Mod.Assets.Request<Texture2D>("Content/Items/ShinyRock_Glow");

// The same, from anywhere: the mod's name first.
Asset<Texture2D> same = ModContent.Request<Texture2D>("MyMod/Content/Items/ShinyRock_Glow");

// A game image.
Asset<Texture2D> pickaxe = ModContent.Request<Texture2D>("Terraria/Images/Item_1");

The same path gives back the same Asset. A missing PNG throws right at the request; Mod.Assets.HasAsset<Texture2D>(path) and ModContent.HasAsset("MyMod/...") ask first.

The texture loads on the game thread only. The game's engine (Unity) kills the app when a texture is created anywhere else, and mods load on another thread. So a request made in Load stays NotLoaded, and the texture loads the first time something reads Value (or calls Wait()) on the game thread: in SetStaticDefaults, PostSetupContent, a hook or a draw call. Reading Value in Load throws an InvalidOperationException that says so. Keep the Asset from Load in a field, and read Value later:

public static Asset<Texture2D> Glow;

public override void Load() => Glow = Mod.Assets.Request<Texture2D>("Content/Items/ShinyRock_Glow");

// later, in a hook on the game thread:
Texture2D texture = Glow.Value;
int width = texture.Width;

For now only Texture2D can be requested (sounds, effects and fonts come with their loaders), and a game image that the mobile version does not have throws when it loads.

Any other file of the mod is read by its path in the mod folder, with the extension:

Call Gives
Mod.FileExists("Data/drops.json") true if the file is there
Mod.GetFileBytes("Data/drops.json") its bytes
Mod.GetFileStream("Data/drops.json") a Stream (dispose it)
Mod.GetFileNames() every file of the mod, like "Content/Items/ShinyRock.png"
ModContent.GetFileBytes("MyMod/Data/drops.json") the same, by the mod's name

A path that leaves the mod's folder ("../...") is never read.


← Your first mod  ·  Testing and errors →

Clone this wiki locally