Description of e-mail format of Diplomacy electronic Judges
Version 0.1-0.5 Christophe Courtois - September 2003
This document describes the output format of the njudge Diplomacy adjudicator.
WARNING : This is
work in progress; please report any mistake, incoherence, gap...
Variants, and especially Macchivelli, may not be well described
here.
Describe the current e-mail format to make compatibility between the judge and the tools which use its output easier.
Help the next versions of the judge to be fully compatible with the previous versions (compatibility mode).
Describe the enhancements to this format in the new versions of njudge or other judges.
If not specified otherwise, all information there is given for all judges and must be accepted by all clients.
The following e-mails can be sent by the judge. Not everything is covered in this document. If an e-mail type is not listed here, or not described, or not precisely enough, and a some tool depend on it, please tell me ([email protected]).
Described in this document:
Judge and game identification (message headers)
Power is selected
Game starts
Movements results
Will be described [WORK IN PROGRESS]
Press to players
Player(s) is/are late or abandoned
End of game (draw)
Version
Will not be described (probably useless)
Take-over of abandoned powers
Signons of other players
Bad signon
Parameters of the game
Administrative e-mails about options change
Summary
History
TO BE COMPLETED
Technical headers of the e-mail must NOT be used for processing.
Attachments must not be used for e-mails sent to players.
Only following parts have some meaning and may contain information for the judge:
the From: (for returning the e-mail, if Resent or Reply-To not there),
the Reply-To: (optional, for returning the e-mail, if Resent not there)
the Resent: (optional, for returning the e-mail)
the body.
The e-mail informations are pure text.
Some judges may sent the e-mails with a defined charset (usually ISO-8859-1 or ISO8859-2) to preserve national characters in the player's messages, the header and the footer, but the judge itself writes pure ASCII English.
(ISO-8859-15 would be possible for Western Europe, but some obsolete software would default to ASCII instead of ISO-8859-1, so it's not used.).
The subject of the e-mail has often changed in recent njudges. It must not be taken into account by the judge, and is only for human use.
At the judge keeper's discretion, the judge may add a header at the beginning of the e-mail, whose text and size is totally free. It can potentially contain some informations which could fool parsers...
The judge may add a footer at the end of the e-mail, with the same provisions as the header.
This part is present in many e-mails (in fact, most that mapping tools need).
This part is managed by the msg_header function in mail.c in the njudge code.
Each line begins by two colons (::), followed by a blank space.
First line :
'Judge: ' [7 characters, space included]
The code of the judge [4 letters] [This is a tradition ; more letters could be used.]
Followed by two spaces.
Only if the player is signed onto a game:
'Game: ' [6 characters, space included]
The name of the current game, with the first letter uppercase.
Followed by two spaces.
'Variant: ' [9 characters, space included]
First, the variant name ('Standard', 'Modern'...), with the first letter uppercase,
followed by a space
if available, and by the variant modifier (Gunboat, Blind, AF_Rules, Shorthand, Wings at least 1.0-1.5.x njudge)
End of first line
Second line (only if the player is signed onto a game:
'Deadline: ' [10 characters, space included]
Phase of the game [TO SOLVE: see exact format and allowed length]. If game is not started, this is the first phase.
followed by a space
Deadline date as given by the ptime function, in English (code in jm.c).
If the deadline is not yet known (game has not started), it is by default at 00:00:00, Jan. 1st 1970 (judge timezone time)
Following fields are separated by a space (this is the default format for dates):
Day of week (3 letters, lowercase with first uppercase)
Month (3 letters, lowercase with first uppercase)
Day number (2 digits with leading zero if necessary)
Year (4 digits)
Time/minutes/seconds (as HH:MM:SS, with hours from 00 to 24)
Timezone of the judge location (+ ou – and 4 digits)
Other lines are optional. Known and totally optional uses are:
Map line for a web link (judge FROG)
OTHERS?
Examples :
:: Judge: FROG Game: S1b6p2 Variant: Standard Gunboat :: Deadline: S1901M Thu Jan 01 1970 01:00:00 +0100 :: Judge: FROG Game: S3b7p1 Variant: Standard Gunboat :: Deadline: F1906B Thu Sep 04 2003 23:30:00 +0200 :: Map: http://frog.born2play.org/~observer/cartes.php3?Partie=s3b7p1 :: Judge: ALEX Game: Test Variant: Standard :: Deadline: S1901M Fri May 09 2003 23:30:00 +0200
This is the e-mail that a player receives when he successfully subscribed to a game. Parts are:
Message header as described above
Empty line
Message “You've been selected to play a power in game “ and the game name (lowercase) between quotation marks.
If the game can't start immediately:
A line “You'll be notified when N more players sign on.”, where N is the number of missing players.
A line “Game 'xxxx' now has M players.', where xxxx is the full (lowercase) game name, and M the already subscribed players.
TO DO if this is important: preference list management, what happens if the game could start now, or effectively starts.
Example (header and footer suppressed) :
:: Judge: FROG Game: S1b6p2 Variant: Standard Gunboat :: Deadline: S1901M Thu Jan 01 1970 01:00:00 +0100 You've been selected to play a power in game 's1b6p2'. You'll be notified when 6 more players sign on. Game 's1b6p2' now has 1 player. Preference list 'FTGIEA' set.
This is the e-mail that all players receive when enough players have subscribed, and the judge or the master starts the game.
The parts are:
Message header, as described above.
A blank line
The message “You have been selected as XXXXX in game 'yyyyy' of Diplomacy.', where XXXXX is the power name (lowercase with first letter uppercase), and yyyy the game name (lowercase). (NB : Note the difference : You have been instead of You've been for power selection). The power may be Observer or Master.
A blank line.
The message “The following players are in this game:” followed by all players, master and observer of the game, one on each line, in this format:
Five spaces
The power name (or Master or Observer), with a colon.
From the 19th character, the e-mail address of the player (or [email protected] if the game is gunboat).
A blank line
The following part describes the starting positions of the game. In njudge 1.x, it is not computer-generated but is copied from the report file in the judge data directory. To avoid breaking tools, it should follow this format (some variants as Chaos don't):
Message “Starting positions for ”, and the first season name.
A blank line
For each power:
For each unit of this power, a line with:
Power name, a colon, one or two spaces
The unit name (usually “Fleet” or “Army”)
A point.
Two blank lines
The message “The
deadline for the first orders is “, and the date with the
default format [official 1.x judges].
OR
The message
“The deadline for the first movement orders is “, and
the date with the default format [seen at least on Frog, a 0.8.6
judge].
Example :
:: Judge: FROG Game: Azur Variant: Standard Gunboat
:: Deadline: S1901M Tue Dec 11 2001 23:30:00 +0100
You have been selected as Master in game 'azur' of Diplomacy.
The following players are in this game:
Master: [email protected]
Austria: [email protected]
England: [email protected]
France: [email protected]
Germany: [email protected]
Italy: [email protected]
Russia: [email protected]
Turkey: [email protected]
Observer: [email protected]
Observer: [email protected]
Observer: [email protected]
Observer: [email protected]
Observer: [email protected]
Observer: [email protected]
Observer: [email protected]
Observer: [email protected]
Observer: [email protected]
Starting position for Spring of 1901.
Austria: Army Vienna.
Austria: Army Budapest.
Austria: Fleet Trieste.
England: Fleet London.
England: Fleet Edinburgh.
England: Army Liverpool.
France: Army Paris.
France: Army Marseilles.
France: Fleet Brest.
Germany: Army Berlin.
Germany: Army Munich.
Germany: Fleet Kiel.
Italy: Army Rome.
Italy: Army Venice.
Italy: Fleet Naples.
Russia: Army Moscow.
Russia: Army Warsaw.
Russia: Fleet St Petersburg (south coast).
Russia: Fleet Sevastopol.
Turkey: Army Constantinople.
Turkey: Army Smyrna.
Turkey: Fleet Ankara.
The deadline for the first movement orders is Tue Dec 11 2001 23:30:00 +0100.
This can be rather complicated. The different parts are:
The usual message header
The movements of this turn (see below)
The dislodged units list (only if necessary and this turn was not about retreat orders) (see below)
The ownership of supply centers (if there is no dislodged unit are already dealt with) (see below)
The next phase and deadline, or the 'game over' message if a solo victory is reached.
These are separated from the message header by a blank line.
The first line indicates what the results are about. Parts are:
“Movement results for “ ,
followed by the full-name of the game turn,
a dot,
a space,
between parenthesis: the game name (lowercase), a dot, the number of the turn in the game.
Blank line.
For each power:
For each unit that this power posess, a line made from:
Power name (lowercase with uppercase first letter),
A colon,
A space,
The unit name (lowercase with first letter uppercase) (usually Fleet or Army)
A space
The territory name (lowercase with first letter uppercase)
For a non-movement (if turn was resolved without all orders):
A comma,
a space,
the words “No Order Processed”
If necessary: two spaces, and “(*dislodged*)” or “(*destroyed*)”.
For a simple movement:
A space,
the symbol “->” (dash and “greater than”),
a space,
the destination territory,
a dot,
If necessary: two spaces, and some indication on why the order failed:
“(*bounce*)”
or “(*bounce, destroyed*)”
or “(*bounce, dislodged*)”
or (Macchiavelli only) “(*blocked*)”, or “(*blocked, destroyed*)”
For a support:
A space,
the word “SUPPORT” (uppercase)
a space,
the movement of the supported unit, as described in the previous paragraph, including the last dot
followed if necessary by two spaces and:
“(*cut*)”,
or “(*cut, dislodged*)”,
or “(*cut, destroyed*)”,
or “(*void*)”
For a hold:
A space,
the word “HOLD” (uppercase),
a space
If necessary: two spaces, and “(*dislodged*)”.
For a convoy:
A space,
the word “SUPPORT” (uppercase)
a space,
the movement of the convoyed unit, as described in the previous paragraph, including the last point
followed if necessary by two spaces and “(*dislodged*”)
A blank line [all following options add another line; that will make two blank lines]
If necessary, the list of dislodged or destroyed units: for each of these units:
A blank line,
“The”, and a space,
the adjective describing the power (lowercase with the first letter uppercase), and a space,
the unit type (lowercase with the first letter uppercase), and a space,
“in” or “in the” (depending on the territory type), and a space
the full territory name (lowercase with the first letter of each word uppercase), a space
“with no valid retreats was
destroyed”
OR:
“can retreat to”, followed
by:
a space,
territory full names (lowercase with the first letter of each word uppercase),
separated by a space, “or” and a space if there is more than one,
a point.
NB: the line may wrap if it is too long.
If the judge does not need to wait for retreat orders, and this is Fall, we have directly the centers ownership:
A blank line,
“Ownership of supply centers:”
A blank line
For each power, a new line:
the power name (lowercase with first letter uppercase),
a colon,
from the 12th character on the line, the list of the supply centers (lowercase with first letter uppercase), each followed by a space and a comma, except the last one which is followed by a point.
NB: for successful powers, the line may wrap and we obtain multiple lines, but the 11 first characters of the line will always be blanked on such following lines.
A blank line,
For each power, a new line:
the power name (lowercase with first letter uppercase),
a colon,
from the 12th character (if the power has less than 9 centers), or the 11th (if the power has between 10 and 99 centers):
the centers number that the power owns,
a space, “Supply centers”, a comma,
one or two spaces (depending of the numbers of units),
the current units number,
a space, “ Units”, a colon, two spaces
“Removes” and two spaces,
OR
“Builds” and three spaces,
the number of units to build/remove, a space,
“unit” or “units”, a point.
If the power has won as a solo: two spaces and “(* VICTORY!! *)”.
If the game is finished (a player has won alone):
A blank line,
“The game is over. Thank you for playing.” (2 spaces between the sentences).
If the game is not finished, message about the new deadline.
A blank line,
The first line is: “The next phase of 'yyyyy' will be Retreats for” (where yyyyy is the game name), a space, the season (Winter, Fall...), a space, “of”, a space, the year, a point.
The second line is: “The deadline for
orders will be”, a space, the deadline date with the default
format, a point.
Examples for a turn with dislodged armies:
:: Judge: FROG Game: S1b6p2 Variant: Standard Gunboat
:: Deadline: F1920M Mon Oct 28 2002 23:30:00 +0100
:: Map: http://frog.born2play.org/~observer/cartes.php3?Partie=s1b6p2
Movement results for Fall of 1920. (s1b6p2.086)
Austria: Army Armenia -> Smyrna.
Austria: Army Bohemia -> Silesia. (*bounce, dislodged*)
Austria: Army Tyrolia -> Piedmont. (*bounce*)
Austria: Fleet Ionian Sea SUPPORT French Fleet Tunis. (*cut, dislodged*)
Austria: Fleet Smyrna -> Aegean Sea.
Austria: Army Ukraine SUPPORT Army Galicia -> Warsaw.
Austria: Army Sevastopol SUPPORT English Army Moscow.
Austria: Army Galicia -> Warsaw.
Austria: Fleet Albania SUPPORT Fleet Trieste -> Adriatic Sea.
Austria: Fleet Trieste -> Adriatic Sea.
England: Army Moscow SUPPORT Austrian Army Ukraine -> Warsaw. (*void*)
France: Fleet Norway SUPPORT German Fleet St Petersburg (north coast).
France: Fleet Portugal -> Spain (south coast).
France: Army Burgundy SUPPORT German Army Munich.
France: Fleet Tunis SUPPORT Fleet Naples -> Ionian Sea.
France: Fleet North Atlantic Ocean -> Liverpool.
France: Fleet Adriatic Sea -> Trieste. (*bounce, dislodged*)
France: Fleet Western Mediterranean -> Tyrrhenian Sea.
France: Army Gascony -> Brest.
France: Fleet Naples -> Ionian Sea.
France: Fleet Mid-Atlantic Ocean -> English Channel.
France: Army Marseilles -> Piedmont. (*bounce*)
Germany: Army Kiel SUPPORT Army Munich.
Germany: Fleet North Sea -> Denmark.
Germany: Fleet St Petersburg (north coast) CONVOY Austrian Army Tyrolia -> Switzerland.
Germany: Fleet Edinburgh -> Yorkshire.
Germany: Army Belgium -> Ruhr.
Germany: Army Livonia SUPPORT Army Warsaw -> Moscow.
Germany: Army Warsaw -> Moscow. (*bounce, dislodged*)
Germany: Army Silesia -> Bohemia.
Germany: Army Munich SUPPORT Army Silesia -> Bohemia.
Germany: Fleet English Channel -> North Sea.
Germany: Army Sweden -> Finland.
The following units were dislodged:
The Austrian Army in Bohemia can retreat to Galicia or Vienna.
The Austrian Fleet in the Ionian Sea can retreat to Apulia or Greece or
Eastern Mediterranean.
The French Fleet in the Adriatic Sea can retreat to Apulia or Venice.
The German Army in Warsaw can retreat to Silesia or Prussia.
The next phase of 's1b6p2' will be Retreats for Fall of 1920.
The deadline for orders will be Wed Oct 30 2002 23:30:00 +0100.
Example with convoys:
:: Judge: FROG Game: S1b6p2 Variant: Standard Gunboat
:: Deadline: F1903M Mon Feb 25 2002 23:30:00 +0100
:: Map: http://frog.born2play.org/~observer/cartes.php3?Partie=s1b6p2
Movement results for Fall of 1903. (s1b6p2.010)
Austria: Army Bulgaria SUPPORT Army Galicia -> Rumania. (*cut*)
Austria: Army Serbia SUPPORT Army Bulgaria.
Austria: Fleet Greece SUPPORT Army Bulgaria.
Austria: Army Galicia -> Rumania. (*bounce*)
Austria: Army Budapest SUPPORT Army Galicia -> Rumania.
England: Army Norway SUPPORT Russian Army Livonia -> St Petersburg. (*void*)
England: Fleet Sweden -> Denmark.
England: Fleet London -> North Sea. (*bounce*)
England: Fleet English Channel CONVOY French Army Gascony -> Switzerland. (*dislodged*)
France: Army Gascony -> Burgundy. (*bounce*)
France: Army Burgundy -> Picardy. (*bounce, dislodged*)
France: Fleet Liverpool CONVOY German Army Holland -> London.
France: Fleet Mid-Atlantic Ocean SUPPORT Fleet Brest -> English Channel.
France: Fleet Brest -> English Channel.
Germany: Army Holland -> Ruhr.
Germany: Army Belgium -> Picardy. (*bounce*)
Germany: Fleet Denmark -> Baltic Sea.
Germany: Fleet Helgoland Bight -> North Sea. (*bounce*)
Germany: Army Munich SUPPORT Army Ruhr -> Burgundy.
Germany: Army Ruhr -> Burgundy.
Italy: Army Syria -> Smyrna. (*bounce*)
Italy: Army Venice HOLD.
Italy: Fleet Eastern Mediterranean SUPPORT Fleet Ionian Sea -> Aegean Sea.
Italy: Fleet Ionian Sea -> Aegean Sea.
Russia: Army Livonia -> Prussia.
Russia: Army Rumania SUPPORT Turkish Army Constantinople -> Bulgaria. (*cut*)
Russia: Fleet Sevastopol SUPPORT Army Rumania.
Russia: Fleet Gulf of Bothnia -> St Petersburg (south coast).
Russia: Army Warsaw -> Silesia.
Turkey: Army Constantinople -> Bulgaria. (*bounce*)
Turkey: Army Smyrna -> Syria. (*bounce*)
Turkey: Fleet Black Sea SUPPORT Army Constantinople -> Bulgaria.
Turkey: Fleet Aegean Sea -> Eastern Mediterranean. (*bounce, dislodged*)
The following units were dislodged:
The English Fleet in the English Channel can retreat to Irish Sea or Wales.
The French Army in Burgundy can retreat to Marseilles or Paris.
The Turkish Fleet in the Aegean Sea with no valid retreats was destroyed.
The next phase of 's1b6p2' will be Retreats for Fall of 1903.
The deadline for orders will be Tue Feb 26 2002 23:30:00 +0100.
Footer format ?
Always ASCII ???? => Was charset always ASCII ?
Machiavelli ???
DEDO : translated messages ??? => English compatibility mode
This document was made by Christophe Courtois and is part of the njudge program.
Verbatim and explicitly enhanced versions can be freely redistributed.