Mksprite

Mksprite (unstable branch)

NOTE: This documentation refers to mksprite in the unstable branch.

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

Quick 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. Compression ratio is usually similar or better than PNG 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%)

mksprite is also able to automatically generate mipmaps, even while quantizing:

$ mksprite --format CI4 --mipmap BOX --compress --verbose diamond0.png
Converting: diamond0.png -> ./diamond0.sprite [fmt=CI4 tiles=0,0 mipmap=BOX dither=NONE]
loaded diamond0.png (32x32, LCT_RGBA)
mipmap: generated 16x16
mipmap: generated 8x8
mipmap: generated 4x4
quantizing image(s) to 16 colors
auto detected hslices: 2 (w=32/16)
auto detected vslices: 2 (w=32/16)
compressed: ./diamond0.sprite (784 -> 252, ratio 32.1%)

In this case, the input 32x32 RGBA image was automatically scaled multiple times to generate the various mipmaps, and then all the mipmaps were converted to a single 16 color palette through quantization. This is important as to achieve the better quality, the choice of colors should take all mipmap levels into account.

Command line options

This is mksprite usage, that gives an overview of all options:

Usage: mksprite [flags] <input files...>

Command-line flags:
   -v/--verbose          Verbose output
   -o/--output <dir>     Specify output directory (default: .)
   -f/--format <fmt>     Specify output format (default: AUTO)
   -t/--tiles  <w,h>     Specify single tile size (default: auto)
   -m/--mipmap <algo>    Calculate mipmap levels using the specified algorithm (default: NONE)
   -d/--dither <dither>  Dithering algorithm (default: NONE)
   -c/--compress         Compress output files (using mksasset)
   -d/--debug            Dump computed images (eg: mipmaps) as PNG files in output directory

Supported formats: AUTO, RGBA32, RGBA16, CI8, I8, IA8, CI4, I4, IA4
Supported mipmap algorithms: NONE (disable), BOX
Supported dithering algorithms: NONE (disable), RANDOM, ORDERED.
Note that dithering is only applied while quantizing an image.

All PNG files passed on the command line are converted separately, generating one .sprite file for each of them. By default, the .sprite file is generated in the current directory, but it is possible to change this via -o/--output.

Sprite formats

This tables lists the formats supported by N64; for each one, it lists the PNG formats that are supported in input when using the --format option, and what kind of PNG must be supplied so that the format is autodetected by mksprite without an explicit --format.

N64 format	Supported PNG formats	Autodetection
CI4	LCT_PALETTE LCT_RGB/LCT_RGBA (quantized)	LCT_PALETTE with <= 16 actually used colors
CI8	LCT_PALETTE LCT_RGB/LCT_RGBA (quantized)	LCT_PALETTE with > 16 actually used colors
I4	LCT_PALETTE (greyscaled) LCT_RGB/LCT_RGBA (greyscaled) LCT_GREY LCT_GREY_ALPHA	LCT_GREY with bitdepth <= 4
I8	LCT_PALETTE (greyscaled) LCT_RGB/LCT_RGBA (greyscaled) LCT_GREY LCT_GREY_ALPHA	LCT_GREY with bitdepth > 4
IA4	LCT_PALETTE (greyscaled) LCT_RGB/LCT_RGBA (greyscaled) LCT_GREY LCT_GREY_ALPHA	LCT_GREY_ALPHA with bitdepth < 4
IA8	LCT_PALETTE (greyscaled) LCT_RGB/LCT_RGBA (greyscaled) LCT_GREY LCT_GREY_ALPHA	LCT_GREY_ALPHA with bitdepth >= 4 and < 8
IA16	LCT_PALETTE (greyscaled) LCT_RGB/LCT_RGBA (greyscaled) LCT_GREY LCT_GREY_ALPHA	LCT_GREY_ALPHA with bitdepth >= 8
RGBA16	LCT_PALETTE LCT_RGB/LCT_RGBA LCT_GREY LCT_GREY_ALPHA	LCT_RGB/LCT_RGBA
RGBA32	LCT_PALETTE LCT_RGB/LCT_RGBA LCT_GREY LCT_GREY_ALPHA	--