How to create a map file for the Diplomacy Judge

Version 1.7.1, Aug 10th 2004, by Sergio Lidsell

Introduction

The current version of this document includes all (bar any errors) options supported by nJudge software version 1.7.x.

Why do I need this ?

This "how-to" is meant to help Diplomacy and Machiavelli players create a correct map and seed file for variants they create for the Diplomacy Judge (nJudge).  I wrote this because I got frustrated of not being able to find any concise and correct documentation on how to do this.  The latest version of this file should always be in the njudge CVS repository at www.njudge.org.

To submit a new variant for play/playtesting you contact the judge-keeper and send him a map-file and a seed-file. You should also submit an info-file and a report-file.

See also Christophe Courtois documentation for judge-keepers on how to create and add a new variant to the nJudge.

What is a map-file

The map file ('map.<variant name>') is used to define the area characteristics for the variant in a format that the nJudge software can read. Such as home country definition, official name and abbreviations, whether it is land or sea and much more. For Machiavelli you also define incomes and disasters.

What is the seed-file

The seed-file ('seed.<variant_name>') defines in what areas any units are present and the current area ownerships, as those may differ from the home countries even at start. It has been separated from the map file as the same map file may be used for different start setups.

The seed file structure is in short:
<season><start year><phase>
<power letter><:|m>' '<unit letter>' '<full province name or abbreviation as defined in the map file>
-1
<supply center and ownership* and other data at game start in map file area order>
-1

Where ' ' = space character and text within <> is to be replaced by the data. The <> are not part of the file format. [] is optional. See Appendix 2 for some seed file samples.
*The so called null ownership/contested record.

What is the report-file

The report-file ('report.<variant name>') is a text file with information sent to the players at game start. Usually it contains information about the starting positions of the units. It is not necessary to make the variant work.

What is the info-file

The info-file ('info.<variant name>') is a text file with information about the variant/scenario for the players. It is strongly recommended that you make such a file available to the players.

Structure of the map file

The map file must be named 'map.<variant_name>' (without the quotes of course).

The map data file is divided in three main parts, each of which is terminated by a line containing only '-1' (without the quotes). Comments may precede each block. Comments must begin with a '#'. The main parts are:

1. The area definition section (here you list province and sea area data)
2. The possible moves definition section (i.e. how you move to and from an area)
3. Definition of additional options (see below)

Example 1: Map file structure.
    # My comments go here
    Provincename, x pro prov
    -1
    #More comments
    pro-mv: aaa bbb ccc
    -1
    #Comments yet once more
   <Description of additional option x>
   option x data
   #end <text>
   <Description of additional option y>
   option y data
   #end <text>
    -1

Structure of the Diplomacy map data file with all sections

1. The area definition section
2. The possible moves definition section
3. Summary report SC list definition section
4. Definition of SC restrictions ("Hong-Kong" provinces) section
5. Definition of movement control/gateways section
6. Definition of railway provinces section

Structure of the Machiavelli map data file with all sections

1. The area definition section
2. The possible moves definition section
3. Famine table section
4. Plague table section
5. Variable income list section
6. Summary report SC (i.e. city) list definition section
7. Summary report province control list definition section
8. Storms table section (optional)
9. Unit limits section (used with machiavelli 2 rules, ignored in play with classic machiavelli rules)

Tech note: the differences between the Machiavelli and Diplomacy map files is due to the fact that the nJudge code for Machiavelli and Diplomacy originally was developed separately.

The area definition section

By area all types of provinces and sea areas are intended. The list must contain all valid and unique area names for your scenario. If players use any names not in this list they will raise an error in the judge. You must also specify of what type the province is and at least one unique abbreviation. Any errors in this list will cause the map file to be rejected.

You can only specify one unique area name and abbreviation per line. The data format is:

Field order for Diplomacy games:
<Full area name>','' '<area type>[<convoyability>]' '<list of all valid and unique abbreviations>

Field order for Machiavelli games:
<Full area name>','' '<area type><city income><city type>[<Venice flag>]' '<list of all valid and unique abbreviations>

Quotes and circumflexes are not part of the format. Empty single quotes, ' ', indicate a space character. Note that you can have any number of spaces after the comma, but *one only* after the area type letter.  Data within square brackets, [], is optional.

