Tiny comes with a built-in default font, but you can also use your own custom fonts to give your game a unique look. Custom fonts are bitmap fonts: each character is drawn as a small sprite on a PNG spritesheet, arranged in a grid.

What is a font?

A font in Tiny is a PNG image (the spritesheet) combined with metadata that describes how to read characters from it. Each font has a name, a reference to its spritesheet image, and one or more banks of characters.

What is a font bank?

A font bank is a set of characters within a font that share the same cell size. Each bank defines:

A name to identify the bank (e.g., default, uppercase, symbols).
The width and height of each character cell, in pixels.
A characters list describing which characters are in each row of the grid.
An optional x and y offset where the character grid begins in the spritesheet.

A single font can have multiple banks. This is useful when you want to group different character sets — for example, one bank for Latin letters and another for punctuation — while keeping them under the same font name.

How the character grid works

The characters in a bank are arranged left-to-right, top-to-bottom in the spritesheet. Tiny uses the image width and the character cell width to determine how many characters fit per row.

For example, with an image that is 108 pixels wide and a character cell width of 6 pixels, each row contains 18 characters. If you provide 144 characters, they fill 8 rows of 18 characters.

Adding a font with the CLI

Use the tiny-cli add command with the --font and --chars options to register a PNG as a font.

tiny-cli add --font=myfont --chars "abcdefghijklmnopqrstuvwxyz0123456789" myfont.png

--font marks the PNG as a font instead of a spritesheet. You can optionally give the font a name (e.g., --font=myfont). If you omit the name (--font), it is derived from the filename.
--chars lists all the characters in the spritesheet, in reading order (left-to-right, top-to-bottom).
--size specifies the character cell size in pixels. Use WxH for rectangular cells (e.g., 6x12) or a single number for square cells (e.g., 8). Optional: if omitted, the size is auto-detected from the image.
--offset specifies the pixel offset where the character grid begins in the image (e.g., 8,12 or 8x12). Optional: if omitted, the offset is auto-detected from the image.

Auto-detection

When --size or --offset are omitted, Tiny analyzes the PNG image to detect the values automatically:

Bounding box detection: Scans all pixels to find the region containing non-transparent pixels.
Gap analysis: Looks for fully-transparent columns and rows within the bounding box to identify individual character cells.
Divisor fallback: If gap analysis fails, tries to find cell dimensions that evenly divide the bounding box and can fit all characters.

The auto-detected values are displayed during the add operation. If auto-detection fails, an error message asks you to provide --size explicitly.

Explicit size and offset

You can always provide explicit values to override auto-detection:

tiny-cli add --font=myfont --size 8x12 --chars "abcdefghijklmnopqrstuvwxyz0123456789" myfont.png
tiny-cli add --font=myfont --size 8x12 --offset 4,2 --chars "abcdefghijklmnopqrstuvwxyz0123456789" myfont.png

Adding multiple banks

To add a second bank to an existing font, run the command again with the same font name but different characters:

tiny-cli add --font=myfont --size 8x12 --chars "ABCDEFGHIJKLMNOPQRSTUVWXYZ" myfont-uppercase.png

Both banks are stored under the same font name myfont.

Creating separate fonts

To create distinct fonts, use different names:

tiny-cli add --font=big --size 16x16 --chars "abcdefghijklmnopqrstuvwxyz" big-font.png
tiny-cli add --font=small --size 6x8 --chars "abcdefghijklmnopqrstuvwxyz" small-font.png

Configuration in _tiny.json

When you add a font, it is stored in the fonts section of _tiny.json:

{
  "fonts": [
    {
      "name": "myfont",
      "spritesheet": "myfont.png",
      "banks": [
        {
          "name": "default",
          "width": 8,
          "height": 12,
          "x": 0,
          "y": 0,
          "characters": [
            "abcdefgh",
            "ijklmnop",
            "qrstuvwx",
            "yz012345",
            "6789"
          ]
        }
      ]
    }
  ]
}

The characters array contains one string per row. Each string has as many characters as fit in one row of the spritesheet (image width / character width).

The x and y fields specify the pixel offset where the character grid starts in the spritesheet. They default to 0 when not specified.

Managing fonts

You can view all resources, including fonts, with:

tiny-cli resources

To remove a font, use --delete with the font name or spritesheet filename:

tiny-cli resources --delete myfont.png

What’s next?

Want to add audio to your game? Continue with the Adding Sound to Your Game tutorial.

You can also explore:

API Reference — Complete documentation for every Lua function.
CLI Reference — All available command-line tools.

Managing Custom Fonts