-
Notifications
You must be signed in to change notification settings - Fork 6
/
developer.tex
1075 lines (776 loc) · 38.3 KB
/
developer.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\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:
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 -Xmx256M -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 \texttt{freecol.org} website is in transition to a new
format, and the master copy 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/news/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/index.html}] Add a reference to the
new release.
\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.
\item[\texttt{www.freecol.org/news/index.html}] Add a section for
the new release containing the release announcement, and move the
download button from the previous release to the new one.
\item[\texttt{www.freecol.org/news/releases.html}] Copy in the same
section from the previous file, these two are nearly identical.
\end{description}
Use \texttt{sftp} to log in at
\emph{username}\texttt{,[email protected]} to upload changes (the
website lives in the \texttt{htdocs} subdirectory), or use the
\verb|bin/website.sh| script which uploads everything that has
changed in the git website directory.
\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 ``Admin /
Tools / 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. Do the corresponding action in other
ticket categories that have distinct release milestones.
\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