Creating variants for the Diplomacy judge

v 0.33 Christophe Courtois (christophe@courtois.cc) & Millis Miller (millis@faztek.org)

This documentation is not finished and may contain many errors.


1 Introduction
1.1 History
1.2 Last version
1.3 Why?
2 What you can and must do
2.1 Possibilities
2.3. Variant options
3 Data to provide
3.1. Map files
3.1.1 Declaration of lands and centers
3.1.2 Movements
3.1.3 ordering for summaries (optional)
3.1.4 Other optional data
3.2 Seed file
3.2.1 Seed file format
3.2.2 When units do not begin on home centers
3.2.3 Special seed files (seed_b, seed_w...)
3.2.4 In the code
3.3 Info files
3.4 Variant.h


4 Examples
4.1 H32 (Hundred) Wings
4.2 Fleet in Marseille
4.3 Switzerland
4.4 Chess
5 floc.net
6 Mapmaker
7 Addmap
8 Automatic tests
9 Troubleshooting
10 Integration in the official judge source
11 Moving variants between judges
12 Misc
12.1 The author
12.2 Thanks
12.3 Copyright and boring stuff


1 Introduction

1.1 History

1.2 Last version

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/.

1.3 Why?

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.

2 What you can and must do

2.1 Possibilities

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:

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.

2.3. Variant options

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.

3 Data to provide

(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:

You MUST modify theses files in the source code of the judge:

And you MAY provide these files, but the judge will work without them. They will be necessary for the players though.

There are some additional files to modify to package a new variant into the official judge, see later.

3.1. Map files

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.

3.1.1 Declaration of lands and centers

Switzerland,
(Neutral land)

l swi switz swiss
(Accepted order abbreviations)

Adriatic Sea,
(Sea)

w adr adriatic

Ankara,
(Home center of T)

T ank ankar

Belgium,
(Neutral land center but allowing convoys)

xw bel belgi

3.1.2 Movements

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:
(Switzerland, no possible move)

swi
 

adr-xc:
(Between a coast and its neighbours)

alb apu ven tri ion
 

bud-mv:
(Between a land and its neighbours)

vie gal rum ser tri
 

con-mv:
con-xc:

(Province with land movement and sea movement)

bul ank smy
bul/sc bul/ec bla ank smy aeg

 

3.1.3 ordering for summaries (optional)

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

3.1.4 Other optional data

Hong Kong flag, railways, and so on, are described in njudgemapdatahowto.htm. For a good example, see map.colonial.

3.2 Seed file

3.2.1 Seed file format

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.

3.2.2 When units do not begin on home centers

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.

3.2.3 Special seed files (seed_b, seed_w...)

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...

3.2.4 In the code

The part of the code responsible for opening the seed file is ml_signon.c.

3.3 Info files

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.

3.4 Variant.c and variant.h

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.

3.4.1 Variant.c: Variants array

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.

3.4.2 Variant.c: VValue array

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>.

3.4.3 Variant.c: Powers array

If you add any power name, add it at the end of the array powers.

3.4.4 Variant.c: Owners array

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!

3.4.5 Variant.c: pletter array

The pletter contains the abbreviations (F for France, 9 for Warsaw in a chaos...) for the powers in your variant. You must add a new line for your variant, defining which power letters will be used. The position of these power letters correspond to the position of the descriptive names in the powers and onwers arrays, defined above. Powers that are not played in this variant are represented by the 'x'.
If new power(s) were added, ALL lines of all variants must be extended to have the same number of letters.

3.4.6 Variant.c: Sphase array

- 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.

3.4.7 Variant.h: Variants array

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.

3.4.8 Variant.h: magic numbers

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 */

3.4.9 WILD_PLAYER

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.

3.4.10 Variant.h: SETNP macro and default modifiers

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.

3.4.11 starter.flist

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.

4 Examples

4.1 H32 (Hundred) Wings

4.1.1 Setup

(** 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:

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

4.1.2 Test

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.

4.2 Test variant

4.2.1 Setup

(** 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.

4.2.2 Installation

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

4.2.3 Test

Create the game:

create ?foobar password mytest
set players 1

4.3 Switzerland

Let's imagine that Switzerland is a territory like any other one.

TODO

4.4 Chess

TODO (Done already on FREE) ?

5 floc.net

6 Mapmaker

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...

7 Addmap

8 Automatic tests

None known. David Norman may have some.

9 Troubleshooting

These are some problems and solutions:

*

*

10 Integration in the official judge source

CVS, Makefile.am

11 Moving variants between judges

Numbers ???,

12 Misc

12.1 The author

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...)

12.2 Thanks

Many parts of this HowTo are cut-and-pasted from source code and mails of the judge-maint mailing list.

12.3 Copyright and boring stuff

Permission is granted to make and distribute copies of this text provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the derived work is distributed under the terms of a permission notice identical to this one. Translations fall under the category of "modified versions".
Warranty: None. Nothing. Nada. Rien. Que dalle. Nitchevo. Nichts. Do everything at your own risk. Remember this is a sum-up of a non-native English speaker on a subject he recently discovered.
Redistribution is allowed and encouraged; however, it is strongly recommended that the redistributor contact the author before the redistribution, in the interest of keeping things up-to-date (you could send me a copy of the thing you're making while you're at it).
Translators are also advised to contact the author before translating (no translation known for the moment).