DPjudge Status File Format
about the DPjudge | the DPPD | common questions
1. Information Pertaining to All Games
1.1 Game Information

GAME name
This line simply gives the name of the game. It is optional. Since all information on a game is contained in a dedicated subdirectory with the same name as the game, the game name is technically known, but is inserted into the status file (if not already present) simply to aid in game identification if the status file is misplaced somehow. The game name must match the game's subdirectory or an error will be generated.

PHASE phaseName -or-
AWAIT phaseName -or-
SKIP phaseName -or-
WAIT phaseName
Specifies the current phase of the game. If the word AWAIT appears, no changes can be made (except by the Master) to the status file, as this signifies that results of a phase are currently being automatically generated by the judge. The phaseName must either be the single word FORMING, the single word COMPLETED, or must be exactly three words in length, giving the season, year, and type of the current game-phase. The year must be numeric. For example:
         SPRING 1901 MOVEMENT

If the line begins with SKIP, this indicates that no orders are to be solicited for the listed phase. This is rarely used, but one use for it is in Crystal Ball games that begin with an empty board -- this allows players to enter moves (during the previous, "SKIPped" movement phase) and then after locking those moves in, build their units in an adjustment phase.

If the first word is WAIT, this means that the game is waiting for the Master to process the turn. This can happen when the game phase is not recognized by the variant (e.g. an INCOME phase in a Standard game or a phase intentionally inserted into the map FLOW to give the Master the opportunity to implement a rule not supported by the DPjudge). Similar to the WAIT flag for players, the phase will eventually be advanced when the deadline passes if the Master omits to process it himself. Note that the normal way for a Master to prevent the turn from processing is to temporarily change the status from "active" to "waiting", in which case the deadline is simply ignored.

Important: The DPjudge will automatically change the PHASE from FORMING to (for example) SPRING 1901 MOVEMENT when the final needed player JOINs (unless the START_MASTER rule is in effect), and will also change the PHASE to COMPLETED when the game completes. In both these cases, the update to the PHASE line is not the only thing that must be done to change the game's status either to or from "active." Therefore, the PHASE should only be manually modified by the GameMaster when setting up a specific position in a game already in progress. In all other cases, allow the DPjudge to modify the PHASE automatically, or use the "Current Game State" pulldown on the Master's Web page.

DEADLINE yyyymmddhhmm
This line specifies the time and date of the current deadline. The system will automatically update this line when a move processes.

The DPjudge will automatically set the initial deadline of the game when the game begins. The initial deadline will be twice as long as a normal deadline for its type of phase (see TIMING, below).

The DPjudge will never automatically set a deadline that is earlier than any current value of DEADLINE (though of course the GM may manually move the current deadline earlier).

Note that the deadline should be expressed in the game's local time ZONE (see below).

ZONE timeZone
Specifies the time zone for the game, as an alphabetic string recognized by the underlying computing system. Some example ZONEs are: America/New_York, America/Denver, Europe/Paris, Europe/London, etc. Games without a ZONE line will run on GMT.

