2009-12-31 12:41:00 +01:00
|
|
|
\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
|
|
|
|
|
2010-01-10 13:49:48 +01:00
|
|
|
|
|
|
|
\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}}
|
|
|
|
|
2010-03-15 11:39:25 +01:00
|
|
|
We use the \textit{Apache Ant} build system for compiling the
|
2010-01-10 13:49:48 +01:00
|
|
|
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
|
2010-03-07 13:58:17 +01:00
|
|
|
branch you are about to release.
|
2010-01-10 13:49:48 +01:00
|
|
|
|
2010-08-08 15:52:43 +02:00
|
|
|
\item Merge translations from trunk if the release is not made from
|
|
|
|
trunk, with \verb+ant merge-translations+. Skip this step if the
|
|
|
|
localization files are essentially the same as the ones in trunk (we
|
|
|
|
try to ensure this). Make sure they are up to date, however.
|
|
|
|
|
2010-01-10 13:49:48 +01:00
|
|
|
\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.
|
|
|
|
|
2010-03-07 13:58:17 +01:00
|
|
|
\item Change the \verb$FREECOL_VERSION$ constant in FreeCol.java to
|
|
|
|
match the release version 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+.
|
2010-01-10 13:49:48 +01:00
|
|
|
|
2010-01-10 14:16:58 +01:00
|
|
|
\item Call \verb+ant dist+ in order to build all packages. It might be
|
2010-01-10 13:49:48 +01:00
|
|
|
necessary to increase the memory available for ant, for example by
|
2010-01-10 14:16:58 +01:00
|
|
|
setting the environment variable \verb+ANT_OPTS="-Xms256m -Xmx256m"+.
|
2010-10-04 14:32:24 +02:00
|
|
|
Errors in language packs only apply to the installer and need not
|
|
|
|
delay the overall release.
|
2010-01-10 13:49:48 +01:00
|
|
|
|
|
|
|
\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}
|
2010-08-08 15:52:43 +02:00
|
|
|
#!/bin/sh
|
|
|
|
|
|
|
|
FREECOL_VERSION=0.9.0-alpha2
|
|
|
|
PREFIX=freecol-$FREECOL_VERSION
|
|
|
|
USERNAME=myUserName
|
|
|
|
|
|
|
|
cd dist
|
|
|
|
|
|
|
|
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
|
2010-01-10 13:49:48 +01:00
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\item Compile the feature list for the news announcement (use the tracker
|
|
|
|
and/or run the previous version for comparison).
|
|
|
|
|
2010-10-04 14:32:24 +02:00
|
|
|
\item Update the release number in the "Version"-mambot at
|
|
|
|
http://www.freecol.org/administrator > Mambots > Site Mambots > Version.
|
2010-01-10 13:49:48 +01:00
|
|
|
|
2010-01-10 14:33:48 +01:00
|
|
|
\item Publish/unpublish "Download Unstable Version" in the main menu
|
|
|
|
(this page should only be displayed if the unstable version is the
|
|
|
|
latest release).
|
2010-01-10 13:49:48 +01:00
|
|
|
|
2010-03-07 13:58:17 +01:00
|
|
|
\item Add a news item to our website, including a download button.
|
2010-01-10 13:49:48 +01:00
|
|
|
|
|
|
|
\item Remove the download button from the previous release news item.
|
|
|
|
|
2010-03-07 13:58:17 +01:00
|
|
|
\item Post release messages on our mailing lists: developers,
|
|
|
|
translators and users. The addresses are:
|
|
|
|
|
|
|
|
\verb+freecol-{developers,translators,users}@lists.sourceforge.net+
|
|
|
|
|
|
|
|
Include information on savegame compatibility with previous versions
|
|
|
|
on all messages. Beware that you may have to be subscribed to some
|
|
|
|
lists to be able to post.
|
2010-03-03 20:21:40 +01:00
|
|
|
|
2010-03-07 13:58:17 +01:00
|
|
|
\item Post a release message to the FreeCol forum. 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.
|
2010-03-03 20:21:40 +01:00
|
|
|
|
2010-01-10 13:49:48 +01:00
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
The following items can be omitted for unstable releases:
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
|
2010-10-04 14:32:24 +02:00
|
|
|
\item Rename the bug tracking group "Fixed (major.minor.x-branch)"/
|
|
|
|
"Fixed (Trunk)" to Fixed (FreeCol major.minor.number) and create a
|
|
|
|
replacement group "Fixed (major.minor.x)".
|
|
|
|
|
|
|
|
\item Rename the feature tracking group "Added (Trunk)"/"Added
|
|
|
|
(major.minor.x-branch)" to Added (FreeCol major.minor.number) and
|
|
|
|
create a replacement group "Added (major.minor.x)".
|
|
|
|
|
|
|
|
\item 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".
|
2010-01-10 13:49:48 +01:00
|
|
|
|
2010-03-09 12:22:05 +01:00
|
|
|
\item Regenerate the documentation (with \verb+ant manual+) and
|
|
|
|
JavaDoc (with \verb+ant javadoc+) and update JavaDoc and User
|
|
|
|
Documentation on \href{freecol.org}{freecol.org}. You can do that
|
|
|
|
with a script like this:
|
2010-01-10 14:33:48 +01:00
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
#!/bin/sh
|
|
|
|
|
|
|
|
USERNAME=myUserName
|
|
|
|
|
2010-03-07 13:58:17 +01:00
|
|
|
cd doc
|
2010-01-10 14:33:48 +01:00
|
|
|
|
|
|
|
{
|
|
|
|
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}
|
|
|
|
|
2010-03-09 12:22:05 +01:00
|
|
|
Note that generating FreeCol.html requires \verb+htlatex+
|
|
|
|
to be installed.
|
2010-01-10 14:33:48 +01:00
|
|
|
|
2010-01-10 13:49:48 +01:00
|
|
|
|
|
|
|
\end{itemize}
|
|
|
|
|
|
|
|
The following items should be omitted for unstable releases:
|
|
|
|
|
|
|
|
\begin{itemize}
|
|
|
|
|
2010-01-10 14:16:58 +01:00
|
|
|
\item Update the links to "Added (x.y.z-branch)" and "Fixed
|
|
|
|
(x.y.z-branch)" on the roadmap (and release status etc).
|
2010-01-10 13:49:48 +01:00
|
|
|
|
2010-03-08 00:23:42 +01:00
|
|
|
\item Post a news item on the FreeCol project news page on sourceforge
|
|
|
|
(at \verb+https://sourceforge.net/news/?group_id=43225+).
|
2010-01-10 13:49:48 +01:00
|
|
|
|
|
|
|
\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}
|
|
|
|
|
|
|
|
|
|
|
|
|
2009-12-31 12:41:00 +01:00
|
|
|
\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}
|