DPjudge Map File Syntax
about the DPjudge | the DPPD | common questions
View Map Files

The DPjudge already supports a number of existing map variants, each of which is implemented by a .map file in the format described here, and an accompanying "Manusized" PostScript (.ps) graphical template file. You can view each of these files as a working example of a DPjudge .map file.

 
If you can create a .map file of your own, and send it in, along with an appropriately formatted (Manusized) .ps file, you can add to the map variants supported by the DPjudge. Creating a .map file is easy. It is the creation of the accompanying .ps file that is (currently) difficult, mostly due to the fact that Manus is very particular -- the map must look very very good to be accepted. Take a look at the .ps files here.
 

General Directives

# comment...
Any line that has a pound sign (#) as its first non-whitespace character will be considered a comment, and ignored. Comments must span a complete line (that is, you may not add a comment to the end of a non-comment line).

USE[S] fileName...
This line causes another file to be immediately read in. This is used to share map information. For example, the britain.map file USES the standard.geography file, which contains all the geography for the standard Diplomacy map.

MAP mapName
This line is identical to USE mapName.map with the additional provision that the graphical map template (used to generate the actual visual map) will be the one having the mapName specified. For example, the "fleetRome" map not only USEs the same map data (slightly altered) as the standard map, but also uses the same graphical map for display (and therefore, the MAP command is proper for that variant). By contrast, the "britain" and "crowded" maps may USE (that is, load and then alter) the data from the standard map file, but (due to the additional SC dots that must be depicted on the map to support these variants), they use different graphical maps than does the standard game, so the USE command (rather than MAP) is proper for these variants.

TEXTONLY
This line specifies that no graphical map should be made for games using this map file. This is useful to allow testing of adjudication and other play details without dependency on a PostScript template map file, which may be later in development.
Geographic Directives

[oldAbbrev ->] placeName = abbreviation alias...
This type of line specifies all the recognized aliases for a map location. The placeName is the long form of the map location (the form to appear in results mailings). The abbreviation is the DPjudge standard abbreviation for the place-name (the form to appear in all orders when shown to the player on his Web pages). This standard abbreviation must be exactly three characters long and must both begin and end with an alphabetic or numeric character. Each alias is a single word (that is, having no embedded spaces) that is to be recognized as another name for the location in question. If you wish to specify an alias that is more than a single word in length, you must join the separate words using plus-sign characters (+). For example,
      Norwegian Sea = nwg norwegian nrg norwsea norw+sea

If an alias ends with a question-mark (?), it must not contain a plus-sign, and this indicates that the alias (without the question-mark) is to be considered "ambiguous." Ambiguous aliases may not be used in games that use the NO_CHECK rule (the ambiguity will be reported to the player at the time of order-entry). For example, TYR is an ambiguous alias in the standard game map, since it is commonly used as an alias for both Tyrolia and the Tyrrhenian Sea.

If the placeName is preceded on the line by an oldAbbrev and an arrow (->), this indicates that the location being named is a pre-existing location whose abbreviation is currently oldAbbrev. This allows you to completely rename a map location, and/or provide a different standard abbreviation or a different set of aliases. When renaming a location in this way, all existing information about that location (such as adjacencies to this location from other locations) is automatically adjusted to reflect the new abbreviation instead. Note that if you wish to rename a multi-coast space, every coast must be separately renamed. That is, if the map defines SPA and SPA/SC and SPA/NC, it is not sufficient to simply rename SPA; separate rename directives must also be given for the coastal regions or they will retain their original name, abbreviation, and aliases.

COAST abbreviation [ABUTS [abut...]] -or-
LAND  abbreviation [ABUTS [abut...]] -or-
WATER abbreviation [ABUTS [abut...]] -or-
PORT  abbreviation [ABUTS [abut...]] -or-
SHUT  abbreviation [ABUTS [abut...]] -or-
AMEND abbreviation [ABUTS [abut...]]
This type of line specifies the terrain type and adjacencies for the place-name whose abbreviation is given. The terrain must be either WATER, LAND, COAST, PORT, SHUT (impassable), or AMEND. The only difference between PORT and COAST spaces is that fleets located in PORT spaces may convoy armies as if they were in water.

If the terrain is AMEND, all pre-existing data for the abbreviation (from an earlier such line) will be retained, and the adjacency information given on the line will modify that which is already on record. If an area listed to the right of ABUTS begins with a dash (-), then the area is removed (if possible) from any pre-existing list of adjacencies for the location in question.

In all other cases (that is, if the terrain is not AMEND), the adjacency information given on this line will silently supplant (become valid instead of) any previous such line for the same location. In this way, maps can be changed on the fly, such that what was a LAND location can become COAST or WATER and/or can obtain different adjacencies.

The abut locations must be the DPjudge standard abbreviations (the first abbreviation given after the equals-sign in each placename line).

Specifying Army and Fleet Restrictions
This directive is case-sensitive. Army and fleet restrictions are specifyied by use of upper- and lower-case as described below. Everything must be in upper-case except the following:

  • The abbreviation for any COAST location that a fleet cannot occupy must be listed entirely in lowercase. For instance, on the standard map, Spain must be listed as spa since fleets may only occupy either SPA/SC or SPA/NC. Specifying a location using lower-case after the same location was given earlier using upper-case, or vice-versa, will cause the previous location's terrain type and adjacencies to be forgotten (or, in the case of AMEND, will cause the previous location to be converted to the new casing, and its adjacencies preserved so they can be modified by the AMEND directive).
  • In the list of adjacencies, any location that a fleet could occupy but into which a fleet cannot move from the location in question must be listed entirely in lowercase. For example, on the standard map, Tuscany must be listed as tus in the list of locations adjacent to VEN, since a fleet cannot move directly from Venice to Tuscany.
  • In the list of adjacencies, any LAND or COAST location to which an army cannot make a direct (non-convoyed) move from the location in question must be listed with its first character in uppercase and the remainder in lower-case. This is useful to specify offshore islands, and therefore no example on the standard map can be given. Consider, however, allowing an army to be convoyed into the Tyrrhenian Sea (call it Sicily). To implement this, the Tyrrhenian Sea would be given the terrain type PORT (to allow both fleets and armies to occupy the space and to allow fleets in that space to convoy) and all land spaces adjacent to the Tyrrhenian Sea would list their adjacency to that space as Tys (rather than TYS or tys) to indicate than an army may not move directly to the space despite the fact that movement from a COAST (such as Naples) to an adjacent PORT (the Tyrrhenian) would otherwise be allowed. Convoyed movement would be allowed, though, so an order such as A Nap-ION-TYS would be perfectly valid.

Specifying Multi-Coast Spaces

  • If an area abuts a multi-coast province, its adjacencies must list only the coasts that are reachable, and must not list the main space itself (for example, RUM is listed as being adjacent to BUL/EC, but not to BUL itself).
  • The line for every coast of a province should appear in the map file before the line for the space itself.
  • If the map will undergo terrain changes during play, it is important to note that the fleet-friendly space listed last is the one on which a unit in that space will be put if a terrain modification requires it. For example, if a fleet is in Rome when Venice becomes a WATER space, the map file will need to direct that Rome becomes a multi-coast province by adding entries for ROM/EC, ROM/WC, and rom. By listing ROM/WC after ROM/EC, the fleet in Rome will be placed on the west (rather than the east) coast.

Power Restrictions and One-Way Adjacencies
An abut location (appearing to the right of ABUTS) may optionally be preceded by one or more power abbreviations, separated from the location abbreviation by a colon. This indicates that movement across the adjacency is only allowed for units owned by the listed power(s). For example,
     COAST SPA ABUTS EI:NAF
indicates that an English or Italian unit in Spain may move directly to North Africa (and may support actions in North Africa). Units owned by other powers do not have this capability. Power abbreviations are not necessarily required before the colon; if none are given, the adjacency will be essentially impassable by all units. This is useful to set up one-way adjacencies, such as the following example:
     WATER SKA ABUTS BAL
     WATER BAL ABUTS :SKA

This indicates that a unit may move from Skagerrak to the Baltic Sea, but not vice-versa. Without the :SKA, the map would be declared to be in error, as one-way adjacencies are otherwise illegal.

Center Ownership Restrictions
Further restriction on the power eligible to use an adjacency may be made by supplying any number of comma-separated supply centers in a parenthesized list at the end of the abut location. For example,
     BLA ABUTS AEG(CON,SMY)
indicates that a unit in the Black Sea is adjacent to the Aegean Sea if and only if the power that owns the unit also owns both Constantinople and Smyrna.

Special Restrictions
After considering any power and center ownership restrictions that may be given, then if an area listed to the right of ABUTS begins or ends with any non-alphabetic character or characters, all such characters specify restrictions on the adjacency (these are special restrictions; beyond those covered by the upper- and lower-case rules listed above). The recognized restrictions are as follows:

~ (tilde) [implementing weak movement across straits]
  1. Support cannot be offered across the adjacency.
  2. Movement across the adjacency has no strength (except that given by any supporting units). This means that even if the move is made with one valid support, a unit HOLDing at the destination will not be dislodged. This also means that an unsupported move across the boundary will not cut any support being offered by a unit at the destination.

* (asterisk) [implementing the Cape of Good Hope Rule from the 1900 Variant]
  1. Movement across the adjacency (to the listed space) is done at half-strength. This includes convoyed movement whose final step is the crossing of the adjacency.
  2. Support cannot be offered across the adjacency.
  3. Movement across the adjacency does not cut any support being offered by a unit at the destination (unless the move dislodges the supporting unit, of course).
  4. Any unit attempting to retreat across the adjacency is destroyed if any other retreating unit attempts a retreat to the destination space (the other unit succeeds in its retreat attempt).

DROP abbreviation...
This line will remove all data that was given concerning the place(s) with the specified abbreviation(s), including all adjacency information. That is, all record of the space will be forgotten, and no space will be left thinking that it is adjacent to the DROPped location. DROPping a multi-coast space, without designating any particular coast, will also DROP all information for each of the coasts. That is, DROP SPA, used on the standard map, will remove all information on Spain, Spain (north coast), and Spain (south coast).
Political Directives

[oldName ->] powerName [([ownWord][:[abbrev]])] [center...]
This type of line is used to specify a power name, its "ownership word" and single-letter abbreviation (for instance, England's ownership word would be "English", and abbreviation would be "E") and all centers that serve as the home centers for the power. If the ownWord is omitted, the powerName is used for this purpose, and if the abbrev is omitted, the initial letter of the ownWord is used as the abbreviation.

Any and all leading underscores (_) in a powerName will not be displayed when the power is referred to in results and on the graphical map. This is useful to cause powers to alphabetize after others (and thus be displayed in a specific order in the results and on the graphical map).

A plus-sign (+) appearing anywhere in the powerName indicates that the next character in the name is to be displayed in upper-case. Any plus-sign appearing in the ownWord will be displayed as a space.

If preceded by oldName, which must be the name of a previously defined power, followed by an arrow, that power gets renamed to the new power name.

Claiming New Home Centers
One or more center may be specified as &SC and each of these indicates that the power will be eligible to build in one owned non-home center; once having done so, that center will permanently become a home center for that power. Note that such a "claimed" home center may even be a center that also serves as a home center for another power (whenever it is under that power's other control).

Building in Non-Supply Centers
If the center is preceded (immediately, with no intervening space) by a plus-sign (+), the location is not a supply center, but the power will be eligible to build there. This type of location is referred to as a factory site.

Conditional Building in Non-Supply Centers
If the center is preceded (immediately, with no intervening space) by an asterisk (*), the location is not a supply center, but the power will be eligible to build there if and only if the power owns at least one, but not all of his original home supply centers. This type of location is referred to as a partisan site.

Alternative Home Centers
An alternative home center is a supply center where you may build if you forego building in a normal owned and open home center. Otherwise stated, it increases the number of build centers, but not the number of builds. Say you have 3 home centers and 1 alternative home center, all open and owned by you, that would allow you to build 3 units in any 3 of the 4 centers. To indicate an alternative home center, precede the center with an at sign (@). To restrict its usage to a subset, list the home centers between round brackets and separated by commas immediately after the center name. E.g. @CAL(NYO) designates CAL as an alternative to NYO only.

Hiding Builds
When a center is preceded by a tilde sign (~), any unit built there is only revealed in the results of the next movement turn. The adjustment results will simply state BUILD HIDDEN and no unit will be displayed on the map. See also the HIDE_BUILDS rule for applying this effect to all builds for all players. This sign can be combined with other signs if you want to apply more than one special property to the same center, as in ~@CAL(NYO).

If the center is preceded (immediately, with no intervening space) by a dash (-), the center is removed (if possible) from any pre-existing list of home centers for the power, and added to the list of unowned supply centers. This allows for locations to lose "home center" status. Factory and partisan sites may also be removed in this same manner.

Multiple lines for a single powerName may be used to handle long lists of centers.

This type of line sets a "current power" such that all following lines (that specify initial owned centers and units) will apply to this power (as opposed to any other) until another powerName directive is encountered.

UNOWNED [center...] -or-
NEUTRAL [center...] -or-
CENTERS [center...]
This line (all three forms are synonymous) is used to list all unowned supply centers. The UNOWNED power differs from others in that all centers listed as UNOWNED may be listed elsewhere without error -- they are silently moved to owned status. Additionally, any "current power" is forgotten by this line. Again, multiple lines may be used to supply a long list of unowned centers. If you remove a center from the list of UNOWNED centers (using a dash before its name), that location is no longer a supply center at all. For example, to make Warsaw a non-supply center on the standard map, you would need to specify the two lines: "RUSSIA -WAR" and "UNOWNED -WAR" in that order.

DUMMY [ALL] -or-
DUMMY [ALL EXCEPT] powerName... -or-
DUMMIES ALL -or-
DUMMIES [ALL EXCEPT] powerName...
This indicates that either the current power, or all powers, or only those specified by powerName, or again all powers other than those specified, are to be made a DUMMY power in the game. No player will take the role of such a power. Such a power can be put into civil disorder using the CD_DUMMIES rule, or may be played under the CONTROL of another power (see below). Turning all powers into dummies can be useful for testing certain scenarios. In such a case it's advisable to turn on the HIDE_DUMMIES rule, as that allows to log in to the web page of any dummy power.

CONTROL powerName...
This command puts the dummy power under the control of another power, rotating through the list of powers according to the ROTATE directive. (See the CONTROL directive in the game status help file for a more thorough description.)

ROTATE [CONTROL] -or-
ROTATE AFTER [phaseType]... -or-
ROTATE BEFORE phaseType... -or-
ROTATE FOR phaseType...
This is used to specify a rotation of power control for all powers in the game that are controlled by other players. (See the ROTATE directive in the game status help file for a more thorough description.)

NEWHOMES year...
This command will cause home supply centers to be completely reassigned to all players during the adjustment phase of the specified game-year(s). Each power's home SC's will be all of the centers he owns at the time.

UNPLAYED [ALL] -or-
UNPLAYED [ALL EXCEPT] powerName...
This line removes either the current power, all powers, the specified powerName, or on the contrary all powers that are not specified. At the same time all information that had been recorded for those powers is removed as well. This directive is useful to create variants for a smaller number of players on a specific USEd map. If you remove all powers, you should add some new powers afterwards, because a game will not start with less than two powers.

LEAGUE leagueName -or-
LEAGUE leagueName STRICT
-or-
LEAGUE leagueName BENIGN [benignLeague...]
This line assigns "league" affiliation and behavior to the current power. If the line contains neither STRICT nor BENIGN, then the power is associated with the specified leagueName but is not restricted in any way by this association. If the leagueName is followed by the word STRICT, the association with the league also restricts the power from being able to issue a convoy or support order to a unit owned by any power that is not associated with the same league. If the leagueName is followed by the word BENIGN, the league association restricts the power from issuing any convoy or support order that aids a movement order by a unit owned by a power that is not associated with any league listed on the line, if (and only if) that movement order is being made into a space that is currently occupied by a unit owned by a power that is associated with one of the listed leagues. Note that league settings are ignored in any game with the FICTIONAL_OK rule enabled (including all Crystal Ball Diplomacy variant games).

FLAGS mapName...
Lists the maps from where the flags are borrowed. If the same power is present in more than one map, the first one listed takes precedence. Flag icons are stored in web accessible directories, under .../web/images/flags/<mapName>. If this option is not specified, the list consists of the current map name (if the directory exists), followed by the FLAGS list of any map it inherits from (see USE and variants), which in turn may have been set implicitly or explicitly. Note that when defined explicitly, you need to list all maps that have directories to pick from, including the current map, unless it doesn't exist or you want it ignored. Without any map names after the keyword, no flags will appear for any power.

FLAG powerName
This line makes the current power borrow the flag from the specified power. Flag icons are gif-files with the file name in uppercase, usually corresponding to the name of one power. Note that any renamed power inherits initially the flag of the original power.
Military Directives

VICTORY centerCount...
Specifies a list of the supply center counts which will determine victory, from the first game-year forward (the final listed number is repeated for subsequent years). This line is optional; if omitted, the VICTORY criterion is set (for all game-years) to one supply center greater than half the number of centers on the map, unless the VICTORY_HOMES rule is used, in which case the default is based on the number of home centers (click the link for a complete description).

FLOW [season:phase[,phase...] ...]
This line specifies the sequence of phases through a game year. Each season must be followed by a colon and then immediately (no intervening whitespace) by one or more phase types. If more than one phase type is given, these should be separated from each other by commas (again, with no intervening whitespace). This line is optional; if not provided, the following is used:
   FLOW SPRING:MOVEMENT,RETREATS
   FLOW FALL:MOVEMENT,RETREATS
   FLOW WINTER:ADJUSTMENTS

If no parameters are given with the FLOW directive, the whole flow is reset. This can be useful if you're USEing a given map, and want to redefine its flow. Note that if no other FLOW directive follows, the flow will revert to the default given above.
Each individual phase type must begin with a unique letter. Additionally, the phase names MOVEMENT, RETREATS, and ADJUSTMENTS are reserved (and therefore, so are the initial letters M, R, and A).

The word NEWYEAR can be used as a season, and has a special meaning. A flow may contain one or more NEWYEAR directives, which instruct the game when to modify the game-year. A simple NEWYEAR will increment the year game-by one, and NEWYEAR:5 (for example) will increment it by five. Any flow that does not include a NEWYEAR directive will increase the game-year by one after the final phase in the FLOW.

The word IFYEARDIV can also be used as a season, and also has a special meaning. This word will cause the game's next phase to be set to the first phase in the flow if the game-year is indivisible by a specified number. For example, the flow descriptor IFYEARDIV:10 means that the flow will continue normally only if the game-year is divisible by ten. Otherwise, the initial listed element of the FLOW will be next. The divisor may also include a modulus. For example, IFYEARDIV:2=1 means that the flow will be reset (to its first listed element) if the game-year is even, and will continue normally if the game-year is odd.

When any phase that is not supported by the DPjudge code is current, all players will be shown the "waiting for processing" notice on their Webpages, and it will be up to the Master to advance the game to the next phase using the PROCESS command sent to the e-mail interface. (Deadlines will still be in force for these phases, however.)

BEGIN season year phaseType
Specifies the initial game phase. This line is optional; if it is omitted, the initial game phase will be SPRING 1901 MOVEMENT. Only the final BEGIN listed in the map file will be used. This allows for map files to USE other map files and then override the start phase.

OWNS center...
Specifies the list of centers owned by the "current power" at the beginning of the game. If not specified, the list of initially owned centers is set to the home centers that were listed for the "current power." One or more of the centers may be SC!, which allows the player to place a build on any vacant home center (and become its owner) despite the fact that he does not own it at the start of the game. Additionally, SC? may be used, to indicate an ability to build in any unoccupied home center and not take ownership of the center.

CENTERS [center...]
Same as OWNS, but forgets about any previous OWNS lines. If no center is given, the power will start with no centers at all (if not followed by any new OWNS lines that is).

INHABITS center...
Sets the home centers for this power, overwriting any that are given on the power declaration line, including partisan and factory sites.

HOME(S) [center...]
Same as INHABITS, but forgets about any previous INHABITS lines. If no center is given, the power will start with no build sites at all (if not followed by any new INHABITS lines that is).

RESERVES [count]
A RESERVES line given for the "current power" indicates that the power is eligible to maintain count extra unit(s) (default is one), over and above the power's supply center count. However, this is only true if the power owns at least one of its original home centers. Only the final-given RESERVES line will be used -- the counts for multiple RESERVES lines are not added.

MILITIA [count]
Militia are similar to RESERVES (above), except that they are only granted if the additional force is used for home defense. For each MILITIA, the power is eligible to maintain one extra unit, over and above the power's supply center count for each of his units that is positioned atop a home supply center when an adjustment phase arrives. Only the final-given MILITIA line will be used -- the counts for multiple MILITIA lines are not added.

UNITS
This line is optional. If given, all units that have been listed as initial units for the "current power" are immediately forgotten. This can be used to alter the starting position of a power from that given in a USEd file.

unit
Specifies a unit that the current power owns at the beginning of the game. The unit will replace any unit that may have previously been listed as beginning in that same space,
Dynamic Directives

IN phase ... -or-
IN phaseAbbrev ...
Indicates that one or more map directives are to be applied to the map (modifying any current settings) during specific game phases. This can be used to cause spaces to change terrain (or become impassable, if the terrain is SHUT) in specific seasons. The IN directive introduces directives to be run only in phases that match the given phase. The phase may be either a complete phaseAbbreviation (such as S1904M) or may be any initial part of a fully-written phase name (such as SPRING or SPRING 1904). For example, IN SPRING will introduce a directive or directives to be applied whenever the current game phase begins with SPRING. If a single map directive is to be applied, it may be specified on the same line as the IN, separated from it by a colon. For example:
     IN SPRING: WATER ARC
Alternatively, multiple directives may be given, each on its own line, below the IN directive. Note that in this case (where directives are given on subsequent lines of the file), all subsequent lines until the end of the file will apply to the most recent IN (or FROM, as described below). To return to giving directives that apply at all times, use the directive FROM START.

FROM movementPhaseAbbrev ... -or-
FROM START
The FROM directive is similar to the IN directive (discussed above) except that the directive or directives are applied once the indicated phaseAbbr has been reached, and remain in effect thereafter. The same forms as allowed by the IN directive (that is, single- or multiple-line) are supported, but the movementPhaseAbbreviation given must be a complete phase abbreviation (such as S1904M). That is, it may not be a fully-written phase name or any initial part thereof (as can be given in an IN directive), and it may not indicate any phase type other than movement. When using the multiple-line form of the directive, the directive FROM START can be used to return to giving directives that apply at all times. Note that when a .map file is loaded, all directives in FROM clauses, including any applying to the current phase, are processed (in the order in which the phases occurred), and then any IN clause(s) are processed for the current phase.
Behavioral Directives

[variant] DIRECTIVE[S] -and-
END DIRECTIVE[S]
All lines between the beginning of a DIRECTIVE stanza and its END (or the end of the map file) will be considered to be part of the status file of any game using this map. If a variant is specified, then the lines in the stanza are only in-force if the game uses the particular variant (STANDARD, PAYOLA, and so on). Note that any line that is legal in a status file can appear in such a stanza; the lines are not limited to those described on this Webpage.

RULE[S] rule...
Specifies a DPjudge RULE that will be in effect for all games using this map. For example, RULE BUILD_ANY would appear in a map file for the Chaos variant, since that variant allows players to build new units in any unoccupied, owned supply center. If this line occurs outside of a DIRECTIVE stanza, it will be in effect for all games using this map, regardless of any rules-variant (payola, etc.) that the game may use. Note that if any rule name is prepended by exclamation point (!), that rule will be turned off if possible, and this will be done after all other RULEs have been processed.
The DPjudge is copyright © 1995-2017 by Manus Hand. All rights reserved.