How to build a Diplomacy Judge Map Data file

Version 1.5, July 29th 2003, by Sergio Lidsell

Introduction

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

Why do I need this ?

This "how-to" is meant to help Diplomacy and Machiavelli players create a correct map file for variants they create for the Diplomacy Judge (n-judge).  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.

What is a map-file

The map file ('map.<variant name>') is used to define the area characteristics for the nJudge software. 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.

For a complete description of this see Christophe Courtois documentation for judge-keepers on how to create and add a new variant to the nJudge.

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 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 parts are:

1. The province data list
2. The allowable moves list
3. Additional options

Example:
    # 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

The additional options

These vary. See samples for Diplomacy and Machiavelli below.

Structure of the Diplomacy map data file with all options

1. The province list
2. The allowable moves list
3. Center list for the summary report
4. Definitions of SC restrictions ("Hong-Kong" provinces)
5. Definitions of movement control / gateways
6. Definitions of railway provinces

Structure of the Machiavelli map data file with all options

1. The province list
2. The allowable moves list
3. Famine table
4. Plague table
5. Variable income list
6. Center (city) list for the summary report
7. Province list for the summary report
8. Storms table (optional)
9. Unit limits (machiavelli 2 only, ignored if used in mach 1 datafile)

Tech note: the n-judge code for Machiavelli and Diplomacy is mostly separated, which of course means that similar bugs must be corrected in two code listings and that code in practice performing the same logic may unintentionally diverge procedurally.

The province data list

By province all types of areas are intended. The list must contain all valid province names for your scenario. Any names not in this list will raise an error in the judge and be rejected. In addition you must specify of what type the province is and any valid abbreviations.

You can only specify one unique province name per line. The dataformat is:

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

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

Quotes and circumflexes are not part of the format. ' ', yes this indicates 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.

The full province 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 set the characteristics of the province. The following are available:

Example 1. Province list

Switzerland,   l  swi switz swiss
Adriatic Sea,  w  adr adriatic 
Ankara,        T  ank ankar
Belgium,       xw  bel belgi
Eastern Mediterranean, w eas emed east eastern eastmed ems eme
English Channel,       w eng english channel ech

Convoyability, 'w', and duality

Supported by all Diplomacy variants. This flag can be used to indicate wether a fleet occupied *land* area can be used in a convoy route. 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 regardless of how the map is coded.

The Machiavelli fields

Arguments used in both the Basic and the Advanced game

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 2. Machiavelli province list

Switzerland,   l0f  swi switz swiss
Adriatic Sea,  w0.  adr adriatic 
Ankara,        T1f  ank ankar
Belgium,       x0P  bel belgi
Berlin,        G3f  ber berli
Brest,         F1P  bre
Denmark,       x1PV den denma

The allowable moves list

After the province list you need to add a list of the valid moves between provinces. 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 move type per line can be specified. The dataformat is:
<valid abbreviation>'-'<move type>':'' '<list of provinces that can be moved to>

The valid abbreviation is any 3-letter abbreviation from the province list. 

The "move to" list

Abbreviations in the "move-to" listing must be separated by one space.

Provinces can have an additional modifier here: <prov>['/'<modifier>]. There are three modifier groups: "coasts", controls and moves. The coast and control modifiers must match the corresponding move type.

That is moves for e.g. bul-ec must have a corresponding bul/ec province in the moves list and so on.

Example: 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 provinces. Only allowed for fleets. See "Gateways" below for the Diplomacy implementation. A conduit province is any ordinary province that has the additional move type '/cc' defined for it. To select which province controls (the "gatekeeper") the conduit the following data format is used:

<province>'-xc: '<conduit province>/cc <gatekeeper province> <all other provinces that can be moved to>
<conduit province>'-cc: '<all provinces that use the conduit>

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

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

The optional map data

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.

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

Example:

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:

Hongkong settings
  C: hk
  RB: someotherprovA someotherprovA
#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. To use the 'set gateways' flag must be set. What is commonly known as gateways and gatekeepers. 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.

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. This unit must then be ordered to allow passage by the controlling power. 

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

Example:

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

Orders are written thus: <unit> SC 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:

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.

Example:

Province order for summary report:
  ven pie tus rom apu nap tun 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 afr
#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 been added 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.

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 (dice)>123456<income at the beginning of the game (initial)>

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

#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
# 'r' Unit can only be bribed
#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 xxxx xxxx xxxx
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!)

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: 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 1: "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 2: "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 3: "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
  sc: lon meds reds
#end of gateway setting

Only fleet can move through land province

This is achieved by only defining moves for fleets.

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

Appendix 1. Machiavelli disaster table samples.

Famine sample

Plague sample

Storms sample

Appendix 2. Seed file examples.

SC ownership defined by unit start positions.

S1901M
A: A Budapest
E: F London
-1
-1

Notice the absence of data between the -1's.

SC ownership defined in seed file.

In this case the game starts with the builds (nothing is owned), thus there is only the SC ownership data.

F1900B
-1
....A....BC..DEF..GH.I....J...K..LN.PQ.RST...U.V..W.X.YZ0..1234.56.... 78.9..
-1

In this case F(rance) starts with 5 units but does only own 4 SC's (which also happen to be the home SC's).

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

Complex ownership data sample (from Machiavelli variant)

F1498A
Am A Austria
Fm A Mil
&m G Sav
-1
N:XAAAAAABBBBBBCCCCCCCDDEEFFFFGGHHIILLMMMMMMNOPPPPPPPPPPPPRRRSSSSSSSSTTTTTTUULV n:Xlnqruvaaeooraaaoorrauaaeloreueuosouaaeiooataaaaaeiiiioraooaaaailpwirruuyprae n:Xbcuesiryrlseprrmreolrssrorinlrnntwcnrsldnprdlrtvraossnogmmllrveaoiveenrrpbgn O:.TP.LAFF.VPTV.A...&.VT...L.VF.TA.V.&&FAF&&F.VA.P&P.&LL.F&PP.FA&&.PAP&VT&A.P.V C:.TP.LAFF.VPTV.A...&.VT...L.VF.TA.V.&&FAF&&F.VA.P&P.&LL.F&PP.FA&&.PAP&VT&A.P.V H:.TP.LAF..VPTV.A.....VT...L.V..TA.V...FA.....VA.P.P..LL.F.PP..A...PAP.VT.A.P.V F:00000000000000000000000000000000000000000000000000000000000000000000000000000
-1
-1

Revision history
v. 1.00,  June 25th by Sergio Lidsell.
v. 1.00b,  October 20th by Sergio Lidsell. Minor corrections and additions.
v. 1.5, July 29th 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.

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