\documentclass[12pt]{book}
\usepackage[T1]{fontenc}
\usepackage{longtable}
\usepackage{graphicx}
\usepackage{index}
\usepackage[colorlinks=true,hyperindex=true]{hyperref}
\makeindex

\begin{document}
\author{\href{http://freecol.sourceforge.net/index.php?section=8}{The FreeCol Team}}
\title{FreeCol Documentation\\Developer Guide for Version v0.9.0}
\maketitle{}

\tableofcontents
\newpage


\hypertarget{How to become a FreeCol developer}
            {\chapter{How to become a FreeCol developer}}



\hypertarget{The goal of our project}{\section{The goal of our project}}

We are aiming towards making a clone of the old computer
classic "Sid Meier's Colonization".

New features should in general not be added before we reach
FreeCol 1.0.0, unless they are implemented as optional features
using the class "GameOptions".

The big exception to this rule is the our client-server model that
will allow players from all over the world to compete in a game
of FreeCol.

Read more \href{http://www.freecol.org/index.php?section=2}{here}.


\hypertarget{SourceForge project site}{\section{SourceForge project site}}

You should visit and get familiar with our project site at
\href{http://sourceforge.net/projects/freecol/}{SourceForge}.

This site contains trackers for bugs and features requests,
a task manager and lots of other important services.

We expect developers to use this site regularly when making
changes to the codebase.


\hypertarget{How to get tasks}{\section{How to get tasks}}

You may find available tasks in the bug and feature request
trackers --- just grab any task you are planning to do (in the
immediate future) by posting a comment telling that you intend
to do this task. Please create a new bug report/feature request
for tasks that is not being listed here (and before you start
working on them). Please remember to post a comment when
you are done, or if you are unable to complete the work.

Major changes to the code should be discussed on the
developer's mailing list before they are implemented. This is to
ensure that your work will not be in vain if somebody else knows
a better way of doing it. It is also a good idea to discuss changes
that is not directly related to the next release on our 
\href{http://www.freecol.org/index.php?section=18}{roadmap}.


\hypertarget{How to use the trackers}{\section{How to use the trackers}}

This is how a bug tracker item should be updated while you are working:

\begin{enumerate}
\item Assign yourself to the tracker item before you start working on it.

\item Please verify that no duplicate entry has been posted.

\begin{itemize}
\item If you can find a duplicate and the bug has NOT been fixed:
  Please use the resolution "Duplicate", set the status to "Closed"
  and post a comment with the ID of the other tracker item (add a
  comment to the other tracker item as well).

\item If you can find a duplicate and the bug has been fixed: Use the
  resolution "Out of date" and close the tracker item.
\end{itemize}

\item Set the item's status to pending if you require input from the person
   originally submitting the item.

\item If you are unable to complete the item: Assign it to "None" and
   make a comment describing any problems relevant for another developer.

\item After you have completed the work: Set the group to "Fixed (SVN)",
   resolution to "Fixed" and the status to "Closed". Please also write
   a comment telling that the work is done.
\end{enumerate}

This is how a feature request item should be updated while you are
working:

\begin{enumerate}
\item Assign yourself to the tracker item before you start working on it.

\item Please verify that no duplicate entry has been posted.

\begin{itemize}
\item If you can find a duplicate and the feature has NOT been
  implemented: Please use the group "Duplicated", set the status to
  "Closed" and post a comment with the ID of the other tracker item
  (add a comment to the other tracker item as well).

\item If you can find a duplicate and the feature has been
  implemented: Use the group "Out of date" and close the tracker item.
\end{itemize}

\item Set the item's status to pending if you require input from the person
   originally submitting the item.

\item Set the group to "Accepted" if you decide that this feature
   request should be added before the next release (please discuss on
   the mailing list if there are any reasons not to include this
   feature).

\item If you are unable to complete the item (or you think someone else
   should be implementing it): Assign it to "None" and make a comment
   describing any issues relevant for another developer.

\item After you have completed the work: Set the group to "Added (SVN)"
   and the status to "Closed". Please also write a comment telling that
   the work is done.
\end{enumerate}

You can use any suitable canned response instead of writing a comment.
For example: You can use the "Fixed: Use SVN" after you have fixed a bug.


\hypertarget{Mailing lists}{\section{Mailing lists}}

Our primary means of communication is the developers mailing list:
freecol-developers@lists.sourceforge.net

You can (and should) subscribe to this list 
\href{http://lists.sourceforge.net/lists/listinfo/freecol-developers}{here}.


\hypertarget{Subversion (SVN)}{\section{Subversion (SVN)}}

Subversion (SVN) is the tool we are using to
manage the changes within our source code tree. This system
makes it possible for all developers to have their own
"working copy" by supporting synchronization between the
central version of the code ("the repository") and a copy.
SVN also makes it possible to "undo" changes that were
previously committed to the repository.

\href{http://www.freecol.org/index.php?section=17}{This page}
describes how you can start using SVN and get a working copy of the
code (without commit privileges).

You can use \verb+svn update+ for updating an existing working
copy. Changes can only be applied by those who have write-access, so
you will need to either send the changes to the developer mailing list
or use the patch tracking system.


\hypertarget{Compiling the code}{\section{Compiling the code}}

We use the {\textit Apache Ant} build system for compiling the
game. You can get a copy of this program
\href{http://ant.apache.org}{here}. After it has been installed, you
simply type \verb+ant+ in the top directory of your "working copy" in
order to compile the game.  The file \verb+FreeCol.jar+ will then be
generated, and you can start the game simply by writing:

\verb+java -Xmx128M -jar FreeCol.jar+



\hypertarget{Code documentation}{\section{Code documentation}}

Our primary code documentation is the Javadoc generated
documentation. You can convert this documentation to HTML by
typing \verb+ant javadoc+. The directory "javadoc" will then be
created and you can start watching the documentation by opening
"index.html" from that directory.

There is also some additional documentation 
\href{http://www.freecol.org/index.php?section=3}{here}.


\hypertarget{Quality of code}{\section{Quality of code}}

First of all, your code will be read and modified by several
different developers. Therefore it is important to create a
block of JavaDoc documentation with all methods/classes/packages
you implement.

You should also spend more time thinking about the overall
structure than when you are working alone.

Please read the \href{http://java.sun.com/docs/codeconv/}{Java Code
  Conventions}. This will only take about 15 minutes and will really
help you write beautiful code.

And one more thing. Please configure your editor in such a way
that code indentations result in the insertion of 4 spaces. Tabs
are the work of the devil!




\hypertarget{How to build a FreeCol release}{\chapter{How to build a FreeCol release}}

\begin{itemize}

\item Make sure that all relevant changes have been committed to the
  branch you are about to release. In particular, remember to merge
  translations from trunk if the release is not made from trunk.

\item Create a copy of the branch you want to release in the tags
  folder. Subversion does not distinguish between tags and
  branches. Example:

{\small
\begin{verbatim}
  svn copy -m "Creating tag for release 0.9.0-alpha2." \
  https://freecol.svn.sourceforge.net/svnroot/freecol/freecol/branches/0.9.x \
  https://freecol.svn.sourceforge.net/svnroot/freecol/freecol/tags/0.9.0-alpha2
\end{verbatim}
}

\item Check out the newly created branch and do all further work in that
  new branch.

\item Change the \verb$FREECOL_VERSION$ constant to match the release version in
  FreeCol.java and commit the change. Start a clean compile, run all
  tests and verify the specification(s). You can do that by calling
  \verb+ant prepare-commit+.

\item Call \verb+ant dist+ in order to build all packages. It might be
  necessary to increase the memory available for ant, for example by
  setting the environment variable \verb+ANT_OPTS="-Xms256m -Xmx256m"+.

\item Install one of the generated packages and verify that you can play
  normally for at least five turns. Other good tests include loading a
  saved game and running the game in debug mode for a hundred turns or
  so. It might also be a good idea to compile the game from one of the
  source packages.

\item Upload the packages to \verb$sftp://frs.sourceforge.net/$ and ensure that
  all packages get uploaded. You can use a script similar to this:

\begin{verbatim}
  #!/bin/sh

  FREECOL_VERSION=0.9.0-alpha2
  PREFIX=freecol-$FREECOL_VERSION
  USERNAME=myUserName

  sftp $USERNAME,freecol@frs.sourceforge.net <<FILE
  cd /home/frs/project/f/fr/freecol/freecol
  mkdir $PREFIX
  cd $PREFIX
  put $PREFIX-installer.exe
  put $PREFIX-installer.jar
  put $PREFIX-installer-with-sources.jar
  put $PREFIX-mac.tar.bz2
  put $PREFIX-src.tar.gz
  put $PREFIX-src.zip
  put $PREFIX.tar.gz
  put $PREFIX.zip
  exit
  FILE
\end{verbatim}


\item Compile the feature list for the news announcement (use the tracker
  and/or run the previous version for comparison).

\item Update the release number in the "Version"-mambot.
  (http://www.freecol.org/administrator > Mambots > Site Mambots >
  Version)

\item Publish/unpublish "Download Unstable Version" in the main menu
  (this page should only be displayed if the unstable version is the
  latest release).

\item Add a news item to our website.

\item Remove the download button from the previous release news item.

\item Post release messages on our mailing lists: developers, translators
  and users. Include information on savegame compatibility with previous versions 
  on all messages.
  
\item Post release message to forum FreeCol. Include information on savegame compatibility with previous versions,
  as well as information on how to post bug reports regarding the release in the bug tracker.
    
\end{itemize}

The following items can be omitted for unstable releases:

\begin{itemize}

\item Trackers: Rename the group "Added (Trunk)"/"Added (x.y,z-branch)" to
  Added (FreeCol x.y.z). Rename the group "Fixed (x.y,z-branch)"/
  "Fixed (Trunk)" to Fixed (FreeCol x.y.z). Create new groups with the
  names you just renamed from. Change the links on "Tracker > Admin >
  Bugs/Feature... > Preferences". Add redirects for "bugtracker/x.y.z"
  and "featuretracker/x.y.z". Create a new group for "In x.y.z".

\item Update JavaDoc and User Documentation on
  \href{freecol.org}{freecol.org}. You can do that with a script like
  this:

\begin{verbatim}
#!/bin/sh

USERNAME=myUserName

cd docs

{
    echo cd /home/groups/f/fr/freecol/htdocs
    echo put FreeCol.pdf
    echo put FreeCol.html
    echo put images/* images
    find javadoc/ -printf "put %p %p\n"
} | sftp $USERNAME,freecol@web.sf.net

\end{verbatim}



\end{itemize}

The following items should be omitted for unstable releases:

\begin{itemize}

\item Update the links to "Added (x.y.z-branch)" and "Fixed
  (x.y.z-branch)" on the roadmap (and release status etc).

\item Post a news item on SF.net

\item Create news items at \href{Linuxgames.com}{Linuxgames.com},
  \href{linux-gamers.com}{linux-gamers.com} and
  \href{happypenguin.org}{happypenguin.org}.

\end{itemize}


\hypertarget{Missing features}{\chapter{Missing features}}

We know that FreeCol does not yet emulate all features of the original
game. In particular, the initial contact with other nations differs
considerably from that in the original game. At some point, we will
fix this, as far AI players are concerned. In a multi-player game,
however, European nations played by other humans will never behave
like the AI nations in the original game.

Other missing features include the intervention force. You can report
any missing feature as a bug.

Since we do not have access to the source code of the original game,
we can only guess at the algorithms used to calculate production,
combat results, bells required to elect a founding father and so
on. In some cases, players have reverse-engineered the algorithm. If
you know of some calcuation in FreeCol that differs from that of the
original game, please tell us about it.

We know that the calculation of the player's score differs from that
of Colonization, and we will fix that issue.

We also know that the calculation of production differs, but we lack
the necessary data to fix the issue. If you have further information,
please contribute by telling us about your conclusions.


\hypertarget{Colonization production reports}
            {\section{Colonization production reports}}


All production numbers are given for colonists and experts for the
production of the goods (col/ex). When adding to the list, please give
all relevant data, particularly the difficulty level, production bonus
of the colony and all relevant founding fathers.

\begin{itemize}

\item Difficulty: viceroy, colony production bonus: 0

\begin{tabular}{lr@{ / }r}
Food production:\\

Hills: & 2 & 4\\
Conifer forest: & 2 & 4\\
Broadleaf forest: & 2 & 4\\
\bigskip
Plains / minor river / plowed: & 7 & 9\\


Lumber production:\\

Conifer forest: & 6 & 12\\
Broadleaf forest: & 4 & 8\\
Conifer forest / road: & 8 & 14\\
\end{tabular}


\item Difficulty viceroy, colony production bonus: 1

\begin{tabular}{lr@{ / }r}
Food production:\\

Hills: & 3 & 6\\
Conifer forest: & 3 & 6\\
Broadleaf forest: & 3 & 6\\
\bigskip
Plains / minor river / plowed: & 8 & 11\\

Lumber production:\\

Conifer forest: & 8 & 16\\
Broadleaf forest: & 6 & 12\\
Conifer forest / road: & 10 & 18\\
\end{tabular}

\end{itemize}



\hypertarget{Changing the Rules}{\chapter{Changing the Rules}}

We would like to make FreeCol configurable, so that the game engine
becomes capable of emulating many similar games. For this purpose,
we have made many of the game's features configurable.

At some point in the future, we will probably add a special rule set
editor, but at the moment, your only option is to edit the file
specification.xml directly. This file defines the abilities of units,
founding fathers, buildings, terrain types, goods and equipment, for
example. You can find this file in the \textit{data/freecol} directory.

This is still work in progress, however, and the schema for the rule
set certain to change again in the future. If you wish to develop your
own rule set, you will have to monitor FreeCol development closely.

This having been said, we are particularly interested in hearing about
problems caused by your changes to the rule set. Some dialogs might be
unable to display more types of goods than are currently defined, for
example. Or other dialogs might not recognize your new Minuteman unit
as an armed unit. Please help us improve FreeCol by telling us about
such problems.

If you have a working rule set that adds a new flavour to the game, we
will gladly distribute it along with our default rule set. If you have
ideas that can not currently be implemented, we will probably try to
remove these limitations.

If you try to modify the rule set, you are strongly encouraged to
check whether the result is still valid. You can do this by validating
the result with the command \verb$ant validate$.


\hypertarget{Modifiers and Abilities}{\section{Modifiers and Abilities}}

Most of the objects defined by the rule set can be customized via
modifiers and abilities.  Abilities are boolean values (``true'' or
``false''). If the value is not explicitly stated, it defaults to
true. If an ability is not present, it defaults to false. Modifiers
define a bonus or penalty to be applied to a numeric value, such as
the number of goods produced by a unit. The modifier may be an
additive, multiplicative or a percentage modifier. Modifiers default
to ``identity'', which means they have no effect.

The code also checks that all abilities and modifiers it uses are
defined by the specification. Therefore, you must define all of them,
even if you do not use them. You can do this by setting their value to
the default value, e.g. ``false'' in the case of an ability, or ``0''
in the case of an additive modifier.

\newcommand{\ability}[1]{\index{#1}\index{Ability!#1}\hypertarget{#1}{\vspace{1em}\noindent\textbf{#1}}}
\newcommand{\modifier}[1]{\index{#1}\index{Modifier!#1}\hypertarget{#1}{\vspace{1em}\noindent\textbf{#1}}}
\newcommand{\affectsPlayer}{\\\textit{Affects: Player\\Provided by:
    Nation, Nation Type, Founding Father}}
\newcommand{\affectsUnit}{\\\textit{Affects: Unit\\Provided by:
    Nation, Nation Type, Founding Father, Unit Type, Equipment Type}}
\newcommand{\affectsBuilding}{\\\textit{Affects: Building\\Provided by:
    Building Type}}
\newcommand{\affectsColony}{\\\textit{Affects: Colony\\Provided by:
    Map}}
\newcommand{\affectsColonyTwo}{\\\textit{Affects: Colony\\Provided by:
    Building Type, Nation, Nation Type, Founding Father}}
\newcommand{\affectsTile}{\\\textit{Affects: Tile\\Provided by:
    Tile Type}}


\ability{model.ability.addTaxToBells}
\affectsPlayer

The player adds the current tax rate as a bonus to bells
production. The bonus is modified every time the tax increases or
decreases.

\ability{model.ability.alwaysOfferedPeace}
\affectsPlayer

The player is always offered peace in negotiations with AI players.

\ability{model.ability.ambushBonus}
\affectsUnit

The unit is granted an ambush bonus equal to the terrain's defence value.

\ability{model.ability.ambushPenalty}
\affectsUnit

The unit suffers an ambush penalty equal to the terrain's defence value.

\ability{model.ability.autoProduction}
\affectsBuilding

The building needs no units to produce goods, and will never produce
more goods than can be stored in the colony.

\ability{model.ability.automaticEquipment}
\affectsUnit

The unit automatically picks up equipment if attacked.

\ability{model.ability.automaticPromotion}
\affectsUnit

A unit that can be promoted will always be promoted when successful in
battle.

\ability{model.ability.betterForeignAffairsReport}
\affectsPlayer

The player is provided with more information about foreign powers.

\ability{model.ability.bombard}
\affectsUnit

The unit is able to bombard other units.

\ability{model.ability.bombardShips}
\affectsBuilding

The building has the ability to bombard enemy ships on adjacent tiles.

\ability{model.ability.bornInColony}
\affectsUnit

The unit can be born in a colony, provided that enough food is available.

\ability{model.ability.bornInIndianSettlement}
\affectsUnit

The unit can be born in an Indian settlement, provided that enough food is available.

\ability{model.ability.build}
\affectsBuilding

The building can build units or equipment.

\ability{model.ability.buildCustomHouse}
\affectsPlayer

The player can build custom houses.

\ability{model.ability.buildFactory}
\affectsPlayer

The player can build factories.

\ability{model.ability.canBeCaptured}
\affectsUnit

The unit can be captured. Land units that can not be captured are
destroyed, naval units that can not be captured are either sunk or
damaged.

\ability{model.ability.canBeEquipped}
\affectsUnit

The unit can be equipped.

\ability{model.ability.canNotRecruitUnit}
\affectsPlayer

The player can not recruit specified units.

\ability{model.ability.captureEquipment}
\affectsUnit

The unit can capture equipment from another unit.

\ability{model.ability.captureGoods}
\affectsUnit

The unit can capture goods from another unit.

\ability{model.ability.captureUnits}
\affectsUnit

The unit can capture enemy units.

\ability{model.ability.carryGoods}
\affectsUnit

The unit can transport goods.

\ability{model.ability.carryTreasure}
\affectsUnit

The unit can transport treasures, not treasure trains.

\ability{model.ability.carryUnits}
\affectsUnit

The unit can transport other units.

\ability{model.ability.convert}
\affectsUnit

The unit is a native convert.

\ability{model.ability.dressMissionary}
\affectsBuilding

The building can commission missionaries.

\ability{model.ability.electFoundingFather}
\affectsPlayer

The player can elect Founding Fathers.

\ability{model.ability.expertMissionary}
\affectsUnit

The unit is an expert missionary, but not necessarily commissioned.

\ability{model.ability.expertPioneer}
\affectsUnit

The unit is an expert pioneer, but not necessarily equipped with tools.

\ability{model.ability.expertScout}
\affectsUnit

The unit is an expert scout, but not necessarily equipped with horses.

\ability{model.ability.expertSoldier}
\affectsUnit

The unit is an expert soldier, but not necessarily equipped with muskets.

\ability{model.ability.expertsUseConnections}
\affectsPlayer

Experts working in factories can produce a small amount of goods even
if the raw materials are not available in the colony.

\ability{model.ability.export}
\affectsBuilding

The building can export goods to Europe directly.

\ability{model.ability.foundColony}
\affectsUnit

The unit can found new colonies.

\ability{model.ability.foundInLostCity}
\affectsUnit

The unit may be generated as the result of exploring a Lost City Rumour.

\ability{model.ability.hasPort}
\affectsColony

The colony has access to at least one water tile. This ability can not
be set by the specification, but it can be used as a required ability.

\ability{model.ability.ignoreEuropeanWars}
\affectsPlayer

The player will not be affected by the Monarch's declarations of war.

\ability{model.ability.improveTerrain}
\affectsUnit

The unit is able to improve terrain.

\ability{model.ability.independenceDeclared}
\affectsPlayer

The player has declared independence.

\ability{model.ability.mercenaryUnit}
\affectsUnit

The unit may be offered as a mercenary unit.

\ability{model.ability.missionary}
\affectsUnit

The unit is able to establish missions and incite unrest in native
settlements.

\ability{model.ability.moveToEurope}
\affectsTile

Units on the tile are able to move to Europe.

\ability{model.ability.multipleAttacks}
\affectsUnit

The unit can attack more than once.

\ability{model.ability.native}
\affectsUnit

The unit is a native unit.

\ability{model.ability.navalUnit}
\affectsUnit

The unit is a naval unit.

\ability{model.ability.pillageUnprotectedColony}
\affectsUnit

The unit is able to steal goods from and destroy buildings in an
unprotected colony.

\ability{model.ability.piracy}
\affectsUnit

The unit is a privateer.

\ability{model.ability.produceInWater}
\affectsBuilding

The building enables units to produce on water tiles.

\ability{model.ability.refUnit}
\affectsUnit

The unit can be part of the Royal Expeditionary Force.

\ability{model.ability.repairUnits}
\affectsBuilding

The building can repair units.

\ability{model.ability.royalExpeditionaryForce}
\affectsPlayer

The player is a Royal Expeditionary Force.

\ability{model.ability.rumoursAlwaysPositive}
\affectsPlayer

The player will always get positive results from exploring Lost City
Rumours.

\ability{model.ability.scoutForeignColony}
\affectsUnit

The unit can scout out foreign colonies.

\ability{model.ability.scoutIndianSettlement}
\affectsUnit

The unit can scout out native settlements.

\ability{model.ability.selectRecruit}
\affectsPlayer

The player can select a unit to recruit in Europe. This also applies
to units generated as a result of finding a Fountain of Youth.

\ability{model.ability.teach}
\affectsBuilding

The building enables experts to teach other units. However, the
building may place limits on the experience level of teachers.

\ability{model.ability.tradeWithForeignColonies}
\affectsPlayer

The player may trade goods in foreign colonies.

\ability{model.ability.undead}
\affectsUnit

The unit is an undead unit (used only in revenge mode).





\modifier{model.modifier.bombardBonus}
\affectsPlayer

The player's units are granted a bombard bonus when attacking.

\modifier{model.modifier.buildingPriceBonus}
\affectsPlayer

The player can build or buy buildings at a reduced price.

\modifier{model.modifier.defence}
\affectsUnit

The unit has a defence bonus or penalty.

\modifier{model.modifier.immigration}
\textit{Affects: Player\\Provided by: Goods Type}

Goods of this type contribute to the player's immigration points.

\modifier{model.modifier.landPaymentModifier}
\affectsPlayer

The player can buy Indian land at a reduced price.

\modifier{model.modifier.liberty}
\textit{Affects: Player\\Provided by: Goods Type}

Goods of this type contribute to the colony's and the owning player's
liberty points.

\modifier{model.modifier.lineOfSightBonus}
\affectsUnit

The unit has an increased line of sight.

\modifier{model.modifier.minimumColonySize}
\affectsColonyTwo

The population of the colony can not be voluntarily reduced below this
number. The modifier does not in any way affect a population reduction
due to starvation or other events.

\modifier{model.modifier.movementBonus}
\affectsUnit

The unit has an increased movement range.

\modifier{model.modifier.nativeAlarmModifier}
\affectsPlayer

The player generates less native alarm.

\modifier{model.modifier.nativeConvertBonus}
\affectsPlayer

The player has a greater chance of converting natives.

\modifier{model.modifier.nativeTreasureModifier}
\affectsPlayer

The player generates greater treasures when destroying native settlements.

\modifier{model.modifier.offence}
\affectsUnit

The unit has an offence bonus or penalty.

\modifier{model.modifier.religiousUnrestBonus}
\affectsPlayer

The player generates greater religious unrest in Europe.

\modifier{model.modifier.sailHighSeas}
\affectsUnit

The unit's travel time between Europe and the New World is reduced.

\modifier{model.modifier.tradeBonus}
\affectsPlayer

Prices in the player's market remain stable for longer.

\modifier{model.modifier.treasureTransportFee}
\affectsPlayer

The player pays a smaller fee for transporting treasures to Europe.

\modifier{model.modifier.warehouseStorage}
\affectsBuilding

The building increases the capacity of the warehouse.


\printindex

\end{document}