\documentclass[12pt]{book} \usepackage{version} \usepackage[T1]{fontenc} \usepackage{longtable} \usepackage{graphicx} \usepackage{index} \usepackage[colorlinks=true,hyperindex=true]{hyperref} \makeindex \begin{document} \author{\href{http://www.freecol.org/team-and-credits.html}{The FreeCol Team}} \title{FreeCol Documentation\\Developer Guide for Version \fcversion} \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''. (Note that if you add a game option, add a default value setting in FreeColServer.fixGameOptions so that use of the option does not break old games. The same applies to client-options, in ClientOptions.fixClientOptions.) 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/about.html}{about FreeCol} on the FreeCol website. \hypertarget{SourceForge project site}{\section{SourceForge project site}} You should visit and get familiar with our project site at \href{https://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 find tasks}{\section{How to find tasks}} While FreeCol has no working roadmap to the 1.0.0 release, you may find available tasks in the bug and feature request trackers --- just grab any task you are planning to work on in the immediate future by posting a comment stating you intend to work on the specified task or by simply assigning the ticket to yourself. Please create a new bug report/feature request for tasks that are not listed in a tracker (and before you start working on them). Please also 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 \href{https://sourceforge.net/p/freecol/mailman/freecol-developers/\#freecol-developers mailing list}{developer's mailing list} before they are implemented. This ensures that your work will not be in vain if somebody else knows a better method of complete the objective or needs to offer feedback so as to not break some other portion of the codebase. Please try to use the standard Sun Java coding style (link omitted, Oracle keeps moving it). We do not rigidly enforce it and tolerate minor variants, but it makes for a more browseable codebase if the style does not vary greatly. \hypertarget{How to use the trackers}{\section{How to use the trackers}} If you are a full developer (i.e. with write privileges), 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 \emph{not} been fixed, please set its status to ``Closed-Duplicate'', its milestone to ``Unspecified'', 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 ``Closed-out-of-date'' status to close the tracker item. \end{itemize} \item Set the item's status to ``Open-Needs-Info'' if you require input from the person originally submitting the item. \item Set the item's status to ``Open-WWC1D'' if the fix requires determining what Col1 did (``What Would Col1 Do?''). \item If you are unable to complete the item: assign it back to ``None'' and make a comment describing any problems relevant for another developer. The milestone of open bugs should be ``Current''. \item If you successfully commit a fix for a bug, set the milestone to ``Fixed-trunk'' and the status to some form of ``Closed'' if you are certain of the fix and the bug was introduced during the current development cycle, or ``Pending-Fixed'' if the bug was present in a release. The intent is that at release time all ``Fixed-Trunk'' bugs can be re-labelled as ``Fixed-\emph{release}''. Please also write a comment telling that the work is done, and it is helpful to refer to any commit/s where relevant changes occurred. \end{enumerate} This is how a feature request item should be updated while you are working:\emph{(Needs updating since the sourceforge migration)} \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" 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. \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) \href{http://lists.sourceforge.net/lists/listinfo/freecol-developers}{subscribe to this list}. \hypertarget{Git}{\section{Git}} Git 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 full copy of the project. Git supports synchronization between the central version of the code (`the repository') and the local copies. Git also makes it possible to undo changes that were previously committed to the repository. \href{http://www.freecol.org/documentation/git.html}{This page} describes how you can start using Git and get a working copy of the code (without commit privileges). You can use \verb+git pull+ for updating an existing working copy. Changes can only be applied by those who have write-access, so you may 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}} FreeCol uses the \textit{Apache Ant} build system for compiling the game. You can download a copy of Ant program from the \href{http://ant.apache.org}{Apache Software Foundation} website. After Ant has been installed, you simply type \verb+ant+ in the top directory of your FreeCol "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 running the following command: \verb+java -Xmx2G -jar FreeCol.jar+ Once Ant builds the JAR file, you can rebuild FreeCol as needed any time a modification to the code requires testing. Using Ant to create a new version of the FreeCol file simply requires another command of \verb+ant+. Only the files changed since the last compilation are rebuilt. This can lead to the occasional bug, so it is a good idea to run \verb+ant clean+ between all non-trivial builds. This starts the new build from scratch. \hypertarget{Using an IDE}{\section{Using an IDE}} Most FreeCol developers don't seem to use an IDE, so there is no ``official'' setup available. However, in the config folder, you can find contributed configuration files for both NetBeans and Eclipse. The following information has also been contributed by players that do use an IDE. The FreeCol gitignore file (a list of files and directories that are ignored by Git) includes support for the following IDEs: Eclipse, JetBrains, JDeveloper, and NetBeans. Certain Linux and Windows specific files are also ignored. \hypertarget{Using Eclipse}{\subsection{Using Eclipse (thanks to ``nobody'')}} \emph{This section is out of date since we migrated from svn to git. Leaving as-is for now in the hope the procedure is similar.} Since I'm quite a fan of the Eclipse IDE, I thought I would share my experience with building FreeCol in Eclipse on the Windows platform. I assume that you have installed JDK, Eclipse and Git (both Eclipse plug-in and stand alone client). Make sure that your path environment variable contains both the JDK and SVN client directories. First, add a new repository location in Eclipse in the SVN Repositories view, for the \href{https://svn.freecol.org/svnroot/freecol/freecol/}{FreeCol repository}. Leave all the other settings unchanged and click Finish. Select either 'trunk' or the branch you want to build, right-click on it and select 'Find/Check out as...' In the Check Out dialog, make sure the option 'Check out as a project configured using the New Project Wizard' is selected, and click Finish. Select 'Java Project' in the 'Java' category, and click Next. Name your project (FreeCol is an obvious choice). Leave all the other options as is, and click Finish. Eclipse starts to copy all the files from the repository. Depending on the server and your connection, this may take from 1-10 minutes. Get a cup of coffee or a glass of cold milk while you wait. After downloading has finished, you should see your new project in the Project Explorer. Right-click on the project and select 'Configure Build Path...' from the 'Build Path' sub-menu. First off, let's make sure that Eclipse has detected the source file folder 'src'. Select the 'Source' tab, and make sure there is an entry with the name [project name]/src. If not, add it. Don't close the window, as we need to make other changes here. Next, we have to add the external jar files to the project, so Eclipse can properly verify the code. Select the 'Libraries' tab, and click the 'Add JARs...' button. Browse to the 'jars' subfolder in the FreeCol project, and select all the jar-files by holding down the CTRL-key. Click OK, and OK again. Eclipse should now be able to properly build the project without any errors. If not, fix it. However, we don't actually want Eclipse to do this, since we instead want to use the Ant build file from the repository. Right-click on the project, and select 'Properties...' all the way at the bottom of the menu. Select 'Builders' in the menu to the left. You should now see one entry in the list, named 'Java Builder'. This is the default, built-in java builder in Eclipse. Click 'New...' to create our Ant builder instead. Select 'Ant Builder' from the list and click OK. In the configuration dialog, click the 'Browse Workspace...' button the 'Buildfile' section. Click on the FreeCol project, and select 'build.xml' from the list on the right. Click OK. Click OK again, and the Ant builder is created. You can keep both builders active at the same time, but if you want to save processing power, you can uncheck the 'Java Builder'. Eclipse will warn you about doing this, but don't be alarmed, you can always turn it on again. Click OK. If you have activated Automatic building in Eclipse, Ant should start building the project right away. Possible errors could be, that Ant cannot access either the java compiler or a stand-alone svn client. In either of these cases, make sure you added the right directories to your path environment variable. If the build went succesfull; congratulations. Open the project folder in the file system, and you will see 'FreeCol.jar' in the root folder. Since this is an executable jar file, you can double-click it and launch the game right away. Enjoy. \hypertarget{Using NetBeans}{\subsection{Using NetBeans (thanks to ``wintertime'')}} We have a NetBeans project with updated settings, but it is not at the standard location the IDE expects it at, as the IDE gets slower while a large project, like FreeCol, is open. You have the option of just clicking on ``build.xml'' in ``Files'' pane and starting the build commands easily through the ``Navigator'' pane inside the IDE that way. If you opt for using the provided project, it is recommended to use NetBeans 8.1 (or newer), because previous versions contained a bug in that it wont read or write the editor setting for the Java version, if it was correctly set to 1.8 (though it seems version 8.0.2 can read the project file after updating it with 8.1). Just copy the ``FreeCol/config/nbproject'' folder to ``FreeCol/nbproject'' once. Without this step it will not work! Open the project inside NetBeans once; it will remember this, as long as you do not close the project manually. \hypertarget{Creating a new NetBeans project}{\subsection{Creating a new NetBeans project (thanks to ``xsainnz'')}} \emph{This section is out of date and incomplete. Please, use the existing NetBeans project! Leaving as-is for now in the hope its still educational and updated someday.} \begin{itemize} \item In Netbeans, Select File > New Project \item New Project Window \begin{itemize} \item Select Java Category, Java Free-Form Project \end{itemize} \item Name and Location Panel \begin{itemize} \item In the Location box, browse to where ever you put the source (.../freecol/) \item It should auto detect the build file location, project name and folder \end{itemize} \item Build and Run Actions Panel \begin{itemize} \item Leave the settings as they are \end{itemize} \item Source Package Folders Panel \begin{itemize} \item Add the 'src' folder as Source packages and 'tests' as Test packages \end{itemize} \item Java Sources Panel \begin{itemize} \item Click 'Add JAR/Folder, \item browse into the jars folder \item select all of the jars \item click open. \end{itemize} \item Click Finish \end{itemize} \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/documentation/}{here}. \hypertarget{Code Quality}{\section{Code Quality}} The code you contribute to FreeCol 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://www.oracle.com/technetwork/java/codeconvtoc-136057.html}{Java Code Conventions}. This will only take about 15 minutes and will really help you write beautiful code. Please configure your editor or IDE that code indentations result in the insertion of 4 spaces. Avoid using tabs. \hypertarget{How to build a FreeCol release}{\chapter{How to make a FreeCol release}} You will need to have installed \texttt{ant} to do the build, and \texttt{git} to make the commits, however this will be normal for a developer. To generate the online manual you will also need \texttt{htlatex}, and \texttt{pdflatex} for the print manual. You can avoid these requirements by setting the ant properties \texttt{online.manual.is.up.to.date} and \texttt{print.manual.is.up.to.date} respectively, however this is not recommended for a release. Uploads to sourceforge use \texttt{sftp}. \begin{itemize} \item Make sure that all relevant changes have been committed to the branch you are about to release. If you plan to upload the manual and/or JavaDoc, regenerate it (with \verb+ant manual+ and \verb+ant javadoc+), and fix any JavaDoc errors. \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. \item Lately we release from the git master and continue to work from there, so there is no urgent need to create a special release branch. \item 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. You will be prompted for the version of this release. Alternatively, you can specify the version on the command line, by with something like: \verb+ant -Dfreecol.version=0.9.0-alpha2 dist+ instead (replace 0.9.0-alpha2 with the correct version, of course). It might be necessary to increase the memory available for ant, for example by setting the environment variable \verb|ANT_OPTS="-Xms256m -Xmx256m"|. Errors in language packs only apply to the installer and need not delay the overall release. \item Install one of the generated packages and verify that you can play normally for at least five turns (the java installer can be run from the command line with \texttt{java -cp freecol-\emph{version}-installer.jar com.izforge.izpack.installer.Installer}). 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 \verb+ant dist+ will change the \verb+FREECOL_VERSION+ constant in FreeCol.java and the \verb+fcversion+ macro in \texttt{doc/version.sty} to the release version. Commit these changes. \item Upload the packages to \verb+sftp://frs.sourceforge.net/+. A script \verb|bin/release.sh| is provided that does this job, including rebuilding and uploading the manual and JavaDoc. \item Write a release announcement (see previous versions for comparison). Include information on savegame compatibility with previous FreeCol versions on all messages. Recent practice is to keep the announcement brief but refer to a detailed \textbf{Release Notes} page on the sourceforge freecol wiki. \item The source for the \texttt{freecol.org} website lives in the git tree in the \texttt{www.freecol.org} top-level directory. To update the website, for now, you will need to add a new \texttt{www.freecol.org/\_posts/freecol-}\emph{version}\texttt{-released.html} file and edit the following files: \begin{description} \item[\texttt{www.freecol.org/download.html}] Update the release version number. \item[\texttt{www.freecol.org/sitemap.html}] Add a reference to the new release. \item[\texttt{www.freecol.org/status.html}] Update the release version number. \end{description} \item Change directory to the \texttt{www.freecol.org} subdirectory and build the website with Jekyll (\texttt{jekyll build}). This creates a new fully linked version of the website in the \texttt{\_site} subdirectory. \item Change directory to the \texttt{\_site} subdirectory and upload to \emph{username}\texttt{,freecol@web.sf.net} with \texttt{sftp}. The website lives in the \texttt{htdocs} subdirectory there. There is a script in \verb|bin/website.sh| script which uploads everything. \item Post the release announcement to: \begin{itemize} \item Our mailing lists: developers, translators and users. Beware that you may have to be subscribed to some lists to be able to post. The addresses are: \texttt{freecol-\{developers,translators,users\}@lists.sourceforge.net} \item The FreeCol \href{https://sourceforge.net/p/freecol/discussion/141200/}{forum}. \item The project \href{https://sourceforge.net/p/freecol/news/}{news} page on sourceforge. \end{itemize} \item Consider revising the preamble to the ``Bugs'' page, particularly the ``Known Common Problems'' section. Go to ``Tickets / Admin-Bugs / Options'' to make changes. \item Go to the bug tracker and create a new milestone (``Edit Milestones'') called ``Fixed\_\emph{release}'' (e.g. ``Fixed\_0.10.2''). Select the ``Fixed\_trunk'' group and do a mass edit (the pencil icon in the top right of the bug tracker list) and move all bugs to the new milestone. Repeat for the ``Pending\_Fixed'' group setting them to ``Closed\_Fixed''. \item Start a new wiki page for the release notes for the next release. \end{itemize} \hypertarget{Missing features}{\chapter{Missing features}} We know that FreeCol does not yet emulate all features of the original game. However there are several features which are inevitably different to Colonization due to FreeCol being a multiplayer game --- interactions with other European players being the obvious example. Similarly we do not attempt to exactly emulate the graphical look and feel of Colonization, although no displayed information should be lost. Otherwise, any missing feature from Colonization is considered to be a bug. Please report such omissions on the \href{https://sourceforge.net/p/freecol/pending-features-for-freecol/}{pending features} tracker. FreeCol developers do not have access to the source code of the original Colonization game, so some assumptions are made as to how to implement certain features. This is particularly true in complex, detailed areas such as production and combat. 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 notify the developer mailing list. There is an effort underway to completely document Colonization's production amounts \href{https://sourceforge.net/p/freecol/wiki/WWC1D\%20-\%20resource\%20output\%20v2/}{here}. \hypertarget{Changing the Rules}{\chapter{Changing the Rules}} FreeCol is designed with end-user configuration in mind, so that the game engine can emulate the other similiar games. For this purpose, the developers provide number of configuration options for many of the game's features. At some point in the future, we will probably add a special rule set editor, but at the moment, the most effective 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. Try to avoid overriding the base Colonization-compatible rules in \textit{data/classic}. For a small self-contained rule change, another option is to build a \emph{mod} --- see the Mods section following. 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 flavor 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 usually 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}} TODO: This section is out of date (version 0.11.2). \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. \hypertarget{Mods}{\chapter{Mods}} FreeCol packages a number of simple modifications to the FreeCol rules and resources, generally known as \emph{mods}. The standard mods live in \texttt{.../data/mods}. Users can add their own mods to a \texttt{mods} directory under their main data directory. A mod consists of a directory that includes at minimum a file \texttt{mod.xml}, a file \texttt{FreeColMessages.properties}, and other files that implement the required changes. \texttt{mod.xml} simply contains: \texttt{} where the identifier is some unique name (distinct from other existing mods). The \texttt{FreeColMessages.properties} file should contain at minimum entries for \texttt{mod.}\emph{identifier}\texttt{.name} and \texttt{mod.}\emph{identifier}\texttt{.shortDescription}, so that the mod selection dialog can display the mod correctly. Other messages needed by the mod belong in \texttt{ModMessages.properties}. The difference between these is that \texttt{FreeColMessages.properties} is always loaded so that the mod name and description can appear in the mod selection dialog, but \texttt{ModMessages.properties} is only loaded if the mod is selected. Many mods define extra resources. If so, a \texttt{resources.properties} file will be needed, and similarly files for the resources involved. For example, the ``example'' mod defines a ``milkmaid'' unit, which needs an image, so the example mod directory contains an image file for the milkmaid, and a reference to this file in \texttt{resources.properties}. Most mods change the specification. This is done in a \texttt{specification.xml} file. This file is in the same general format as the existing freecol rule sets, but does not attempt to provide a comprehensive set. The first non-comment line should be: \texttt{}. Note that mods typically do not specify which ruleset they extend. When modifying a specification, expect additional elements you provide to be applied additively, but attributes of an existing element are cleared unless a special \texttt{preserve="true"} attribute is present. If you need to delete or redefine an element, respecify it in context with just its \texttt{id} and \texttt{delete="true"} attributes. So for example, in the freecol ruleset we need to remove the \texttt{model.modifier.minimumColonySize} modifier from the stockade building, which is done as follows: \begin{verbatim} \end{verbatim} Note that not all elements take a \texttt{delete} tag yet. You may need to read or modify the source to be certain a mod will work. \hypertarget{Resources}{\chapter{Resources}} Various links pointing to more or less reliable information about the original Colonization game: \begin{itemize} \item \href{http://strategywiki.org/wiki/Sid_Meier%27s_Colonization} {Strategy Wiki} \item \href{http://www.colonization.biz/}{The Unofficial Microprose Colonization Home Page} \item \href{http://dledgard0.tripod.com/FAQs/play_col_at_viceroy.htm} {Play Colonization at Viceroy level} \item \href{http://www.colonizationfans.com/}{Colonization Fan Page} \item \href{http://www.ibiblio.org/GameBytes/issue21/misc/colstrat.html} {Bill Cranston's Strategy guide} \item \href{http://civilization.wikia.com/wiki/Colonization_tips} {Tomasz Wegrzanowski' Strategy Guide}, contains very valuable material on the number of bells required to elect a Founding Father, among other things \end{itemize} \hypertarget{Map Format}{\chapter{Map Format}} A map file, as found in \texttt{.../data/maps}, is a cut-down version of a normal freecol save file. Map files should have the \texttt{.fsm} (``FreeCol Saved Map'') extension, as distinct from \texttt{.fsg} (``FreeCol Saved Game''). Saved maps and games are both actually just standard Java archives, as operated on by the \texttt{jar(1)} utility. Saved maps should contain the following files: \begin{itemize} \item \texttt{savegame.properties}, a standard Java properties file containing the map.height and map.width properties. \item \texttt{thumbnail.jpg}, a high level picture of the map, as used in the map selection dialog \item \texttt{savegame.xml}, the XML representation of a FreeCol game, but with the following skeleton: \begin{itemize} \item \texttt{} header \item \texttt{savedGame} \begin{itemize} \item \texttt{game} \begin{itemize} \item \texttt{cibola} (seven entries) \item \texttt{nationOptions} (native \texttt{nationOption}s only) \item \texttt{player} (native players only) \item \texttt{map} \end{itemize} \end{itemize} \end{itemize} \end{itemize} \printindex \end{document}