Abbreviations must be separated by one space. A minimum of three letters is recommended, even if the judge accepts two letter combinations. One letter combinations are not allowed.

The full area name is the name displayed in judge messages, while the abbreviations are used by the user for order input.

The area types

This information is used to define the characteristics of the area. The following are available:

Example 2. Area list.

Switzerland,   l  swi switz swiss (a neutral land province).
Ankara,        T  ank ankar       (a prov. containing T(urkeys) home SC).
Belgium,       xw  bel belgi      (a neutral land prov. containing an SC)
                                  (and that allows coastal convoys).
Adriatic Sea,  w  adr adriatic    (a sea area). 
Eastern Mediterranean, w eas emed east eastern eastmed ems eme em
English Channel,       w eng english channel ech ec

Convoyability, 'w', and duality

Usage supported by all Diplomacy variants. The "water" flag can also be used to indicate wether a *land* area can be used in a convoy route (a fleet must obviously be present in the area). It is always 'w'. The flag can only be used in these combinations: 'lw', 'xw', '<0-9,A-Z>w'.

Used by e.g. Gibraltar in 1900 variant and Baleares (Mallorca etc) in Acient Med variant.

This feature is controlled by the judge DUALITY flag. This has nothing to do with the judge coastal_convoys flag, which is used to enable coastal convoys in all areas allowing coastal movement (see the possible moves definition). If the coastal_convoys flag is set the DUALITY flag setting will be ignored.

The Machiavelli fields

Arguments used in both the Basic and the Advanced game

Allowed area types are 'l', 'w', 'x', '0-9,A-Z' (the 'g', 'r' and 'v' arguments will cause an error).

Tech note: Basic Machiavelli is in practice 3-season Diplomacy (especially the Mach2 implementation). Supported from fall 2002.

Arguments only used in the Advanced game

The following arguments must be present in the map file but are ignored unless the Advanced game flag is set. Any income and city type following 'w' causes an error.

City income can be set between 0 (no income = no city) and 7 (8-9 are not allowed). City incomes from 2-7 indicate the presence of a major city. Notice that both fortified/unfortified cities/ports may have an income up to 7. Notice also the exceptions below for the fortress city type.

The Venice flag, 'V', indicates that the city follows the "Venice rules" (see Mach rules).

Tech note: Venice is hardcoded in the old (and buggy) judge software, but is changed to a flag in Millis Millers brand new and revised n-judge release. (Also notice that in Mach2 there is no Venice province, just a city in a sea area!)

Example 3. Machiavelli area list.

