0.2 : Mar-Apr 2003
0.31 : July 2003 First updates
0.32 : 23rd July 2003 Updated and spelling corrections (Millis Miller)
0.33 : 27th July 2003 Update of the updates
This is a guide which aims to help people creating variants for
the Diplomacy judge.
The reference version is the HTML version.
The text should be automatically generated against the HTML.
Anyway,
the last version of this file should always be in the last CVS
snapshot of the judge at http://www.njudge.org/.
There seems to lack documentation on how to make a variant. David Norman provides some useful help but I think that many things shoudn't need to go through him now that everyone can have a judge at home.
I'll try to sum up here most knowledge on variants creation, beginning by the basic ones, made from existing maps. I won't cover variants with new rules not yet implemented in the judge.
All this was tested on a njudge v. 1.4.1 from June 2003.
Trivial "almost-variants" without recompilation needed are:
Easy variants covered here are:
A bit more difficult, which will lead you to use MapMaker and perhaps contacting David Norman:
Variants with totally new and complex maps
You'll have to understand the code of the judge yourself for changing any rule...
And creating the map files and pictures if currently out of subject.
There are variants based on maps, like standard, modern, h32... , and there are the variant options or modifiers: Wings, Gunboat, Blind, Shorthand. See the info file for each of them, but basically Shorthand and Gunboat only affect press, while Blind and Wings may have impact on map files.
(Warning: Some file names changed with judge 1.4; many old judges will use numbers instead of variant name as an extension).
For a complete new variant, you MUST provide this:
Report file : this file is sent at
game start, giving the initial positions.
Example: data/report.loeb9
You MUST modify theses files in the source code of the judge:
variant.c
And you MAY provide these files, but the judge will work without them. They will be necessary for the players though.
Rules file: Only if you create a
whole new game.
Example: data/rules.machiavelli
There are some additional files to modify to package a new variant into the official judge, see later.
A map file is in the data/ subdirectory. The name is map.<variant_name>.
The format is fully described by a document from Sergio Lidsell that is part of the judge package: njudgemapdatahowto.htm. Following are just examples from the standard map to sum it up.
|
Switzerland, |
l swi switz swiss |
|
Adriatic Sea, |
w adr adriatic |
|
Ankara, |
T ank ankar |
|
Belgium, |
xw bel belgi |
A line must be created for each movement type allowed for a province, land routes (mv) and sea routes (xc). If a province has only one specified, it is not reachable by the other (i.e. A land-locked province such as Munich only has a land route specified).
Fleets use sea-routes (which also specify allowed coasts if relevant) and all non-fleet units use land routes.
|
swi-mv: |
swi |
|
adr-xc: |
alb apu ven tri ion |
|
bud-mv: |
vie gal rum ser tri |
|
con-mv: |
bul ank smy |
This specifies how centres are groups in the summary report ('summary <gamename>'). They can be in any arbitrary order desired, thoguh it is normal to group them by home-owner and geographical proximity to aid legibility.
Center order for summary report:
ven
rom nap tun edi lon lvp bre par mar por spa bel hol mun kie ber
den swe nor stp war mos sev con ank smy bul rum gre
ser bud vie tri
#End of center ordering
Hong Kong flag, railways, and so on, are described in njudgemapdatahowto.htm. For a good example, see map.colonial.
The seed file is in the data/ subdirectory. The name is seed.<variant_name>.
The first line contains the first game
season. This is a redundancy with what is in variant.c, but
both sources must give the same value. If the seed file and
variant.c don't match on the start season, the judge will
crash at the first resolution of orders. (Even if the test disappears
some day, the file format probably won't change to preserve variant
files compatibility with obsolete old judges).
Then
follow the positions of the units at the start of the game for each
power, and the centers that each player possess at the beginning. On
the standard map you obtain (file seed.standard):
S1901M
A: A Budapest
A: A
Vienna
A: F Trieste
E: A Liverpool
E: F Edinburgh
...
T: F Ankara
-1 Null ownership/contested record will
initialize from the map data.
-1
The last line indicates the start position of each power. In the standard game and most variants, it is not given, and the home centers are the one occupied by units.
Another example is the seed for the Chaos variant (seed.chaos) :
F1900B
-1
....A....BC..DEF..GH.I....J...K..LN.PQ.RST...U.V..W.X.YZ0..1234.56....78.9..
-1
There is no units at the beginning. Each character is a territory. Each dot is one without an owner, and letters and numbers indicate the power who possess the center at the beginning. There is no list of units ready to begin, and the first season is a build phase, so the players must begin by building a unit.
For the last version of the Hundred variant, called h32 (seed.h32) we have:
S1425M
B: A Dijon
B: A
Flanders
B: A Luxembourg
B: F Holland
E: A Calais
E:
A Guyenne
E: A Normandy
E: F English Channel
E: F London
F: A Dauphine
F: A Orleanais
F: A Paris
F: A Toulouse
F: A Provence
-1
........E...FEB.B.EB..E.B..E..FF.......F.
-1
In this seed, France begins with 5 units on the board, but possess only 4 centers, and will have to gain a center in the first year to avoid to disband a unit.
There are special seed files for the special variants options (wings, gunboat...). For example, a variant with the wings option can have a seed file ending by _w. If such a file does not exist, the standard seed file is used, and the game begins without any wing units on the board. The only seed file with such a property currently in the source tree is seed_w.modern, the wings version of the Modern variant. It is the same file as seed.modern, except that some units at the beginning are wings (see info.wings):
B: W London
F: W Bordeaux
There is no example of a seed_b or seed_bw file, although all is in place in the judge code to use it (it may be removed in the future). There is in any case little point in having special seed files for Blind variants...
The part of the code responsible for opening the seed file is ml_signon.c.
The info.<variant> contains all informations on your variant: differences against the standard map, new units or territory, special territories, starting positions and home centers, default variant modifiers (wings...), supply centers and how many must be won, who made the variant... See other info files as example.
They are used as reference files for the players, providing information about the variant, and are retrieved with the judge command 'get info.<variant>'. The judge itself doesn't need them.
These two files are part of the source code of the judge. Any modification implies that that judge must be recompiled. Here follows all possible modifications in these files, in the order where you'll meet them in the code.
In variant.c, search char *variants[]: this array contains the user names of the variants. You must add yours at the end, BEFORE the name of the variant modifiers. Don't forget the comma.
Just after that, you must define a define for the variant (used later in variant.h). Any name is permitted, though by convention it is of the form V_<variant-name>.
If you add any power name, add it at the end of the array powers.
If you have add any power, add the possessive form in the array owners, in the same order.
Note: the sizes of both powers and owners array must match, otherwise you will get unexpected names used!
- The sphase array contains the start season of the variant. It must be the same one as in the seed file that you have created.
In variant.h, in the first enum field, you must add a new V_ line. If you didn't count it before, this array's comments contain each variant number, that will be used as the variant number in the dip.master file.
You may have to update these 'magic
numbers' if you really have to, especially the second one if you find
something more insane than a chaos (and you'll have to find yourself
if lowercase letters are OK for power names...):
/** UPDATE
DEFINES AS NECESSARY BELOW **/
#define NVAROPTS 4 /* Number of
variant options (blind/gunboat/shorthand/a/f) */
#define
MAX_POWERS 36 /* Max. powers in a single game (letters+digits) */
#define LPOWER 24 /* Length of the longest power name */
If you have added new powers, you MUST increment this define accordingly by the number of powers added. The subsequent defines should be values after this (in njudge 1.4.1 onwards, this is automatic). Failure to do this will commonly result in the Master being called another name.
The macro SETNP contains the default behaviour of your variant: number of players, victory points. You must add a line for yours too.
The line for the standard (7 players by default, 18 centers to win) is:
case V_STANDARD: dipent.np = 7; dipent.vp = 18; break; \
Many variant modifiers can be added as the default setup of the variant. Most can be overriden at game creation by a SET commande. These many modifiers are defined in the file dip.h. Some well known are:
Other more or less useful modifiers are: XF_MANUALPROC, XF_NOMINORPRESS, XF_AUTODISBAND, XF_ANYDISBAND...
Don't forget the \ at the end of the line.
This file lists almost all files from
data/. You shoul add there your info, seed, report
files, as it is used as a reference for players.
(** FIXME : This part must ber updated with
variant names as extensions **)
H32 (Hundred Years War) with wings seems
at first sight stupid, but I think the game would be changed by it.
We need for this the seed_w file to place the first wings,
and the report_w file to let it know to the players. We need
just to copy the seed.22 and report.22 as seed_w.22
and report_w.22, and modifying them for example this way:
report_w.22:
Starting position for Spring of 1425.
Burgundy:Army Dijon.
Burgundy:Wing Flanders.
...
France: Wing Toulouse.
France: Army (unpaid and angry) Provence.
Add seed_w.22 and report_w.22 to starter.flist in the source file directory.
For this small variant, you don't need anything more. You can test it immediately:
create ?testh32w password h32 wings
set players 1
Create a new game by sending to the judge:
create ?test password h32 wings
set
players 1
And as Burgundy, you'll be able to send your planes from Flanders directly to London.
(** FIXME : This part must ber updated with
variant names as extensions **)
This variant is called Mytest and aims
to be almost the same as the standard.
- See in variant.h what is the biggest variant number. It is 34 (colonial96) for my 1.3.2-pre judge, so it will be variant number 35. Create seed.35 and report.35 by copying seed.1 and report.1. Adjust this value if you have another judge with more or less variants.
- Create the info.mytest file.
- Add the following lines in the variants array of variant.c:
"colonial96", /* Colonial
1996 Diplomacy */
"mytest", /* Test !!!! */
/**
ADD NEW VARIANTS ABOVE THIS LINE! **/
- In the vvalue array:
V_colonial96, /* 34 Colonial 1996
variant */
V_mytest, /* 35 Test */
/** ADD NEW
VARIANTS ABOVE THIS LINE! **/
- The powers and owners don't change.
- Add a line similar to the one of the standard variant to the pletter array:
".xxBxxCxxxxFxxxxxxJxxxxxxxRxxxTxxHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?xOM",
/* Colonial 1996 Diplomacy */
".AxxxxxxxExFGxxxxIxxxxxxxxRxxxTxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?xOM",
/* MyTest variant */
/** ADD NEW VARIANTS ABOVE THIS LINE!
**/
- The start season in sphase must be the same as in the seed file:
"S1870M", /* Colonial 1996
Diplomacy */
"S1901M", /* My test */
/** ADD
NEW VARIANTS ABOVE THIS LINE! **/
- In variant.h, expand the enum this way:
V_colonial96, /* 34 Colonial 1996
Diplomacy */
V_mytest, /* 35 my test */
/** ADD NEW
VARIANTS ABOVE THIS LINE! **/
NVARIANT /* Last variant + 1 */
- In the SETNP macro, add this line (here we'll have 7 players, 10 victory points only; disband is allowad at any turn, and a retreat leads automatically to a disband):
case V_mytest: dipent.np = 7; dipent.vp = 10; dipent.xflags |= XF_ANYDISBAND ; dipent.xflags |=XF_AUTODISBAND ;break; \
- It's over for the code modification.
You should read the upgrade documentation (for example my Installation guide) to avoid losing your specific configuration and some mail of you have an active judge. Basically, you have to do this:
**** FIXME ***** A VALIDER !!!!!! (histoire avec num de vrsion)
- The quick and dirty way is to modify directly the Makefile (change the VERSION variable from it standard version to 1.3.2+custom variants for example), and install info.mytest, seed.35 and report.35 into the data/ directory of your current running judge.
- The Right Way, compulsory if you have are coming from a fresh tarball, is to :
- change the version number in
configure.ac (see README.hackers for details):
AC_INIT("njudge", 1.3.2.020030413+variants) ;
or change the Makefile after lauching
- add your variant files to the starter.flist.
- You must get the smail.in and defaults.inc.in from your old judge source if they are not standard.
- Then compile and upgrade. On my system it means:
./configure
--with-dir=/home/alex/dip --with-user=alex
--with-domain=christophecourtois.org
make all
make upgrade
Create the game:
create ?foobar password mytest
set
players 1
Let's imagine that Switzerland is a
territory like any other one.
TODO
DN : There are a number of files you need - a map, a report, a seed and an info file, plus you have to update the variant.h (and variant.c in the newer versions of the judge). It can be done without MapMaker. But by using MapMaker : (1) It takes a fraction of the time (2) You get Mapper, Mapit and a PS map too (3) You get floc.net support And also, you get my experience of getting a variant through draft versions without confusing the various systems that run around the judges...
None known. David Norman may have some.
These are some problems and solutions:
|
* |
* |
CVS, Makefile.am
Numbers ???,
The author is 28 years old, writes SQL all day long for big corporations to eat and pay the mortgage, and is trying to learn Java, C and PHP (The most difficult part is to find some time for it...)
Many parts of this HowTo are cut-and-pasted from source code and mails of the judge-maint mailing list.