home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 3 / AACD03.BIN / AACD / Games / Freeciv / README.graphics < prev    next >
Text File  |  1999-10-20  |  6KB  |  124 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: 'default.tilespec'.  The basename of
  39. this file (here, 'default') 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. ----------------------------------------------------------------------
  84. Tag uniqueness and tag prefixes:
  85. --------------------------------
  86.  
  87. An important requirement is that there must be no duplicated tags
  88. across all the graphics files (those referenced from the top-level
  89. tilespec file).  That is, each tag must be unique.  (This is because
  90. the tags are used to reference the graphics, and for non-unique tags
  91. Freeciv would not know which graphic to use.)  To assist in
  92. maintaining this uniqueness, there is a rough prefix system used for
  93. standard tags:
  94.  
  95.   f.          national flags
  96.   r.          road/rail
  97.   s.          general "small"
  98.   u.          unit images
  99.   t.          basic terrain types (with _n0s0e0w0 to _n1s1e1w1)
  100.   ts.          terrain special resources
  101.   tx.          extra terrain-related
  102.   gov.          government types
  103.   unit.          unit overlays: hp, stack, activities (goto, fortify etc)
  104.   upkeep.     unit upkeep and unhappiness
  105.   city.          city related (city, size, sq.-prod., disorder, occupied)
  106.   cd.          city defaults
  107.   citizen.    citizens, including specialists
  108.   explode.    explosion graphics (nuke explosion)
  109.   spaceship.  spaceship components
  110.   treaty.     treaty thumbs
  111.   user.          crosshairs (in general: user interface?)
  112.  
  113. In general, graphics tags hard-wired into Freeciv _must_ be provided
  114. by the spec files, or the client will refuse to start.  Graphics tags
  115. provided by ruleset files (at least for the "standard" rulesets)
  116. should also be provided, but generally the client will continue even
  117. if they are not, though the results may not be satisfactory for the
  118. user.  To work properly tags should correspond to appropriately sized
  119. graphics.  (The basic size may vary, as specified in the top-level
  120. tilespec file, but the individual tiles should be consistent with
  121. those sizes and/or the usage of those graphics.)
  122.   
  123. ----------------------------------------------------------------------
  124.