Switzerland,   l0f  swi switz swiss (a neutral province with a fortress)
Adriatic Sea,  w0.  adr adriatic    (a sea area)
Ankara,        T1f  ank ankar       (a T(urkish) home prov. with a fortified city
Armenia,       T0.  arm armen       (a T(urkish) home prov. with no city)
Belgium,       x0P  bel belgi       (a neutral prov. with a port fortress)
Berlin,        G3f  ber berli       (a G(erman) home prov. with a fortified (major) city)
Brest,         F1P  bre             (a F(rench) home prov. with a fortified port city)
Venice,        V3PV ven venic       (a V(enetian) home prov. with a fortified port (major) city)
                                    (and the 'Venice' attribute set)

The possible moves definition section

After the province list you need to add a list of the valid moves between provinces. Here you will define what moves can be done, and between what areas. All provinces must have bidirectional paths. I.e. if province A can move to province B then province B must also be able to move to province A. Provinces may also be able to only move to themselves. If none of these condition are  met the map will be rejected by the judge.'

Only one unique area and move type combination per line can be specified. The dataformat is:
<source area>'-'<move type>':'' '<target area>['/'<move modifier>]' '<target area>['/'<move modifier>]...

Both the source and the target are defined by any valid abbreviation. It is recommended you use the 3-letter abbreviation from the area definition list.

Example 4. Impassable area.

swi-mv: swi
Resolution: allowed, but no land move in or out possible

alb-mv: alb rag dur her
alb-xc: alb
Resolution: allowed, but no sea move to the coast possible.

Example 5. All moves are possible.

swi-mv: mun tyr
mun-mv: swi
tyr-mv: swi
Resolution: allowed, swi can move to mun tyr and back.

Example 6. Moves have an error.

swi-mv: mun tyr
mun-mv: tyr
tyr-mv: swi
Resolution: not allowed, swi can move to mun but not back.

The move modifiers

There are three modifier groups: coasts, controls and moves. The coast and control modifiers must match the corresponding move type. But xc can pair with any of ec, wc, nc, sc. E.g. bul-ec must be paired with bul/ec and so on

Example 7: Moves list

swi-mv: swi
adr-xc: alb apu ven tri ion
ank-mv: arm con smy
ank-xc: bla arm con
bla-xc: rum sev arm ank con bul/ec
bul-ec: con bla rum
con-mv: bul ank smy
con-xc: bul/sc bul/ec bla ank smy aeg
eng-xc: mao iri wal lon nth bel pic bre

"Controlled conduits"

These are used in Machiavelli only to control access between areas. Only allowed for fleets. See "Gateways" below for the Diplomacy implementation. A conduit area is any ordinary area that has the additional move type '-cc' or '/cc' defined for it. To select which area controls (the "gatekeeper") the conduit the following data format is used:

<source area>'-xc: '<conduit area>/cc <gatekeeper area> <all other areas that can be moved to>
<conduit area>'-cc: '<all areas that are affected by the conduit>

Note that it actually does not matter where in the "move to"-list the conduit area is defined as long as it is immediately followed by the abbreviation of the "gatekeeper" area. (It is not tested if it is possible to define multiple gatekeeper areas for the same conduit. E.g. ets-xc: psa/cc pio psa/cc pat. Nor if multiple conduits are possible for one source area. E.g. ets-xc: psa/cc pio sie/cc pat.)

Example 8: The ETS to PSA conduit

ets-xc: psa/cc pio sie pat...  =  you can not move from ETS to PSA if there is a fleet unit in PIO
psa-cc: ets  =  to fulfill the bi-directional moves rule

Tech note: there is a special 'ally' command in Machiavelli that the controlling power can issue to let another power's unit get through. This command differs from the gateway rules in as much as that it is not unit specific.

If you've made an error !

If you have made an error the judge will throw an error report at compile time (as it checks the map file structure). Should the judge keeper forward this to you, you can use it to understand what the error is. Just keep in mind that the judge software does not warn about naming conflicts (e.g. you have abbreviated, common error, two provinces the same). If that is the case you will just get a generic warning "No movement table for <province_name>" when the judge encounters the duplicate entry.

The rest of the report is self-explaining as each line will read: 'Can't get back to <provA> from <provB> (coast|land)'.

The additional options

In this map section a lot of special information is defined. I have divided the following in three sections. The first concerns options common to Diplomacy and Machiavelli, the second to those specific for Diplomacy and the third and last to those specific for Machiavelli. Each section of options is delimited by 'hardcoded text'...'#end [<hardcoded text>]'. See below for details.

Common options

The summary center list

This is a list of all supply centers (or cities for Machiavelli) that you want to appear in the game center/city summary report. Ordering is arbitrary, but by convention the most common order is by game power starting home centers and "geographically sensible".

The province abbreviations used must be valid and unique.

Example 9:

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

Diplomacy only options

Supply center restrictions -- HongKong provinces

In this section provinces that are owned by a power but cannot be used for builds are defined. These provinces are known as Hong Kong provinces, as they first appeared as said province in Colonial Diplomacy. To use the 'set hongkong' flag must be set.

The data format is: <power-letters>':'' '<province list>

Example 10:

Hongkong settings
  C: hk
  RB: someotherprovA someotherprovB
#end of hongkong setting

Do notice that the "hong-kong"-rule is in addition to normal rules. So if this is the case:
    HongKong  E  hk (an english supply center) and
    C: hk (hongkong setting for china)
It means that England may *build in and count* HongKong for builds, but not China.

And if this is the case:
    HongKong  C  hk (a chinese supply center) and
    C: hk (hongkong setting for china)
It means that China may *build in* HongKong, but still *not count it* for builds.

Movement control -- gateway provinces

In this section you define provinces that control access to other provinces. What is commonly known as gateways and gatekeepers. To use the 'set gateways' flag must be set. This is a two step definition. First you define a gatekeeper province in the province list. No moves in or out of this province must be possible. Secondly you define the gateway itself in the gateway section.

The provinces whose movement is controlled must always be defined as a pair, and also be able to move to each other.

Notice that the gatekeeper controlling province need not be able to move to the provinces between which it controls movement. In the example below you could e.g. exchange Egypt for London: 'sca: lon meds reds'.

Tech note: when you have a unit in the province that confers control of the gatekeeper a notional unit is created in the gatekeeper province. To allow any other power to pass, this unit must then be ordered to allow passage by its controlling power. 

The gateway dataformat is:
<gatekeeper province>':'' '<control giving province>' '<affected prov. 1><affected prov 2>

Example 11:

Suez Canal, g sca
-1
meds-xc: reds egy con blas ang syr
reds-xc: eri sud egy meds mec ade goa
sca-mv: sca
-1
Gateway
  sca: egy meds reds
#end of gateway setting

Orders are written thus: <unit> SCA S <unit> <prov1> M <prov2>.

Railways

In this section you define provinces through which a railway pass. To use the 'set railways' flag must be set. This is a two step definition. First you define a notional railway province in the province list. No moves in or out of this province must be possible. Secondly you define the railway "path" and what powers that may use the railway, in the railway section.

The railway path cannot be circular, but it may of course end adjacent to the start province. Each province  included in the path must be adjacent to the previous province and regular movement must be allowed between them. (Different railways can probably intersect. You cannot change railway at an intersection.)

The railway dataformat is:
<railway province>':'' '<power letters>' '<prov. 1><prov 2><prov n+1>

Example 12:

Trans Siberian Railway, r tsr
-1
tsr-mv: tsr
-1
Railway
  tsr: RG mos prm oms kra irk
#end of railway setting

Tech note: If an enemy unit enters (or is present in) a railway province, then movement along the railway is stopped in the preceeding province. A railway province may be used as a gateway province or as a gatekeeper, but movement along the railway is not affected by this.

Orders are written thus: A <prov adj to railway> M TSR M <target railway prov>.

Machiavelli only options

The summary province list

This is a list of all provinces that you want to appear in the game summary report. Ordering is arbitrary, but by convention the most common order is by game power starting home provinces and "geographically sensible". (Tech note: province ownership is only relevant in Advanced Machiavelli.)

The province abbreviations used must be valid and unique.

Example 13:

Province order for summary report:
  ven pie tus rom apu nap tun afr edi lon wal liv yor cly por spa bel hol mun ruh kie ber pru sil den
  swe nor fin pet liv mos war ukr sev con ank arm syr smy bul rum gre ser alb bud vie tri gal boh tyr
#End of province ordering

The disaster tables

In Advanced Machiavelli there are two "disaster tables" that add an element of chance and complexity to the game. These are: famine and plague. In the n-judge implementation one additional disaster has been added: storms. Sample tables have are shown in Appendix 1. Note that it is not necessary to include all provinces in a disaster table or any select province only once...

The tables are ignored in Basic Machiavelli.

Tech note 1: Use of the tables are governed by specific flags. Nevertheless it is recommended that they are always present, but left empty for variants where no disasters are used. This to avoid the judge to incidentally crash.

Tech note 2: The element of chance introduced by the tables has oft been "slandered" by Diplomacy purists as giving unfair advantage to some player. But due to the dynamics of Advanced Machiavelli it rather introduces an element of  further complexity as the created disadvantage must be countered by better strategy, tactics and diplomacy by the stricken players. The disasters also remove most possibilities to create stalemate lines (which anyway are very uncommon in Machiavelli).

The variable income list

Advanced Machiavelli uses money to maintain and build units. The income is based on revenue from provinces, cities, sea areas and "trade". The variable income list symbolizes this trade income.

The table defines what province or power generates/receives this income. The table is divided in six columns that correspond to a random value between 1 and 6 that is generated each spring to decide what the income will be.

The field format is:
<recipient (city)><number of rolls (1d6)>123456<income at the beginning of the game (initial)>

Example 14:

Dice may be any value between 0 and 9. 0 (zero) means you won't get any money.
The value in columns 1-6 may be any value between 0 and 999.
The initial value is only used with Mach2 may be any value between 0 and 999 (supported from 2002). It is calculated thus:
nJudgeInitial=AHInitial-(IncomeAtSetup-MaintenanceAtSetup). Income and maintenance costs at setup are calculated by summing the income from all provinces defined as controlled in the setup and detracting the costs for all units available at setup.

Tech note: The city mentioned must be a home city province of a country or "free" province (e.g, Genoa) intended to receive the income.

Unit limits

In Machiavelli 2 (2nd ed., published 1995) powers cannot build or use all unit types available. These restrictions can be coded in the unit limits table. (This table is ignored if it is present in the map data file of a Mach1 game.) Are supported from nJudge release 1.2 (2002).

Example 15:

#Limits follow following format:
# <power-letter> <Army x 4chars> <Fleet x 4chars> <garrison x 4char>
#Each char is:
# 'x' = Unit allowed anytime
# '.' Unit never allowed
# 'b' Unit can only be built but not aquired by bribery
# 'r' Unit can only be aquired by bribery
#Unit qualifers are in order:
# Ordinary, Citizens, Mercenary, Professional

Limits for Units Types:
A xxx. xrr. xxx.
E xxxx xxxx xxxx
F xxxx xxxx xxxx
G xxxb xxxx xxxb
I xxx. xxx. xxx.
R xxxx xxxx xxxx
T xxx. x.r. xxx.
S x.x. x... x.x.
#end of limit (this line is compulsory!)

Structure of the seed file

The seed file consists of three main parts: the start year, the start positions and the game status record. The game status record data entries must be in the map file area definition order.

Diplomacy

The game status record can only contain information about supply center ownership data. The only reason to use this is if SC control at game start differs from the map file setup data. E.g. if Austria controls an English home SC at start as in the Shift Right variant. Or if a player starts with more units than he has SC to support them. In this case you must list the map file SC control.

Diplomacy seed file format:

<S|F><year><M>
<country letter>':'' '<unit type> <area name>
-1
[<country letter|.><country letter|.><country letter|.>...]
-1
-1

Example 16. Hundred Diplomacy, F(rance) starts with 5 units but does only own 4 SC's.

S1425M
F: A Dauphine
F: A Orleanais
F: A Paris
F: A Toulouse
F: A Provence
... and so on
-1
........E...FEB.B.EB..E.B..E..FF.......F.
-1

Example 17. Shift Right variant, Austria starts controlling the english home SC's.

S1901M
A: A Liverpool
A: F Edinburgh
A: F London
E: A Rome
... and so on
-1
....G.....T..RF...G..A...........TA.AR.ITE.....R....E...I..G.I..F.....EF.I..
-1

Machiavelli

Now things get really complicated. The machiavelli game status record contains information about control, home ownership and events (flags). The only reason to use this is if control at game start differs from the map file setup data (as, e.g. in the Struggle for Dominance II), if the map file cannot express the control setup needed (as, e.g. in Age of Communes) of or if some specific event has begun at game start (e.g. a siege).

Machiavelli seed file format:

<S|U|F><year><A>
<country letter>':'' '<unit type> <area name>
-1
N:<first letter in area name>       (this is just a mnemonic device)
n:<second letter in area name>
n:<third letter in area name>
O:<country letter|.|&>[<country letter|.|&>[<country letter|.|&>...
[o:<country letter|.|&>[<country letter|.|&>[<country letter|.|&>...]
C:<country letter|.|&>[<country letter|.|&>[<country letter|.|&>...
[c:<country letter|.|&>[<country letter|.|&>[<country letter|.|&>...]
H:<country letter|.|&>[<country letter|.|&>[<country letter|.|&>...
F:<0|...
-1
-1

The initial letter on every line indicate what data goes there:

1. N: and n: are used to indicate what area the other arguments are valid for. As mentioned above this is a mnemonic device to help the reader of the record.
2. O: = area control (province ownership)
3. C: = city control
4. H: = home area control (same as in the map file)
5. F: = flags, i.e. what event that is current in the area (famine, rebellion etc.)
6. o: and c: are used to indicate pending status changes in an ongoing game

Example 18.  Classic Mach sample.

Tips and tricks

Some useful tricks with the file format follow below.

Unconquerable province

This could be useful in primarily Machiavelli to ensure income to a power (but would also ensure survival to a  power in an adjacency game if it was set as part of a home province, so set it preferrably as a controlled non-hc province). It is also used for signalling purposes in NoPress games.

Example 19: swi-mv: swi

"Safe havens" / "Siberian training camps" / "Military supremacy"

By creating a gateway to a province that is only accessible through the "gatekeeper", you can effectively block access to a province. An interesting option would be to place a home SC behind this gatekeeper (think about those pesky russians or huns that just throw out new armies). 

Example 20: "Safe Haven".

Arabia SC can only be accessed through Syria, but Arabia controls the access. This could easily be blocked though.

Arabia, T ara
Syria, l syr
Onlyoasis, g oas
Stpgate, g sgt
Livoniagate, g lgt
Warsawgate, g wgt
Ukrainagate, g ugt
Krimgate, g kgt
- - - - - - - - - - - - - - - - - - - - -
ara-mv: syr
syr-mv: ara arm smy
oas-mv: oas
- - - - - - - - - - - - - - - - - - - - -
Gateway
  oas: ara ara syr
#end of gateway setting

Example 21: "Siberian training camp".

Moscow can be accessed through Stp, Liv, Ukr, War, Sev, but gateways control all accesses. This lets Moscow easily slip out a unit, but will be very difficult to block.

Gateway
  sgt: mos mos stp
  lgt: mos mos liv
  wgt: mos mos war
  ugt: mos mos ukr
  kgt: mos mos sev
#end of gateway setting

Example 22: "Military Supremacy".

A superpower controls some canals/passes in/out of your country because of its military supremacy. Notice that the controlling province, London, is not adjacent to the gateway, Suez Canal, in this case.

Gateway
  sca: lon meds reds
#end of gateway setting

Only fleet can move through land province

This is achieved by only defining moves for fleets.

Example23. Only fleets can move past Constantinople

ank-xc: arm con
bul-xc: con...
con-xc: bul/sc bul/ec bla ank smy aeg
   and no con-mv is defined.

Example24. Only fleets can move past Albania

alb-mv: alb
alb-xc: alb rag dur

Appendices

1. Machiavelli disaster table samples

Famine sample

Plague sample

Storms sample

2. Power name pairs available as of nJudge version 1.7.2

As it is unnecessary to "re-invent the wheel", here follows a listing of all official power names and their corresponding adjectives hardcoded into the nJudge software (currently the 'variant.c' file).

The following names are reserved and cannot be used in a variant or scenario: Neutral, Autonomous, Observer and Master.

Good and useful power names

Geographical and ordinal name pairs: North, Northern; South, Southern; East, Eastern; West, Western; First, First; Second, Second; Third, Third; Fourth, Fourth; Fifth, Fifth.

Odd power names

The Chromatic variant names: Yellow, Yellow; Dark, Dark; Light, Light; Red, Red; Blue, Blue.

The Chaos variant powers (noun and adjective are the same): A-Ank, B-Bel, C-Ber, D-Bre... 4-Swe, 5-Tri, 6-Tun, 7-Ven, 8-Vie, 9-War.

The RootZ variant powers: Austria1, 1Austrian; Austria2 2Austrian; England1, 1English and so on.

And some more names: Heartland, Heartlander; Lowland, Lowlander; Dissentos, Dissentos.

Revision history
v. 1.00,  June 25th 2002 by Sergio Lidsell.
v. 1.00b,  October 20th 2002 by Sergio Lidsell. Minor corrections and additions.
v. 1.5, July 29th 2003 by Sergio Lidsell. Added index, Machiavelli disaster table and seed file samples. Added seed file info and ref. to the 'variant how to'. Very minor content corrections. Changed the version number to make it correspond to the nJudge version.
v. 1.7.1, August 10th 2004 by Sergio Lidsell. Added description of the seed file format and of official power names. Revision of text (clean up, clarifications and syntax). Changed title of document (previously njudgemapfilehowto.htm). Changed the version number to make it correspond to the nJudge version.

Thanks
A special thanks to Millis Miller n-judge programming guru, without whose help, corrections and clarifications this document would never have been.