TIMING key value...
This line specifies the timing data used to set deadlines. It consists of any number of key/value pairs, which are recognized as follows:
AT hh:mm[,hh:mm...]
Specifies the times-of-day at which all deadlines should occur. The hour is specified using a 24-hour clock, and based on the game's timezone. Deadlines need to respect the DPjudge turn processing schedule and thus can only occur at 0, 20 or 40 minutes past the hour, unless it's a REAL_TIME game or the delay (see NEXT) is less than 20 minutes. If you specify a time-of-day that falls in between, the deadline will be adjusted upwards to the next valid time slot. Note that when a deadline is to be set less than 12 hours in the future (or less than half the gap between the previous and next time-of-day if more than one gets specified), AT is ignored. Otherwise, all deadlines will fall at the next occuring specified time-of-day after or around (see FUDGE ) the requisite delay period has passed.
FUDGE delay
Specifies the amount of fudge time, pushing the deadline to an earlier time-of-day in case the previous deadline was only shortly exceeded. The delay must be some positive whole number followed by either M (for minutes), or H (for hours). The default is one third the gap between the previous and next time-of-day (given in the AT data of the TIMING), while the maximum is half that same gap (respectively, 8 and 12 hours in case only one time-of-day is specified). The minimum is 1 minute in REAL_TIME games and 20 minutes otherwise. This setting gets ignored if there's no AT timing parameter.
DAYS dayList
Specifies the days of the week on which the deadline could fall. The dayList must be seven characters in length, with the first character representing Sunday and each subsequent letter representing Monday, Tuesday, etc. The letter at each position must either be the first letter of the day name (that is, S for Sunday, etc.), which indicates that the deadline may fall on that day of the week, or a dash (-), which indicates that it may not. If not provided, the game will use -MTWTF- as its DAYS control. If the day-letter is in UPPER-CASE, this indicates that deadlines for any phase may be set on that day. If it is in lower-case, this indicates that movement phase deadlines may not be set on that day. (Therefore, at least one of the days must be specified in upper-case.)
START delay
Specifies an offset relative to 00:00, midnight to determine when skipped days start and end. The delay can be negative. E.g. if this parameter is set to 8H and DAYS is left as the default, no deadlines will be set between Saturday 08:00 and Monday 07:59. If it's -2H the blackout period is from Friday 22:00 to Sunday 21:59. Absences expressed in full days are affected in the same way.
NEXT delay
Specifies the default time period to be used to set the next deadline. The delay must be some positive whole number followed by either M (for minutes), H (for hours), D (for days), or W (for weeks). There's a catch though. In combination with the AT control, delays specified in days or weeks have an 8 hour fudge period. Late orders entered in this period will not cause the deadline to be pushed back for the full delay period and then some, but will be set to the AT time-of-day of the previous day as if the orders had been entered on time (or on the most recent AT time-of-day if the player is a couple of days late). This means that e.g. a 1D delay actually acts the same add a 16H delay. You must specify the delay in hours (or minutes) instead (e.g. 24H) if you want to guarantee at least a full day until the next deadline. See below for the default value if no NEXT control is given.
phaseType delay
Specifies a time period to be used (instead of the value from NEXT) for any phase whose final word begins with the letters making up phaseType. For example, to set a game to have one-day deadlines for all phases except movement phases, which should have three-day deadlines (note that these are the default settings for any game not given a NEXT or appropriate phaseType control), use:
WARN delay[,delay...]
Specifies a time span before the deadline at which time any players who have not yet submitted orders will be sent a "friendly reminder." If this option is not specified, warning is given four hours before the deadline. To prevent warnings from being given, specify a delay of 0 (or any value greater than the length of the deadline delay). Multiple warnings may be specified, by separating the time controls from each other using a comma with no whitespace. For example, to specify that warnings should be given to players without submitted orders one day before the deadline and then again at twelve hours and at six hours before the deadline, use:
         TIMING WARN 1D,12H,6H
GRACE delay
Specifies a time span after the deadline. Whenever that time span expires before the game-phase processes, any player who still has not submitted orders will either be automatically resigned or (in games using the CIVIL_DISORDER rule) declared to be in civil disorder. In games without a GRACE period set in the TIMING line:
  • players are never automatically resigned (note that immediate resignation of late players when the deadline hits can be specified by setting the grace period to zero, such as GRACE 0H), and
  • civil disorder processing (in games using the CIVIL_DISORDER rule) occurs at the deadline (no waiting).
NOT vacationInfo
Specifies one or more upcoming vacations, during which time no deadline should be set. The format of vacationInfo is the same as the format of the game's DEADLINE (that is, yyyymmddhhmm but can be shortened in length to omit days, hours, or minutes). A vacation spanning more than a single day can be specified by listing the first and last day of the suspension separated by a dash (-). The first day may be omitted, indicating a suspension from the current date. Multiple vacations can be listed by separating them from each other with a comma (and no whitespace). For example:
     TIMING NOT 20040831,20040920-20040927
