Mksprite

Mksprite

Mksprite is libdragon's tool for converting images (such as textures or sprites) from the PNG format into a format compatible with Nintendo 64, saved on a file with the .sprite extension.

A .sprite is an image file that can contain:

• Pixels for an image (in one of the support RDP formats)
• (optional) a palette of colors
• (optional) precalculated mipmap levels

Tutorial

Running mksprite can be as easy as:

mksprite filename.png

This will create a .sprite file. It will automatically select the N64 format that is more similar to the input PNG file, trying to avoid color conversions as much as possible.

For instance, trying to run mksprite on a RGB PNG, we obtain this:

$ mksprite --verbose ../srtitle400.png
Converting: ../srtitle400.png -> ./srtitle400.sprite [fmt=AUTO tiles=0,0 mipmap=NONE dither=NONE]
loaded ../srtitle400.png (640x400, LCT_RGB)
auto selected format: RGBA16
auto detected hslices: 40 (w=640/16)
auto detected vslices: 25 (w=400/16)

so mksprite selected the N64 RGBA16 because the input PNG is in LCT_RGB format. Instead, trying to convert a PNG file with a palette:

$ mksprite --verbose ../hoi.png
Converting: ../hoi.png -> ./hoi.sprite [fmt=AUTO tiles=0,0 mipmap=NONE dither=NONE]
loaded ../hoi.png (640x200, LCT_PALETTE)
palette: 43 colors (used: 41)
auto selected format: CI8
auto detected hslices: 40 (w=640/16)
auto detected vslices: 12 (w=200/16)

in this case, the tool selected the CI8 format, and created a sprite file that contains the exact PNG palette, without an index remapping, preserving the input data as much as possible.

It is possible to force a specific output format. If necessary, mksprite will quantize the image using an industry leading quantization algorithm (exoquant), with optional dithering. For instance:

$ mksprite --format CI8 --dither ORDERED --verbose ../srtitle400.png
Converting: ../srtitle400.png -> ./srtitle400.sprite [fmt=CI8 tiles=0,0 mipmap=NONE dither=ORDERED]
loaded ../srtitle400.png (640x400, LCT_RGB)
quantizing image(s) to 256 colors
auto detected hslices: 40 (w=640/16)
auto detected vslices: 25 (w=400/16)

Moreover, mksprite also supports libdragon asset compression:

$ mksprite --format CI8 --dither ORDERED --compress --verbose ../srtitle400.png
Converting: ../srtitle400.png -> ./srtitle400.sprite [fmt=CI8 tiles=0,0 mipmap=NONE dither=ORDERED]
loaded ../srtitle400.png (640x400, LCT_RGB)
quantizing image(s) to 256 colors
auto detected hslices: 40 (w=640/16)
auto detected vslices: 25 (w=400/16)
compressed: ./srtitle400.sprite (256584 -> 52378, ratio 20.4%)