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