specifies that no deadline should occur on 31 August 2004 or between 20 September and 27 September (inclusive) of 2004. Vacations are removed automatically whenever a deadline is set beyond the end of the vacation.
     TIMING NOT -20020812
specifies that the next deadline should not occur until on or after 12 August 2002.

DELAY delayCount
Specifies the number of deadline checks (which happen automatically every twenty minutes) that should occur without processing this game, despite the fact that the game is ready for processing. The delayCount is decremented once when each such deadline check occurs. This line is automatically inserted (with a delayCount of 1) when the last player enters orders for a turn (assuming there is no outstanding "wait for the deadline" request), and is also set to 24 (eight hours) when a late notice is sent out. Note that a PROCESS command sent to the e-mail interface will ignore any DELAY and will process the game (if ready for processing) immediately. Whenever a game is PREVIEWed automatically, the DELAY is set to 72, which is the (one full day) maximum allowable setting.

PRIVATE privacyWord
Used to designate a game open only to invited players (who have been given the privacyWord by the GameMaster). The privacy keyword specified is required after a player's password in a JOIN, TAKEOVER, or similar command. By marking a game PRIVATE in this way, only invited players should be able to get into the game. Drop the privacyWord parameter to make an already private game public.

RULE rule...
Specifies one or more rule that will be in force for the game. Consult the complete set of rules for details on the functionality of any specific RULE. 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. Note that all RULE lines must be specified before any power-specific directives are given in the status file.

MAP mapName -or-
TRIAL mapName
Specifies the game map to be used. If not given, the mapName will default to standard. Map files have the extension .map and must be installed in the map directory at the DPjudge site or, in case of trial maps, in the trial directory. A trial map is a map in development, or whose functionality (special rules, etc.) is not yet fully supported. Games played on trial maps can only be created through mail. The judgekeeper will automatically be informed of any trial games created. The map file syntax description should be consulted to create any new map. The supported maps, including trial maps, are listed and viewable on the map files list.

MORPH mapFileLine -or-
This line is used to add a new mapFileLine to the map being used for the game. The mapFileLine should be a properly formatted line that could appear in a map file, according to the map file syntax description. In this way, existing maps may be altered in various ways (providing that the underlying graphical support map is compatible with the additional lines and need not be updated). To add more than one line, either use multiple MORPH lines or start with a single MORPH stanza on one line, followed by the map file lines, and finished by END MORPH on a separate line. Any blank lines are ignored.

TEAM[S] powerName-...-powerName ...
This command creates teams that can be controlled by a single player. The first power name becomes the controlling (main) power, the other powers, connected to the first one by hyphens, become dummies controlled by the main power. Only the main power can be a non-map power. More than one team can be specified on the same line by separating them with spaces. If the power name contains a hyphen, omit it. For example an Empire game could have the following team pairings:
   TEAMS B.C.-California Cuba-Florida Heartland-Mexico
   TEAMS NewYork-Peru Quebec-Texas
Note: Team games are called duplex games on KL judges.

MASTER dppdData
Specifies the DPPD (DP Player Database) ID number, e-mail address, and name of the GameMaster. The dppdData must be in standard DPPD ID format; for example: #42|joe@blow.com|Joe_Blow

PASSWORD masterPassword
Specifies the GameMaster's password. The masterPassword can be used to access all player pages, send press as any player via the e-mail interface, and access the GameMaster's Web page.

TESTER [email]
Used primarily for debugging. Sends mail only to the specified address, not to any of the players, observers, or even the master. If no address is given, sends no mail at all.

START gameStartDate
Game start date. This information is automatically provided when the game starts, or can be manually inserted by the GameMaster.

FINISH endDate
Day on which the game ended.

RESULT lastPhase victor...
Game termination information. The lastPhase is the final phase of the game that was played, and each victor is one of the powers achieving a place in the draw (or, in the case of a single victor, a solo win). This line is inserted automatically when the game is completed.

