PNG2MSX and PNG2SPR[+] are free command line tools to convert PNG images to TMS9918 (MSX-1 VDP) format (i.e. CHRTBL/CLRTBL/NAMTBL-ready values, and SPRTBL/SPATBL-ready values).

TMX2BIN is a free command line tool to convert Tiled maps to binary.

• Deprecation notice
• Usage
• Options
• Palettes
• Version history
• Future plans
• Author and last words

PCX2MSX[+] and PCX2SPR[+] have been replaced by PNG2MSX and PNG2SPR[+], will not be further maintained, and may be removed in future versions.

Exit code will be zero if ok and non-zero if there was an error. This allows using this programs in makefiles, command chains, etc.

From command line, type:

• PNG2MSX [options] charset.png
• PNG2MSX [options] charset.png [extra.png ...]
• PNG2MSX [options] charset.png -n [screen.png ...]
• PNG2SPR [options] sprites.png
• PNG2SPR+ [options] sprites.png

charset.png, extra.png, screen.png, and sprites.png are the name of the input PNG file(s).

Please note that:

• Extra pixels (width or height not multiple of 8 or 16) will be ignored (this behaviour differs to the original PCX2MSX)

The output files will have the same name as the input file plus an additional extension (.chr, .clr, .nam, .spr[.asm] or .spat[.asm]). If files exist with the same name, they will be overwritten.

From command line, type:

• TMX2BIN [options] tmxFilename

tmxFilename is the name of the input TMX file. The next restrictions apply to the input file:

• Must be well formed (XML identifier followed by <map> tag).
• All the XML file lines must be shorter than 1024b.
• It should have at least one layer. Extra layers, if present, will be ignored.
• The layer must have its data encoded as "csv". Other Tiled encoding methods, such as XML or Base64, are not supported.
• Tilesets with more than 256 tiles are not supported. Values greater than 255 will cause a warning, as each value is meant to be stored in one byte.

Order of options is non important. Unknown options will be silently ignored. If there are mutually exclusive options, is undefined which one will be taked into account.

Execution control:

• -v verbose execution By default, only exceptional output (warnings and error) is written. Use -v to see the differents parts of the process

• -d dry run Doesn't write output files. Useful to just validate input PNG files

Colors (see Palettes):

• -e index color by euclidean distance (this is the default)

• -g index color by weighted distance

Mirroring:

• -i inverted Flips bitmap vertically.

• -m mirrored Flips bitmap horizontally.

Error control:

• -il ignore line on color collision Continue processing the file even if collisions are found. Offending lines will be have 0x00 both as pattern and color. Can be useful in combination with -d to check all the collisions at once.

Pattern generation:

• -hl force higher color to be foreground
• -lh force lower color to be foreground
• -f<0..7> force bit <n> to be foreground (set) on patterns
• -b<0..7> force bit <n> to be background (reset) on patterns These four options allow some control on how patterns are created, and which color is foreground and which one is background. Can be useful if colors are going to be set programatically (e.g.: fonts colored with FILVRM) or to improve compression results.

Optimization:

• -o attempt to optimize CLRTBL for compression If possible, modifies the unused color of solid color lines (pattern = 0x00 or 0xff) for the CLRTBL byte to match the value of bytes before or after it, inverting the pattern if necessary. This can create longer runs of repeated values in the CLRTBL, leading to better compression ratios. This optimization is applied after the applying the requested pattern generation algorithm (-hl, -lh, -f<0..7>, -b<0..7>).

NAMTBL generation:

• -n<00..ff> generate NAMTBL [starting at value <n>] Generates NAMTBL. If various PNG files are provided, NAMTBL is generated from the additional files, mapped against blocks of the first PNG file. If optional index value is specified, name table will be generated to load the character definition after that index (e.g.: tileset loaded without overwriting ASCII font). Usually to be used in combination with -rm and/or -rr.

• -bb<00..ff> blank block at position A blank block (pattern = 0x00, color = 0x00) will be generated at specified position. Removed blocks will have this index in the name table. Usually to be used in combination with -n and/or rm (e.g.: to keep ASCII 0x20 " " as the blank block)

• -rr remove repeated tiles Only the first copy of identical tiles will be kept. Usally to be used in combination with -n. If various PNG files are provided, blocks removed from the first file will be also removed from the additional files (e.g.: related tilesets: on/off, day/night...)

• -rm<0..f> remove solid tiles of <n> color Removes all the solid tiles composed entirely of pixels of the specified color (hexadecimal). If various PNG files are provided, blocks removed from the first file will be also removed from the additional files (e.g.: related tilesets: on/off, day/night...)

