### xbattle-5.4.1 README file

    XBATTLE 5.4.1
      A concurrent multi-player battle strategy game

      Developed by:
        Greg  Lesher (lesher@cns.bu.edu)

      Based (with permission) on the original by:
        Steve Lehar  (slehar@cns.bu.edu)	0.0-4.0
        Greg  Lesher (lesher@cns.bu.edu)	1.0-5.4.1

      FTP Release:
        ftp://cns-ftp.bu.edu/pub/xbattle/xbattle-5.4.1.tar.gz
        ftp://cns-ftp.bu.edu/pub/xbattle/xbattle-5.4.1.tar.Z

      Web page:
        http://cns-web.bu.edu/pub/xpip/html/xbattle.html

    DESCRIPTION

      This is version 5.4.1 of xbattle, by Greg Lesher, based on the original by
      Steve Lehar released in 1991, and including certain enhancements,
      modifications, and bug fixes suggested by a number of contributers from all
      over the world.  The extensive changes from version 5.1, the last official
      xbattle release, are outlined below.  The latest version can be obtained by
      anonymous ftp to cns-ftp.bu.edu in the pub/xbattle direction in compressed
      and gzip-ed tar format (xbattle-5.4.1.tar.Z and xbattle-5.4.1.tar.gz).  There
      is an xbattle Web page (http://cns-web.bu.edu/pub/xpip/html/xbattle.html),
      which contains the latest release information, tutorials, file archives,
      and a comprehensive on-line manual.

      xbattle is a concurrent multi-player game which combines elements of
      strategy with arcade-like action to capture a wide range of military
      scenarios.  The game is based on X Windows, which you must have installed
      to run xbattle.  Opponents play from separate displays, with commands being
      executed concurrently -- the players do not take "turns", but rather they
      all issue their commands simultaneously.  There can be any number of
      players, with each player assigned to a specific team, indicated by marker
      colors.  The game board is a matrix of cells (square, hexes, etc.) that can
      be occupied by colored troops, with the goal of the game being to eliminate
      the enemy from the board by attacking cells occupied by enemy troops.  A
      wide variety of command line options (and previously configured game files)
      provide an abundance of different scenarios and gaming environments.

      If you have never used xbattle before, we strongly suggest you read through
      the online introduction at the Web site specified above.  To get the feel of
      the game, you can run the tutorials (called "tutorial1" and "tutorial2")
      that are supplied with the game.  These are shell scripts that run on unix
      systems and start up a series of small example games that you can play around
      with to learn the various options available with the game.  If you are not on
      a unix system, print out the tutorials and type in the embedded command lines
      by hand.  If you are interested in the philosophical and game design issues
      of xbattle, or want to get immediate notice of the latest releases, updates,
      and bug fixes, send email to xbattle_request@gnu.ai.mit.edu and we will put
      you on the xbattle mailing list.

    INSTALLATION

      After un-gzip-ing ("gzip -d" or "gunzip") and un-tar-ing ("tar -xf") the
      release, create a makefile using "xmkmf", then compile using the command
      "make".  If you want to be able to alter default values (board size,
      colors, etc.) copy the file "xbattle.dot" into your home directory ($HOME)
      or from wherever you will be starting xbattle as ".xbattle".  For those
      having problems getting "xmkmf" to work correctly, you may be able to copy
      the default "makefile.std" to "makefile" and execute "make" without risking
      an xmkmf encounter.  See the INSTALL file for more detailed instructions.

    DIFFERENCES BETWEEN VERSION 5.4.1 AND VERSION 5.4

      Version 5.4.1 of xbattle includes fixes of several bugs reported by various
      players.  These bug fixes are outlined below.

      SCUTTLE SYNTAX ALTERED

      Changes to the build and scuttle command made scuttling very difficult when
      not used in conjunction with the build command.  In version 5.4, the
      scuttle_cost option determined how many troops were expended to scuttle
      each growth unit of a city.  In the new version, scuttle_cost determines how
      many troops are expended to scuttle [int] growth units (default: 5), where
      [int] is determined by:
          -scuttle          [int]           enable scuttling with [int] units
      When used in conjunction with the build command, the scuttle argument has
      no effect.

      BUG FIXES

      On some machines the "char" type is assumed signed, while on others it is
      assumed unsigned.  A new typedef for signed and unsigned char types has
      been created.

      Issuing a scuttle command in a non-city cell previously cost friendly troops.
      This has been remedied --- in this situation the scuttle command is ignored.

      Earlier versions of xbattle would not handle 24 bit color systems correctly
      due to a colormap allocation error.  Version 5.4.1 should handle most
      displays gracefully.

      With triangular tiling, the maxval for downward pointing cells was not being
      correctly set.  They are now.

      Previously, it was possible to move a single extra troop into cells which
      already contained maxval troops.  This has been remedied.

      A bug in dig and scuttle caused a segmentation fault when spending all of the
      troops in a cell.  Several responsible statement misorderings were corrected.

      KNOWN BUGS IN VERSION 5.4.1

      Running on a Pentium with OSF/1, game crashes for unknown reason when using
      the xbts/castle.xbt demonstration board.

    DIFFERENCES BETWEEN VERSION 5.4 AND VERSION 5.3

      The changes from 5.3 to 5.4 have primarily involved cleaning up the code
      for official release.  During the course of full option-testing, several
      anomalies were found and eliminated.  In addition, there have been several
      minor changes designed to make the game more consistent.  A summary of
      the functional differences follows.  See further below for differences
      between 5.1 and 5.3.

      CELL SIZING

      The former command to change cell size, -square <int>, was replaced by the
      new command, -cell <int>.  The -square option was maintained, but now
      is used to specify a square tiling.  Thus the commands are now:
          -square                           use square tiling
          -cell             <int>           area of cell
      Cell sizing has been changed so that the cell area remains constant (at
      <int> * <int>), regardless of the cell shape.  Previously, the argument
      determined the length of the side of a cell.

      COST FRACTIONS

      It is now possible to specify various troop costs (build_cost, scuttle_cost,
      fill_cost, dig_cost) in terms of either an absolute number, or as a fraction
      of the maximum maxval.  If the argument to these options is less than one,
      the fraction method is used, else the absolute number method is used.

      OTHER CHANGES

      Fixed minor bugs related to the horizon and movement methods.

      The -erode and -erode_thresh options were changed so that the argument of
      the first determines the minimum time before erosion occurs, while the
      argument of the second specifies the probability that erosion will occur
      at each subsequent update cycle, expressed in a percentage.

      The -sea_tones option was fixed so that it actually does something.  The
      arguments to -dig and -fill were made optional, and now serve as shortcuts
      to specifying -sea_tones.

      The dig and fill mechanisms were slightly changed, such that the -dig_cost
      and -fill_cost arguments were used to change troop values after these
      operations.  Previously all troops in the cell were used up.  A side-effect
      is that filling and digging of seas no longer results in loss of movement
      vectors.

      Fixed bug related to managed cells.

      Fixed several bugs related to load/dump/edit commands.

      Added support for different maxvals in different cells, as is required by
      the -octagon tiling method.

      Changed how -scuttle and -scuttle_cost work when not using the -build option.
      Each scuttle operation ("s" command) now subtracts 1 troop production point
      from a town for every scuttle_cost friendly troops in the cell.  This many
      troops are also expended.

      KNOWN BUGS IN VERSION 5.4

      Digging a non-sea cell with horizon enabled crashes the game.  The same
      error can occur when scuttling.

      Troops can move into cells with a maxval of 0.

      Scuttling a cell with no city costs troops.

      On some platforms (SGIs, in particular), the use of the C "char" type is
      assumed to be unsigned, while xbattle counts on it being signed.

      The maxval for downward pointing triangles is never set.

      24 bit displays are handled incorrectly, resulting in an X error.

    DIFFERENCES BETWEEN VERSION 5.3 AND VERSION 5.2

      The changes from 5.2 to 5.3 have involved additional cleaning up of the 5.1
      code, elimination of a number of 5.1 and 5.2 bugs, addition of different
      tiling shapes, and a number of relatively minor changes.  A summary of the
      functional differences follow.  See further below for differences between
      5.2 and 5.1.

      MULTIPLE TILING METHODS

      Using the newly created cell shape structure of v5.2, several new tiling
      methods have been added to supplement the standard square and hexagon tiling.
      These are:
          -diamond                          use diamond tiling
          -octagon                          use octagonal/square tiling
          -triangle                         use triangular tiling
      All of these versions involve the periodic tiling of regular polygons.  All
      options (including commands which depend on specific cell relations, such as
      -horizon, -attack, -repeat, and -march) are supported by all the tiling
      methods.  Try the .xbo files diamond.xbo, octagon.xbo, and triangle.xbo for
      quick demonstrations (just use xbattle -<shape.xbo>, since -white me is in
      the .xbo files).

      CHANGED ARMIES AND BASES

      Due in part to ideas of Jim McCarthy (mccarthy@mccarthy.rochny.uspra.abb.com),
      the routines for armies and base placement were rewritten to support any
      number of sides and any tiling method.  Armies/bases are now placed along
      tangents evenly placed on the edge of a large (imaginary) ellipse centered
      within the board.   For less than 5 sides, everything looks pretty much the
      same (3 sides is hard-coded to use 90 degree spacings rather than 120
      degrees).  Things can get a little strange looking for lots of sides, since
      the tangents will not be horizontal or vertical, but at least it works.

      BLACK AND WHITE SUPPORT

      Added back in the black and white monitor support which was lost in the
      transition from v5.1 to v5.2.  Note that with black and white monitors, many
      of the drawing methods (-draw option) are unusable since terrains are not
      stored as GCs (stipples), but rather as once-drawn pixmaps.  In short, if
      you are using ANY kind of terrain, either -draw 2 (DRAW_PIXMAP) or -draw 4
      (DRAW_MASKING) will automatically be invoked (the former will only work with
      square cells).

      IMPLEMENT -NOSPIGOT OPTION

      Thanks to Germano Caronni (caronni@tik.ethz.ch), the -nospigot <int> command,
      which has been in the xbattle option list for a long time without a
      corresponding implementation.  With this command activated, troops will
      automatically cease attacks when they are highly outnumbered, preventing the
      "spigoting" (perhaps "siphoning" would be more appropriate) which can empty
      whole supply lines into needless slaughter.  Neighboring supply lines are
      shut off whenever the troops in a cell are outnumbered by a ratio given by
      the argument to the -nospigot command.

      OTHER CHANGES

      A dozen or so generic bug fixes, many due to Jim McCarthy
      (mccarthy@mccarthy.rochny.uspra.abb.com) (the fixes, not the bugs).

      Added way to change "map" color, seen when a cell's terrain is unknown (with
      -map and -localmap options) and the "mark" color, used for the grid.  These
      colors are now defined just like side colors (e.g. "-color map 255 0 215").

      Fixed -map and -localmap options such that cells are redrawn correctly when
      they swith from unknown to known terrain (and vice versa).

      Fixed biased horizon so that it works with all tiling methods.

      Fixed bugs with -march option, simplifying the march code and march vector
      drawing in the process.

      Genericized definition of direction and marching vectors, allowing for simple
      addition of new regular polygons for future tilings.

      Genericized default color initialization (see parse.h).

      Cleaned up inefficiencies in the way horizons were handled, which had
      resulted in many unnecessary (and time-consuming) explicit checks of cell
      visibility.

      KNOWN BUGS IN VERSION 5.3

      No known bugs.

    DIFFERENCES BETWEEN VERSION 5.2 AND VERSION 5.1

      The changes from 5.1 to 5.2 have involved a major restructuring of the code,
      as well as many outward changes.  Version 5.2 is more-or-less backward
      compatible with 5.1, but there are some important exceptions.  These
      exceptions are: stored and dumped file formats differ and .xbattle default
      structure differs.  A summary of major functional differences follows.

      COMMAND LINE PARSING

      The command line parsing routines were completely rewritten, using a more
      generic method of specifying options.  A quick look at options.h will show
      that each option is now specified by a argument string, a number of
      parameters, and two default values (an integer and a float).  While this has
      little direct effect on the user, it makes adding new options much easier
      than before, and has resulted in a score of new options related to default
      values, such as the cost of a paratrooper (-para_cost) or the range between
      rbases (-rbase_range).  Extending the parsing routines also allowed me to
      incorporate more complex default functions, such as specifying colors and
      stipple patterns in the command line.  Since all the default values
      previously loaded from the default .xbattle file are now command line
      accessible, the default storage format was changed to be just like a .xbo
      file (see new .xbattle).

      Old default values which are now specifiable include:
          -build_cost     <int>           cost to build city segment
          -dig_cost       <int>           cost of each dig step
          -erode_thresh   <int>           threshold for erosion
          -fill_cost      <int>           cost of each fill step
          -guns_cost      <int>           cost of each artillery shell
          -guns_damage    <int>           damage done by each artillery shell
          -hill_tones     <int>           number of allowable hill levels
          -para_cost      <int>           cost of each paratrooper
          -para_damage    <int>           invading strength of each paratrooper
          -rbase_range    <int>           minimum distance of rbase from enemy base
          -sea_tones      <int>           number of allowable sea levels
          -forest_tones   <int>           number of allowable forest levels
          -sea_value      <float>         darkness of seas for b/w games
      Color definitions are now handled by:
          -color          <str> <r><g><b> set RGB values for color <str>
          -color_inverse  <str> <str2>    set color <str> inverse to <str2>
          -stipple        <str> 8*<hex>     stipple (b/w) pattern for color <str>
      The palette is created (there is a default too) by adding colors as they
      are specified using -color.  These colors can be used for side colors or
      for inverse side colors.

      One last feature of the new command line parsing scheme is that every
      command can be issued as a negative by prefixing it with "no_".  Thus -grid
      and -no_grid have opposite effects.  This is especially useful for
      cancelling out individual options issued in the default .xbattle file or in
      a .xbo file, and for biasing individual players (i.e. -red { -no_guns
      -no_para } me).  When negated, options take no parameters since they are
      just being turned off.

      TERRAIN DISPLAY

      The previous method of keeping track of terrain (hills and seas and such)
      was abandoned, and a more flexible approach taken.  This has allowed, among
      other things, multiple sea depths.  Thanks largely to suggestions and code
      from Jack Bennetto (bennetto@physics.rutgers.edu), terrain generation was
      completely revamped, leading to much more realistic looking board layouts.
      The relevant new commands are:
          -peaks          <int>             number of terrain peaks (and troughs)
          -peak_bias      <float>           peak distribution bias (0.0-2.0)
          -trough_bias    <float>           trough distribution bias (0.0-2.0)
      which control the number of peaks, and the distribution of levels --- the
      lower the bias values, the flatter most of the terrain is (1.0 default).

      Terrain colors are now completely specifiable via;
          -sea_color      <int> <r><g><b>   RGB values for sea level <int>
          -hill_color     <int> <r><g><b>   RGB values for hill level <int>
          -forest_color   <int> <r><g><b>   RGB values for forest level <int>
      Each level can be independently specified or a reduced set of levels can be
      specified, with xbattle automatically interpolating the non-specified levels.
      When seas are filled, their hue is changed to that of shallower water, rather
      than the previous block-reduction method.  The old method is supported by:
          -sea_block                        use block-fills rather than hue-fills

      DRAWING METHODS

      Significant internal changes were made to the way everything is drawn in
      version 5.2.  Tiling-specific (i.e. hex or square) drawing commands have
      been almost completely eliminated, which will soon lead to alternative
      tiling schemes (e.g. octagons & squares).  One side effect is that
      side-specific hex sizes can now be used.  The only other external change
      is the way cell drawings are updated.  The method is specified by:
        -draw           <int>             specify a troop drawing method
      with the following available options:
        -draw 0 (SIMPLE)   erase
        -draw 1 (BACKING)  erase backing pixmap, copy to screen
        -draw 2 (PIXMAP)   copy blank pixmap to workspace, copy to screen
        -draw 3 (WINDOW)   copy screen to workspace, erase, copy back to screen
        -draw 4 (MASKING)  copy screen to workspace, clear center,
    				OR in cell, copy back to screen
      The old default method (SIMPLE) just erased the cell onscreen, then redrew
      the contents, resulting in flickering cells.  Methods 1-4 are flicker free,
      but are somewhat slower due to the need to copy things from pixmap to window.

      OTHER NEW AND MODIFIED COMMANDS

      Due to a suggestion by Simon Lai (sjlai@broncho.ct.monash.edu.au), added
      a method to limit the number of cities a side can build in a game:
          -build_limit    <int>             limit cities each side can build

      The maximum troop values can be specified with biases for each side:
          -maxval         <int>             maximum cell troop capacity

      Due to a suggestion by Jack Bennetto (bennetto@physics.rutgers.edu), added
      a shorthand method for loading .xbo (option) files:
          -opt_file.xbo                     shorthand for -options opt_file.xbo

      Added a command which allows loading just the terrain and cities from a
      dumped (or edited) .xbt file.  Troops and towns and whatnot can be super-
      imposed over this map.  When used with -edit, it has the somewhat different
      effect of generating default terrain for editing (instead of just a flat
      board to which terrain can be manually added).  The command is:
          -overwrite                        just use terrain from loaded file

      OTHER CHANGES

      Genericized keyboard bindings for process control and editing, but still
      need to be compiled in.  See keyboard.h and edit.h.

      Added keyboard-based setting of direction vectors (good for small cells and
      people who lack fine motor skills).

      Genericized most internal constants, converting to #define in constant.h

      Changed -map, -localmap, and -basemap to show "unknown" color if terrain is
      not visible.  Currently hardwired in as bright pink.

      Rewrote store/replay routines to take advantage of new drawing methods,
      resulting in more efficient game storage.

      Rewrote dump/load routines, resulting in more efficient and comprehensive
      board storage.

      Add in X-Windows based error management, thanks to Eduard Martinescu
      (martines@martinescu.rochny.uspra.abb.com).

      KNOWN BUGS IN VERSION 5.2

      Cell sizes are linked to a side, not a player, so that if there are multiple
      players on a side, they must all have the same sized cells.

      March works, but looks goofy.

      For hexes only, -map, -basemap, and -localmap are partially broken,
      incorrectly redraws cells as they become visible or invisible.

      Side-based horizon bias is broken --- all sides must have same horizon.

      Black and white support broken.