win/share/tile.doc

   1 Window ports can optionally make use of the tiles (pictures for NetHack
   2 symbols) found in this directory.  They are distributed in a text format
   3 with routines to help in converting them to a system's preferred format
   4 and using them there.  The original tiles were provided by Warwick Allison.
   5
   6 The tile distribution format for monsters.txt, objects.txt, and other.txt
   7 starts with a palette header like:
   8
   9 A = (0, 0, 0)
  10 ...
  11 P = (254, 254, 254)
  12
  13 and then each tile has an entry like:
  14
  15 # tile 292 (comment identifying tile)
  16 {
  17   AAAAGHPAAAAACDAA
  18   AAAFGDEMLOCNAAAA
  19 ...
  20 }
  21
  22 Each port can convert these .txt files to whatever format it wants the
  23 game executable to use, probably providing only one merged output file.
  24 See the tilemap.c discussion at the bottom for more hints on adding tiles.
  25
  26
  27 Shared code provided for conversion utilities:
  28
  29 tile.h contains shared declarations.
  30
  31 tiletext.c defines the external variables from tile.h and supplies
  32 the external routines for reading and writing the defined text format.
  33
  34 Each conversion utility is expected to use tiletext.c and provide code of
  35 its own for reading and/or writing another format.  The important global
  36 variables implement a colormap shared between tiletext.c and the other
  37 half of utilities.  As an example of conversion utilities, we provide
  38 txt2ppm (tiletext.c + ppmwrite.c) and gif2txt (tiletext.c + gifread.c).
  39 (Sorry, we're not paying Unisys patent royalties for the right to provide
  40 you with a gifwrite.c, which would necessarily use the LZW compression
  41 algorithm they claim.)
  42
  43 The text I/O routines are:
  44
  45 boolean 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
  50 int fclose_text_file();
  51         close file
  52 boolean 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
  55 boolean write_text_tile(pixel[TILE_Y][TILE_X]);
  56         writes tile
  57
  58 There are two additional shared routines provided for writers:
  59
  60 void 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
  63 void merge_colormap();
  64         merge the current input colormap into the output one
  65
  66 Due to the amount of state being kept, only one text or gif file can be
  67 open at a time.  If you are combining multiple files into one other-format
  68 file with a single common colormap, you may need to open each source file
  69 and merge their colormaps into a common colormap before processing any tiles.
  70
  71 Although there are expected to be only 16 colors in the distribution tiles,
  72 conversion programs should be prepared to accept up to MAXCOLORMAPSIZE
  73 colors and map them to a smaller number if their port requires it.
  74
  75
  76 Expected 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
  90 When 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
  97 The gif reading routines accept further variations so long as the gif is
  98 n*TILE_X pixels across.
  99
 100 The gif I/O routines are:
 101
 102 boolean 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
 107 int fclose_gif_file();
 108         tear down decode mechanism
 109         close file
 110 boolean 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
 116 Array provided by shared code for NetHack use, by compiling and running
 117 tilemap.c to form tile.c:
 118
 119 short 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
 124 tilemap.c (shudder) accounts for things disappearing due to compilation
 125 options -- there should be a tile for everything appearing under any
 126 supported option, but under some options some tiles won't be referenced.
 127 Therefore, tilemap.c has the knowledge to provide the comments for gif2txt
 128 and is compiled with GIF2TXT to link in there, along with the various
 129 strings for things that are compiled in (monst.o etc.).
 130
 131 If you add monsters/objects/other things to NetHack and need to add tiles
 132 to 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.
 134 While the "comment identifying tile" in the .txt file must be correct,
 135 the number of the tile need not be, and can just be a duplicate of the
 136 tile on either side (or any other integer, for that matter).  In an
 137 official release, the tiles in a .txt file will be numbered consecutively
 138 so that you may cross-reference with a graphics format, but the conversion
 139 code does not care about the numbering.  (In fact, running txt2ppm, ppmtogif,
 140 and gif2txt gives you a consecutively numbered version of the .txt file.)