Repository navigation
Mod Structure
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.
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.
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. |
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 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.
Bunny Loader wiki ·
Discord ·
Repository ·
BL Editor
Written for Bunny Loader 0.5.5-beta and Terraria Mobile 1.4.5.8.6.
Bunny Loader is not affiliated with Re-Logic or 505 Games.