Sprite size:

• -8 generate 8x8px sprites Output is adjusted so it can be used in 8x8px sprites modes

• -h generate half sprites (8x16px, 16b per sprite) Processing order is adjusted so multicolored sprites are grouped by half sprites (8px width, 16px height)

Ordering:

• -hl lower colors will have higher priority planes (default)

• -lh higher colors will have higher priority planes These two options allow some control on how the colors get ordered (namely, to avoid the flickering routines make flicker the brigther colors)

• -th traverse spritesheet horizontally, then vertically (default)

• -tv traverse spritesheet vertically, then horizontally

Sprite size:

• -w<16..255> sprite width (default: 16px) Sprite width inside the spritesheet.

• -h<16..255> sprite height (default: 16px) Sprite height inside the spritesheet.

Centering:

• -x<0..255> X offset (default: center) X offset for horizontal coordinates for SPATBL. Default is center of the sprite (i.e.: half width). Negative coordinates may appear if non-zero X offset is used.

• -y<0..255> Y offset (default: middle) Y offset for vertical coordinates for SPATBL. Default is center of the sprite (i.e.: half width). Negative coordinates may appear anytime.

SPATBL generation:

• -p<0..4> attribute padding size (default: 1b) Padding size, in bytes, to be append after each sprite group. Default is 1 byte (enough for a marker value byte).

• -t<00..ff> terminator byte (default: 0xD0 (SPAT_END)) First padding byte value. If default value 0xD0 (SPAT_END) is used, pattern number will be reset after each sprite group; this is recommended for large spritesheets.

• -b binary spat output (default: asm) Save SPATBL as binary file. Default is the more versatile ASCII assembly code file.

Metatiles:

• -t<0..255> reorganize data as metatiles of <0..255>x<0..255> bytes If not provided, the output data will be the same as it is in the TMX file. If a metatile size is provided, the data will be scanned from left to right and from top to bottom in blocks of the specified size. E.g.: Given a TMX with:

   123456
   7890ab
   cdefgh
   ijklmn
  

  The default output will be 123456 7890ab cdefgh ijklmn (spaces added for clarity). A metatile size of 2 will output 1278 3490 56ab cdij efkl ghmn (6 metatiles of 2x2 bytes). If the width and/or height of the TMX data is not multiple of the specified size, extra data will be silently ignored. Thus, a metatile size of 3 will output: 123789cde 4560abfgh (2 metatiles of 3x3 bytes, rest of data ignored).

For each pixel, the color index is computed by looking for the lowest either euclidean or weigthed color distance, depending of the options.

As the MSX palette is not well defined, with several emulators using slightly different palettes, and the MSX2 palette does not exactly match the MSX palette, Four different palettes are used in a best effort to cover all the use cases and get the right color for every developer:

¹ TI TMS9918 palette, according Wikipedia wikipedia.org/wiki/Texas_Instruments_TMS9918#Colors

² TI TMS9219 and V9938 palettes from hap's meisei emulator

³ Palette used by pixel artist @Yazioh, because of reasons

⁴ TOSHIBA palette from reidrac's MSX Pixel Tools github.com/reidrac/msx-pixel-tools

Transparent pixels are indexed from the following values:

Since version 3.1 PNG2MSX and PNG2SPR[+] try to autodetect the closest palette, then use the autodetected palette to match the colors, ignoring the other palettes. This behaviour attempts to minimize color clashes between different palettes (particularly medium blue and dark blue), but can lead to unexpected results if colors from different palettes are mixed in one image.

See version history

• [*] Improve source code.
• PCX2MSX[+] Improve NAMTBL options (banks, etc.).
• PCX2MSX[+] Output NAMTBL as assembly.
• TMX2BIN metatiles with different width and height.
• TMX2BIN Multiple layers.

Coded by theNestruo

• Original PCX2MSX was coded by Edward A. Robsy Petrus [25/12/2004]. PCX2MSX is inspired by that original version, but is not related with it in any other way.
• Tiled © 2008-2020 Thorbjørn Lindeijer.
• LodePNG © 2005-2025 by Lode Vandevenne.
• Test graphics extracted from the original freeware version of Ninja Senki © 2010 Jonathan Lavigne.
• PNG2SPR+ demo sprites extracted from Sydney Hunter and the Caverns of Death © 2011 Keith Erickson / Studio Piña

Greetings to: Robsy, Iban Nieto, Jon Cortázar