home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Exec 1 / CD_Magazyn_EXEC_nr_1.iso / Gry / freeciv.lzx / Freeciv / README.graphics < prev    next >
Text File  |  2000-02-23  |  6KB  |  126 lines
  1. ----------------------------------------------------------------------
  2. Freeciv Graphics, and Tile Specification Files
  3. ----------------------------------------------------------------------
  4.  
  5. Using Graphics:
  6. ---------------
  7.  
  8. To use different graphics with Freeciv, use the '--tiles' argument to
  9. the Freeciv client.  Eg, to use the 'engels' graphics, start the
  10. client as:
  11.   
  12.     civclient --tiles engels
  13.  
  14. What Freeciv actually does in this case is look for a file called
  15. 'engels.tilespec' somewhere in your Freeciv data path.  (See the file
  16. INSTALL for some information on the Freeciv data path.)  That tilespec
  17. file contains information telling Freeciv which graphics files to use,
  18. and what those graphics files contain.
  19.  
  20. That is all you need to know to use alternative graphics provided by
  21. Freeciv or by third-party add-ons.  The rest of this file describes
  22. (though not fully) the contents of the tilespec file and related
  23. files.  This is intended as developer reference, and for people
  24. wanting to create/compile alternative tilesets and modpacks for
  25. Freeciv.
  26.  
  27. ----------------------------------------------------------------------
  28. Overview:
  29. ---------
  30.  
  31. The purpose of the 'tilespec' file and related 'spec' files is to
  32. allow the detailed layout of the graphics within the files to be
  33. flexible and not hard-coded into Freeciv, and to allow add-ons to
  34. conveniently provide additional graphics.
  35.  
  36. There are two layers to the tilespec files:
  37.  
  38. The top-level file is named, eg: 'trident.tilespec'.  The basename of
  39. this file (here, 'trident') corresponds to the parameter of the
  40. '--tiles' command-line argument for the Freeciv client, as described
  41. above.
  42.  
  43. The top-level tilespec file contains general information on the full
  44. tileset, and a list of files which specify information about the
  45. individual graphics files.  These filenames must be located somewhere
  46. in the data path, though not necessarily the same place as the
  47. top-level tilespec file.  Note that with this system the number and
  48. contents of the referenced files are completely flexible at this
  49. level.
  50.  
  51. An exception is that the intro graphics must be in individual files,
  52. as listed in the tilespec file, because Freeciv treats these
  53. specially: these graphics are freed after the game starts, and
  54. reloaded later as necessary.
  55.  
  56. ----------------------------------------------------------------------
  57. Individual spec files:
  58. ----------------------
  59.  
  60. Each spec file describes one graphics file (currently xpm format only)
  61. as specified in the spec file.  The graphics file must be in the
  62. Freeciv data path, but not necessarily "near" the spec file.  (Thus
  63. you could have multiple spec files using a single graphics file in
  64. different ways.)
  65.  
  66. The main data described in the spec file is in sections named
  67. [grid_*], where * is some arbitrary tag (but unique within each file).
  68. A grid corresponds to a regular rectangular array of tiles.  In
  69. general one may have multiple grids in one file, but the default
  70. tilesets usually only have one per file.  (Multiple grids would be
  71. useful to have different size tiles in the same file.)  Each grid
  72. defines an origin (top left) and spacing, both in terms of pixels, and
  73. then refers to individual tiles of the grid by row and column.  The
  74. origin, and rows and columns, are counted as (0,0) = top left.
  75.  
  76. Each individual tile is given a "tag", which is a string which is
  77. referenced in the code and/or from ruleset files.  A grid may be
  78. sparse, with some elements unused (simply don't mention their row and
  79. column), and a single tile may have multiple tags (eg, to use the same
  80. graphic for multiple purposes in the game): just specify a list of
  81. comma-separated strings.
  82.  
  83. If a given tag appears multiple times in the spec files, the *last*
  84. such tag is used.  (That is, in the order of files listed in the
  85. tilespec file, and order within each file.)  This allows selected
  86. graphics to be "overridden" by listing a replacement spec file near
  87. the end of the 'files' list in the toplevel tilespec file, without
  88. having to modify earlier files in the list.
  89.  
  90. ----------------------------------------------------------------------
  91. Tag prefixes:
  92. -------------
  93.  
  94. To help keep the tags organised, there is a rough prefix system used 
  95. for standard tags:
  96.  
  97.   f.          national flags
  98.   r.          road/rail
  99.   s.          general "small"
  100.   u.          unit images
  101.   t.          basic terrain types (with _n0s0e0w0 to _n1s1e1w1)
  102.   ts.          terrain special resources
  103.   tx.          extra terrain-related
  104.   gov.          government types
  105.   unit.          unit overlays: hp, stack, activities (goto, fortify etc)
  106.   upkeep.     unit upkeep and unhappiness
  107.   city.          city related (city, size, sq.-prod., disorder, occupied)
  108.   cd.          city defaults
  109.   citizen.    citizens, including specialists
  110.   explode.    explosion graphics (nuke, units)
  111.   spaceship.  spaceship components
  112.   treaty.     treaty thumbs
  113.   user.          crosshairs (in general: user interface?)
  114.  
  115. In general, graphics tags hard-wired into Freeciv _must_ be provided
  116. by the spec files, or the client will refuse to start.  Graphics tags
  117. provided by ruleset files (at least for the "standard" rulesets)
  118. should also be provided, but generally the client will continue even
  119. if they are not, though the results may not be satisfactory for the
  120. user.  To work properly tags should correspond to appropriately sized
  121. graphics.  (The basic size may vary, as specified in the top-level
  122. tilespec file, but the individual tiles should be consistent with
  123. those sizes and/or the usage of those graphics.)
  124.   
  125. ----------------------------------------------------------------------
  126.