doc/README.rulesets

   1 ----------------------------------------------------------------------
   2                        Freeciv Rulesets
   3 ----------------------------------------------------------------------
   4           (Originally by David Pfitzner, dwp@mso.anu.edu.au)
   5
   6 Quickstart:
   7 -----------
   8  Rulesets allow modifiable sets of data for units, advances, terrain,
   9  improvements, wonders, nations, cities, governments and miscellaneous
  10  game rules, without requiring recompilation, in a way which is
  11  consistent across a network and through savegames.
  12
  13 - To play Freeciv normally: don't do anything special; the new
  14   features all have defaults which give the standard Freeciv
  15   behaviour.
  16
  17 - To play a game with rules more like Civ1, start the server with:
  18        ./fcser -r data/civ1.serv
  19   (and any other command-line arguments you normally use; depending on
  20   how you have Freeciv installed you may have to give the installed
  21   data directory path instead of "data").
  22
  23   Start the client normally. The client must be network-compatible
  24   (usually meaning the same or similar version) but otherwise nothing
  25   special is needed. (However some third-party rulesets may
  26   potentially require special graphics to work properly, in which case
  27   the client should have those graphics available and be started with
  28   an appropriate '--tiles' argument.)
  29
  30   As well as a Civ1 style as above, Freeciv now has a Civ2 style
  31   similary, although currently it is almost identical to standard
  32   Freeciv rules.
  33
  34   Note that the Freeciv AI might not play as well with rules other
  35   than standard Freeciv. The AI is supposed to understand and
  36   utilize all sane rules variations, so please report any AI
  37   failures so that they can be fixed.
  38
  39 The rest of this file contains:
  40
  41 - More detailed information on creating and using custom/mixed
  42   rulesets.
  43
  44 - Information on implementation, and notes for further development.
  45
  46 ----------------------------------------------------------------------
  47 Using and modifying rulesets:
  48 -----------------------------
  49
  50 Rulesets are specified using the server command "rulesetdir".  The
  51 command above of "./fcser -r data/civ1.serv" just reads a file which
  52 uses this command (as well as a few of the standard server options).
  53 The server command specifies in which directory the ruleset files
  54 are to be found.
  55
  56 The ruleset files in the data directory are user-editable, so you can
  57 modify them to create modified or custom rulesets (without having to
  58 recompile Freeciv). It is suggested that you _don't_ edit the
  59 existing files in the "civ2civ3", "classic", "experimental",
  60 "multiplayer", "alien", "civ1", or "civ2"
  61 directories, but rather copy them to another directory and edit the
  62 copies. This is so that its clear when you are using modified rules
  63 and not the standard ones.
  64
  65 The format used in the ruleset files should be fairly
  66 self-explanatory. A few points:
  67
  68 - The files are not all independent, since eg, units depend on
  69   advances specified in the techs file.
  70
  71 - Units have a field, "roles", which is like "flags", but
  72   determines which units are used in various circumstances of the
  73   game (rather than intrinsic properties of the unit).
  74   See comments in common/unit.h
  75
  76 - Rulesets must be in UTF-8; translatable texts should be American English
  77   ASCII.
  78
  79 ----------------------------------------------------------------------
  80 Restrictions and Limitations:
  81 -----------------------------
  82
  83 units.ruleset:
  84
  85   Restrictions:
  86
  87     - At least one unit with role "FirstBuild" must be available
  88       from the start (i.e., tech_req = "None").
  89
  90     - There must be units for these roles:
  91       - "Explorer"
  92       - "FerryBoat"        (Must be able to move at sea)
  93       - "Hut"              (Must be able to move on land)
  94       - "Barbarian"        (Must be able to move on land)
  95       - "BarbarianLeader"  (Must be able to move on land)
  96       - "BarbarianBuild"   (Must be able to move on land)
  97       - "BarbarianBoat"    (Must be able to move at sea)
  98       - "BarbarianSea"
  99
 100 nations.ruleset
 101
 102   Restrictions:
 103
 104     - Government used during revolution can't be used as default_government
 105       or init_government for any nation
 106
 107 ----------------------------------------------------------------------
 108 Implementation details:
 109 -----------------------
 110
 111 This section and following section will be mainly of interested to
 112 developers who are familiar with the Freeciv source code.
 113
 114 Rulesets are mainly implemented in the server. The server reads the
 115 files, and then sends information to the clients. Mostly rulesets
 116 are used to fill in the basic data tables on units etc, but in some
 117 cases some extra information is required.
 118
 119 For units and advances, all information regarding each unit or advance
 120 is now captured in the data tables, and these are now "fully
 121 customizable", with the old enumeration types completely removed.
 122
 123 ----------------------------------------------------------------------
 124 Game settings defined in the ruleset:
 125 -------------------------------------
 126
 127 Game settings can be defined in the section [settings] of the file
 128 game.ruleset. The name key is equal to the setting name as listed by
 129 'show all'. If the setting should be locked by the ruleset, the last
 130 column should be set to TRUE.
 131
 132 set =
 133     { "name", "value", "lock"
 134       "bool_set", TRUE, FALSE
 135       "int_set", 123, FALSE
 136       "str_set", "test", FALSE
 137     }
 138
 139 ----------------------------------------------------------------------
 140 Update information:
 141 -------------------
 142
 143 The information about the changes in the definition of a ruleset between
 144 different versions of Freeciv is kept in the wiki at http://www.freeciv.org/
 145 The URLs below list the differences between the freeciv versions from 2.2.x
 146 to the current version:
 147
 148 http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_3.0_to_3.1
 149
 150 http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.6_to_3.0
 151
 152 http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.5_to_2.6
 153
 154 http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.4_to_2.5
 155
 156 http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.3_to_2.4
 157
 158 http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.2_to_2.3