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.
PCX2MSX[+]PCX2SPR[+]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.pngPNG2MSX [options] charset.png [extra.png ...]PNG2MSX [options] charset.png -n [screen.png ...]PNG2SPR [options] sprites.pngPNG2SPR+ [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.
-vverbose execution By default, only exceptional output (warnings and error) is written. Use-vto see the differents parts of the process-ddry run Doesn't write output files. Useful to just validate input PNG files-eindex color by euclidean distance (this is the default)-gindex color by weighted distance
-iinverted Flips bitmap vertically.-mmirrored Flips bitmap horizontally.
-ilignore 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-dto check all the collisions at once.-hlforce higher color to be foreground-lhforce lower color to be foreground-f<0..7>force bit to be foreground (set) on patterns-b<0..7>force bit 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.-n<00..ff>generate NAMTBL [starting at value ] 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-rmand/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)-rrremove 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 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...)
-8generate 8x8px sprites Output is adjusted so it can be used in 8x8px sprites modes-hgenerate half sprites (8x16px, 16b per sprite) Processing order is adjusted so multicolored sprites are grouped by half sprites (8px width, 16px height)-hllower colors will have higher priority planes (default)-lhhigher 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)
-w<16..255>sprite width (default: 16px) Sprite width inside the spritesheet.-h<16..255>sprite height (default: 16px) Sprite height inside the spritesheet.-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.-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.-bbinary spat output (default: asm) Save SPATBL as binary file. Default is the more versatile ASCII assembly code file.
-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:The default output will be123456 7890ab cdefgh ijklmn123456 7890ab cdefgh ijklmn(spaces added for clarity). A metatile size of 2 will output1278 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:
| Index | TMS9918 palette1 | TMS9219 palette2 | Yazioh palette3 | TOSHIBA palette4 | V9938 palette2 | Name |
|---|---|---|---|---|---|---|
| 1 | 000000 | 000000 | 000000 | 000000 | 000000 | Black |
| 2 | 0AAD1E | 23CB32 | 3EB849 | 66CC66 | 24DA24 | Medium green |
| 3 | 34C84C | 60DD6C | 74D07D | 88EE88 | 6DFF6D | Light green |
| 4 | 2B2DE3 | 544EFF | 5955E0 | 4444DD | 2424FF | Dark blue |
| 5 | 514BFB | 7D70FF | 8076F1 | 7777FF | 486DFF | Medium blue |
| 6 | BD2925 | D25442 | B95E51 | BB5555 | B62424 | Dark red |
| 7 | 1EE2EF | 45E8FF | 65DBEF | 77DDDD | 48DAFF | Cyan |
| 8 | FB2C2B | FA5948 | DB6559 | DD6666 | FF2424 | Medium red |
| 9 | FF5F4C | FF7C6C | FF897D | FF7777 | FF6D6D | Light red |
| 10 | BDA22B | D3C63C | CCC35E | CCCC55 | DADA24 | Dark yellow |
| 11 | D7B454 | E5D26D | DED087 | CCCC88 | DADA91 | Light yellow |
| 12 | 0A8C18 | 23B22C | 3AA241 | 55AA55 | 249124 | Dark green |
| 13 | AF329A | C85AC6 | B766B5 | BB55BB | DA48B6 | Magenta |
| 14 | B2B2B2 | CCCCCC | CCCCCC | CCCCCC | B6B6B6 | Gray |
| 15 | FFFFFF | FFFFFF | FFFFFF | EEEEEE | FFFFFF | White |
1 TI TMS9918 palette, according Wikipedia (https://en.wikipedia.org/wiki/Texas_Instruments_TMS9918#Colors)
2 TI TMS9219 and V9938 palettes from hap's meisei emulator
3 Palette used by pixel artist @Yazioh, because of reasons
4 TOSHIBA palette from reidrac's MSX Pixel Tools (https://github.com/reidrac/msx-pixel-tools)
Transparent pixels are indexed from the following values:
| Index | RGBA value | Description | Name |
|---|---|---|---|
| 0 | ??????00 | Actually transparent (any color with alpha channel = 0) | Transparent |
| 0 | FF00FF | Fuchsia (traditional color used to denote transparency) | Transparent |
| 0 | 404040 | Dark gray (was used in the old PCS2MSX reference files) | Transparent |
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.TMX2BINmetatiles with different width and height.TMX2BINMultiple layers.
Coded by theNestruo
- Original
PCX2MSXwas coded by Edward A. Robsy Petrus [25/12/2004].PCX2MSXis inspired by that original version, but is not related with it in any other way. - Tiled (c) 2008-2020 Thorbjørn Lindeijer.
- LodePNG (c) 2005-2023 by Lode Vandevenne.
- Test graphics extracted from the original freeware version of Ninja Senki (c) 2010 Jonathan Lavigne.
PNG2SPR+demo sprites extracted from Sydney Hunter and the Caverns of Death (c) 2011 Keith Erickson / Studio Piña
Greetings to: Robsy, Iban Nieto, Jon Cortázar