===================
Freeciv Version 2.6
===================

Welcome to Freeciv!

This archive contains Freeciv, a free Civilization-like game, primarily
for X under Unix.  It has support for multiplayer games locally or
over a network, and an AI which gives most people a run for their money.

Freeciv aims to be mostly rule-compatible with Civilization II [tm],
published by Sid Meier and Microprose [tm].  A few rules are different
where we think it makes more sense, and we have lots and lots of
adjustable parameters to make customizing games possible.

Freeciv has been implemented completely independently of Civilization;
you do not need to own Civilization to play Freeciv.


Translations:
=============

You may find a translated version of this file, as well as of other parts
of the Freeciv documentation, in the following places:

        Catalan                 ./doc/ca
        Dutch                   ./doc/nl
        French                  ./doc/fr
        German                  ./doc/de
        Italian                 ./doc/it
        Japanese                ./doc/ja
        Swedish                 ./doc/sv

Even if there is no translation for your language, the game itself may
support it.  Please see "Native Language Support" below.


Web site:
=========

Freeciv's web site is here:

  http://www.freeciv.org/

We invite you to visit.  You can get the latest Freeciv news, releases
and patches, find out about the Freeciv mailing lists, and see the
Freeciv metaserver, which records games being played around the world.


License:
========

Freeciv is released under the GNU General Public License (version 2
or, at your option, any later version).  In short, you may copy this
program (including source) freely, but see the COPYING file for full
details.

Some materials that were used to prepare the graphics in the game (in
the 'data' subdirectory), such as 3D models used to prepare bitmap
images, are not distributed with the main source code due to their
size; they are not necessary to build Freeciv from source, as the
(manually) derived graphics are also included in the distribution.
These materials are available in the separate 'graphics-materials'
distribution (e.g., freeciv-2.4.0-graphics-materials.tar.bz2), or from
version control (Git).


Compiling and installing:
=========================

Please read the INSTALL file carefully for instructions on how to get
Freeciv compiled and installed on your machine.


Freeciv is modular:
===================

Freeciv is actually several programs, a server and one or more clients.  When
a game is in progress, there will be one server program running, and as many
client programs as there are human players.  The server does not use a gui,
but the clients do.  The clients come in many flavors:

freeciv-gtk2:  This uses the GTK+ 2 libraries. To install, see section 1a of
  the INSTALL document.
  This client has been replaced by freeciv-gtk3, but it still exist for benefit
  of those who cannot to switch to gtk3.

freeciv-gtk3:  This uses the GTK+ 3 libraries. To install, see section 1b of
  the INSTALL document.
  This client is better supported and more developed than the others,
  as such it is considered to be the default interface throughout the rest of
  this document.

freeciv-gtk3.22:  This uses the GTK+ 3 libraries. Version 3.22 or 3.24
  is required. To install, see section 1c of the INSTALL document.

freeciv-qt:  This uses the QT library. Development of this client has recently
  reached the state where it's considered generally usable, but it still lacks
  number of features gtk-clients have.

freeciv-sdl:  This uses Simple DirectMedia Layer libraries version 1.2.
  This client is currently unmaintained but is usable.

freeciv-sdl2: This uses Simple DirectMedia Layer libraries version 2.
  This client is going to replace freeciv-sdl in the future.

freeciv-xaw:  This uses the X Window System along with its Athena Widget
  interface.
  This client, somewhat minimalistic compared to the others, is currently
  unmaintained.


Starting a game:
================

  NOTE:
  The following examples assume that Freeciv has been installed on
  your system, and that the directory containing the "freeciv-gtk3"
  and "freeciv-server" programs is in your PATH.  If Freeciv is not
  installed, then you may want to use the "fcgui" and "fcser" programs,
  which can be found in the top Freeciv directory.  They are used
  in exactly the same fashion as "freeciv-gtk3" and "freeciv-server".

Running Freeciv involves starting the server, then the client(s)
and AI(s), then telling the server to start the game.  Here are the
steps:

Server:

  To start the server:

  |  % freeciv-server

  Or for a list of command-line options:

  |  % freeciv-server --help

  Once the server is started, a prompt will appear:

  |  For introductory help, type 'help'.
  |  >

  and, you can see this information by using the help command:

  |  > help
  |  Welcome - this is the introductory help text for the Freeciv server.
  |
  |  Two important server concepts are Commands and Options.
  |  Commands, such as 'help', are used to interact with the server.
  |  Some commands take one or more parameters, separated by spaces.
  |  In many cases commands and command arguments may be abbreviated.
  |  Options are settings which control the server as it is running.
  |
  |  To find out how to get more information about commands and options,
  |  use 'help help'.
  |
  |  For the impatient, the main commands to get going are:
  |    show   -  to see current options
  |    set    -  to set options
  |    start  -  to start the game once players have connected
  |    save   -  to save the current game
  |    quit   -  to exit
  |  >

  If you like, you can use the 'set' command to set any of the various
  server options for the game.  You can get a list of the options
  with the 'show' command, and detailed descriptions of each with the
  'help <option-name>' command.

  For example:

  | > help size
  |  Option: size  -  Map size in 1,000 tiles units
  |  Description:
  |    This value is used to determine the map dimensions.
  |      size = 4 is a normal map of 4,000 tiles (default)
  |      size = 20 is a huge map of 20,000 tiles
  | Status: changeable
  | Value: 4, Minimum: 1, Default: 4, Maximum: 29

  And:

  |  > set size 8

  This will make the map twice as large as the default.

Client:

  Now all the human players should join, by running the Freeciv
  client:

  |  % freeciv-gtk3

  This assumes the server is running on the same machine.  If not, you
  can either specify it on the command line with the '--server' option,
  or enter it into the first dialog box once the client starts.

  For example, suppose the server is running on a different machine
  called 'neptune'.  Then players would join with a command like:

  |  % freeciv-gtk3 --server neptune

  If you're the only human player, then only one client needs to be
  started.  In standard Unix fashion you can start the client
  "in the background" by appending an ampersand:

  |  % freeciv-gtk3 &

  Another option for the client you may like to try is the '--tiles'
  option, which can be used to select different "tilesets" (that is,
  different graphics for the map terrain, units, and so on).  The
  distribution comes with 8 main tilesets:
  - amplio2: An isometric tileset with larger and more detailed tiles.
  - isotrident: An isometric tileset similar in shape to the one in Civ 2.
  - cimpletoon: amplio2 with alternative units that display direction they
                are facing.
  - trident: a Civ 1-style ('overhead') tileset with 30x30 tiles.
  - hexemplio: an iso-hexagonal tileset with larger tiles derived
               from amplio2
  - toonhex: tileset combining hexemplio tiles with cimpletoon units
  - isophex: an iso-hexagonal tileset
  - hex2t: a hexagonal tileset

  In this release, each map topology has its own default tileset; with
  default settings, amplio2 is the default tileset.
  To try another one, for instance the trident tileset, start the
  client with:

  |  % freeciv-gtk3 --tiles trident

  Other tilesets are available from http://www.freeciv.org/wiki/Tilesets


  Clients can be authorized to issue server commands.  To allow them
  to use informational commands only, type at the server prompt

  |  > cmdlevel info

  Clients can now use '/help', '/list', '/show settlers', etc.

Computer Players:

  There are two ways to create AI players.  The first is to set
  the number of players (human and AI) by setting the 'aifill'
  server option.  For example:

  |  > set aifill 7

  After using the 'start' server command to start the game, any players
  which aren't controlled by humans will be AI players.  For the above,
  if two human players had joined, 5 AI players would be created.

  The second way is to explicitly create an AI with the 'create'
  server command.  For example:

  |  > create HumanKiller

  This will create an AI-controlled player called HumanKiller.

  AI players are assigned to nations after all human players have
  chosen their nations, but you can choose a particular nation for an
  AI player by using the normal name for that nation's leader.  For
  example, to play against AI-controlled Romans, use this server
  command:

  |  > create Caesar

  Note, this is just a preference:  If no other human player chooses
  to play the Romans, then this AI will.

Server:

  When everybody has joined (use the "list" command to see who's in),
  start the game with the "start" command:

  |  > start

And the game is on!

  NOTE: In this version of Freeciv, the GTK, Qt, and SDL clients have the
  capability to automagically start a freeciv-server session when the user
  selects "Start New Game" from the main menu. This reduces the steps
  needed to get started playing a game of Freeciv. On the other hand,
  it also means that if the client crashes for some reason or becomes
  unavailable, the freeciv-server session will also be lost. So starting a
  separate freeciv-server session and then connect to it with the client is
  generally the recommended method.


Announcing the game:
====================

If you do not want to limit your opponents to local friends or AI players,
visit the Freeciv metaserver:

  http://meta.freeciv.org/

It is a list of Freeciv servers.  To make your own server announce itself
there, start freeciv-server with the '--meta' option, or just '-m' for short.

Caveats:

 1) Due to the inclusion of new features, different client and server
    versions are often incompatible. The 2.5.0 version is for example
    incompatible with any 2.4.x or earlier versions.

 2) If the Metaserver button in the connection dialog doesn't work,
    check if your ISP uses a mandatory WWW proxy and make freeciv-gtk3
    use it through the $http_proxy environment variable.  For instance,
    if the proxy is proxy.myisp.com port 8888, set $http_proxy
    to http://proxy.myisp.com:8888/ before starting the client.

 3) Sometimes there are no games on the metaserver.  That happens.
    The number of players there vary with the time of the day. Try
    starting one yourself!


Playing the game:
=================

The game may be saved at any time using the 'save' server command,
like so:

  |  > save mygame.sav

(If your server is compiled with compression support, and the
'compresstype' server option is set to other than PLAIN, then the
file written may be compressed and called 'mygame.sav.gz', 'mygame.sav.bz2',
or 'mygame.sav.xz' depending on the setting.)

The Freeciv client works pretty much as you would expect from a
multiplayer civilization game.  That is, the human players all move
at the same time, then all the AI players move when all the human
players have completed their turn.  There's a turn timeout value,
which is by default set to 0 seconds (no timeout).  The server
operator can alter this value at any time with the 'set' command.

Have a look at the online help system. All three mouse-buttons are
used, and documented in the help.

Players can hold down 'Shift' and push the 'Return' key to announce
the end of their turn, or just push the 'Turn Done' button.

Use the 'Players' dialog to see who has announced their end of turn,
and who you're waiting for.  (Hey feller, are you asleep or what?? ;).

Use the input line at the bottom of the window for broadcasting
messages to other players.

You can send a message to an individual player (e.g., 'peter') like so:

  |  peter: move that armor away *NOW*!

The server is smart enough to perform "name completion", so if you had
typed "pet:", it will find a player name that matches the part of the
name you typed.

You can send a message to all your allies by prefixing it with the
letter '.' (yes, that is a period).

You can issue server commands from the client input line:

  |  /list
  |  /set settlers 4
  |  /save mygame.sav

The server operator will probably let you issue informational commands
only.  This is partly because allowing clients to use all server
commands has security implications; consider if a player tried:

  |  /save /etc/passwd

Of course the server should not be running with superuser privileges in
any case, to reduce this sort of risk.

If you're just starting, and would like to get an idea of a strategy,
have a look in the Freeciv playing HOWTO, contained in the HOWTOPLAY
file.

For lots more information about the client, the server, and the
concepts and rules of the game, see the Freeciv manual, available
at the wiki:

  http://www.freeciv.org/wiki/Manual


Ending the game:
================

There are six ways in which a game can end:

1) Only winners remain in game
   1a) If victory condition 'ALLIED' is enabled in server setting 'victories':
       All the remaining nations, short of those who have ceded the game
       (/surrender), are allied or in the same team.
   1b) If victory condition 'ALLIED' is disabled in server setting 'victories':
       Only one nation or one team is left, or all other players of all
       other teams have ceded the game (/surrender).
2) The final turn (/show endturn) is reached.
3) If victory condition 'SPACERACE' is enabled in server setting 'victories' and
   a player builds and launches a spaceship, which reaches Alpha
   Centauri first.
4) If victory condition 'CULTURE' is enabled in server setting 'victories' and
   a player has reached both ruleset-defined minimum number of culture points
   and ruleset-defined minimum lead in culture points.
5) If the modpack has special victory conditions and a player has reached one
   of those.
6) The server operator uses the /endgame command.

A score-table will be shown in all cases.  Hint: The server operator
can set the final year while the game is still going by changing the
'endturn' option.  This is nice when the winner is obvious, but you
don't want to play through the boring 'cleanup phase'.


Restoring games:
================

You can restore a saved game by using the '-f' server option, eg:

  |  % freeciv-server -f oursave2001.sav

or, if the save-file was created by a server that compressed it:

  |  % freeciv-server -f oursave2001.sav.gz

Now the players can rejoin the game:

  |  % freeciv-gtk3 -n Alexander

Notice how the player-name is specified with the -n option. It's vital
that the player uses the same name as they had when the game was running,
if they're to be allowed in.

The game may then be restarted with the 'start' command as usual.


Native Language Support:
========================

Freeciv supports several languages.

You may choose which local language to use by specifying a "locale".
Each locale has a standard name (e.g., 'de' for German).  If you have
installed Freeciv, you may choose a locale by setting the environment
variable LANG to that locale's standard name before running freeciv-server
and freeciv-gtk3.

For example, assuming you wish to use the German localization, you
would do:

  export LANG; LANG=de   (in the Bourne shell (sh)),
or
  setenv LANG de         (in the C shell (csh)).

(You could do this in your .profile or .login file.)

Sometimes there is a conflict between the local library implementation
and the internal locale determination.  It is often possible to work
around problems with a more detailed descriptor:

  LANG=de_DE.UTF-8

We'd like to know about such problems.  Please report them as bugs
(see BUGS).


Log messages:
=============

Both the client and server print messages known as "log messages".
There are five categories of log messages: "fatal", "error", "normal",
"verbose", and "debug".

By default, fatal, error and normal messages are printed to standard
output where the client or server was started.  You can direct log
messages to a file instead of the screen with the "--log filename",
or "-l filename" command line options.

You can change the level of log messages displayed with "--debug
level" or "-d level" (or instead "-de level" for the Xaw client, since
"-d" is ambiguous between "-debug" and "-display"), where "level" is
0, 1, 2, or 3.  0 means show fatal messages only, 1 means show fatal
and error messages, 2 means fatal, error and normal messages (the
default), and 3 means show all fatal, error, normal, and verbose
messages.

If you compiled with DEBUG defined (an easy way to do this is to
configure with --enable-debug), then you can get debug level messages
by setting the level to 4.  Also, it is possible to control debug
level messages (but not other messages) on a per-file and per-line
basis.  To do this use "--debug 4:str1:str2" (as many strings as you
like, separated by colons) and any filenames which match those strings
as a substring will have debug log messages turned on, and all other
debug messages will be suppressed.  To control lines, use:
"--debug 4:str1,min,max" and for files which match str1 only debug
messages within the specified minimum and maximum lines will be
printed.  Only one set of (min,max) can be applied to each file.

Example:

  |  % freeciv-server -l my.log -d 3

This sends all server log messages to file "my.log", including verbose
level messages.

Example:

  |  % freeciv-gtk3 --debug 0

This suppresses all non-fatal client log messages.

Example:

  |  % freeciv-server -d 4:log:civserver,120,500:autoattack

This turns on all fatal, error, normal and verbose messages for the
server, and debug level messages for some specified modules.  Note
that "log" will match "gamelog.c" as well as "log.c".  For
"civserver.c", debug messages between lines 120 and 500 will be
printed.  This example only works if the server was compiled with
DEBUG.


Bugs:
=====

Found a bug?  We really want to hear from you so we can fix it.
See the file BUGS, for a list of known bugs in this release, and
information about reporting new bugs.


Mailing lists:
==============

We maintain 5 mailing lists:

  freeciv-announce@freelists.org
                   Announcements of general interest.
                   This is a "Read Only" list, with infrequent messages.
                   In other words you can't mail this list, just read it.
                   Subscribe: https://www.freelists.org/list/freeciv-announce
  freeciv-i18n@freelists.org
                   Freeciv translation.
                   All discussions related to translating the Freeciv code,
                   documentation, and website, into other languages than
                   English.
                   Subscribe: https://www.freelists.org/list/freeciv-i18n
  freeciv-dev@freelists.org
                   Freeciv development.
                   Subscribe: https://www.freelists.org/list/freeciv-dev
  freeciv-tickets@lists.osdn.me
                   Automated notifications about updates to
                   bug and patch tickets.
                   Subscribe: https://lists.osdn.me/mailman/listinfo/freeciv-tickets
  freeciv-commits@gna.org
                   Notifications of changes to the code repository.
                   This is a "Read Only" list, carrying automated messages.
                   In other words you can't mail this list, just read it.
                   (At the time of writing, gna.org is expected to shut
                   down soon; we're not yet sure what arrangements we'll
                   have for a replacement commits mailing list.)

All lists are open to the general public and everyone is welcome to join.
Only maintainers may post to the -announce and -commits lists.


Internet Relay Chat (IRC)
=========================

Several players and developers hang out on #freeciv and #freeciv-dev
channels on the Libera.Chat network. Try connecting to the server

        irc.libera.chat


And finally:
============

Have fun and give 'em hell!

                                   -- The Freeciv team.

==============
THE FREECIV AI
==============

This document is about freeciv's default AI. Freeciv supports also
using custom AI modules, though at the time of writing none exist.
See README.AI_modules about support of custom modules.


CONTENTS
========
Introduction
Contacting the current AI developers
Long-term AI development goals
Want calculations
Amortize
Estimation of profit from a military operation
Selecting military units
Ferry system
Diplomacy
Difficulty levels
Things that needs to be fixed
Idea space


INTRODUCTION
============

The Freeciv AI is widely recognized as being as good as or better
military-wise as the AI of certain other games it is natural to compare
it with.  It is, however, still too easy for experienced players.

The code base used to be in a bad shape but it has gotten a lot
better.  The reason for this is that the developer (Syela) who in a
few months put together a working AI had suddenly disappeared.  His
bright ideas could only be matched by his inability to name variables
and to comment the code.  Subsequent AI developers were not brave (or
stupid?) enough to start from scratch, taking instead a small bite
here and there, trying hard not to break much, to understand Syela's
original design and only then to throw it away.  Or perfect it.

Code that implements the AI is divided between ai/ and server/advisors.
Latter is used also by human players for such automatic helpers
as auto-settlers and auto-explorers.


CONTACTING THE CURRENT AI DEVELOPERS
====================================

AI development used to have its own mailing list, freeciv-ai@freeciv.org.
Go to

  http://www.freeciv.org/wiki/Community_Forums

to read the archives.

Currently freeciv-dev@freelists.org is used for all discussion about
Freeciv development.


LONG-TERM AI DEVELOPMENT GOALS
==============================

The long-term goals for Freeciv AI development are
 -> to create a challenging and fun AI for human players to defeat
 -> to create an AI that can handle all the rules possibilities that
    Freeciv can offer


WANT CALCULATIONS
=================

Build calculations are expressed through a structure called adv_choice.
This has a variable called "want", which determines how much the AI
wants whatever item is pointed to by choice->type. choice->want is

   -199   get_a_boat
   < 0    an error
   == 0   no want, nothing to do
   <= 100 normal want
    > 100 critical want, used to requisition emergency needs
    > ??? probably an error (1024 is a reasonable upper bound)
    > 200 Frequently used as a cap. When want exceeds this value,
          it is reduced to a lower number.

These are ideal numbers, your mileage while travelling through the
code may vary considerably.  Technology and diplomats, in particular,
seem to violate these standards.


AMORTIZE
========

Hard fact:
amortize(benefit, delay) returns benefit * ((MORT - 1)/MORT)^delay
(where "^" == "to the power of")

Speculation:
What is better, to receive 10$ annually starting in 5 years from now
or 5$ annually starting from this year?  How can you take inflation
into account?  The function amortize is meant to help you answer these
questions.  To achieve this, it rescales the future benefit in terms of
todays money.

