Log In  

Cart #font_utils-0 | 2024-03-29 | Embed ▽ | License: CC4-BY-NC-SA

This cartridge contains two command line utilities, font2gfx and gfx2font, to perform conversion between fonts and sprite sheets.


First, load the cart with load #font_utils.

After loading, you have two options:

  • Either an automatic installation: run the cart (press CTRL-R) and follow the instructions.
  • or a manual installation:
    • cp /ram/cart/exports/appdata/system/util/font2gfx.lua /appdata/system/util/
    • cp /ram/cart/exports/appdata/system/util/gfx2font.lua /appdata/system/util/


Converting a font into a sprite sheet

Use font2gfx input.font

This will create two files: a gfx file containing the sprite sheet, and a lua file containing the configuration of the font (character width, height, variable width offsets, and so on).

You can optionally specify a specific output: font2gfx input.font output.gfx

If the output already exists, you can add a flag to overwrite: font2gfx -o input.font

Converting a sprite sheet into a font

Use gfx2font input.gfx

You need to have a lua file containing the configuration for the font. For example, here is the configuration for the default font (lil.font):

font_config = {
    width = 5,
    width_128 = 10,
    height = 11,
    x_offset = 0,
    y_offset = 0,
    flags = 3,
    char_offsets = {
        ["#"] = 1,
        ["."] = -1,
        ["I"] = -1,
        ["M"] = 1,
        ["T"] = 1,
        ["W"] = 1,
        ["i"] = -1,
        ["l"] = -1,
        ["m"] = 1,
        ["w"] = 1,

You can optionally specify a different configuration file: gfx2font input.gfx input.lua, and/or a different output file: gfx2font input.gfx input.lua output.font

If the output already exists, you can add a flag to overwrite: font2gfx -o input.font

Using the font

To use the font in a program (or in the terminal), use poke(0x4000, get(fetch("some.font"))).

Memory layout for non-monospace fonts

I didn't find any information in the wiki about the format of non-monospace fonts, so here is what I found:

The fifth byte seems to contain two flags: the lower bit indicates that the font is not monospace. The second bit is also set for the default picotron font, but I don't know its purpose.

Then each character (at least in the range 32-127) have a configuration stored using 4 bits.

To find the index for a character configuration: divide the character code by 2; if the code is even, the configuration is in the 4 lower bits, otherwise it's in the 4 higher bits.

The 3 lower bits of a character configuration contains a delta to the base width (between -4 and +3), and the fourth bit pushes the character upward by 1 pixel (note that this vertical offset is currently not taken into account by my utilities).

P#145026 2024-03-29 20:45


variable-width fonts are documented in the release post: https://www.lexaloffle.com/bbs/?tid=49075
and official docs, in a very terse way: https://www.lexaloffle.com/dl/docs/pico-8_manual.html#Custom_Font

P#145044 2024-03-29 22:24

Thank you for the links! I didn't know pico-8 also supported variable-width fonts, I thought this was a new addition in picotron... I'll update the tools to handle the tab width and the vertical offset.

P#145079 2024-03-30 05:10

Btw I think -o should be renamed to -f, as -o usually means "output" instead of "overwrite" and -f means "force" (this is also true for the standard picotron commands like cp) so someone might overwrite a file accidentally.

P#147236 2024-04-24 09:00

You're right. Initially the standard picotron commands didn't have the -f option, and at least one of them had -o to mean overwrite, so that's what I went for. I'll probably change it when I update the cart.

P#147237 2024-04-24 09:15

[Please log in to post a comment]