Skip to content

Making Font Packs

JonataOliveiraa edited this page Nov 14, 2026 · 1 revision
Texture and font packs

A font pack replaces the fonts the game uses for its text, from item names to the numbers that pop up in combat. Like a texture pack, it is a package without code. The easiest way to make one is BL Editor, which turns a .ttf or .otf file into the game's five fonts; the files it produces are described below.

MyFont/
  manifest.json      "type": "font", "blVersion": 3
  Fonts/
    Mouse_Text.json  Mouse_Text.0.png
    Item_Stack.json  Item_Stack.0.png
    Death_Text.json  Death_Text.0.png
    Combat_Text.json Combat_Text.0.png
    Combat_Crit.json Combat_Crit.0.png

Each file replaces that game font (a missing one keeps the original). The sample is samples/FonteComicNeue.

File in Fonts/ Game font Where it shows
Mouse_Text.json FontAssets.MouseText Tooltips, menus, almost the whole UI
Item_Stack.json FontAssets.ItemStack Item counts in the inventory
Death_Text.json FontAssets.DeathText Death message and big titles
Combat_Text.json FontAssets.CombatText[0] Damage numbers
Combat_Crit.json FontAssets.CombatText[1] Critical damage numbers

The name is matched without case, spaces or underscores.

Making the files. tools/mods/fonts.py builds the atlas from a font file (it needs Python with Pillow, NumPy and fontTools):

python tools/mods/fonts.py ttf "MyFont.ttf" --out "MyFont/Fonts"

It fits the font to the measurements of the mobile fonts (capital height, baseline, line spacing), so the UI does not move, and draws every glyph with 3 times the pixels the game uses (--scale changes it). --preset (latin, europe, all) or --ranges choose the characters, --size-factor and --stroke adjust the letters, --only picks fonts. Characters the font lacks keep the game's glyph.

PC resource packs. The launcher imports a zip with pack.json and Content/Fonts/*.xnb: each .xnb becomes <Font>.json plus its pages, at the PC resolution. fonts.py xnb "<pack>/Content/Fonts" --out "MyFont/Fonts" does the same by hand. Compressed XNB files (LZX/LZ4) are not read.

Why the letters stay sharp. A page with "scale": 3 is three times its logical size; Bunny Loader sets the font's TexelWidth/TexelHeight to match, so each glyph is drawn at the game's size with three times the detail, with trilinear filtering and mipmaps.

The JSON (blfont/1):

{
  "format": "blfont/1",
  "scale": 3,
  "lineSpacing": 24,
  "spacing": 0,
  "pages": ["Mouse_Text.0.png"],
  "fields": "code,page,bx,by,bw,bh,cx,cy,cw,ch,leftBearing,width,rightBearing",
  "glyphs": [[65, 0, 120, 3, 12, 14, 0, 2, 12, 24, 0, 12, -0.667]]
}

Each glyph has its UTF-16 code, its page, its rectangle in the page (bx,by,bw,bh, in logical pixels), its offset from the pen and the top of the line (cx,cy,cw,ch, as XNA's SpriteFont.Glyph.Cropping) and its advance (leftBearing + width + rightBearing). lineSpacing and spacing are informative: the game's values are kept. The game's SpriteFont objects are edited in place (characters replaced, new ones appended), because the mobile UI keeps references to them.

Packs are applied by the native core, with no C# involved: the topmost package on the Packages tab wins per file. A server that does not allow texture packs refuses players that use one (Allow textures in the host settings).

How a PNG gets in, and what it costs:

  • The pack's PNG replaces the Value of the game's own asset (the same Asset<Texture2D> object the tables and the UI hold), never the table entry. The PNG goes in at the moment the game loads that texture, during the loading screen, and again if the game unloads and reloads it; the few the game loads before its texture tables exist are replaced right after, and with the fast intro on, the splash waits for them. Enabling or reordering packs in the menu applies them on the next frames.
  • A pack texture is uploaded once to the GPU and keeps no copy in RAM and no mipmaps. A large pack (the Calamity Texture Pack: 3211 PNGs, ~225 MB of pixels) adds ~25 MB to the game's memory and a few seconds to the loading screen on the MuMu emulator, with no pause on the menu or when opening the world; it used to add ~290 MB and ~12 s to opening the world.
  • Each replaced sprite is its own texture, outside the game's atlas pages, so many different replaced sprites on screen mean more draw calls than the vanilla atlas. Keep the sheet sizes of the originals: a different size logs size mismatch and sprite frames may break.

Packages with blVersion below 3 (texture and font packs included) do not load: move content/Images and content/Fonts to the root and set "blVersion": 3.


← Making texture packs

Clone this wiki locally