Suppose we have a constant rate of inflation, x percent.  Then in five
years time 10$ will buy as much as 10*(100/(100+x))^5 will buy today.
Denoting 100/(100+x) by q we get the general formula, N dollars Y
years from now will be worth N*q^Y in todays money.  If we will
receive N every year starting Y years from now, the total amount
receivable (in todays money) is N*q^Y / (1-q) --- this is the sum of
infinite geometric series.  This is exactly the operation that
amortize performs, the multiplication by some q < 1 raised to power Y.
Note that the factor 1/(1-q) does not depend on the parameters N and Y
and can be ignored.  The connection between MORT constant and the
inflation rate x is given by
    (MORT - 1) / MORT = q = 100 / (100 + x).
Thus the current value of MORT = 24 corresponds to the inflation rate
(or the rate of expansion of your civ) of 4.3%

Most likely this explanation is not what the authors of amortize() had
in mind, but the basic idea is correct: the value of the payoff decays
exponentially with the delay.

The version of amortize used in the military code (military_amortize())
remains a complete mystery.


ESTIMATION OF PROFIT FROM A MILITARY OPERATION
==============================================

This estimation is implemented by kill_desire function (which isn't
perfect: multi-victim part is flawed) plus some corrections.  In
general,
        Want = Operation_Profit * Amortization_Factor
where

* Amortization_Factor is completely beyond me (but it's a function of the
estimated time length of the operation).

* Operation_Profit = Battle_Profit - Maintenance

where

* Maintenance
  = (Support + Unhappiness_Compensation) * Operation_Time
  (here unhappiness is from military unit being away from home
   and Support is the number of shields spent on supporting this unit
   per turn )

* Battle_Profit
  = Shields_Lost_By_Enemy * Probability_To_Win
    - Shields_Lost_By_Us * Probability_To_Lose

That is Battle_Profit is a probabilistic average.  It answer the
question "how much better off, on average, we would be from attacking
this enemy unit?"


SELECTING MILITARY UNITS
========================

The code dealing with choosing military units to be built and targets
for them is especially messy.  Here is what we've managed to decipher.

Military units are requested in military_advisor_choose_build
function.  It first considers the defensive units and then ventures
into selection of attackers (if home is safe).  There are 2
possibilities here: we just build a new attacker or we already have an
attacker which was forced, for some reason, to defend.  In the second
case it's easy: we calculate how good the existing attacker is and if
it's good, we build a defender to free it up.

Building a brand-new attacker is more complicated.  Firstly,
ai_choose_attacker_* functions are charged to find the first
approximation to the best attacker that can be built here.  This
prototype attacker is selected using very simple attack_power * speed
formula.  Then (already in kill_something_with) we search for targets
for the prototype attacker (using find_something_to_kill).  Having
found a target, we do the last refinement by calling
process_attacker_want to look for the best attacker type to take out
the target.  This type will be our attacker choice.  Note that the
function process_attacker_want has side-effects wrt the tech selection.

Here is an example:

First ai_choose_attacker_land selects a Dragoon because it's strong
and fast.  Then find_something_to_kill finds a victim for the
(virtual) Dragoon, an enemy Riflemen standing right next to the town.
Then process_attacker_want figures out that since the enemy is right
beside us, it can be taken out easier using an Artillery.  It also
figures that a Howitzer would do this job even better, so bumps up our
desire for Robotics.

This is the idea, anyway.  In practice, it is more complicated and
probably less efficient.


FERRY SYSTEM
============

The ferry (i.e. boats transporting land units) system of Freeciv is
probably better described by statistical mechanics than by logic.
Both ferries and prospective passenger (PP) move around in what looks
like a random fashion, trying to get closer to each other.  On
average, they succeed.  This behaviour has good reasons behind it, is
hell to debug but means that small bugs don't affect overall picture
visibly (and stay unfixed as a result).

Each turn both boats and PPs forget all about prior arrangements
(unless the passenger is actually _in_ the boat).  Then each will look
for the closest partner, exchange cards and head towards it.  This is
done in a loop which goes through all units in essentially random
order.

Because most units recalculate their destination every turn, ignoring
prior arrangements is the only good strategy -- it means that a boat
will not rely on the PP to notify it when it's not needed anymore.
This is not very effective but can only be changed when the PPs behave
more responsibly.  See diplomat code for more responsible behaviour --
they try to check if the old target is still good before trying to
find a new one.

When a boat has a passenger, it's a different story.  The boat doesn't
do any calculations, instead one of the passengers is given full
control and it is the passenger who drives the boat.

Here are the main data fields used by the system.
Value of ai.ferry in the passenger unit is:
  FERRY_NONE : means that the unit has no need of a ferry
  FERRY_WANTED : means that the unit wants a ferry
  >0 : id of it's ferry
Value of ai.passenger in the ferry unit can be either of:
  FERRY_AVAILABLE : means that the unit is a ferry and is available
  >0 : id of it's passenger

When boat-building code stabilizes, it can be seen how many free boats
there are, on average, per PP.  If there are more boats than PPs, it
makes sense that only PPs should look for boats.  If boats are few,
they should be the ones choosing.  This can be done both dynamically
(both possibilities are coded and the appropriate is chosen every
turn) and statically (after much testing only one system remains).
Now they exist in parallel, although developed to a different degree.


DIPLOMACY
=========

The AI's diplomatic behaviour is current only regulated by the
'diplomacy' server setting.

AI proposes cease-fire on first contact.

AI is not very trusting for NEUTRAL and PEACE modes, but once it hits
ALLIANCE, this changes completely, and it will happily hand over
any tech and maps it has to you.  The only thing that will make the AI
attack you then is if you build a spaceship.

For people who want to hack at this part of the AI code, please note
 * pplayers_at_war(p1,p2) returns FALSE if p1==p2
 * pplayers_non_attack(p1,p2) returns FALSE if p1==p2
 * pplayers_allied(p1,p2) returns TRUE if p1==p2
 * pplayer_has_embassy(p1,p2) returns TRUE if p1==p2
i.e. we do not ever consider a player to be at war with himself, we
never consider a player to have any kind of non-attack treaty with
himself, and we always consider a player to have an alliance with
himself.

The introduction of diplomacy is fraught with many problems.  One is
that it usually gains only human players, not AI players, since humans
are so much smarter and know how to exploit diplomacy, while for AIs
they mostly only add constraints on what it can do.  Another is that it
can be very difficult to write diplomacy that is useful for and not in
the way of modpacks.  Which means diplomacy either has to be optional,
or have fine-grained controls on who can do what diplomatic deals to
whom, set from rulesets.  The latter is not yet well implemented.


DIFFICULTY LEVELS
=================

There are currently seven difficulty levels: 'handicapped, 'novice',
'easy', 'normal', 'hard', 'cheating', and 'experimental'.
The 'hard' level is no-holds-barred. 'Cheating' is the same
except that it has ruleset defined extra bonuses, while 'normal'
has a number of handicaps. In 'easy', the AI also does random stupid
things through the ai_fuzzy function. The 'experimental' level is
only for coding - you can gate new code
with the H_EXPERIMENTAL handicap and test 'experimental' level
AIs against 'hard' level AIs. In 'novice' the AI researches slower
than normal players.

Other handicaps used are:
  H_DIPLOMAT     Can't build offensive diplomats
  H_LIMITEDHUTS  Can get only 25 gold and barbs from huts
  H_DEFENSIVE    Build defensive buildings without calculating need
  H_RATES        Can't set its rates beyond government limits
  H_TARGETS      Can't target anything it doesn't know exists
  H_HUTS         Doesn't know which unseen tiles have huts on them
  H_FOG          Can't see through fog of war
  H_NOPLANES     Doesn't build air units
  H_MAP          Only knows map_is_known tiles
  H_DIPLOMACY    Not very good at diplomacy
  H_REVOLUTION   Cannot skip anarchy
  H_EXPANSION    Don't like being much larger than human
  H_DANGER       Always thinks its city is in danger

For an up-to-date list of all handicaps and their use for each
difficulty level see ./ai/handicaps.h.


THINGS THAT NEED TO BE FIXED
============================