DESC[RIPTION] gameDescription -or-
Description of the game. Multiple DESC lines may be used if needed. Alternatively, start with a single DESC stanza on one line, followed by the game description across multiple lines, and finished by END DESC on a separate line. Any blank lines are ignored. Use html tags to format the text. Completely ignored, but will show up on the Web page in the information table for the game.

NAME gameNameOrigin -or-
Origin of the game's name. Syntax identical to DESC. Completely ignored, but will show up on the Web page in the information table for the game.

ALLOW nonMapPowerType...
Permits players to assume roles other than leaders of map powers. Observers are ALLOWed by default, but other types of players may be allowed into the game and may play various roles as supported by the code. For example, Exchange variant games ALLOW INVESTORs who can serve as controller of a power.

PROPOSAL result proposingPower
This line will appear only in games that use the PROPOSE_DIAS rule. It specifies the currently proposed game conclusion. All players owning supply centers will be permitted to vote on this proposal. (A "veto" vote will remove the PROPOSAL; otherwise, if all players agree to it, the game ends as proposed.)

NEED availablePowers
Important: A Master should never add or modify a NEED line! These should always be left to the DPjudge to add and remove when e-mailed JOIN, RESIGN and TAKEOVER commands are received!
This type of line is used to specify available (abandoned or otherwise unfilled) positions. The data given in availablePowers is automatically generated. Each whitespace separated word in availablePowers consists of the name of an abandoned power, followed by its unit and center count -- for example, GERMANY-(8/9).

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 CONTROL directive later in this documentation.) The "ROTATE" and "ROTATE CONTROL" directives are identical -- they direct that power control will change hands immediately before any phase in which the power will have orders to issue. The "ROTATE AFTER" directive indicates that control will pass to the next player after each and every phase, regardless of whether the power will have orders to issue. You may also specify a specific phase type by its first initial. When used with AFTER, control will rotate after the specific phase type. When used with BEFORE, control will rotate immediately before the given phase type. When used with FOR, control will rotate before the given phase type if and only if the power will have orders to issue. For example,
indicates that control will change before each and every movement phase. As a second example,
indicates that control will rotate before each and every movement phase, and also, that control for any power who has a retreat order to issue will be rotated before the retreat phase.

1.2 Power Information

[POWER] powerName -or-
[POWER] powerID -or-
OBSERVER observerName -or-
otherType playerName
Marks the beginning of data for a particular player. All lines below (until another line indicating a power or player) will pertain to the power or player listed. While a game is FORMING, players who have JOINed appear in the file as either the powerName that the player will be assigned, or using a powerID of the form POWER#1, POWER#2, etc. Note that the word POWER is optional in all cases.

ADDRESS playerEmail[,otherEmail...]
Specifies the e-mail address or addresses of the current player of the power. All mail sent to the power (including "press sent" mailings for messages sent from the Web interface) will be sent to all listed addresses. If an e-mail containing a valid SIGNON for a power is received from an e-mail address that is not listed in the power's ADDRESS line, the reply to the processed e-mail will be sent to the playerEmail address(es).

PLAYER playerData [phase priorPlayerData...] -or-
PLAYER RESIGNED [phase priorPlayerData...] -or-
PLAYER DUMMY [phase priorPlayerData...]
Specifies the history of all players of the power, including the present player. The playerData is the player's DPPD ID number, e-mail address, and name, given in standard DPPD format. For example:
     PLAYER #42|joe@blow.com|Joe_Blow
The phase is the game phase (in the form S1901M, etc.) in which the player took over the power (and therefore the phase in which the prior player resigned the power). Any priorPlayerData is similarly formatted, and provides a history of all prior players of a power. For example:
     PLAYER #42|joe@blow.com|Joe_Blow S1911R NO-ID|john@doe.net|
