1Window ports can optionally make use of the tiles (pictures for NetHack 2symbols) found in this directory. They are distributed in a text format 3with routines to help in converting them to a system's preferred format 4and using them there. The original tiles were provided by Warwick Allison. 5 6The tile distribution format for monsters.txt, objects.txt, and other.txt 7starts with a palette header like: 8 9A = (0, 0, 0) 10... 11P = (254, 254, 254) 12 13and then each tile has an entry like: 14 15# tile 292 (comment identifying tile) 16{ 17 AAAAGHPAAAAACDAA 18 AAAFGDEMLOCNAAAA 19... 20} 21 22Each port can convert these .txt files to whatever format it wants the 23game executable to use, probably providing only one merged output file. 24See the tilemap.c discussion at the bottom for more hints on adding tiles. 25 26 27Shared code provided for conversion utilities: 28 29tile.h contains shared declarations. 30 31tiletext.c defines the external variables from tile.h and supplies 32the external routines for reading and writing the defined text format. 33 34Each conversion utility is expected to use tiletext.c and provide code of 35its own for reading and/or writing another format. The important global 36variables implement a colormap shared between tiletext.c and the other 37half of utilities. As an example of conversion utilities, we provide 38txt2ppm (tiletext.c + ppmwrite.c) and gif2txt (tiletext.c + gifread.c). 39(Sorry, we're not paying Unisys patent royalties for the right to provide 40you with a gifwrite.c, which would necessarily use the LZW compression 41algorithm they claim.) 42 43The text I/O routines are: 44 45boolean fopen_text_file(const char *filename, const char *type); 46 select file for subsequent tile I/O 47 "type" a la fopen 48 returns FALSE if file not opened, otherwise reads/writes header 49 (including colormap) and sets up to decode/encode tiles 50int fclose_text_file(); 51 close file 52boolean read_text_tile(pixel[TILE_Y][TILE_X]); 53 returns FALSE if no next tile in current file 54 otherwise TRUE and insert the tile in the provided array 55boolean write_text_tile(pixel[TILE_Y][TILE_X]); 56 writes tile 57 58There are two additional shared routines provided for writers: 59 60void init_colormap(); 61 initialize the output colormap from the input one 62 must be called before opening output file as colormap is part of header 63void merge_colormap(); 64 merge the current input colormap into the output one 65 66Due to the amount of state being kept, only one text or gif file can be 67open at a time. If you are combining multiple files into one other-format 68file with a single common colormap, you may need to open each source file 69and merge their colormaps into a common colormap before processing any tiles. 70 71Although there are expected to be only 16 colors in the distribution tiles, 72conversion programs should be prepared to accept up to MAXCOLORMAPSIZE 73colors and map them to a smaller number if their port requires it. 74 75 76Expected sequence for editing tiles: 77 edit foo.txt 78 79 -or- 80 81 run txt2ppm foo.txt foo.ppm 82 convert ppm to gif, either via ppmtogif from pbmplus/netpbm or 83 stripping the first 15 bytes of foo.ppm (containing the 84 size of the image) and feeding the rest to any raw-24bit- 85 image-reading program 86 edit tiles with gif-editing program 87 run gif2txt foo.gif foo.txt 88 89 90When converted to ppm, monsters.ppm, objects.ppm, and other.ppm are: 91 each a single ppm format (rgb triples with header) 92 20 tiles across, however many down (need "blank" tile to fill in 93 extras on last row -- currently alternating pixels in 94 first and second colors) 95 allows looking at tiles en masse for comparison or whatever 96 97The gif reading routines accept further variations so long as the gif is 98n*TILE_X pixels across. 99 100The gif I/O routines are: 101 102boolean fopen_gif_file(const char *filename, const char *type); 103 select file for subsequent tile I/O 104 "type" a la fopen 105 returns FALSE if file not opened, otherwise reads gif header 106 (including colormap) and sets up to decode tiles 107int fclose_gif_file(); 108 tear down decode mechanism 109 close file 110boolean read_gif_tile(pixel[TILE_Y][TILE_X]); 111 returns FALSE if no next tile in current file (including when any 112 remaining tiles are "blank"), 113 otherwise TRUE and insert the tile in the provided array 114 115 116Array provided by shared code for NetHack use, by compiling and running 117tilemap.c to form tile.c: 118 119short glyph2tile[MAXGLYPH]; 120 maps glyph number to tile number for display purposes, assuming 121 (non-blank) tiles are numbered sequentially through 122 monsters/objects/other 123 124tilemap.c (shudder) accounts for things disappearing due to compilation 125options -- there should be a tile for everything appearing under any 126supported option, but under some options some tiles won't be referenced. 127Therefore, tilemap.c has the knowledge to provide the comments for gif2txt 128and is compiled with GIF2TXT to link in there, along with the various 129strings for things that are compiled in (monst.o etc.). 130 131If you add monsters/objects/other things to NetHack and need to add tiles 132to go with them, just add an entry in the right place in the appropriate 133.txt file, and one to tilemap.c if the new item is conditionally compiled. 134While the "comment identifying tile" in the .txt file must be correct, 135the number of the tile need not be, and can just be a duplicate of the 136tile on either side (or any other integer, for that matter). In an 137official release, the tiles in a .txt file will be numbered consecutively 138so that you may cross-reference with a graphics format, but the conversion 139code does not care about the numbering. (In fact, running txt2ppm, ppmtogif, 140and gif2txt gives you a consecutively numbered version of the .txt file.) 141