* Cities don't realize units are on their way to defend it.
* AI builds cities without regard to danger at that location.
* AI won't build cross-country roads outside of city radii.
* Locally_zero_minimap is not implemented when wilderness tiles
change.
* If no path to chosen victim is found, new victim should be chosen.
* Emergencies in two cities at once aren't handled properly.
* Explorers will not use ferryboats to get to new lands to explore.
The AI will also not build units to explore new islands, leaving huts alone.
* AI sometimes believes that wasting a horde of weak military units to
kill one enemy is profitable (PR#1340)
* Stop building shore defense in landlocked cities with a pond adjacent.
* Fix the AI valuation of supermarket. (It currently never builds it).
See farmland_food() and ai_eval_buildings() in advdomestic.c
* Teach the AI to coordinate the units in an attack (ok, this one is a bit
big...)


IDEA SPACE
==========

* Friendly cities can be used as beachheads
* Assess_danger should acknowledge positive feedback between multiple
attackers
* It would be nice for bodyguard and charge to meet en-route more
elegantly.
* struct choice should have a priority indicator in it.  This will
reduce the number of "special" want values and remove the necessity to
have want capped, thus reducing confusion.

CONTENTS
========

1. Default build
2. Using freeciv built with AI-modules support
3. Building freeciv with AI-modules support
4. Coding new AI module
5. Using default AI as part of new AI module
6. Callback interface ChangeLog


1. Default build
----------------

By default Freeciv is built with just one, "classic", AI type
statically built in, and with no support for dynamic AI modules.
Classic AI is always used for all players, effectively hiding the
fact that AI module interface even exist.


2. Using freeciv built with AI-modules support
----------------------------------------------

Some modules might be statically linked to freeciv server, and those
are always available. If freeciv is built with also dynamic modules
support enabled, one can load additional AI modules to server with
commandline option "--LoadAI <modulename>"
Whether module is statically linked or dynamically loaded, new AI players
that use that module can be created by giving "create" command AI type as
second parameter
> create Leonidas classic

Players created any other way, such as by aifill will get the AI type
that has been made the default freeciv build time.

Information "list" command shows includes player's AI type:
> list
Leonidas [#ff0000]: Team 0, user Unassigned
  AI, classic, difficulty level Easy


3. Building freeciv with AI-modules support
-------------------------------------------

There's three configure options controlling AI-modules support to be
built in to freeciv.

To statically link some of the supplied AI modules to freeciv,
use --enable-ai-static=<comma,separated,list>. Default value for this
is just "classic". Order of the modules is important in that first of
the modules will be the default AI type used for all the players for whom
it's not explicitly set.

To support dynamically loading additional modules, use
--enable-aimodules. It requires that also --enable-shared has been used,
which may not work on all platforms.
Special value --enable-aimodules=experimental makes freeciv also to build
all the modules in its source tree as dynamically loadable AI modules.

In case you want to use some dynamically loadable module as the default
AI type instead of first type listed for --enable-ai-static, you can
explicitly set the default type with --with-default-ai=<type>.

Dynamic AI modules are expected in their correct installation location
unless one has configured with --enable-debug which allows freeciv
server to look for supplied modules from build directory too. Otherwise you
cannot use dynamic modules from the freeciv build dir, but you need
to "make install" freeciv to install them to correct location.


4. Coding new dynamic AI module
-------------------------------

Dynamic AI module to be loaded with "--LoadAI <modulename>" needs to contain
two functions.

const char *fc_ai_<modulename>_capstr(void)
  This needs to return capability string of the module. This is used to
  check if module is compatible with the version of freeciv one tries to
  load it into. Current freeciv's capstr is in common/ai.h macro FC_AI_MOD_CAPSTR.


bool fc_ai_<modulename>_setup(struct ai_type *ai)
  This function is called for AI module to setup itself. Most importantly
  it should setup callback table ai->funcs so that its other functions
  get called, and fill ai->name so that it can be referred to in creation of
  new players.
  Callback table, with comments when each callback gets called, is defined
  in common/ai.h

For "--LoadAI <modulename>" to find the AI module, it must reside in ${libdir}/fcai/
(/usr/lib/fcai by default) under name fc_ai_<modulename>.so


5. Using default AI as part of new AI module
--------------------------------------------

Default AI here refers to specific code module that any AI module can use, not to any
one AI module. Classic AI module is just a thin wrapper around it, and also Threaded AI
uses it.

Almost all functions in default AI API take pointer to current AI type as parameter.
This is used for accessing memory associated with the correct AI type from the structures
having such AI type specific data.

If a AI type wants to add its own data associated with some code structure, it needs
to make sure data needed by default AI is in the beginning of the allocated data blocks.
For example, see threaded AI: tai_player_alloc(), tai_player_free(), and struct tai_plr.

Default AI code is usually built in freeciv only if some AI type using it has been built;
either 'classic' or 'threaded'. If no such ai type has been built, you can still force
it in for custom ai types to use by passing configure option --with-ai-lib


6. Callback interface ChangeLog
-------------------------------

New in Freeciv 2.6:
-------------------
- Renamed enum danger_consideration as enum override_bool
- Added restart_phase, called when AI gains control of the player whose phase is already
  active, for example when continuing from a saved game
- Added created_by_civil_war, called for AI type of the player who got created from
  civil war
- Added "created" player parameter to split_by_civil_war
- Added game_start, called for all AI types when game starts
- "city_got" is called when the city is fully initialized, "city_lost" when city still valid
- Added gov_value for giving AI control of deciding value of governments
- Added player_save_relations and player_load_relations called on savegame handling for a
  player once per other player in game. Old player_save and player_load are called only once
  overall
- Added want_to_explore, called for AI type of the unit owner, when it is about to autoexplore
- Added currently unused 'reserved' pointers that we can populate with optional callbacks
  without need to change the mandatory capability of the modules

Achievements are something player can gain in game by reaching
set goals. Achievements active in the ruleset are defined in
game.ruleset.

Depending on whether achievement is defined unique or not,
they are granted only to first player, or all players,
to reach the goal for the achievement. Goal is defined by
achievement type and another value specific to that achievement type.


Achievement types
=================

Map_Known
    Achievement is granted when player has mapped at least
    <value>% of the world.

Spaceship
    This achievement is granted when player launches spaceship.
    <Value> is ignored.

Multicultural
    Achievement is granted when player has citizens of at least
    <value> different nationalities (across all their cities).

Cultured_City
    Achievement is granted when player has a city with at least
    <value> culture points.

Cultured_Nation
    Achievement is granted when player has at least <value>
    culture points.

Lucky
    Achievement is granted on turn when random number generator
    gives value less than <value> out of 10000.

Huts
    Achievement is granted once player has entered <value> huts.

Metropolis
    Achievement is granted once there's city of at least size
    <value> in the player's empire.

Literate
    Achievement is granted when player's literacy percent is at least
    <value>.

Land_Ahoy
    Achievement is granted when player has seen <value> different
    islands/continents. Home continent counts, so to give achievements
    for finding first other continent, use value 2.

Actions
=======
An action is something a player can do to achieve something in the game.
It has properties like cost, chance of success and effects. Some of those
properties are configurable using effects and other rule set settings. To
learn how to change them read README.effects and the rule set files of
classic. An action enabler allows a player to do an action.

Generalized action enablers
===============================
Some actions have generalized action enablers. An action like that can have
zero, one or more action enablers defined for it in the ruleset. The player can
do the action only when at least one generalized action enabler says that the
action is enabled (and all its hard requirements are fulfilled). A ruleset
author can therefore disable an action by not defining any action enablers for
it in his ruleset.

A generalized action enabler lives in game.ruleset. It consists of the action it
enables and two requirement vectors. The first requirement vector, actor_reqs,
applies to the entity doing the action. The second, target_reqs, applies to its
target. If both requirement vectors are fulfilled the action is enabled as far
as the action enabler is concerned. Note that an action's hard requirements
still may make it impossible.

In some situations an action controlled by generalized action enablers may be
impossible because of limitations in Freeciv it self. Those limitations are
called hard requirements. The hard requirements of each action are documented
below in the section called "Actions and their hard coded requirements".

If the player don't have the knowledge required to find out if an action is
enabled or not the action is shown to the player in case it is possible. The
client will indicate the uncertainty to the player.

Should the player order a unit to do an illegal action the server will
inform the player that his unit was unable to perform the action. The actor
unit may also lose a ruleset configurable amount of move fragments.

Example
=======
[actionenabler_veil_the_threat_of_terror]
action = "Incite City"
actor_reqs    =
    { "type",   "name", "range", "present"
      "DiplRel", "Has Casus Belli", "Local", TRUE
      "DiplRel", "Provided Casus Belli", "Local", FALSE
    }

[actionenabler_go_bind_your_sons_to_exile]
action = "Incite City"
actor_reqs    =
    { "type",   "name", "range", "present"
      "Tech", "Flight", "Player", TRUE
    }
target_reqs    =
    { "type",   "name", "range", "present"
      "Tech", "Writing", "Player", False
    }

Above are two action enablers. They both enable the action "Incite City". If
all the conditions of at least one of them are fulfilled it will be enabled.
No information is given to the player about what action enabler enabled an
action.

The first action enabler, actionenabler_veil_the_threat_of_terror, is
simple. It allows a player to incite a city if he has a reason to declare
war on its owner AND the cities owner don't have a reason to declare war on
him.

The second action enabler, actionenabler_go_bind_your_sons_to_exile, is more
complex. It allows a player that has Flight to bribe the cities of
civilizations that don't have Writing. The complexity is caused by the
requirement that the target don't know Writing. If the civilization of the
target city knows Writing or not may be unknown to the acting player. To
avoid this complexity a requirement that the acting player has an embassy to
the target cities civilization (and therefore knowledge about its techs) can
be added.

Requirement vector rules
========================
An action enabler has two requirement vectors that must be true at the same
time. This creates some corner cases you won't find with single requirement
vectors. The rules below tries to deal with them.

A "DiplRel" requirement with the range "Local" should always be put in the
actor requirements.
 * A local DiplRel requirement can always be expressed as an actor
   requirement.
 * Only having to care about local DiplRel requirements in the actor
   requirements allows the Freeciv code responsible for reasoning about
   action enablers to be simpler and faster.
 * If player A having a diplomatic relationship to player B implies that
   player B has the same relationship to player A the relationship is
   symmetric. Examples: "Is foreign" and "War"
 * Symmetric local DiplRel requirements can be moved directly from the
   target requirement vector to the actor requirement vector.
 * Asymmetric local DiplRel requirements must test for the same thing in
   the opposite direction. Example: "Hosts embassy" -> "Has embassy"

Actions and Lua
===============
Right before an action is executed, but after it is known to be legal, a
signal is emitted to Lua. It has access to the same information as the
server. It obviously don't have access to the result of the action since it
isn't done yet.

The signal's name starts with action_started_, then the actor kind, then
another _ and in the end the target kind. The signal that is emitted when a
unit performs an action on a city is therefore action_started_unit_city.

The signal has three parameters. The first parameter is the action that is
about to get started. The second is the actor. The third parameter is the
target. The parameters of action_started_unit_city is therefore action,
actor_unit and finally target city.

To get the rule name of an action, that is the name used in action enablers,
you can use the method rule_name(). To get a translated name that is nice to
show to players use name_translation().

Example 1
=========
The following Lua code will log all actions done by any unit to a city or to
another unit:

function action_started_callback(action, actor, target)
  log.normal(_("%s (rule name: %s) performed by %s on %s"),
             action:name_translation(),
             action:rule_name(),
             actor.owner.nation:plural_translation(),
             target.owner.nation:plural_translation())
end

signal.connect("action_started_unit_city", "action_started_callback")
signal.connect("action_started_unit_unit", "action_started_callback")

Example 2
=========
The following Lua code will make a player that poisons the population of
cities risk civil war:

function action_started_callback(action, actor, target)
  if action:rule_name() == "Poison City" then
     edit.civil_war(actor.owner, 5);
  end
end

signal.connect("action_started_unit_city", "action_started_callback")

Actions and their hard coded requirements
=========================================

Actions done by a unit against a city
=====================================
"Establish Embassy" - Establish a real embassy to the target player
 * UI name can be set using ui_name_establish_embassy
 * actor must be aware that the target exists
 * actor can't have a real embassy to the target player
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Investigate City" - Look at the city dialog of a foreign city
 * UI name can be set using ui_name_investigate_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Sabotage City" - Destroy a building or the production in the target city.
 * UI name can be set using ui_name_sabotage_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.

"Targeted Sabotage City" - Targeted version of the above.
 * UI name can be set using ui_name_targeted_sabotage_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.

"Poison City" - Kill a citizen in the target city.
 * UI name can be set using ui_name_poison_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.

"Steal Tech" - Steal a random tech from the targets owner.
 * UI name can be set using ui_name_steal_tech
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Targeted Steal Tech" - Targeted version of the above.
 * UI name can be set using ui_name_targeted_steal_tech
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Incite City" - Pay the target city to join the actors owners side.
 * UI name can be set using ui_name_incite_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Steal Gold" - Steal some gold from the owner of the target city.
 * UI name can be set using ui_name_steal_gold
 * adjustable with the Max_Stolen_Gold_Pm effect and with the
   Thiefs_Share_Pm effect
 * actor must be aware that the target exists
 * the targets owner must have more than 0 gold.
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Establish Trade Route" - Establish a trade route to the target city.
 * UI name can be set using ui_name_establish_trade_route
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * actor must have a home city.
 * target must be foreign or trademindist tiles away from that home city.
 * trade route type pct (see "Trade settings") can't be 0%.
 * it is possible to establish a trade route between the cities as far as
   the two cities them self are concerned. (Example: If one of the cities
   can't have any trade routes at all it is impossible to establish a new
   one.)

"Enter Marketplace" - Get a one time bounus without creating a trade route.
 * UI name can be set using ui_name_enter_marketplace
 * actor must be aware that the target exists
 * if force_trade_route is true "Establish Trade Route" must be impossible
 * actor must be on the same tile as the target or on the tile next to it.
 * actor must have a home city.
 * target must be foreign or trademindist tiles away from that home city.
 * trade route type (see Trade settings) can't be 0%.

"Help Wonder" - Add the shields used to build the actor to the target city.
 * UI name can be set using ui_name_help_wonder
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be building a wonder.
 * target city must still need the extra sheilds to build the wonder.

Actions done by a unit against another unit
===========================================
"Sabotage Unit" - Halve the target unit's hit points.
 * UI name can be set using ui_name_sabotage_unit
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be visible for the actor.

"Bribe Unit" - Make the target unit join the actors owners side.
 * UI name can be set using ui_name_bribe_unit
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.
 * target must be visible for the actor.

Overview
========

An agent is a piece of code which is responsible for a certain
area. An agent will be given a specification by the user of the agent
and a set of objects which the agent can control (the production
queue of a city, a city, a unit, a set of units or the whole
empire). The user can be a human player or another part of the code
including another agent. There is no extra interaction between the
user and the agent needed after the agent got its task description.

Examples of agents:
 - an agent which is responsible for moving a certain unit from A to B
 - an agent which is responsible for maximize the food production of a
 city
 - an agent which is responsible for the production queue of a city
 - an agent which is responsible for defending a city
 - an agent which is responsible for a city
 - an agent which is responsible for all cities

An agent may use other agents to accomplish its goal. Such decencies
form a hierarchy of agents. The position in this hierarchy is denoted
by a level. A higher level means more complexity. So an agent of level
n can only make use of agents of level (n-1) or lower. Level 0 defines
actions which are carried out at the server and are atomic actions
(actions which can't be simulated at the client).

By such a definition an agent doesn't have to be implemented in C and
also doesn't have to make use of client/agents/agents.[ch].

The core of an agent consist of two parts: a part which makes
decisions and a part which carries out the decision. The results of
the first part should be made available. An agent lacking the
execution part is called advisor.

An agent should provide a GUI besides the core.

Implementation
==============

The received task description and any decision been made can be saved
in attributes. An agent should not assume anything. This includes
especially: _no magic numbers_. Everything should be settable by the
user.

Use client/agents/agents.[ch] to get informed about certain
events. Don't hesitate to add more callbacks. Use
client/agents/agents:wait_for_requests instead of
client/civclient:wait_till_request_got_processed.

Client/server model
===================

Each client player has an attribute block and the server also holds
such an attribute block for every player. All attribute blocks the
server holds are included in the save game. The client and server
synchronize their blocks. The server sends its block to the client at
game start or reload. The client sends an updated block at each end of
turn to the server. Since the maximum packet size is limited to
currently 4k and the attribute block can have arbitrary size (although
limited to 64k in this initial version) the attribute block can't be
transferred in one packet. So the attribute block is divided into
attribute chunks which are reassembled at the receiver. No part of the
server knows any inner structure of the attribute block. For the
server an attribute block is just a block of bytes.

User interface
==============

Since an attribute block isn't a good user interface the user can
access the attributes through a mapping/dictionary/hashmap/hashtable
interface. This hashtable will get serialized to the attribute block
and the other direction around. The key of the hashtable consists of:
the (real) key, x, y and an id. The (real) key is an integer which
defines the use and format of this attribute. The values of the
hashtable can have arbitrary length. The internal structure of an
value is unknown to the attribute handling.

For easier access there are wrapper functions for the common types
unit, city, player and tile. So there are easy methods for attaching
arbitrary data to a unit, a city, a player (self or other) or a tile.

=========================================================================
  Delta
=========================================================================

If delta is enabled for this packet the packet-payload (after the bytes
used by the packet-header) is followed by the delta-header. (See HACKING
to learn how to understand the packet-header.) The delta-header
is a bitvector which represents all non-key fields of the packet. If
the field has changed the corresponding bit is set and the field
value is so included in delta-body. The values of the unchanged fields
will be filled in from an old version at the receiving side. The old
version filled in from is the previous packet of the same kind that has
the same value in each key field. (If the packet's kind don't have any
key fields the previous packet of the same kind is used) If no old
version exists the unchanged fields will be assumed to be zero.

For bool field another optimization called bool-header-folding is
applied. Instead of sending an indicator in the bitvector if the given
bool values has changed (and so using 1 byte for the real value) the
actual value of the bool is transfered in the bitvector bit of this
bool field.

Another optimization called array-diff is used to reduce the amount of
elements transfered if an array is changed. This is independent of the
delta-header bit i.e. it will only be used if the array has changed
its value and the bit indicates this. Instead of transferring the
whole array only a list of (index, new value of this index) pairs are
transferred. The index is 8bit and the end of this pair list is
denoted by an index of 255.

For fields of struct type (or arrays of struct) the following function
is used to compare entries, where foo stands for the name of the struct:

  bool are_foo_equal(const struct foo *a, const struct foo *b);

The declaration of this function must be made available to the generated
code by having it #include the correct header. The includes are hard-
coded in generate_packets.py.

=========================================================================
  Compression
=========================================================================

To further reduce the network traffic the (delta) packets are
compressed using the DEFLATE compression algorithm.
To get better compression results multiple packets are
grouped together and compressed into a chunk. This chunk is then
transfered as a normal packet. A chunk packet starts with the 2 byte
length field which every packet has. A chunk packet has no type. A
chunk packet is identified by having a too large length field. If the
length of the packet is over COMPRESSION_BORDER it is a chunk
packet. It will be uncompressed at the receiving side and re-feed into
the receiving queue.

If the length of the chunk packet can't be expressed in the available
space of the 16bit length field (>48kb) the chunk is sent as a jumbo
packet. The difference between a normal chunk packet and a jumbo chunk
packet is that the jumbo packet has JUMBO_SIZE in the size field and
has an additional 4 byte len field after the 2 byte len field. The
second len field contains the size of the whole packet (2 byte
first length field + 4 byte second length field + compressed data).
The size field of a normal chunk packet is its size + COMPRESSION_BORDER.

Packets are grouped for the compression based on the
PACKET_PROCESSING_STARTED/PACKET_PROCESSING_FINISHED and
PACKET_FREEZE_HINT/PACKET_THAW_HINT packet pairs. If the first
(freeze) packet is encountered the packets till the second (thaw)
packet are put into a queue. This queue is then compressed and sent as
a chunk packet. If the compression would expand in size the queued
packets are sent uncompressed as "normal" packets.

The compression level can be controlled by the
FREECIV_COMPRESSION_LEVEL environment variable.

=========================================================================
  Files
=========================================================================

There are four file/filesets involved in the delta protocol:
 1) the definition file (common/packets.def).
 2) the generator (common/generate_packets.py).
 3) the generated files (*/*_gen.[ch] or as a list
 client/packhand_gen.c, client/packhand_gen.h, common/packets_gen.c,
 common/packets_gen.h, server/hand_gen.c and server/hand_gen.h).
 4) the overview (README.delta, this file)

The definition file lists all valid packet types with their
fields. The generator takes this as input and creates the generated
files.

For adding and/or removing packets and/or fields you only have to
touch the definition file. If you however plan to change the generated
code (adding more statistics for example) you have to change the
generator.

=========================================================================
  Changing the definition file
=========================================================================

Adding a packet:
 1) choose an unused packet number. The generator will make sure that
 you don't use the same number two times.
 2) choose a packet name. It should follow the naming style of the
 other packets: PACKET_<group>_<remaining>. <group> may be SERVER,
 CITY, UNIT, PLAYER, DIPLOMACY and so on.
 3) decide if this packet goes from server to client or client to server
 4) choose the field names and types
 5) choose packet and field flags
 6) write the entry into the corresponding section of common/packets.def

If you add a field which is a struct (say "foobar") you have to write
the following functions: dio_get_foobar, dio_put_foobar and
are_foobars_equal.

Removing a packet:
 1) add a mandatory capability
 2) remove the entry from common/packets.def

Adding a field:
 Option A:
   1) add a mandatory capability
   2) add a normal field line:
      COORD x
 Option B:
   1) add a non-mandatory capability (say "new_version")
   2) add a normal field line containing this capability in an add-cap
   flag:
      COORD x; add-cap(new_version)

Removing a field:
 Option A:
   1) add a mandatory capability
   2) remove the corresponding field line
 Option B:
   1) add a non-mandatory capability (say "cleanup")
   2) add to the corresponding field line a remove-cap flag

After changing the definition file the generator has to be run. The
common/Makefile will take care of this. You don't need to run
autoconf/automake/configure.

=========================================================================
  Capabilities and variants
=========================================================================

The generator has to generate code which supports different
capabilities at runtime according to the specification given in the
definitions with add-cap and remove-cap. The generator will find the
set of used capabilities for a given packet. Lets say there are two
fields with "add-cap(cap1)" and one field with an "remove-cap(cap2)"
flag. So the set of capabilities are cap1, cap2. At runtime the
generated code may run under 4 different capabilities:
 - neither cap1 nor cap2 are set
 - cap1 is set but cap2 isn't
 - cap1 is not set but cap2 is
 - cap1 and cap2 are set

Each of these combinations is called a variant. If n is the number of
capabilities used by the packet the number of variants is 2^n.

For each of these variant a seperate send and receive function will be
generated. The variant for a packet and a connection are calculated
once and then saved in the connection struct.

The effects.ruleset file contains all effects in play in a Freeciv scenario.
They have the following form (this is perhaps the most complicated example I
could find):

[effect_hydro_plant]
type  = "Output_Bonus"
value = 25
reqs  =
    { "type", "name", "range", "present", "quiet"
      "Building", "Factory", "City", TRUE, FALSE
      "Building", "Hydro Plant", "City", TRUE, FALSE
      "OutputType", "Shield", "Local", TRUE, TRUE
      "Building", "Hoover Dam", "Player", FALSE, FALSE
      "Building", "Nuclear Plant", "City", FALSE, FALSE
    }

The text in the brackets is the entry name, which just has to be unique, but
is otherwise not used. The type field tells Freeciv which effect you are
defining.  The value is the effect's value, which depends on which effect it
is. The reqs table contain a list of requirements for this effect being in
effect. You need to satisfy all requirements listed here for this effect to
take effect in the game. Requirements with present = TRUE must be present,
those with present = FALSE must not be present.

Value is integral amount parameter for many effects (must be in the range
-32767 to 32767).

Requirement range may be one of: "None", "Local",
"CAdjacent" (Cardinally Adjacent), "Adjacent", "City",
"Continent", "Player", "Allied, "World". Some requirement types may only work at
certain ranges; this is not yet documented. In particular, at present,
"Continent" effects can affect only cities and units in cities.

A requirement may have a 'survives' field, and if this is 'TRUE', the effect
survives destruction. This is supported for only a few conditions and
ranges: wonders (at world or player range), nations, and advances
(both at world range only).

A requirement may have a 'present' field, and if this is 'FALSE',
the requirement is negated (the condition must not be true for the req to be
met).

A requirement may have a 'quiet' field, and if this is 'TRUE', the help
system does not try to autogenerate text about that requirement. This
can be used if the help system's text is unclear or misleading, or if
you want to describe the requirement in your own words. The 'quiet'
field has no effect on the game rules.


Requirement types and supported ranges
======================================

Tech:            World, Alliance, Team, Player
TechFlag:        World, Alliance, Team, Player
Achievement:     World, Alliance, Team, Player
Gov:             Player
Building:        World, Alliance, Team, Player, Continent, Traderoute, City, Local
Extra:           Local, Adjacent, CAdjacent, Traderoute, City
BaseFlag:        Local, Adjacent, CAdjacent, Traderoute, City
RoadFlag:        Local, Adjacent, CAdjacent, Traderoute, City
ExtraFlag:       Local, Adjacent, CAdjacent, Traderoute, City
Terrain:         Local, Adjacent, CAdjacent, Traderoute, City
Resource:        Local, Adjacent, CAdjacent, Traderoute, City
UnitType:        Local
UnitFlag:        Local
UnitClass:       Local
UnitClassFlag:   Local
Nation:          World, Alliance, Team, Player
NationGroup:     World, Alliance, Team, Player
Nationality:     Traderoute, City
DiplRel:         World, Alliance, Team, Player, Local
OutputType:      Local
Specialist:      Local
MinYear:         World
Topology:        World
Age (of unit):   Local
Age (of city):   City
Age (of player): Player
MinSize:         Traderoute, City
MinCulture:      World, Alliance, Team, Player, Traderoute, City
AI:              Player
MaxUnitsOnTile:  Local, Adjacent, CAdjacent
TerrainClass:    Local, Adjacent, CAdjacent, Traderoute, City
TerrainFlag:     Local, Adjacent, CAdjacent, Traderoute, City
TerrainAlter:    Local
CityTile:        Local, Adjacent, CAdjacent
Style:           Player
UnitState:       Local
MinMoveFrags:    Local
MinVeteran:      Local
MinHitPoints:    Local


MinSize is the minimum size of a city required.
AI is ai player difficulty level.
TerrainClass is either "Land" or "Oceanic".
TerrainAlter is "CanIrrigate", "CanMine", or "CanRoad".
CityTile is either "Center" (city center) or "Claimed" (owned).
DiplRel is a diplomatic relationship.
MaxUnitsOnTile is about the number of units present on a tile.
UnitState is "Transported" or "OnLivableTile".
MinMoveFrags is the minimum move fragments the unit must have left.
Nationality is fulfilled by any citizens of the given nationality
present in the city.


Effect types
============

Tech_Parasite
    Gain any advance known already by amount number of other teams,
if team_pooled_research is enabled, or amount number of other players
otherwise. Note that if you have two such effects, they combine into
one much worse effect (the number of players required to gain an advance
is increased).

Airlift
    Allow airlift to/from a city. The value tells how many units per
    turn can be airlifted, unless server setting 'airlifttingstyle' sets
    the number unlimited for either source or destination city. If airlifts
    are set to unlimited, they are enabled by any positive value of this
    effect.

Any_Government
    Allow changing to any form of government regardless of tech prerequisites.

Capital_City
    The city with this effect is the capital city.

Gov_Center
    The city with this effect is governmental center. Corruption and
    waste depends on distance to nearest such city.

Enable_Nuke
    Allows the production of nuclear weapons.

Enable_Space
    Allows the production of space components.

Specialist_Output
    Specify what outputs a specialist is producing. Should be used with an
OutputType requirement.

Output_Bonus
    City production is increased by amount percent.

Output_Bonus_2
    City production is increased by amount percent after Output_Bonus, so is
multiplicative with it.

Output_Add_Tile
    Add amount to each worked tile.

Output_Inc_Tile
    Add amount to each worked tile that already has at least 1 output.

Output_Per_Tile
    Increase tile output by amount percent.

Output_Tile_Punish_Pct
    Reduce the output of a tile by amount percent. The number of units to
remove is rounded down. Applied after everything except a city center's
minimal output.

Output_Waste_Pct
    Reduce waste by amount percent.

Force_Content
    Make amount' unhappy citizens content. Applied after martial law and unit
penalties.

Give_Imm_Tech
    Give amount techs immediately.

Growth_Food
    Food left after cities grow or shrink is amount percent of the capacity of
the city's foodbox. This also affects the 'aqueductloss' penalty.

Have_Embassies
    Like having embassies with all other players.

Irrigation_Pct
    The tile gets value % of its terrain's irrigation_food_incr bonus.
(This is how irrigation-like extras have an effect.)

Mining_Pct
    The tile gets value % of its terrain's mining_shield_incr bonus.
(This is how mine-like extras have an effect.)

Make_Content
    Make amount unhappy citizens content. Applied before martial law and unit
penalties.

Make_Content_Mil
    Make amount unhappy citizens caused by units outside of a city content.

Make_Content_Mil_Per
    Make amount per unit of unhappy citizens caused by units outside of a city
content.

Make_Happy
    Make amount citizens happy.

Enemy_Citizen_Unhappy_Pct
    There will be one extra unhappy citizen for each value/100 citizens
    of enemy nationality in the city.

No_Anarchy
    No period of anarchy between government changes. (This also neuters
the Has_Senate effect.)

Nuke_Proof
    City is nuke proof.

Pollu_Pop_Pct
    Increases pollution caused by each unit of population by amount
percent (adds to baseline of 100%, i.e. 1 pollution per citizen).

Pollu_Pop_Pct_2
    Increases pollution caused by each unit of population by amount
percent (adds to baseline of 100%, i.e. 1 pollution per citizen).
This factor is applied after Pollu_Pop_Pct, so is multiplicative with it.

Pollu_Prod_Pct
    Increases pollution caused by shields by amount percent.

Health_Pct
    Reduces possibility of illness (plague) in a city by amount percent.

Reveal_Cities
    Immediately make all cities known.

Reveal_Map
    Immediately make entire map known.

Incite_Cost_Pct
    Increases revolt cost by amount percent.

Unit_Bribe_Cost_Pct
    Increases unit bribe cost by amount percent. Requirements are from the
point of view of the target unit, not the briber.

Max_Stolen_Gold_Pm
    The upper limit on the permille of the players gold that may be
stolen by a unit doing the "Steal Gold" action. Evaluated against the city
stolen from.

Thiefs_Share_Pm
    The permille of the gold stolen by a unit doing the "Steal Gold"
action that is lost before it reaches the player ordering it. Evaluated
against the actor unit.

Illegal_Action_Move_Cost
    The number of move fragments lost when the player tries to do an action
that turns out to be illegal.

Size_Adj
    Increase maximum size of a city by amount.

Size_Unlimit
    Make the size of a city unlimited.

SS_Structural, SS_Component and SS_Module
    A part of a spaceship; this is a "Local" ranged effect. It (for now)
applies to improvements which cannot be built unless "Enable_Space" is felt.
Buildings which have this effect should probably not be given any other
effects.

Spy_Resistant
    If a spy specifies a target for sabotage, then she has an AMOUNT percent
chance to fail. Also in diplomatic combat defending diplomatic units in cities
will get an AMOUNT percent bonus. All Spy_Resistant's are summed before being
applied.

Move_Bonus
    Add amount movement to units. Use UnitClass' requirement with range of
'Local' to give it a specific class of units only.

Unit_No_Lose_Pop
    No population lost when a city's defender is lost.

Unit_Recover
    Units recover amount extra hitpoints per turn.

Upgrade_Unit
    Upgrade amount obsolete units per turn.

Upkeep_Free
    Improvements with amount or less upkeep cost become free to upkeep (others
are unaffected).

Tech_Upkeep_Free
    If this value is greater than 0, the tech upkeep is reduced by this value.
    For tech upkeep style "Basic" this is total reduction, for tech upkeep
    style "Cities" this reduction is applied to every city.

No_Unhappy
    No citizens in the city are ever unhappy.

Veteran_Build
    Increases the veteran class of newly created units of this type. The
total amount determines the veteran class (clipped at the maximum for the
unit).

Veteran_Combat
    Increases the chance of units of this type becoming veteran after combat
by amount percent.

HP_Regen
    Units that do not move recover amount percentage of their full hitpoints
per turn.

City_Vision_Radius_Sq
    Increase city vision radius in squared distance by amount tiles.

Unit_Vision_Radius_Sq
    Increase unit vision radius in squared distance by amount tiles.

Defend_Bonus
    Increases defensive bonuses of units. Any unit requirements on this effect
    will be applied to the _attacking_ unit. Attackers with "BadWallAttacker" flag
    will have their firepower set to 1.

Gain_AI_Love
    Gain amount points of "AI love" with AI(s).

Turn_Years
    Year advances by AMOUNT each turn unless Slow_Down_Timeline causes it
    to be less.

Turn_Fragments
    Year fragments advance by AMOUNT each turn.

Slow_Down_Timeline
    Slow down the timeline based on the AMOUNT. If AMOUNT >= 3 the timeline
will be max 1 year/turn; with AMOUNT == 2 it is max 2 years/turn;
with AMOUNT == 1 it is max 5 years/turn; with AMOUNT <= 0 the timeline is
unaffected. The effect will be ignored if game.spacerace isn't set.

Civil_War_Chance
    Base chance in per cent of a nation being split by civil war when its
capital is captured is increased by this amount. This percentage is in-
creased by 5 for each city in civil disorder and reduced by 5 for each one
celebrating.

City_Unhappy_Size
    The maximum number of citizens in each city that are naturally content;
in larger cities, new citizens above this limit start out unhappy. (Before
Empire_Size_Base/Step are applied.)

Empire_Size_Base
    Once your civilization has more cities than the value of this effect,
each city gets one more unhappy citizen. If the sum of this effect and
Empire_Size_Step is zero, there is no such penalty.

Empire_Size_Step
    After your civilization reaches Empire_Size_Base size, it gets one more
unhappy citizen for each amount of cities it gets above that. Set to zero to
disable. You can use Empire_Size_Step even if Empire_Size_Base is zero.

Max_Rates
    The maximum setting for each tax rate is amount.

Martial_Law_Each
    The amount of citizens pacified by each military unit giving martial law.

Martial_Law_Max
    The maximum amount of units that will give martial law in city.

Rapture_Grow
    Can rapture grow cities.

Revolution_Unhappiness
    If value is greater than zero, it tells how many turns citizens
    will tolerate city disorder before government falls. If value is
    zero, government never falls.

Has_Senate
    Has a senate that prevents declarations of war in most cases.

Inspire_Partisans
    Partisan units (defined in units.ruleset) may spring up when this player's
cities are taken.

Happiness_To_Gold
    Make all Make_Content and Force_Content effects instead generate gold.

Max_Trade_Routes
    Number of trade routes that city can establish.
    This is forced on trade route creation only. Existing trade routes
    are never removed due to reduction of effect value. This is to
    avoid micro-management, need to create same trade routes again
    after their max number has been temporarily down.

Fanatics
    Units with "Fanatics" flag incur no upkeep.

No_Diplomacy
    Cannot use any diplomacy.

Not_Tech_Source
    Tech cannot be received from this player by any means.

Trade_Revenue_Bonus
    One time trade revenue bonus is multiplied by pow(2, amount/1000).
    The amount value is taken from the caravan's home city.

Traderoute_Pct
    Percentage bonus for trade from traderoutes. This bonus applies after
    the value of the traderoute is already calculated. It affects one end
    of the traderoute only.

Unhappy_Factor
    Multiply unhappy unit upkeep by amount.

Upkeep_Factor
    Multiply unit upkeep by amount.

Unit_Upkeep_Free_Per_City
    In each city unit upkeep is deducted by this amount. As usual, you can use
with OutputType requirement to specify which kind of upkeep this should be.

Output_Waste
    Base amount in percentage that each city has in waste. Waste can be used
with any output type, use an OutputType requirement to specify which.

Output_Waste_By_Distance
    For each tile in real distance that a city is from nearest
Government Center, it gets amount of extra waste.

Output_Penalty_Tile
    When a tile yields more output than amount, it gets a penalty of -1.

Output_Inc_Tile_Celebrate
    Tiles get amount extra output when city working them is celebrating.

Upgrade_Price_Pct
    Increases unit upgrade cost by amount percent. This effect works at
    player level. You cannot adjust upgrade costs for certain unit type or
    for units upgraded in certain city.

Retire_Pct
    The chance that unit gets retired (removed) when turn changes.
    Retirement only happens if there are no enemy units or cities within
    a few tiles. (This exists mainly to implement barbarian behavior.)

Visible_Wall
    Instruct client to show specific buildings version of the city graphics.
    Zero or below are considered normal city graphics.

Tech_Cost_Factor
    Factor for research costs.

Shield2Gold_Factor
    Factor in percent for the conversion of unit shield upkeep to gold upkeep.
    A value of 200 would transfer 1 shield upkeep to 2 gold upkeep. The range
    of this effect must be player or world. Note that only units with the
    "Shield2Gold" flag will be affected by this.

Tile_Workable
    If value > 0, city can work target tile.

Irrig_Possible
    If value > 0, unit can build irrigation to target tile. In addition to
    requirements given to this effect, unit must also have Settlers flag.

Mining_Possible
    If value > 0, unit can build mine to target tile. In addition to
    requirements given to this effect, terrain type must be one to which mine
    can be built.

Transform_Possible
    If value > 0, unit can transform target tile. In addition to requirements
    given to this effect, terrain type needs to be one that can be transformed.

Irrig_TF_Possible
    If value > 0, unit can transform target tile terrain to another by irrigating.
    In addition to requirements given to this effect, terrain must be one that
    can be transformed by irrigating.

Mining_TF_Possible
    If value > 0, unit can transform target tile terrain to another by mining.
    In addition to requirements given to this effect, terrain must be one that
    can be transformed by mining.

Migration_Pct
    Increase the calculated migration score for the a city by amount in
    percent.

City_Radius_Sq
    Increase the squared city radius by amount. Currently, this can only
    usefully have "MinSize", "Building", or "Tech" requirements.

City_Build_Slots
    Increase the number of units with no population cost a city can build in
    a turn if there are enough shields.

City_Image
    The index for the city image of the given city style.

Victory
    Positive value means that player wins the game.

Performance
    Value is how much performance type culture city produces.

History
    Value is how much history type (cumulative) culture city produces.

National_Performance
    Value is how much performance type culture, not tied to any specific city,
    nation produces.

National_History
    Value is how much history type (cumulative) culture, not tied to any any
    specific city, nation produces.


Effects and Lua
===============
Lua has some integration with effects. The effects module allows you to
get an effect type's current value given that it is evaluated against the
entities you specify. Only a subset of the entities a hard coded effect can
be evaluated against is supported. An effect type's value is the sum of the
effects of that type from effects.ruleset whos requirement vectors are
fulfilled given the entities you specified.

Example
-------
Get the value of Tech_Parasite for the player
effects.player_bonus(find.player(0), "Tech_Parasite")


Details about requirement types
===============================

The DiplRel requirement type
----------------------------
Look for the diplomatic relationship "Never met", "War", "Cease-fire",
"Armistice", "Peace", "Alliance", "Team", "Gives shared vision",
"Receives shared vision", "Hosts embassy", "Has embassy",
"Hosts real embassy" (not from an effect), "Has real embassy",
"Has Casus Belli" (reason for war), "Provided Casus Belli" or "Is foreign".

A DiplRel is considered fulfilled for the range
 * world if some player in the world has the specified diplomatic
   relationship to some other living player.
 * player if the player has the specified diplomatic relationship to some
   other living player.
 * local if the first player has the specified relationship to the second
   player. Example: When testing a build requirement for an extra the first
   player is the owner of the unit and the second player the owner of the
   terrain the extra is built on.

Only the exact relationship required fulfills it. Example: An alliance or
an armistice agreement won't fulfill a "Peace" requirement.

It is possible to create a requirement that in some situations won't have a
player to check. In those cases the requirement will always be considered
unfulfilled. This applies to both present and not present requirements. The
ranges Alliance, Team, Player and Local needs a player. The Local range also
needs the player the first player's relationship is to.

Example: The requirements below are about the relationship to the owner of a
tile. The table shows in what situations a requirement is fulfilled.

Requirement is                            fulfilled when the tile is
                                        | domestic | unclaimed | foreign
"DiplRel", "Is foreign", "Local", TRUE  | no       | no        | yes
"DiplRel", "Is foreign", "Local", FALSE | yes      | no        | no

The MaxUnitsOnTile requirement type
-----------------------------------
Check the number of units present on a tile. Is true if no more than the
specified number of units are present on a single tile.

Hint: By using negation ("not present") it is possible to check if a tile
has more than the given numbers. It is possible to combine a negated and a
non negated requirement to specify a range.

The UnitState requirement type
------------------------------
"Transported" is fulfilled if the unit is transported by another unit.
"OnLivableTile" is fulfilled if the unit is on a tile where it can exist
                outside of a transport.

===========================================================================
 Authentication and Freeciv database support (fcdb)
===========================================================================

The Freeciv server allows the authentication of users, although by default
it is not enabled, and anyone can connect with any name.

In order to support authentication, the Freeciv server needs access to a
database backend in which to store the credentials. To support different
database backends, the database access code is written in Lua using luasql.
In principle, luasql supports SQLite3, MySQL, and Postgres backends, and
the Freeciv server can be built with any or all of these; however, the
supplied scripts currently do not support Postgres out of the box.

As well as storing and retrieving usernames and passwords, the supplied
database access script logs the time and IP address of each attempted
login, although this information is not used by the Freeciv server itself.

To use the Freeciv database and authentication, the server has to be built
with the '--enable-fcdb' and '--enable-auth' options to 'configure'. It
must also be installed properly, as it searches for database.lua in the
install location; the server cannot simply be run from a build directory if
authentication is required.

================================
 Quick setup: SQLite
================================

The simplest setup is to use the SQLite backend, and this is probably the
best option for new deployments. In this setup, the authentication data is
stored in a simple file accessed directly by the Freeciv server; there is
no need for a separate database server process.

In order to use this, the server must have been built with
'--enable-fcdb=sqlite3'.

To set this up, first create a database configuration file called something
like fc_auth.conf, with the 'database' key specifying where the database
file is to live (of course it must be readable and writable by the Freeciv
server):

  [fcdb]
  backend="sqlite"
  database="/my/path/to/freeciv.sqlite"

If you have experimental xml registry backend built in to freeciv, above
configuration can also be given as

<?xml version="1.0" encoding="UTF-8"?>
<Freeciv options="+xml">
  <fcdb>
    <database>"/my/path/to/freeciv.sqlite"</database>
    <backend>"sqlite"</backend>
  </fcdb>
</Freeciv>

(For more information on the format of this file, see below. There are more
settings available, but this file is entirely sufficient for a SQLite
setup.)

Now start the server with
  freeciv-server --Database fc_auth.conf --auth --Newusers

The first time you do this, you need to create the database file and its
tables with the following server command:
  /fcdb lua sqlite_createdb()

Now you can create some users by connecting with the client; due to the
--Newusers flag, when you connect with the client with a previously unknown
username, the server will prompt for a password and save the new account to
the database.

You may want to prepopulate the users table this way and then restart the
server without --Newusers for the actual game, or you can run the game with
--Newusers.

--------------------------------
 Advanced SQLite usage
--------------------------------

SQLite supports working with a temporary database in memory which is never
written to disk. To do this, specify 'database=":memory:"' in the
configuration file. The database will last only for the lifetime of the
freeciv-server process; its contents will be lost if the server quits or
crashes (it is not saved in the saved game file). You'll probably need the
--Newusers option :)

================================
 MySQL
================================

This setup uses a network connection to a separate MySQL database server.
MySQL was the only backend supported before Freeciv version 2.4, so is
supported for backward compatibility, but SQLite is probably a better
option for new deployments unless you have special requirements.

In order to use this, the server must have been built with
'--enable-fcdb=mysql'.

You can still use an existing pre-2.4 MySQL authentication database with
Freeciv 2.4 or later. Note however that the format of the configuration
file has changed slightly from that which used to be supplied to the --auth
option:
 - Section header is now '[fcdb]' instead of '[auth]'
 - You should add 'backend="mysql"'
 - the 'table' directive is now called 'table_user', and the default table
   name is now 'fcdb_auth'; if your setup relied on the old default, you'll
   need 'table_user="auth"'
 - the 'login_table' directive is now called 'table_log', and the default
   table name is now 'fcdb_log'; if your setup relied on the old default,
   you'll need 'table_log="loginlog"'

If you want to use MySQL for a fresh userbase, the supplied
scripts/setup_auth_server.sh can be used to create database tables in an
existing MySQL database, and a suitable config file describing that
database, which can be passed to the server's '--Database' option.

Before running this script, you will need to have a MySQL database server
running, with a user account for the Freeciv server and a database to
contain the data (ideally empty). (The space required for a Freeciv user
database is very small.)

Having created the tables and config file, you should be able to invoke the
server in a similar way to SQLite.

================================
 Command-line options
================================

The following server command-line options are relevant to authentication:

  -D, --Database <conffile>
      Specifies a configuration file describing how to connect to the
      database. Without this, all authentication will fail.
  -a, --auth
      Enable authentication. Without this, anyone will be able to connect
      without authentication, and --Database has no effect.
  -G, --Guests
      Allow guests. These are usernames with names starting "guest". If
      enabled, any number of guests may connect without accounts in the
      database; if a guest name is already in use by a connection, a new
      guest name is generated.
      Once connected, guests have the same privileges as any other account.
      If this option is not specified, accounts are required to connect,
      and guest account names are forbidden.
  -N, --Newusers
      Allow Freeciv clients to create new user accounts through the Freeciv
      protocol.
      Without this, only accounts which already exist in the database can
      connect (which might be desirable if you wants users to register via
      a web front end, for instance).

================================
 Lua script database.lua
================================

This script is responsible for checking usernames, fetching passwords, and
saving new users (if --Newusers is enabled). It encapsulates access to the
database backend, and hence the details of the table layout.

The script lives in data/database.lua in the source tree, and is installed
to 'sysconfdir'; depending on the options given to 'configure' at build
time, this may be a location like /usr/local/etc/freeciv/database.lua.

The supplied version supports basic authentication against a SQLite or
MySQL database; it supports configuration as shown in the following
example (for MySQL; SQLite does not need all of these options).

  [fcdb]
  backend="mysql"
  host="localhost"
  user="Freeciv"
  port="3306"
  password="s3krit"
  database="Freeciv"
  table_user="auth"
  table_log="loginlog"

If that's sufficient for you, it's not necessary to read on.

Freeciv expects the following lua functions to be defined in database.lua:

  -- try to load data for an existing user
  -- return TRUE if user exists, FALSE otherwise
  function user_load(conn)
  -- save a new user to the database
  function user_save(conn)
  -- log the connection attempt (success is boolean)
  function user_log(conn, success)

  -- test and initialise the database connection
  function database_init()
  -- free the database connection
  function database_free()

Where 'conn' is on object representing the connection to the client which
requests access.

The return status of all of these functions should be one of

  fcdb.status.ERROR
  fcdb.status.TRUE
  fcdb.status.FALSE

indicating an error, a positive or a negative result.

The following lua functions are provided by Freeciv:

  -- return the client-specified username
  auth.get_username(conn)
  -- return the client IP address (string)
  auth.get_ipaddr(conn)
  -- tell the server (the MD5 hash of) the correct password to check against
  -- for this connection (usually to be called by user_load())
  -- returns whether this succeeded
  auth.set_password(conn, password)
  -- return (the MD5 hash of) the password for this connection (as specified
  -- by the client in user_save(), or as previously set by set_password()).
  auth.get_password(conn)

  -- return a value from the --Database configuration file
  fcdb.option(type)

'type' selects one of the entries in the configuration file by name (for
instance fcdb.option("backend")). For backward compatibility with Freeciv
2.4, definitions such as fcdb.param.BACKEND are provided for conventional
option names, but there's no need to use them in new code.

Freeciv also provides some of the same Lua functions that ruleset scripts
get -- log.*(), _(), etc -- but the script is executing in a separate
context from ruleset scripts, and does not have access to signals, game
data, etc.

================================
 TODO
================================

* Move password comparison / policy to Lua script
  <http://www.hostedredmine.com/issues/660267>
* Give database.lua access to do more stuff
  <https://www.hostedredmine.com/issues/657141>
* Allow setting cmdlevel per-user, etc
  <https://www.hostedredmine.com/issues/657143>
* Give database.lua access to game signals and events
  <https://www.hostedredmine.com/issues/657142>
* Improve this README

  Citizen Governor (aka Citizen Management Agent, or CMA)
=========================================================

The Citizen Governor is designed to help you manage your cities, i.e.
deploy the workers on the available tiles around (or make them
scientists, taxmen, or even entertainers), to get the most out of the
city. You can switch the Governor on or off at any time for any city,
but there are some handicaps (explained below), if you have governor
controlled and non-governor-controlled cities nearby.

The heart of Governor system is an optimizing algorithm, that tries
to deploy the workers of a city in such a way, that a user-defined
goal is achieved as much as possible. You know probably, there is
already a kind of optimizing, when you open a city, and click on
the center tile (the city symbol) of the mini map. This optimization
tries to maximize mostly the science output; but it doesn't care about
disorder.

The new City Management Agent goes far beyond this old form of
optimizing. First, it performs this task every time anything changes
with the city. If the city grows or shrinks, troops go in or out,
tiles get irrigation or mining, or are occupied by an enemy, the Governor
becomes active. Second, it supports all kinds of optimizing, like
production (shields), gold, science, or luxury. Third, it gives the
player a fine-grained control over this, with the possibility of
setting constraints for any kind of city output. The latter includes
the constraint of celebration, which makes it very easy to let your
cities grow, even in harder times. The forth, and probably most
valuable thing in war times, is that is keeps your cities content,
preventing them from revolt.


  Usage
=========

You can set up the Governor for a city by opening the city window and
clicking on the Governor tab. On the left side, you can choose a preset for
a specified goal, on the right side you can specify more complex goals
by moving the sliders. You can choose a preset at first, and then
modify it. Once you have created a new setting, you can add a preset
name for it. This is not required, but very useful, since you can
watch and even change the city's setting from within the city report,
if it is given a name. Don't forget to save settings (in the Game
menu), when you've created new presets.

The sliders are of two kinds: the rightmost sliders are factors, which
gauges how much one product is worth compared to the others (e.g how
much shields are worth with respect to everything else). The leftmost
sliders are constraints: you can command the city not to lose food,
e.g. by setting the surplus constraint to zero; and you can allow the
city to lose gold by setting the gold surplus to -3 e.g., and urge
them to make at least 5 shields per round by setting the production
surplus to 5. The most powerful constraint, though, is the Celebrate
constraint, which makes the city celebrate at once (which usually takes
effect the round after you change it).

It is obvious that the Governor can't fulfill all these constraints in
every case. Whenever the constraints can't be fulfilled, the Governor
quits its service for that city, giving a message: "The agent can't
fulfill the requirements for Berlin. Passing back control." You then
have the choice of either managing the city on your own (which has some
drawbacks, see below), or open that city and change the surplus
requirements so that they can be fulfilled.

When you have made a setup for a city, you need to click on
"Control city" to switch on the Governor. If this button's text is greyed,
either the Governor is already active, or the task is impossible. In the
latter case you see dashes instead of numbers in the results block.
If you ever want to switch off the Governor deliberately, click "Release
city".


  Advanced Usage
==================

Usually the goal(s) of your cities depend on the phase your game is in,
whether you want to spread widely, grow quickly, research advanced techs
or wage war. You may want to set up a high factor for science to research,
or a high shields factor to produce units. The highest factor available
is 25, that means: if the shields factor is set to 25, and other to 1,
the Governor prefers a single shield over 25 gold (or trade also). This is
pretty much because money can buy units too. That also means that
the Governor is indifferent about producing gold, science, luxury, and food;
but when you wage war, you usually prefer gold or luxury. So it's probably
a good idea to set a second (or even third) preference for the city's output,
e.g. gold factor 5. That still prefers 1 shield over 5 gold (and 1 gold over 5
food or anything else).

Constraints aren't useful in all cases. If you want a high income,
it's probably better to set the gold factor to 25, than to set a
minimal surplus of 5 or so. Because a big city can make more gold than
a small one, you'd end up setting a different surplus for each city.

However, if the shields surplus of a city is below zero, it cannot
support all of its units any more. You will lose some of the units the
city supports. If the food surplus is negative, the city will starve
and eventually (when the granary is empty) shrink. This may be
intended, but if the city supports any settlers, you will lose them
before the city shrinks. Constraints can also have a warning function.

Which constraints can be fulfilled depends widely on the global
science, tax, and luxury rates. E.g. a gold surplus >= 0 is easier to
fulfill with a higher tax rate than a lower one. You should always
consider to change these rates, when you going to change the Governor
settings for the most of your cities.

Hint: To avoid accidentally releasing your cities, when you change the
rates, it is best to do so from within the tax dialog rather than from
the rates display in the main window.


  Drawbacks
=============

The Governor is a very powerful tool, which not only releases you from the
micromanagement of your cities, but gives you more performance than
you have ever seen (well, for most players).

There are some drawbacks, though. Once you've switched on the Governor, it
grabs any good tile it can get. So you encounter very hard times
trying to manage a city nearby a Governor-controlled one. This is true for
the city window and the main map worker's interface as well. If you
want to have Governor-controlled and "handmade" cities, they probably
should be on different islands.

There are several situations where the Governor can't fulfill the
requirements just temporarily, e.g. when you move a ship from one city
to another, or when an enemy walks through your country. The Governor
passes back control in these cases, and you have to reenable it
manually. A general approach to prevent this might be, to set the
minimal surpluses as low as possible (-20). Of course you must be
careful with the food and shield surpluses.

While the Governor does a really good job for a single city, no tile will
ever be released for the good of another city. Also, the Governor controlled
cities are computed in a more random order; the results may depend on it and
change, when a recalculation is done (when tax changes e.g.). So, no
guarantee is given that the overall results are always optimal.


  Settings file
=================

The client allows the user to load and save preset parameters for the
agent. Choosing "Save Settings" from the "Game" menu will not only
save your general options and message options, but it will save any
changes you made to you Governor presets as well.

The format for the options file (usually ~/.freeciv/.freeciv-client-rc-X.Y , where X.Y
is the version of freeciv in use) is as follows (in case you which to change
these presets manually, i.e. with a text editor).

Under the heading [cma], is a "number_of_presets". This should be set
to the number of presets that are present in the options file. If you
manually add or remove a preset, you need to change this number as
appropriate.

After this, is an array that houses the presets. Here is the header:

preset={ "name","minsurp0","factor0","minsurp1","factor1","minsurp2",
"factor2","minsurp3","factor3","minsurp4","factor4","minsurp5",
"factor5","reqhappy","factortarget","happyfactor"

so the order of the preset should be as follows:

name of preset, minimal surplus 0, factor 0, ... ,
require city to be happy, what the target should be [0,1],
the happiness factor

Currently there are 6 surpluses and factors. They are:
0 = food, 1 = production, 2 = trade, 3 = gold, 4 = luxury,
5 = science

Also currently, "factortarget" is not changeable within the client,
see "client/agents/cma_core.h" for more information.

The array should be terminated with a '}'.

Here are 21 presets you can use if you can't come up with some on
your own:

"Max food",0,10,0,1,0,1,0,1,0,1,0,1,0,0,1
"Max production",0,1,0,10,0,1,0,1,0,1,0,1,0,0,1
"Max trade",0,1,0,1,0,10,0,1,0,1,0,1,0,0,1
"Max tax",0,1,0,1,0,1,0,10,0,1,0,1,0,0,1
"Max luxury",0,1,0,1,0,1,0,1,0,10,0,1,0,0,1
"Max science",0,1,0,1,0,1,0,1,0,1,0,10,0,0,1
"+2 food",2,1,0,1,0,1,0,1,0,1,0,1,0,0,1
"+2 production",0,1,2,1,0,1,0,1,0,1,0,1,0,0,1
"+2 trade",0,1,0,1,2,1,0,1,0,1,0,1,0,0,1
"+2 gold",0,1,0,1,0,1,2,1,0,1,0,1,0,0,1
"+2 luxury",0,1,0,1,0,1,0,1,2,1,0,1,0,0,1
"+2 science",0,1,0,1,0,1,0,1,0,1,2,1,0,0,1
"Max food no gold limit",0,10,0,1,0,1,-20,1,0,1,0,1,0,0,1
"Max production no gold limit",0,1,0,10,0,1,-20,1,0,1,0,1,0,0,1
"Max trade no gold limit",0,1,0,1,0,10,-20,1,0,1,0,1,0,0,1
"Max gold no gold limit",0,1,0,1,0,1,-20,10,0,1,0,1,0,0,1
"Max luxury no gold limit",0,1,0,1,0,1,-20,1,0,10,0,1,0,0,1
"Max science no gold limit",0,1,0,1,0,1,-20,1,0,1,0,10,0,0,1
"Max food+prod. no gold limit",0,10,0,10,0,1,-20,1,0,1,0,1,0,0,1
"Max food+prod.+trade",0,10,0,10,0,10,0,1,0,1,0,1,0,0,1
"Max all",0,1,0,1,0,1,0,1,0,1,0,1,0,0,1

here are 6 more that have been added as an afterthought:

"+1 food, max prod. no gold limit",1,1,0,10,0,1,-20,1,0,1,0,1,0,0,1
"+2 food, max prod. no gold limit",2,1,0,10,0,1,-20,1,0,1,0,1,0,0,1
"+3 food, max prod. no gold limit",3,1,0,10,0,1,-20,1,0,1,0,1,0,0,1
"+4 food, max prod. no gold limit",4,1,0,10,0,1,-20,1,0,1,0,1,0,0,1
"+5 food, max prod. no gold limit",5,1,0,10,0,1,-20,1,0,1,0,1,0,0,1
"+6 food, max prod. no gold limit",6,1,0,10,0,1,-20,1,0,1,0,1,0,0,1

and even more, some with multiple goals:

"research at any cost",0,1,0,5,-20,1,-20,1,-20,1,-20,25,0,0,1
"celebration and growing",1,1,0,25,-20,1,-20,12,-20,1,-20,1,1,0,1
"grow at any cost",1,25,0,5,-20,1,-20,1,-20,1,-20,5,0,0,1
"research and some shields",0,1,0,8,0,1,-3,1,0,1,0,25,0,0,1
"shields and a bit money",0,1,0,25,0,1,-3,3,0,1,0,1,0,0,1
"many shields and some money",0,1,0,25,0,1,0,9,0,1,0,1,0,0,1
"shields and some research",0,1,0,25,0,1,-2,1,0,1,0,8,0,0,1
"celebrate and grow at once",1,1,0,25,-20,1,-20,1,-20,1,-20,8,1,0,1

Last updated: 10 Apr 2015

----------------------------------------------------------------------
Freeciv Graphics, and Tile Specification Files
----------------------------------------------------------------------

Using Graphics:
---------------

To use different graphics with Freeciv, use the '--tiles' argument to
the Freeciv client. Eg, to use the 'engels' graphics, start the
client as:

    freeciv-gtk3 --tiles engels

What Freeciv actually does in this case is look for a file called
'engels.tilespec' somewhere in your Freeciv data path. (See the file
INSTALL for some information on the Freeciv data path.) That tilespec
file contains information telling Freeciv which graphics files to use,
and what those graphics files contain.

That is all you need to know to use alternative graphics provided by
Freeciv or by third-party add-ons. The rest of this file describes
(though not fully) the contents of the tilespec file and related
files. This is intended as developer reference, and for people
wanting to create/compile alternative tilesets and modpacks for
Freeciv.

----------------------------------------------------------------------
Overview:
---------

The purpose of the 'tilespec' file and related 'spec' files is to
allow the detailed layout of the graphics within the files to be
flexible and not hard-coded into Freeciv, and to allow add-ons to
conveniently provide additional graphics.

There are two layers to the tilespec files:

The top-level file is named, eg: 'trident.tilespec'.  The basename of
this file (here, 'trident') corresponds to the parameter of the
'--tiles' command-line argument for the Freeciv client, as described
above.

The top-level tilespec file contains general information on the full
tileset, and a list of files which specify information about the
individual graphics files. These filenames must be located somewhere
in the data path, though not necessarily the same place as the
top-level tilespec file. Note that with this system the number and
contents of the referenced files are completely flexible at this
level.

An exception is that the intro graphics must be in individual files,
as listed in the tilespec file, because Freeciv treats these
specially: these graphics are freed after the game starts, and
reloaded later as necessary.

----------------------------------------------------------------------
Graphics formats:
-----------------

All clients currently use 24/32 bit PNGs.

----------------------------------------------------------------------
Tileset options:
----------------

In the top-level tilespec file you can set options for the tileset.
Each of these should go within the [tilespec] section. Currently
options include:

  Strings (enclosed in "")
  ------------------------
  options               : A capability string, this should be "+Freeciv-a.b-tilespec", where
                          "a.b" it the current freeciv version.
  name                  : the name of the tileset
  type                  : general type of tileset, different types have
                          quite different format. Supported types are
                          "overhead" and "isometric"
  main_intro_file       : GFX file for the intro graphics
  minimap_intro_file    : GFX file for the radar screen intro graphics

  String vectors
  --------------
  preferred_themes      : List of preferred client themes to use with this
                          tileset

  Integers
  --------
  priority              : when user does not specify tileset, client
                          automatically loads available compatible tileset
                          with highest priority.
  normal_tile_width     : the width of terrain tiles
  normal_tile_height    : the height of terrain tiles
  unit_width            : unit sprite width. Default is always ok, setting is
                          provided just for symmetry with unit_height
  unit_height           : unit sprite height if more than 1.5x terrain tile
                          height in isometric tileset
  small_tile_width      : the width of icon sprites
  small_tile_height     : the height of icon sprites
  fog_style             : Specifies how fog is drawn.
                          "Auto" :     Code automatically adds fog.
                          "Sprite :    A single fog sprite is drawn on top of all
                                       other sprites for fogged tiles. The
                                       tx.fog sprite is used for this.
                          "Darkness" : No fog, or fog from darkness_style = 4.
  darkness_style        : Specifies how "encroaching darkness" is drawn.
                          "None"           : No darkness.
                          "IsoRect"        : A single sprite can be split into 4
                                             parts, each containing the darkness
                                             for that particular cardinal direction.
                                             (Iso-view only.)
                          "CardinalSingle" : Four different sprites exist, each
                                             holding the darkness for a particular
                                             direction. Any or all of the sprites
                                             may be drawn.
                          "CardinalFull"   : The sprite is chosen based on the vector
                                             sum of the darkness in all 4 cardinal
                                             directions. 15 different sprites are
                                             needed.
                          "Corner"         : Corner darkness & fog, 81 sprites needed.
  unit_flag_offset_x   : Gives an offset from the tile origin at which to
  unit_flag_offset_y     draw flags behind units or cities. With isometric
  city_flag_offset_x     tilesets this should be non-zero so that the flag
  city_flag_offset_y     is placed correctly behind the unit/city.
  occupied_offset_x    : Gives an offset from the tile origin at which to
  occupied_offset_y      draw city occupied icon (in many tilesets placed above the flag)
  unit_offset_x        : Gives an offset from the tile origin at which to
  unit_offset_y          draw units.
  activity_offset_x    : Gives an offset from the tile origin at which to
  activity_offset_y      draw normal unit activity icons. "Auto" icons are not
                         affected by this as they are usually wanted in different
                         offset than real activity icons for both to appear simultaneously
                         "Auto" icons are auto_attack, auto_settler, patrol, connect.
  unit_upkeep_offset_y : Gives an offset from the unit origin at which to draw
                         the upkeep icons when they are shown along the unit. The upkeep
                         icons can safely extend below the unit icon itself.
                         If this value is omitted, normal tile height is used instead;
                         - Upkeep icons appear below the unit icon if the unit icons are
                           equal to tile height (typical in overhead tileset)
                         - Upkeep icons overlay lower part of the unit icon, if unit icon
                           is higher than tile height (typical in iso tilesets)
  unit_upkeep_small_offset_y:
                         Like unit_upkeep_offset_y, but to be used in case there's only small
                         space for the overall icon produced. Defaults to unit_upkeep_offset_y -
                         not having alternative layout.
  citybar_offset_y     : Gives an offset from city tile origin at which to
                         draw city bar text.
  hex_side             : When is_hex is specified (see is_hex, below), this
                         value gives the length of the "extra" side of the
                         hexagon. This extra side will be on the top/bottom
                         of the tile if is_isometric (below) is given, or
                         on the left/right of the tile otherwise. The actual
                         dimensions of the hex tile are determined from the
                         normal_tile_width/normal_tile_height of the tileset
                         as well as the hex side. The "normal" dimensions
                         give the X and Y offsets between adjacent tiles in
                         the tileset - this is not the same as the dimensions
                         of the tile itself. The dimension of the bounding
                         box of the hexagonal tile will be equal to the
                         "normal" dimension minus the hex_side. For instance
                         "normal" dimensions of 64x32 with a hex_side of 16
                         for an iso-hex tileset will give hexagons of size
                         48x32.
  city_names_font_size : Font size used in drawing city name
  city_production_font_size : Font size used in drawing city production
                         (Deprecated, ignored by many clients)

  Booleans (FALSE or TRUE)
  ------------------------
  is_hex                : set to TRUE for a hexagonal tileset. If is_isometric
                          is also specified then you have an iso-hex tileset.
                          Hex tilesets should be used with topologies 8-11 and
                          iso-hex tilesets with topologies 12-15.

  String lists (a comma-separated list of strings)
  ------------------------------------------------
  files                 : A list of .spec files to scan for sprites.
                          See "individual spec files", below.


----------------------------------------------------------------------
Terrain options:
----------------

The top-level tilespec file also contains information on how to draw each
terrain type.  For each terrain type include a section "[tile_xxx]".
This section contains information on how to draw this terrain type.
(The terrain types are specified in the server ruleset file.)

  [tile_XXX] options
  ----------------
  tag                   : Tag of the terrain this drawing information refers
                          to. That must match the "graphic" or "graphic_alt"
                          field given in the ruleset file.x
  blend_layer           : If non-zero, given layer of this terrain will be
                          blended with adjacent terrains. Blending is done
                          civ2-style with a dither mask. Only iso-view
                          currently supports blending. Only the base graphic
                          will be blended.
                          The blending mask has sprite t.dither_tile.
  is_reversed           : Draw layers in reverse order.
  num_layers            : The number of layers in the terrain. This value
                          must be 1, 2 or 3. Each layer is drawn
                          separately. The layerN options below control the
                          drawing of each layer (N should be 0, 1 or 2)
  layerN_is_tall        : Left right corner of terrain sprites is not based
                          on normal_tile_width and normal_tile_height, but
                          to corner of the full tile.
  layerN_offset_x       : Offset for terrain sprites
  layerN_offset_y
  layerN_match_type     : If 0 or unset, no terrain matching will be done and
                          the base sprite will be drawn for the terrain. If
                          non-zero, then terrain matching will be done. A
                          matched sprite will be chosen that matches all
                          cardinally adjacent tiles whose terrain has the same
                          match_type.
  layerN_match_with     : List of match_types to match against
  layerN_sprite_type    : With traditional tilesets each tile is drawn using
                          one sprite. This default sprite_type is "whole".
                          Which sprite to use may be specified using a
                          match_type, and there may be multiple layers
                          (each having one sprite). This method corresponds
                          to sprite_type "single".
                          A more sophisticated drawing method breaks the tile
                          up into 4 rectangles. Each rectangular cell is
                          adjacent to 3 different tiles. Each adjacency is
                          matched, giving 8 different sprites for each of the
                          4 cells. This sprite_type is "corner".

Additionally the top-level tilespec file should contain information about
the drawing of each layer. This is needed because the way each layer is
drawn must be consistent between different terrain types. You may not have
more than 3 layers (either in this section or in the [tile_XXX] sections).

  [layerN] options
  ----------------
  match_types            : Gives a string list of all different match types.
                           This list must include every possible match_type
                           used by terrains for this layer.
                           First letter of the match_type must be unique
                           within layer.

  Extra options
  ------------

  Tilespec should define style of extra graphics for each extra type in
  section [extras] like:

  [extras]
  styles =
      { "name",          "style"
        "road",          "RoadAllSeparate"
        "rail",          "RoadAllSeparate"
        "river",         "River"
        "tx.irrigation", "Cardinals"
      }

  RoadAllSeparate    : A single sprite is drawn for every connection the tile has;
                       only 8 sprites are needed.
  RoadParityCombined : A single sprite is drawn for all cardinal connections and
                       a second sprite is drawn for all diagonal connections;
                       32 sprites are needed.
  RoadAllCombined    : One sprite is drawn to show roads in all directions.
                       There are thus 256 sprites (64 for a hex tileset).
  River              : Cardinal connections are drawn, as well as delta at the coast
  Single1            : Single sprite at layer Special1
  Single2            : Single sprite at layer Special2
  3Layer             : 3 Sprites, tagged <name>_bg, <name>_mg, and <name>_fg
  Cardinals          : Sprite for each cardinal connection

----------------------------------------------------------------------
Individual spec files:
----------------------

Each spec file describes one graphics file (PNG format is standard,
although some clients may accept other formats as well) as specified in
the spec file. The graphics file must be in the Freeciv data path, but
not necessarily in the same location as the spec file. Note you can have
multiple spec files using a single graphics file in different ways.

The main data described in the spec file is in sections named
[grid_*], where * is some arbitrary tag (but unique within each file).
A grid corresponds to a regular rectangular array of tiles. In
general one may have multiple grids in one file, but the default
tilesets usually only have one per file. (Multiple grids would be
useful to have different size tiles in the same file.) Each grid
defines an origin (top left) and spacing, both in terms of pixels, and
then refers to individual tiles of the grid by row and column. The
origin, and rows and columns, are counted as (0,0) = top left.

x_top_left     : x-coordinate of the leftmost pixel of the leftomost cell
y_top_left     : y-coordinate of the topmost pixel of the topmost cell
dx             : cell width
dy             : cell height
pixel_border   : Number of pixels between cells, unless overridden by axis specific value
pixel_border_x : Number of pixels between cells in x-direction, overrides pixel_border
pixel_border_y : Number of pixels between cells in y-direction, overrides pixel_border
tiles          : Table of tags, each line having "row", "column", and "tag"

[grid_example]
x_top_left   = 1   ; Border (in x=0) also in left side of the entire grid
y_top_left   = 1   ; Border (in y=0) also in top side of the entire grid
dx           = 96
dy           = 48
pixel_border = 1
tiles = { "row", "column", "tag"
 0, 0, "tag1"
 0, 1, "tag2"
 1, 0, "tag3"
 1, 1, "tag4"
}


Each individual tile is given a "tag", which is a string which is
referenced in the code and/or from ruleset files. A grid may be
sparse, with some elements unused (simply don't mention their row and
column), and a single tile may have multiple tags (eg, to use the same
graphic for multiple purposes in the game): just specify a list of
comma-separated strings.

If a given tag appears multiple times in the spec files, the *last*
such tag is used. (That is, in the order of files listed in the
tilespec file, and order within each file.) This allows selected
graphics to be "overridden" by listing a replacement spec file near
the end of the 'files' list in the top-level tilespec file, without
having to modify earlier files in the list.

----------------------------------------------------------------------
Tag prefixes:
-------------

To help keep the tags organised, there is a rough prefix system used
for standard tags:

  f.	      national flags
  r.	      road/rail
  s.	      general "small"
  u.	      unit images
  t.	      basic terrain types (with _n0s0e0w0 to _n1s1e1w1)
  ts.	      terrain special resources
  tx.	      extra terrain-related
  gov.	      government types
  unit.	      unit overlays: hp, stack, activities (goto, fortify etc)
  upkeep.     unit upkeep and unhappiness
  city.	      city related (city, size, sq.-prod., disorder, occupied)
  cd.	      city defaults
  citizen.    citizens, including specialists
  explode.    explosion graphics (nuke, units)
  spaceship.  spaceship components
  treaty.     treaty thumbs
  user.	      crosshairs (in general: user interface?)

In general, graphics tags hard-wired into Freeciv _must_ be provided
by the spec files, or the client will refuse to start. Graphics tags
provided by ruleset files (at least for the "standard" rulesets)
should also be provided, but generally the client will continue even
if they are not, though the results may not be satisfactory for the
user. To work properly tags should correspond to appropriately sized
graphics. (The basic size may vary, as specified in the top-level
tilespec file, but the individual tiles should be consistent with
those sizes and/or the usage of those graphics.)

----------------------------------------------------------------------
Sprites
-------

Depending on the information given here the tileset must/may contain certain
sprites.

  Theme Sprites
  -------------

  citizen sprites :

    This provides citizen graphics. Each citizen has one or more sprites
    which are shown in the city dialog. The types of citizen are "happy",
    "content", "unhappy", and "angry". The tag name is "citizen.<type>_<n>".
    <type> is one of the listed types. <n> is the number of the graphic
    (numbered starting with 0, unlike most other graphics) which allows more
    than one sprite to be used. No more than 6 sprites per citizen may be
    used.

    Currently the citizen and specialist sprites may not have any
    transparency, as this is ignored in much of the drawing. This is
    considered a bug.

  specialist sprites:

    These provide specialist graphics just like the citizen graphics. However
    specialist types come from the ruleset and may be changed in modpacks.
    The sprite name is "specialist.<type>_<n>". Again <type> is the
    type of specialist (currently "elvis", "scientist", "taxman") while <n>
    is the sprite number. See "citizen sprites" above.

  progress indicators:

    There are three types of progress indicator. "science_bulb" indicates
    progress toward the current research target. "warming_sun" indicates
    progress toward global warming. "cooling_flake" indicates progress
    toward nuclear winter. Each indicator should have 8 states, numbered
    0 (least) through 7 (most). The sprite names are "s.<type>_<n>".

  government icons:

    There should be one icon for each government. Its name is "gov.<gov>",
    where <gov> is the government name. Government types come from
    governments.ruleset (currently "anarchy", "despotism", "monarchy",
    "communism", "fundamentalism", "republic", "democracy").

  tax icons:

    One icon for each tax type. These are used to show the tax rates. The
    sprites are "s.tax_luxury", "s.tax_science", "s.tax_gold". Commonly
    the specialist sprites are reused for this.

  right arrow:

    A sprite "s.right_arrow" is used on the panel when more units are
    present than can be shown.

  Terrain sprites
  ---------------
  base sprite           : If the terrain has no match type or is layered, a
                          base sprite is needed. This sprite has tag
                          "t.<terrain>1" (e.g., "t.grassland1"). More than
                          one such sprite may be given ("t.grassland2", etc.)
                          in which case one will be chosen at random for each
                          tile.
  matched sprites       : If the terrain has a match type or is layered, a
                          set of matched sprites is needed. This consists of
                          16 sprites with tags "t.<terrain>_n<V>e<V>s<V>w<V>"
                          (e.g., "t.hills_n0e0s1w0". Each direcional value
                          <V> is either 0 or 1. Note that the directions are
                          in map coordinates, so n (north) in iso-view is
                          northeast on the mapview. (Note this only applies
                          for cell_type "single".)
  cell sprites          : For matched terrains that have cell_type "rect",
                          32 different sprites are needed. Each sprite is
                          a rectangle corresponding to one cell, and there are
                          8 different sprites per cell. Each sprite has
                          a name like "t.ocean_cell_u110" where "ocean" is the
                          terrain, "u" means up (north on the map) and
                          110 indicates which of the adjacent tiles are
                      	  mismatched. For instance u110 means

				    /\
				   /B \
				  /\ 1/\
				 / A\/C \
				 \1 /\ 0/
				  \/D \/
				   \  /
				    \/

			  a matching terrain exists at C but not at A or B. In
                          this case D is the current tile.

  Examples:

    ; This specifies a civ2-like grassland tile. A single sprite
    ; t.grassland is needed; it will be drawn blended.
    [terrain_grassland]
    blend_layer = 1
    num_layers  = 1
    layer0_match_type = 0

    ; This specifies a civ1-like mountain tile. 16 sprites
    ; t.mountains_n0s0e0w0 ... t.mountains_n1s1e1w1 are needed. One of them
    ; will be drawn to match the adjacent tiles. Assuming only mountains
    ; has this match_type, adjacent mountains will match.
    [terrain_mountains]
    blend_layer = 0
    num_layers  = 1
    layer0_match_type = 7

    ; This specifies a civ2-like hills tile. A base sprite t.hills will be
    ; needed, plus 16 matching sprites. The base sprite will be drawn,
    ; dithered with adjacent base sprites, and the matching sprite will be
    ; drawn on top. (In most civ2 tilesets the base sprite is the grassland
    ; sprite).
    [terrain_hills]
    blend_layer = 1
    num_layers  = 2
    layer0_match_type = 0
    layer1_match_type = 8

    ; This specifies a civ2-like ocean tile. Ocean is drawn via a cell-based
    ; system as explained above.
    [terrain_ocean]
    blend_layer = 1
    num_layers  = 1
    layer0_match_type = 6
    layer0_cell_type = "rect"

  Terrain Special Sprites
  -----------------------

  farmland/irrigation:

    tx.farmland and tx.irrigation provide the basic sprites for farmland
    and irrigation. Additionally, there is support for drawing continuous
    farmland and irrigation (as is used in Civ3). Here there are 16
    irrigation sprites (and the same for farmland), starting with
    tx.irrigation_n0s0e0w0 and running through tx.irrigation_n1s1e1w1.
    An appropriate sprite will be chosen depending on which adjacent tiles
    also have farmland/irrigation. If any of these sprites are not present,
    the default sprite will be used as a fallback.

===========================================================================
 Modpack installer tool
===========================================================================

Installing modpacks
-------------------

The modpack installer is a simple tool to download custom Freeciv
content called "modpacks" from the Internet, and automatically install
them into the correct location to be used by the Freeciv client and
server.

A "modpack" can consist of one or more of:
 - 'rulesets' for game rules
 - 'scenarios' for game maps (with or without players/cities/etc)
 - 'tilesets' for game graphics
 - 'soundsets' or 'musicsets' for sound effects and in-game music

Depending which client you installed, you will probably have one modpack
installer tool called something like 'freeciv-mp-gtk3' or
'freeciv-mp-qt' -- these different versions have the same features.
There may also be a command-line-only tool called 'freeciv-mp-cli',
which is mainly useful for headless game servers.

In standard Freeciv builds, when you start the graphical modpack
installer, it will show a list of modpacks from modpack.freeciv.org,
curated by the Freeciv developers. You can select one and press
"Install modpack"; the tool will download the files for the selected
modpack, and any other modpacks it depends on, and install them ready
for the main Freeciv programs to use.

You can also point the installer at modpacks or lists on other servers:

 * If someone has given you an individual modpack URL (ending in
   '.modpack'), you can paste it into the "Modpack URL" box, and when
   you press "Install modpack", the modpack will immediately be
   downloaded and installed.

 * If someone has given you a URL for a list of modpacks (probably
   ending in '.list') and you want to browse them with the standard
   Freeciv modpack installer build, you need to start the tool with
   that URL on its command line, for instance:

     freeciv-mp-gtk3.exe --List http://example.com/2.6/my-modpacks.list

   (note the capital letter in '--List')

(The tool has some other command-line options, but most users will not
need to use them. Use --help for a list of them.)

Once you have installed a modpack, how you use it depends on the modpack
type:

 - Scenarios (maps) should be listed under 'Start scenario game' from
   the client start page, or from the game server prompt via
   '/list scenarios'.
   (For network play, scenarios need only be installed on the game
   server.)

 - Rulesets should appear on the 'Ruleset' drop-down from the client's
   'Start new game' page. On the game server, you can load a ruleset
   with '/read <name>' or failing that perhaps '/set rulesetdir <name>'.
   (For network play, rulesets need only be installed on the game
   server.)

 - Tilesets should appear for selection in the local client options, in
   the appropriate topology-specific 'Tileset' drop-down under 'Graphics'.
   (Tilesets should be installed on the game client machine.)

 - Soundsets and musicsets should appear in the dropdowns on the 'Sound'
   page of the local client options.
   (These should be installed on the game client machine.)

With standard Freeciv builds, modpacks get installed into a per-user
area, not into the main Freeciv installation. So you shouldn't need any
special permissions to download them, and if you uninstall the Freeciv
game, any modpacks you downloaded are likely to remain on your system.
Conversely, if you delete downloaded modpacks by hand, the standard
rulesets, tilesets etc supplied with Freeciv won't be touched.

The precise location where files are downloaded to depends on your build
and platform. For Unix systems it is likely to be under the hidden
'.freeciv' directory in your home directory. It is likely to be near
where the Freeciv client stores its saved games.

Most modpacks are specific to a particular major version of Freeciv; for
instance, while a 2.5 ruleset or tileset can be used with all Freeciv
2.5.x releases, it cannot be used as-is with any 2.6.x release. So, most
modpacks are installed in a specific directory for the major version,
such as ~/.freeciv/2.6/ on Unix. (The modpack installer displays which
version it will install for at the top of its window.)

An exception to this is scenario maps; scenarios created for one version
of Freeciv can usually be loaded in later versions, so they are
installed in a version-independent location (typically
~/.freeciv/scenarios/ on Unix).

Once a modpack is installed, there is no uninstall action, and if you
remove the files by hand, the installer will still consider the modpack
to be installed; the installer maintains its own database
(.control/modpacks.db) listing which modpack versions are installed, but
does not keep track of which files were installed by which modpack. If
the database gets of of sync with reality (or is deleted), it's
harmless for already installed modpacks and the main Freeciv programs
(which do not consult the database), but can confuse the modpack
installer's dependency tracking later.

Modpacks consist mostly of data files read by the Freeciv engine; they
do not contain compiled binary code (and are thus platform-independent).
Rulesets can contain code in the form of Lua scripts, but this is
executed in a sandbox to prevent obvious security exploits. Modpacks are
installed to a specific area and cannot overwrite arbitrary files on
your system. Nevertheless, you should only install modpacks from sources
you trust.


Serving modpacks for the installer
----------------------------------

The rest of this document discusses how to set up a web server so that
users can download modpacks you publish. (If you just want to install
modpacks, you need not read on.)

To host modpacks, you just need a web server that can host plain static
files; you do not need to run any custom code or frameworks on that web
server, just to publish files with a specific layout, detailed below.
(You can browse http://modpack.freeciv.org/ for some working examples of
modpack trees.)

For a long time (up to and including 2.6.1), the standard Windows
Freeciv builds were effectively unable to access https (secure) URLs, so
for maximum accessibility to those old versions, you should serve from a
web server that supports plain http, if possible.

On the modpack server, there are up to three layers of files required:
  1. modpack.list: A list of available modpacks (optional, advanced).
  2. *.modpack: A control file for an individual modpack.
  3. The individual files comprising the modpack.

Each of these layers is described in detail below.

Each layer refers to files in the next layer down. References can be
with relative URLs (so that a modpack or set of modpacks can be moved
without changing any file contents), or with absolute URLs (so that the
different layers can be hosted on different web servers).

Almost all of these file formats are specific to one major version of
Freeciv; this document only describes the formats for the major version
of Freeciv it is shipped with. If you wanted to publish modpacks for
both 2.5.x and 2.6.x, you would publish two sets of modpack control
files, and perhaps two different modpack.list files.


1. modpack.list, a list of modpacks

(Advanced usage only -- most publishers can skip to the next section)

This is only needed if you want to let users browse a list of available
modpacks before choosing one to install. To look at your modpack.list
instead of the standard one, users will usually have to start the
modpack installer with non-standard arguments (see above).

If you build and distribute your own Freeciv binaries, you can build
in a custom modpack list URL with the '--with-modlist' argument to
'configure':

  ./configure --with-modlist=http://example.com/2.6/my-modpacks.list'

(You could even build and distribute just the modpack installer -- once
installed, in principle there's nothing stopping the standard Freeciv
client/server using modpacks installed by it -- but you would need to
take care that the data paths used by your modpack installer build were
the same as those used by the standard builds, since getting the paths
right is most of the point of the modpack installer.)

modpack.list is a file in Freeciv's "spec-file" format, the same as is
used for rulespecs, tilespecs, etc; see those for examples of the
general syntax.

Here's an example:

[info]
options = "+Freeciv-2.6-modlist"
message = "2019-12-31: updated Mappamundi tileset. Happy new year!"

[modpacks]
list =
{ "name", "version", "type", "subtype", "license", "URL", "notes"
  "Ancients", "2.6-1b", "Modpack", "-", "GPLv2+", "./ancients.modpack"
  "Survivors", "2.6r6", "Scenario", "iso", "GPLv2+", "./survivors-2.6r6.modpack", "Installs custom ruleset and two world maps"
  "Mappamundi", "20191231", "Tileset", "iso", "MIT", "http://otherserver.example.com/mappamundi-20191231.modpack"
}

Here's what's in the [info] section:
 - "options" should be exactly as shown here.
 - "message" is displayed on the status line when the modpack installer
   starts up. Should be kept to one line.

The [modpacks] section is a header line, followed by a list of modpack
lines.
The header line ("name, "version", etc) should usually be left as shown
here, and followed by one line for each modpack:
 - "name", "version", "type":
     These three fields should match those in the .modpack file which
     "URL" links to.
 - "subtype":
     Optional free text. For tilesets or scenarios, conventionally
     indicates the map topology with one of "overhead", "iso", "hex",
     or "hex & iso" (and these will be localised). Otherwise "-".
 - "license":
     Free text summarising the distribution terms for the modpack
     content (by naming a well-known license, not quoting the full
     license text!)
 - "URL":
     The URL to a .modpack file for the individual modpack.
     Either a relative URL starting "./" (in which case it's relative to
     the URL of modpack.list) or an absolute URL (which can be on some
     other web server).
 - "notes":
     Optional free text; usually shown as a tooltip.


2. *.modpack control file, defining an individual modpack

This is the core control file for a modpack, specifying what files it
contains, where to download them from, and where they are installed.

Most modpack authors will just publish the URL of a .modpack file
directly, for users to give to the modpack installer tool. (There
doesn't have to be a modpack.list file anywhere that refers to the
.modpack file.)

Again, this is a file in Freeciv's "spec-file" format, the same as is
used for modpacks like rulespecs, tilespecs, etc; see those for examples
of the general syntax. Its filename must end in ".modpack".

Here is an example of a .modpack file:

[info]
options = "+Freeciv-2.6-modpack"
baseURL = "./ancients-2.6-1b"
name    = "Ancients"
type    = "Modpack"
version = "2.6-1b"

[dependencies]
list =
{ "modpack", "URL", "type", "version"
  "Ancients-tiles", "./ancients-tiles.modpack", "Tileset", "2.6-1b"
}

[files]
list =
{ "src", "dest"
  "ancients/ancients.serv", "ancients.serv"
  "ancients/game.ruleset"
  ; ...
}

The [info] section has overall control information:
 - "options": must be exactly as shown in the example.
 - "name":
     A short name for the modpack. This is used for version and
     dependency tracking, so should not contain minor version
     information, and should not change once a modpack has been
     released for a given major version of Freeciv. Case-insensitive.
 - "version":
     Textual version information. If another modpack uses this one as a
     dependency, this string is subject to version number comparison
     (using the rules of Freeciv's 'cvercmp' library, which should give
     sensible results for most version numbering schemes).
 - "type":
     This must be one of the following:
      - "Ruleset" (foo.serv, foo/*.ruleset, foo/*.lua, etc)
      - "Tileset" (foo.tilespec, foo/*.png, etc)
      - "Soundset" (foo.soundspec, foo/*.ogg, etc)
      - "Musicset" (foo.musicspec, foo/*.ogg, etc)
      - "Scenario" (foo.sav; installed to a version-independent location)
      - "Modpack": conventionally used for modpacks that contain more
        than one of the above kinds of material
     At the moment, only "Scenario" causes special behavior.
 - "baseURL":
     URL to prepend to the "src" filenames in the [files] section.
     May be relative to the .modpack file (starting with "./"), or
     absolute (in which case the files can be on some web server
     different to where the .modpack file lives).

The [files] section lists the individual files comprising your modpack.
(It must list every file individually; any files in the same directory
on the webserver that are not listed will not be downloaded.)
After the header, each line can contain two strings:
 - "src"
     Mandatory. Path of file on webserver, relative to "baseURL",
     and also by default installation path.
 - "dest"
     Optional. Normally, "src" is also used as the path (relative to the
     installation root) for the file to be installed on the user's
     system. If for some reason you need the installation path for some
     file to be different, specify it here.
     Usually, the path under "src" will be fine for this, in which case
     there is no need to have a "dest" string on the line.
     Path components should be separated with forward slashes ('/').

In the example, the first file would be downloaded from
  ./ancients-2.6-1b/ancients/ancients.serv
(relative to the URL of the .modpack file), and installed in
  ancients.serv
in the relevant path of the user's system.

Some advice on the structure of files in modpacks:

 * You should generally install files in a directory named after the
   modpack, with a few exceptions (.serv, .tilespec, .soundspec, and
   .musicspec files must be installed to the top level, and should
   reference files in your subdirectory).

   Individual files' and directories' install names should usually not
   embed version numbers, dates, etc, so that when a new version of
   modpack X is installed, it cleanly overwrites the old version, rather
   than leaving both cluttering up the user's installation.

 * The modpack installer does not stop different modpacks overwriting
   each other's files, so published modpacks should be disciplined about
   namespace usage. If you've derived from someone else's modpack, you
   should probably give your derivative new filenames, so that both can
   be installed simultaneously.

 * There is no 'white-out' facility to delete files from a user's
   installation -- if a newer version of a modpack has fewer files than
   an old one, the old file will persist in some users' installations,
   so your modpacks should be designed to be tolerant of that.

 * At the moment, there is no restriction on what kind of files a given
   "type" can install, but modpacks should stick to installing the
   advertised kinds of content. It's OK to install extra files such as
   documentation in any case (LICENSE/COPYING, README.txt, etc).

 * If your modpack contains a ruleset, you should usually install a
   .serv file at the top level (which can be a one-line file consisting
   of "rulesetdir <name>", as this is needed for the server to enumerate
   the available rulesets.

The [dependencies] section is optional, and not normally needed. If your
modpack requires another one that can also be installed separately (for
instance, a scenario that needs a specific ruleset), you can specify it
here. After the header, each line consists of:
 - "modpack":
     What the dependency modpack calls itself when installed (that is,
     "name" from its .modpack file).
 - "URL":
     URL to download modpack if needed. Can be relative or absolute.
 - "type":
     Must match "type" from dependency's .modpack file.
 - "version":
     Minimum version of dependency (as declared in its .modpack file).
     Subject to version number comparison algorithm.
If the modpack installer thinks the required version, or a newer
version, of the dependency is already installed, it will do nothing,
otherwise it will download the dependency modpack (and any of its own
dependencies, recursively).


3. Individual modpack files

These are the files comprising the modpack (*.ruleset, *.png, etc), that
will be copied verbatim to the user's Freeciv data directory and read by
the Freeciv client and server. The modpack installer does not modify the
files in any way.

The files must be hosted individually on the web server; the modpack
installer tool cannot unpack any archives such as .zip files.
(Individual scenarios can be compressed, e.g. .sav.gz, as the Freeciv
engine can uncompress these files.)

Because the *.modpack file can change the file paths / names on
download, the layout on the modpack server doesn't have to correspond
with the installed layout. An individual file can be shared between
multiple modpacks, if you want.

How to write modpacks is beyond the scope of this document -- see
README.rulesets, README.graphics, etc for some clues.

 MSYS2 Windows Installer build notes
====================================

This document is about building Freeciv Windows Installer packages
using MSYS2 from https://www.msys2.org/


 Status
====================================

- Msys1, not msys2, is still the official freeciv Windows Installer
  build method
- Buildable clients are gtk3, gtk3.22, gtk2, sdl2, and Qt
  - Official pre-made msys2 environment does not support building gtk2-client


 Setup
====================================

 This chapter is about creating new msys2 build environment.

 If you want to reproduce more official freeciv builds, the environment
 used to make those builds is documented in the next chapter ("Premade environment"),
 with listing of versions current at the time of this freeciv version.

1) Install MSYS2 following the documentation on their homepage

1.1) Download
 https://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-x86_64-20210215.exe
 for win64 host

1.2) Run it to install MSYS2 on build system

1.3) Launch msys2_shell to update packages
> pacman -Syu

2) Install following packages with 'pacman -Su --needed'

2.1) Packages needed for building freeciv
 These packages are needed even if you don't plan to make installer,
 but only build freeciv for local use.

2.1.1) Arch independent packages needed for building freeciv

2.1.1.1) Arch independent packages always needed for building freeciv
 With these packages it's possible to build freeciv source tree that
 has already such generated files present that are created for the
 release tarball.

 - make
 - gettext
 - pkg-config

2.1.1.2) Arch independent packages needed for getting and extracting freeciv
 source tarball

 - tar

2.1.1.3) Arch independent packages needed for building freeciv from repository
 checkout. These are needed in addition to the ones always needed for building
 freeciv.

 - git
 - automake
 - libtool
 - autoconf

2.1.2) Arch-specific packages needed for building freeciv

2.1.2.1) Arch-specific packages for building common parts
 - mingw-w64-i686-gcc / mingw-w64-x86_64-gcc
 - mingw-w64-i686-curl / mingw-w64-x86_64-curl
 - mingw-w64-i686-imagemagick / mingw-w64-x86_64-imagemagick
 - mingw-w64-i686-SDL2_mixer / mingw-w64-x86_64-SDL2_mixer

2.1.2.1.2) Arch-specific optional packages for building common parts
 - mingw-w64-i686-drmingw / mingw-w64-x86_64-drmingw
 - mingw-w64-i686-tolua / mingw-w64-x86_64-tolua

2.1.2.2) Arch-specific packages for building gtk3- and gtk3.22-client
 - mingw-w64-i686-gtk3 / mingw-w64-x86_64-gtk3

2.1.2.3) Arch-specific packages for buildind Qt-client and/or Ruledit
 - mingw-w64-i686-qt5 / mingw-w64-x86_64-qt5

2.1.2.4) Arch-specific packages for building gtk2-client
 - mingw-w64-i686-gtk2 / mingw-w64-x86_64-gtk2

2.1.2.5) Arch-specific packages for building sdl2-client
 - mingw-w64-i686-SDL2_image / mingw-w64-x86_64-SDL2_image
 - mingw-w64-i686-SDL2_ttf / mingw-w64-x86_64-SDL2_ttf
 - mingw-w64-i686-SDL2_gfx / mingw-w64-x86_64-SDL2_gfx

2.2) Packages needed for building installer package
 These are needed in addition to above ones used in the
 building step already.

2.2.1) Arch-specific packages needed for building installer
 package

 - mingw-w64-i686-nsis / mingw-w64-x86_64-nsis


 Premade environment
====================================

Premade msys2 environment is available for download from
http://files.freeciv.org/packages/windows/msys2/

Current version is

win64 host:
-----------
msys2-freeciv-win64-210226.7z, based on
https://sourceforge.net/projects/msys2/files/Base/x86-64/msys2-x86_64-20210215.exe
with packages updated to 26-Feb-2021 level.

Both win32 and win64 targets are included. For each package listed below with <arch>
in the name, actually two packages is installed; one with a name where <arch> is
replaced by 'i686' and one where <arch> is replaced by 'x86_64'


Following packages have been installed:
- make
- pkg-config
- tar
- git
- patch
- nano
- automake
- libtool
- autoconf
- gdb
- mingw-w64-<arch>-gcc
- mingw-w64-<arch>-icu
- mingw-w64-<arch>-curl
- mingw-w64-<arch>-sqlite3
- mingw-w64-<arch>-gtk3
- mingw-w64-<arch>-nsis
- mingw-w64-<arch>-SDL2_mixer
- mingw-w64-<arch>-SDL2_image
- mingw-w64-<arch>-SDL2_ttf
- mingw-w64-<arch>-SDL2_gfx
- mingw-w64-<arch>-imagemagick
- mingw-w64-<arch>-qt5
- mingw-w64-<arch>-drmingw
- mingw-w64-<arch>-meson
- mingw-w64-<arch>-tolua

After all the packages were installed 'pacman -Scc' was run to completely
empty the package cache for having smaller environment package.


 Build
====================================

Launch msys2 shell. Get the freeciv sources there
somehow. Some options are:
1) Download freeciv tarball within msys2 shell with wget
2) Use git within msys2 shell to get them from version control
3) Copy them from Windows folder where they are to a directory that
   is within msys2

> cd win32/installer_msys2
> make <targets>

  Target can be:
  - "all" (default), build all installers
  - "<gui>-installer", where <gui> is
     - gtk3
     - gtk3.22
     - gtk2
     - sdl2
     - qt
  - "ruledit-installer"
  - "snapshot", if your freeciv sources are in git checkout directory,
                builds all installers with commit id in version number

 You can also set minimum Windows version targeted. While setting this
 to an older version allows those Windows versions to run the created
 executables, it may come with the cost of disabling functionality that
 newer Windows versions could otherwise have.
 The version is set via MIN_WIN_VER variable. For values to use, see
 list in: https://msdn.microsoft.com/en-us/library/6sehtctf.aspx
 Current default is 0x0601 (Windows 7).

 It's possible to set number of make jobs used in the build by
 setting suitable make parameter to MAKE_PARAMS variable, e,g,
 MAKE_PARAMS="-j3"


 Problems
====================================

- Freeciv linked against readline in msys2 does not work.
  Configure freeciv with --without-readline


 TODO
====================================

- Readline support

===========================================================================
Freeciv Nation Rulesets and Flags
===========================================================================

This file describes the contents of the nation files. This is intended as
developer reference, and for people wanting to create/compile alternative
nation files for Freeciv. A nation consists of a nation file in the
rulesets and a flag in the tilesets.

The contents of this file is based on this page from the Freeciv wiki:
http://www.freeciv.org/wiki/Nations



----------------------------------------------------------------------
Local Nation files:
-------------------

Starting from freeciv-2.6, to most supplied rulesets nations can be
added locally without need to modify freeciv distribution files.
This section discuss the way there local override files work. Later
sections assume that nation is being added to main freeciv distribution,
even if only to locally modified copy.

Freeciv search data files from several directories in priority order.
Local nations overrides mechanism uses this to include files from
user data directory, ~/.freeciv/<freeciv version>/override/,
e.g., ~/.freeciv/2.6/override/
Freeciv distribution has empty versions of those files in a lower priority
directory. Once user adds the file, it gets used instead of the empty
one.

~/.freeciv/<version>/override/nation.ruleset
  Ruleset sections for nations that user wants to add. This can of course
  use *include directives so that individual nations are in separate files.
  See below sections for the format of the nation rulesets.

~/.freeciv/<version>/override/flags.spec
~/.freeciv/<version>/override/shields.spec
~/.freeciv/<version>/override/flags-large.spec
~/.freeciv/<version>/override/shields-large.spec
  Spec files for flag graphics to add. See below sections for the format
  of spec files and graphics files.


How to add a Nation:
--------------------

To add a nation of your own, you should look at the following files:

data/nation/<nationname>.ruleset

  This is the new nation, which you will have to create. It may help to
  copy one of the other nation files over and edit it. See below for a
  style guide for nation files.
  - The <nationname> bit is to be replaced with the nations name (duh).
  Please don't use whitespaces and special characters. Underlines are
  ok though.
  - The name should be the same as the name of the nation inside the
  ruleset file.
  - The file must be encoded in UTF-8.

data/default/nationlist.ruleset

  This lists all nation files. Add your nation
  (data/nation/<nationname>.ruleset) to this list.

data/flags/*

  This is the flags directory. You will have to add a flag-file
  (see below) for your nation to work (see below).

data/scenarios/*

  You can add starting position for your nation on a scenario map.

Before a nation can be included in the main distribution, the following
files will also have to be edited. Unless you know what you're doing you
shouldn't need to worry about this.

data/nation/Makefile.am

  Another list of nation files - add your nation (<nationname>.ruleset)
  to this list.

data/flags/Makefile.am

  Another list of flag files - add your flag to this list.

translations/nations/POTFILES.in

  Here is yet another list of nations files; again add your nation
  (data/nation/<nationname>.ruleset) to it.
  Nations part of the "core" group go to translations/freeciv/POTFILES.in
  instead.


----------------------------------------------------------------------
How to add a Flag:
------------------

Overview
========

Please note that Freeciv no longer uses XPM files. PNG is the preferred
form for graphics, and flags should be made exclusively in SVG.

A new nation needs a new flag. As of Freeciv 2.1 all flags are stored
in SVG (Scalable Vector Graphics) format. Sodipodi and Inkscape are
two good SVG editors. If you are creating a real-world nation you can
probably find a Free or public domain flag that can be used. One good
place to look is the Open Clip Art Library (OCAL). Remember that any flags
we add must be licenced under the GPL and should be attributed to their
original author, so make a note of where you found the flag, what its
licence is, and who made it.

We also welcome improvements to existing flags. Most of our existing
flags come from the Sodipodi clipart collection, and some of them are
less than perfect. One common problem is that the colors are wrong. If
you fix a flag for a real nation be sure to cite your source so we can
be sure it's accurate. Good sources for nation flag data are Wikipedia
or Flags Of The World.

If you want to improve an imaginary flag, this is also welcome. We
recommend you first contact the original author of the flag
(see the flags/credits file) to discuss your ideas for changes.


Flag Guidelines
===============

Here are a few guidelines for flags:

  - Flags should be rectangles, since an outline is added to them
  automatically.
  - Flags often come in multiple aspect ratios. A 3:2 ratio looks best
  for Freeciv and currently every flag has this ratio. For a flag that
  is "supposed" to be 2:1 or 4:3, you can often find a 3:2 version
  as well.


Flag Specifics
==============

To add a flag you'll have to edit the following files:

data/flags/<flagname>.svg

  Here is the SVG flag image. This is not used directly by Freeciv but
  is  rendered into PNG files (at various resolutions for different
  tilesets). The SVG file is not used in Freeciv 2.0 but all the other
  steps for adding flags are the same.
  - The <flagname> should either be the name of the country that represents
  the flag, or the common name for the actual flag. When in doubt, use the
  same name as the name of the nation.

data/flags/<flagname>.png

data/flags/<flagname>-shield.png

  These are the flag images that are used by Freeciv. They are rendered
  from the SVG file. Once this file has been created it can be used with
  older versions of Freeciv as well. To run the conversion program you
  will need to install Inkscape, ImageMagick, and (optionally) pngquant.
  Once these are installed change to the data/flags directory and run
  ./convert_png <nationname>.svg.

data/misc/flags.spec

  This file has a reference to the flag PNG graphic. The "tag" here must
  match the flag tag you put in the nation ruleset file
  (usually f.<flagname>) and the "file" should point to the PNG image at
  flags/<flagname>.png.

data/misc/flags-large.spec

  Just like flags.spec, but large version of the graphics.

data/misc/shields.spec

  Just like flags.spec, this file must include a reference to the flag
  PNG graphic. The only difference is that the file should point to the
  "shield" graphic, flags/<flagname>-shield.png.

data/misc/shields-large.spec

  Just like shields.spec, but large version of the graphics.

Changes to the .spec files can be submitted as a patch (created using
diff -ruN). Even though the *.spec files may need to be changed, please
include them in the diff -- this should be easier for you, and it
provides a convenient place for us to grab the sprite name. See the
section on How to Contribute in the Freeciv wiki for more instructions.



----------------------------------------------------------------------
Contents and Style:
-------------------

What nations can be added to Freeciv?
=====================================

A nation in Freeciv should preferrably be a current independent country
or a historical kingdom or realm. A nation that is currently governed
by or the part of a greater political entity, or in other ways lacks
complete independence could in most cases be made a Freeciv nation as
well, but must never be listed as _modern_ (see 'Nation grouping' below.)

Copyrighted content may not be added unless full permission is granted by
the holder of the copyright. This rule effectively disallows the
inclusion of nations based on most literary works.


Nation grouping
===============

Freeciv supports a classification of nations in an unlimited number of
groups and every nation should be assigned to at least one. We currently
have Ancient, Medieval, Early Modern, Modern, African, American, Asian,
European, Oceanian and Imaginary groups. Modern nations are existing and
politically independent countries; a nation listed as ancient, medieval
or early modern should have had an independent dynasty or state in ancient
(until 500 AD), medieval (500 - 1500) or early modern (1500 - 1800) times
respectively. Finally, an imaginary nation is - as the name suggests - a
product of someone's imagination.


Nation naming
=============

The default name of the nation should be the name of the people,
country, or empire in English adjective form. For example, the nation
of ancient Babylon is called "Babylonian" in Freeciv. The plural form
should be standard English as well. For example, plural for the Polish
nation is "Poles" in Freeciv. UTF-8 is permitted in nation names.


Conflicting nations
===================

To specify one or more nations that the AI shouldn't pick for the same
game, use this syntax:

	conflicts_with="<nationname>", "<nationname>", ...

You only have to specify this in the nation you're adding, since it
works in both directions. Reasons for conflicting nations could be
either that they represent the same people in different eras
(ex: Roman - Italian) or that the two nations have too similar
flags that they are easily mixed up in the game
(ex: Russian - Serbian.)


Civil war nations
=================

Specify one or more civil war nations. When a player's capital is
captured, that player might suffer a civil war where his or her
nation is divided and a new player created. The nation for this new
player is selected from one of the civil war nations specified in the
ruleset. A civil war nation should be linguistically, geographically
and/or historically related to the current nation. A linguistic
relation is especially important, since city names after a nation
run out of their own city names, are selected from the civil war
nations' city lists.


Legend
======

A legend is required in a nation ruleset. The legend can be a
summarized history of the nation, or just a piece of trivia.
UTF-8 is permitted in legends.


Leaders
=======

A leader should be a historically notable political leader of the
nation. Two living persons per nation are permitted - one of each sex.

An ideal leader list should contain between five and ten names.

Use the person's full name to avoid ambiguity.

Monarchs should be marked with the appropriate succession
number, using Roman numerals in standard English style (not German
e.g. "Otto II."; Hungarian e.g. "IV. Béla"; Danish e.g. "Valdemar 4."
etc.)

Freeciv support any Unicode character, but please keep to
Latin letters. When transcribing from a non-Latin writing system,
be consistent about the system of transcription you are using.
Also, try to avoid unnecessarily technical and/or heavily accented
systems of transcription.

Subject to the above, leaders should be written in native
orthography, e.g. "Karl XII" instead of "Charles XII" for the
Swedish king.

For consistency and readability, put only one leader per line.
Feel free to provide a hint of the leader's identity or a brief
background in a comment beside any leader: This information might
be used in-game at a later stage.

Leader titles for each government type (including Despotism and
Anarchy) may be specified in a separate tag. UTF-8 is permitted in
leader titles.  If the male and female titles are identical in
English, give the latter the ?female: qualifier. Use a unique title
for each government. Ruler titles should be in English, though
exceptions are made for non English titles as long as they are
understood outside of their own language regions and commonly used in
non-academic contexts. Titles from the default ruleset may not be used.


Flag
====

You should provide a unique flag for your nation. Using a flag that
is already used by another nation in the game is not acceptable.

An alternative flag does not have to be specified.


Style
=====

A nation must specify a default style. With the supplied rulesets
each national style has direct relation to equivalent city style.
The available city styles depends on the tileset used.
Practically every tileset has four city styles: "European",
"Classical" (Graeco-Roman style), "Asian" (Pagoda style) and
"Tropical" (African or Polynesian style). In Amplio tileset,
"Babylonian" and "Celtic" are also available. If the tileset used by
a client does not support a particular city style, a fallback style is
used. Selecting a style for your nation is not that strict. Just try
to keep it somewhat "realistic."


Cities
======

As for the list of city names, you should make a clear decision about
the type of the nation you add. An _ancient_ or _medieval_ nation may
list any city that it at some point controlled. However if your
nation is listed as _modern_, its city list must be restricted to
cities within the country's current borders.

The reason for this is, we don't want Freeciv to be used as a political
vehicle for discussions about borders or independence of particular
nations. Another reason is to avoid overlapping with other nations in
the game.

A city should appear in its native form, rather than Anglicized or
Graeco-Roman forms. For example, the Danish capital is "København"
rather than "Copenhagen"; and the ancient Persian capital is "Parsa"
rather than "Persepolis."

City names support any Unicode character, but please keep to
Latin letters. When transcribing from a non-Latin writing system,
be consistent about the system of transcribation you are using.
Also, try to avoid unnecessarily technical or heavily accented
systems of transcribation.

The ordering of cities should take both chronology of founding and
overall historical importance into consideration. Note that a city
earlier in the list has a higher chance of being chosen than later
cities.


Natural city names
==================

Freeciv supports "natural" geographic placements of cities.

Cities can be labeled as matching or not matching a particular
type of terrain, which will make them more (or less) likely to
show up as the "default" name. The exact format of the list
entry is

	"<cityname> (<label>, <label>, ...)"

where the cityname is just the name for the city (note that it
may not contain quotes or parenthesis), and each "label" matches
(case-insensitive) a terrain type for the city (or "river"), with a
preceding ! to negate it. The terrain list is optional, of course,
so the entry can just contain the cityname if desired. A city name
labeled as matching a terrain type will match a particular map
location if that map location is on or adjacent to a tile of the named
terrain type; in the case of the "river" label (which is a special
case) only the map location itself is considered. A complex example:

  "Wilmington (ocean, river, swamp, forest, !hills, !mountains, !desert)"

will cause the city of Wilmington to match ocean, river, swamp, and
forest tiles while rejecting hills, mountains, and deserts. Although
this degree of detail is probably unnecessary to achieve the desired
effect, the system is designed to degrade smoothly so it should work
just fine.

(A note on scale: it might be tempting to label London as !ocean, i.e.
not adjacent to an ocean.  However, on a reasonably-sized Freeciv world
map, London will be adjacent to the ocean; labeling it !ocean will tend
to give bad results. This is a limitation of the system, and should be
taken into account when labelling cities.)

At this point, it is useful to put one city per line, only.

Finally, don't forget to leave a blank line feed in the end of your nation
ruleset.


Update information
==================

The information about the changes in the definition of a nation between
different versions of Freeciv is kept in the wiki at http://www.freeciv.org/
as part of the ruleset differences. The URLs below list the differences
between the freeciv versions from 2.3.x to the current version:

http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.2_to_2.3

The description of a nation file can be found at:

http://www.freeciv.org/wiki/Nations

----------------------------------------------------------------------
                   Notes for Freeciv packagers
----------------------------------------------------------------------

This file is meant to help those people wanting to package Freeciv
for their distribution, and, to some degree, those people who want to
create Freeciv fork.

----------------------------------------------------------------------
Updating from 2.5 to 2.6
------------------------
* Client uses ~/.freeciv/freeciv-client-rc-2.6 for storing its options.
  Options are always saved to that file.
  Loading of options first tries to get options from
  ~/.freeciv/freeciv-client-rc-2.6. If that file does not exist it tries to
  load options from old client files generated by former version of Freeciv
  (e.g. ~/.freeciv-client-rc-2.5 generated by Freeciv 2.5 or ~/.civclientrc
   generated by Freeciv version <= 2.1).
* gtk3-client is now the default client
* Minimum gtk3 requirement for building gtk3-client is now 3.8.
* Minimum qt requirement for building qt-client and freeciv-ruledit is 5.2.
* There's new gtk3.22-client that has gtk+-3.22 as requirement. It can be
  built with --enable-client=gtk3.22. This client suits better for
  systems with gtk+-3.22 or gtk+-3.24 than the gtk3-client compatible with
  much older gtk+ versions.
* There's new experimental sdl2-client. It can be built with
  --enable-client=sdl2
* Development of ruleset editor, freeciv-ruledit, has begun.
  It has same Qt5 dependencies as other Qt programs in Freeciv distribution.
  It is not very usable in 2.6 and should probably not be packaged by
  distributions.
* Lua version to use is 5.3 now.
* System lua library is now used by default. Copy of lua distributed
  with freeciv is used only if system lua is not found, or it's
  explicitly requested with configure option --disable-sys-lua
* There's new configure option --enable-sys-tolua-cmd to use tolua
  command from the build system when generating lua bindings. Plain
  --enable-sys-tolua-cmd searches tolua from the PATH, other values
  are treated as full path to executable. The default is to search
  for tolua from the system. You have to use system tolua when
  cross-compiling.
* Minimum libtool version is now 1.5.2
* Minimum automake version is now 1.10
* For translation support minimum gettext version is now 0.14. It's
  still possible to build completely without translation support
  with configure option --disable-nls
* SDL2-mixer is now the default. To build clients to still use
  SDL1.2-mixer, configure with --enable-sdl-mixer=sdl1.2. sdl-client
  cannot be built with SDL2-mixer, nor can sdl2-client be built with
  SDL1.2-mixer
* Server now saves its readline history to file
  "~/.freeciv/freeciv-server_history" instead of "~/.freeciv-server_history"
* Configure option --with-freeciv-manual / --without-freeciv-manual has
  been replaced with --enable-freeciv-manual / --disable-freeciv-manual
  that can take also value --enable-freeciv-manual=html to make
  freeciv-manual that produces manuals with alternative formatting,
  default still being wiki formatting.
* Added configure options --with[out]-libbz2 and --with[out]-liblzma to
  explicitly enable or disable support for bz2 or xz compressed files.
  The default is still to autodetect if the support can be built in.
  Note that it's usually a bad idea to disable one of these if you
  have had it previously enabled, as then your new version will be
  unable to load old savegames created with that compression type in
  use.
* Ruleset README files have moved from doc/ into data/ directory
  alongside ruleset data, so that they can be displayed inside the
  game. You may want to symlink to these from /usr/share/doc/ or
  equivalent so that users can continue to easily find the
  documentation outside the game.
* GGZ support has been dropped completely.

----------------------------------------------------------------------
Compatibility of modified versions
----------------------------------
If you create patched version of Freeciv, take necessary precautions
to avoid problems when your patched version interacts with unpatched
version, or tries to load or save incompatible data files.

Concept called "capabilities" is widely used in Freeciv. If two things
(server/client, program/datafile...) are incompatible, they have
different capabilities defined. Based on that they can detect
incompatibility and act gracely.
Be sure to update network capability string in fc_version if you break
network compatibility, so your patched server/client does not cause
problems to official Freeciv servers/clients trying to connect it.

If you distribute modified version of freeciv, even (or especially)
one network compatible with upstream, you should change also
FREECIV_DISTRIBUTOR in fc_version to match. This information is sent
by client to (public) server so in case there's any problems with certain
clients, we know a bit more what kind of code they are using.

----------------------------------------------------------------------
Configure time version number adjustment
----------------------------------------

The version label part of the version number can be set via
configure time environment variable FREECIV_LABEL_FORCE.
If the variable contains tag "<base>", that gets replaced with the
label that would be used if FREECIV_LABEL_FORCE was not set at all.

----------------------------------------------------------------------
Announcement of new versions
----------------------------
As of 2.4, the Freeciv client displays the latest available version if
it's newer than the running version. This information comes from the
metaserver.

The metaserver maintains several different versions to report here,
distinguished by "follow tags". The default follow tag is "stable",
updated when a new source release is made, but for instance Windows
builds will follow a different tag such as "win32", which will only be
updated when a new Windows binary is available.

This mechanism is primary intended for the Freeciv maintainers, since
updates to the metaserver need to be made be us. However, if you
maintain a significant version/package of Freeciv, you can contact us
and ask to be allocated a tag to pass to 'configure --with-followtag';
thereafter you'd need to let us know whenever you make a new release
so we can update the metaserver.

(This is unlikely to be of use to Linux distribution packagers, who
have their own means of distributing updates.)

----------------------------------------------------------------------
Optional features
-----------------
Configure enables many optional features by default when their
dependencies are satisfied in the system. Downside of this automation
is that missing dependencies cause no hard error even when you would
want the features. For getting list of features automatically left out
because of missing dependencies you can give option --with-missinglist
to configure, and last thing configure outputs will be that list.

----------------------------------------------------------------------
Shared libfreeciv
-----------------
Libfreeciv contains code common to server, client, and various tools.
By default it's built as static library, but you can build it as
a shared library by giving configure option "--enable-shared"
(and possibly "--disable-static")

----------------------------------------------------------------------
Generated files
---------------
This is list of files Freeciv might generate to filesystem when running.
You may want to remove some of these when Freeciv is uninstalled.

* Client saves its options to file "~/.freeciv/freeciv-client-rc-2.6"
* Server saves its readline history to file "~/.freeciv/freeciv-server_history"
* When running local single player games, challenge files with name
  like "~/.freeciv/challenge_*_*" are generated
* When saving game in server launched by client, savegame go to
  "~/.freeciv/saves/"
* When saving game in independently launched server, savegames go
  to directory specified with "-s" command line option, defaulting
  to working directory
* freeciv-modpack saves data under "~/.freeciv/2.6/" and
  "~/.freeciv/scenarios/"
* Server can write log to file specified with "-l" command line option
* When mapimage feature is used, it can save colortest images to
  working directory and actual map images to save directory (same as above)

----------------------------------------------------------------------
Building multiple clients at once
---------------------------------
Starting from 2.2 it has been possible to build multiple clients running
'make' just once. Just give configure option "--enable-client" comma
separated list of clients to compile, e.g. "--enable-client=gtk3,gtk2,sdl,qt"

----------------------------------------------------------------------
Savegame compression support
----------------------------
Freeciv can use several different compression libraries for compressing
its savegames. See server setting "compresstype".
* zlib (gzip compression) is required to compile freeciv so zlib
  compression support is always present
* bzip2 compression is built into Freeciv if bzip2 libraries and
  headers are present at configure time. One can override this automatic
  detection with configure option --with[out]-libbz2.
* xz compression is built into Freeciv if liblzma library and
  headers are present at configure time. One can override this automatic
  detection with configure option --with[out]-liblzma.

While this feature is called "Savegame compression support" it actually
applies to loading of all the section files: savegames, rulesets, tileset
spec files... If compression support is built into Freeciv, you can
compress any of these files and Freeciv can still load them. Freeciv ships
with all the data files uncompressed, except scenarios which are gzipped.

----------------------------------------------------------------------
Loadable AI modules
-------------------
Freeciv can be built with support of loading AI code from custom module.
There can be multiple modules loaded at once, and AI players can use
different module from each other.
This feature is not enabled by default. When it's not enabled, default
AI code is built in to server and always used.
You can enable this feature with '--enable-aimodules'. For this to work
you have to enable also building of shared libraries (and modules) with
'--enable-shared' as discussed in chapter 'Shared libfreeciv'
All modules, both default and custom, must be installed under
${libdir}/fcai (/usr/lib/fcai for example) for their loading to work.

----------------------------------------------------------------------
Public servers
--------------
Sadly we have no resources to keep public servers for many different
Freeciv versions running. To give your users ability to play on public
servers, try to provide them as current Freeciv client version as possible.
To see list of currently running public servers, see
"http://meta.freeciv.org/metaserver.php" Note that from the web you
can see complete list, while list shown by Freeciv client only lists
compatible servers.

Any a.b.c release is network compatible with any a.b.d release. If you
provide 2.6.c client, it can be used to play on 2.6.d server.

----------------------------------------------------------------------
                       Freeciv Rulesets
----------------------------------------------------------------------
          (Originally by David Pfitzner, dwp@mso.anu.edu.au)

Quickstart:
-----------
 Rulesets allow modifiable sets of data for units, advances, terrain,
 improvements, wonders, nations, cities, governments and miscellaneous
 game rules, without requiring recompilation, in a way which is
 consistent across a network and through savegames.

- To play Freeciv normally: don't do anything special; the new
  features all have defaults which give the standard Freeciv
  behaviour.

- To play a game with rules more like Civ1, start the server with:
       ./fcser -r data/civ1.serv
  (and any other command-line arguments you normally use; depending on
  how you have Freeciv installed you may have to give the installed
  data directory path instead of "data").

  Start the client normally. The client must be network-compatible
  (usually meaning the same or similar version) but otherwise nothing
  special is needed. (However some third-party rulesets may
  potentially require special graphics to work properly, in which case
  the client should have those graphics available and be started with
  an appropriate '--tiles' argument.)

  As well as a Civ1 style as above, Freeciv now has a Civ2 style
  similary, although currently it is almost identical to standard
  Freeciv rules.

  Note that the Freeciv AI might not play as well with rules other
  than standard Freeciv. The AI is supposed to understand and
  utilize all sane rules variations, so please report any AI
  failures so that they can be fixed.

The rest of this file contains:

- More detailed information on creating and using custom/mixed
  rulesets.

- Information on implementation, and notes for further development.

----------------------------------------------------------------------
Using and modifying rulesets:
-----------------------------

Rulesets are specified using the server command "rulesetdir".  The
command above of "./fcser -r data/civ1.serv" just reads a file which
uses this command (as well as a few of the standard server options).
The server command specifies in which directory the ruleset files
are to be found.

The ruleset files in the data directory are user-editable, so you can
modify them to create modified or custom rulesets (without having to
recompile Freeciv). It is suggested that you _don't_ edit the
existing files in the "classic", "civ2civ3", "experimental",
"multiplayer", "civ1", or "civ2"
directories, but rather copy them to another directory and edit the
copies. This is so that its clear when you are using modified rules
and not the standard ones.

The format used in the ruleset files should be fairly
self-explanatory. A few points:

- The files are not all independent, since eg, units depend on
  advances specified in the techs file.

- Units have a field, "roles", which is like "flags", but
  determines which units are used in various circumstances of the
  game (rather than intrinsic properties of the unit).
  See comments in common/unit.h

- Rulesets must be in UTF-8; translatable texts should be American English
  ASCII.

----------------------------------------------------------------------
Restrictions and Limitations:
-----------------------------

units.ruleset:

  Restrictions:

    - At least one unit with role "FirstBuild" must be available
      from the start (i.e., tech_req = "None").

    - There must be units for these roles:
      - "Explorer"
      - "FerryBoat"        (Must be able to move at sea)
      - "Hut"              (Must be able to move on land)
      - "Barbarian"        (Must be able to move on land)
      - "BarbarianLeader"  (Must be able to move on land)
      - "BarbarianBuild"   (Must be able to move on land)
      - "BarbarianBoat"    (Must be able to move at sea)
      - "BarbarianSea"

nations.ruleset

  Restrictions:

    - Government used during revolution can't be used as default_government
      or init_government for any nation

----------------------------------------------------------------------
Implementation details:
-----------------------

This section and following section will be mainly of interested to
developers who are familiar with the Freeciv source code.

Rulesets are mainly implemented in the server. The server reads the
files, and then sends information to the clients. Mostly rulesets
are used to fill in the basic data tables on units etc, but in some
cases some extra information is required.

For units and advances, all information regarding each unit or advance
is now captured in the data tables, and these are now "fully
customizable", with the old enumeration types completely removed.

----------------------------------------------------------------------
Game settings defined in the ruleset:
-------------------------------------

Game settings can be defined in the section [settings] of the file
game.ruleset. The name key is equal to the setting name as listed by
'show all'. If the setting should be locked by the ruleset, the last
column should be set to TRUE.

set =
    { "name", "value", "lock"
      "bool_set", TRUE, FALSE
      "int_set", 123, FALSE
      "str_set", "test", FALSE
    }

----------------------------------------------------------------------
Update information:
-------------------

The information about the changes in the definition of a ruleset between
different versions of Freeciv is kept in the wiki at http://www.freeciv.org/
The URLs below list the differences between the freeciv versions from 2.2.x
to the current version:

http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.5_to_2.6

http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.4_to_2.5

http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.3_to_2.4

http://www.freeciv.org/wiki/How_to_update_a_ruleset_from_2.2_to_2.3

Format description of the scorelog format version 2
===================================================

Empty lines and lines starting with '#' are comments. Each non-comment
line starts with a command. The parameter are supplied on that line
and are seperated by a space. Strings which may contain whitespaces
are always the last parameter and so extend till the end of line.

The following commands exists:
  id <game-id>
    <game-id> is a string without whitespaces which is used
              to match a scorelog against a savegame.

  tag <tag-id> <descr>
    add a data-type (tag)
      the <tag-id> is used in the 'data' commands
      <descr> is a string without whitespaces which
              identified this tag

  turn <turn> <number> <descr>
    adds information about the <turn> turn
      <number> can be for example year
      <descr> may contain whitespaces

  addplayer <turn> <player-id> <name>
    adds a player starting at the given turn (inclusive)
      <player-id> is a number which can be reused
      <name> may contain whitespaces

  delplayer <turn> <player-id>
    removes a player from the game. The player was
      active till the given turn (inclusive)
      <player-id> used by the creation

  data <turn> <tag-id> <player-id> <value>
    give the value of the given tag for the given
    player for the given turn.

===========================================================================
 Sound Support
===========================================================================

The server sends the client a list of primary and secondary sound tags
for certain events. The 'primary' tags are those preferred by the
current modpack. The client does not need to have these sounds. The
'secondary' tags should refer to standard sounds that all
installations of Freeciv should have.

Tags are used to give an easy way to change sounds. A specfile is used
to indicate which tags refer to which sound files. A change of spec
file, given as an option at startup, will change sounds. For example,

	freeciv-gtk3 --Sound mysounds.spec

will read sound files from "mysounds.spec". You will need to download
or copy or link those sounds into whichever directory is mentioned in this
file first, or edit it to refer to the right files. All references are by
default relative to the data/ directory. Soundpacks can be downloaded from
the Freeciv website in the tar format. You will either need to unpack them
with eg "tar -xzvf stdsoundsX.tar.gz" or use 7-Zip (for Windows etc.), and
put the files in the data directory mentioned above.

You can get additional soundsets (sound files and a spec file)
from <http://files.freeciv.org/contrib/audio/soundsets>. At this
address you find also extra sound files to change an existing soundset or
create a new one.

================================
 Plugins
================================

The output of the sounds at the client side are done by plugins. The
set of available plugins depend on the libraries found on the host
system. You can choose the plugin the client should use via the
command line:

	freeciv-gtk3 --Plugin sdl

You can choose "none" to mute the client. Freeciv currently supports
the following plugins:
  - dummy (none)
  - SDL with SDL_mixer library (sdl)

To add support for a new plugin, change these files (where "whatever"
is the name of the new plugin):
	configure.ac			/* add new test */
	client/audio.c			/* link in new plugin */
	client/Makefile.am		/* add the files below */
	client/audio_whatever.c		/* audio plugin */
	client/audio_whatever.h		/* audio plugin's header */

================================
 Tags
================================

There are two kinds of sound tags:
 - defined in the rulesets
 - defined in the program code

While the former can be chosen freely the latter can't be changed.

The sound tags associated with improvements (wonders and normal
buildings), unit movements and unit fights have to be set in the
rulesets. Freeciv just hand these sound tags over to the client where
they are translated into the filenames of the sound files via the
soundspec file. Every soundspec should have generic sound tags for
wonders ("w_generic"), normal buildings ("b_generic"), unit movements
("m_generic") and unit fights ("f_generic").

Sound tags associated with certain events are generated in the Freeciv
code and can't be configured from outside. The soundspec file also has
to have mapping for these tags. The complete list of such tags can be
found in data/stdsounds.spec. The name of the tag is enum name (see
common/events.h) in lowercase. So E_POLLUTION becomes the tag
"e_pollution". There is no generic event tag and no alternate tags are
used.

================================
 TODO
================================

There are a few things that can be done to get better sound support in
Freeciv still:
  * add more plugins (gstreamer, arts, windows, etc)
  * add a sound tag for each technology, as for buildings/units
  * always add more event tags
  * find or create better sound samples and make better spec-file

================================
 Misc
================================

Sound creators: Please name sound files intelligibly. Include a README
where you present the licensing terms used (if public domain, say so)
for the sound files.

Modpack makers: Please give secondary tags that refer to standard tags
so that those who have not downloaded the latest & greatest sound pack
can still enjoy the game.

----------------------------------------------------------------------
                       Freeciv Tilesets
----------------------------------------------------------------------

Quickstart:
-----------

Tilesets are a collection of images which are needed to display the
map.

----------------------------------------------------------------------
Update information:
-------------------

The information about the changes in the definition of a tileset between
different versions of Freeciv is kept in the wiki at http://www.freeciv.org/
The URLs below list the differences between the freeciv versions from 1.14.x
to the current version:

http://www.freeciv.org/wiki/How_to_update_a_tileset_from_2.5_to_2.6

http://www.freeciv.org/wiki/How_to_update_a_tileset_from_2.4_to_2.5

http://www.freeciv.org/wiki/How_to_update_a_tileset_from_2.3_to_2.4

http://www.freeciv.org/wiki/How_to_update_a_tileset_from_2.2_to_2.3

http://www.freeciv.org/wiki/How_to_update_a_tileset_from_2.1_to_2.2

http://www.freeciv.org/wiki/How_to_update_a_tileset_from_2.0_to_2.1

http://www.freeciv.org/wiki/How_to_update_a_tileset_from_1.14_to_2.0