would indicate that john@doe.net (who has no DPPD ID number, and therefore his name is not known) played the power until the Spring 1911 Retreat phase, when Joe Blow (DPPD ID number 42) took over. Before Joe Blow sent in his TAKEOVER command, the PLAYER line looked like this:
     PLAYER RESIGNED S1911R NO-ID|john@doe.net|
If the first word on a PLAYER line is DUMMY or RESIGNED, the player is not e-mailable.
Important: A Master should never manually add RESIGNED to any PLAYER line! The addition and removal of RESIGNED must always be left to the DPjudge to do when e-mailed RESIGN and TAKEOVER commands are received!
  • DUMMY is used if the power will or may receive orders without a specific person playing the power (for example, the Master could enter orders for the power, or other players could be responsible for entering the orders, etc.), or no orders will be entered for it at all (civil disorder). A Master may create DUMMY powers before game-start (that is, by adding
    (etc., etc.) to the status file to cause a certain number of powers to be unassigned to human players. If the CD_DUMMIES rule is in effect, DUMMY powers without orders will be considered to be in civil disorder as soon as all other powers either have submitted orders (and not set their WAIT flag) or have been declared in civil disorder (by the operation of the CIVIL_DISORDER rule).
  • RESIGNED is used when a position is in need of replacement, and a NEED line should appear in the status file describing the missing position. If the CIVIL_DISORDER rule is in effect, any power without submitted orders (including DUMMY powers, but not including those marked RESIGNED), will be considered to be in civil disorder when a deadline occurs, and the phase will process without orders from the power.
Note that while a player may change his ADDRESS information (through use of the SET ADDRESS e-mail directive), except by resignation, a player cannot change the PLAYER line information. Only the Master may do so by modification of the status file.

PASSWORD password
Specifies the password for the player. This line may not appear for any power that has a CONTROL.

CONTROL powerName...
Specifies a list of one or more players who may take control (for order entry, press writing, etc.) of the power. This list is used by the ROTATE command to cause power control to be rotated through other players. The first player in the list is the player currently in control of the power, and the list will rotate from the last power listed back to the first power. This line may not appear for any power that has a PASSWORD. Powers with another player in CONTROL are not shown in the list of powers that can be "logged on," but if a player is in CONTROL of a power, that player will be able to log in as that power from his own page. For example:
indicates that the power is currently controlled by Austria, and that the next time control is ROTATEd, it will be controlled by France, and then on the next rotation, by Italy, etc. The CONTROL scheme is used when setting up a "Missing Man" variant game. In the e-mailed CREATE message (or in the status file before the players JOIN), the Master would create POWER stanzas for any powers not to be played as a series of MORPH lines. For example, if Italy and Germany are to be played missing, controlled by the other players, the status file could contain:



You could also let a single player control the same power the whole game, thereby effectively allowing him to play two powers. If everyone is given a second power (on maps with an even number of powers), the game would only need half the normal number of players. In such a case it makes sense to add the TEAM_VICTORY rule, so that the combined SC total of the powers a player controls determines his victory score.

Specifies a player's desired game termination In games using the PROPOSE_DIAS (or the HIDE_PROPOSER) rule, the vote may only be YES, which indicates that the player is in agreement with the current PROPOSAL. (If any player ever votes otherwise, the proposal and all votes for it will be forgotten.) In games not using the PROPOSE_DIAS rule, each player votes either for a solo victory for himself, or a loss (meaning that the votes of the other players will be used to determine any game resolution) or for a maximum size of draw (including his power) that he will accept. In games not using the NO_DIAS rule, the only allowable n value in an nWAY vote is greater than or equal to the number of players owning supply centers (this signifies a vote for a draw including all survivors).

OWNS center...
Specifies all supply centers owned by a power. In the initial phase of the game (only), one or more of the centers may be SC! to indicate an ability to build in any unowned home center and thereby gain control of that center. It may also be SC? to indicate an ability to build in any unoccupied home center and not take control of the center. Finally, it may be SC* to indicate an ability to build in one of that power's partisan build sites (see the map file documentation).

Specifies that the power wishes that the deadline be reached before the game processes.

unit -or-
unit --> retreatList
Specifies a unit (type and position) owned by the power. If a unit is in retreat from a location, it is followed by an arrow and a retreatList, which is a space-separated list of all the possible locations to which the unit may legally retreat.

RETREAT unit location
Specifies a retreat order to be issued.

Specifies a disband order to be issued in a retreat phase.

BUILD unit -or-
Specifies a build order to be issued in an adjustment phase.

Specifies a remove order to be issued in an adjustment phase.

MSG message
Specifies a message to be shown to the player on his Web page. Player-specific messages and data can, in this way, be provided and updated at will by the Master.

If this line appears, the power (or observer)'s password can be used for read-only viewing of all other power's Web pages (except the Master), and all press messages will be available for viewing when logged in as this power (or observer). Additionally, in BLIND games, an OMNISCIENT power or observer has a full view of the game map, and receives complete game results. If the exclamation point is appended, the player will also receive a copy of all press messages by email.

HOME center...
Provides a list of home supply centers (using the DPjudge's standard place-name abbreviations), if different from those given in the game's map file. This line is used in games in which the home supply centers for powers will change during the game. The line is automatically added on any schedule specified in the .map file for the variant, and when any power builds a new unit to take advantage of the ability to claim to a new home supply center (indicated by the &SC directive described in the Map file documentation).

FUNDS [fund...]
Specifies the funds at the player's disposal. A fund is either of the form $num (which specifies the power's cash-on-hand) or numCURRENCY, which specifies his holdings in some other currency. For example, a power with thirty-four units of cash, twelve units of stock in England, and twenty-two units of postage (to use in sending press messages) might be written:
     FUNDS $34 12E 22c
Obviously, the FUNDS line is variant-specific, and it is not used in the standard game.

SEES center...
(This is only seen in BLIND games that do not use the NO_UNITS_SEE, SEE_NO_SCS, or SEE_ALL_SCS rules.) Specifies all supply centers that can be "seen" by a power. This data is automatically generated and is necessary to assist in the generation of results.
2. Information Pertaining To Standard Games

2.1 Power Information

Marks the beginning of the player's order list. All lines after this line are initially presumed to be an order.

A (movement phase) order to be issued by the player.
3. Information Pertaining To Payola Games

3.1 Game Information

CAP value
Specifies the maximum silver piece income to be awarded to any power in each income phase.

TAX [center] value
Specifies a silver piece amount to be awarded in each income phase for possession of a supply center. If the center is omitted, the value is the tax award for each and every supply center.

3.2 Power Information

ACCEPT acceptList
Specifies the power's current acceptance list.

An offer being made to a unit.

SENT powerName
Specifies a power to which the current player has transferred funds during the current phase of the game. This is used only if the game is run under the ONE_TRANSFER rule.
4. Information Pertaining To Crystal Ball Games

4.1 Power Information

Marks the beginning of one of the two "pipelined" order lists. All orders after either of these lines will be associated with the appropriate order list.

An order to be added to either the SOONER or LATER order list.

In addition to the status file for each game (the lines within which are described above), there is also a separate, single "main status file" used by the DPjudge to track and control all its games. Each line in this "main status file" contains (in a space-separated list) the following information on a single game: the game name, its rule variant (standard, payola, etc.), its general status (active, forming, waiting, completed), and then any number of other flags controllable only by the system and/or the judgekeeper (unlisted, suspect, corrupt, held, etc.). This overall status file is directly editable by the judgekeeper only. A game's Master cannot look at or modify the data for any game in the "main status file" other than through the supported Web and e-mail functionality of the DPjudge. A "suspect" game will be automatically monitored by the judgekeeper, a "corrupt" game will be locked against all changes, even by its Master, a "held" game will never be examined by the deadline checker (until its "held" status is removed), and an "unlisted" game will not show up in any list of games being run on the DPjudge.
The DPjudge is copyright © 1995-2024 by Manus Hand. All rights reserved.