win/share/tile.doc

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