DPjudge Status File Directives

1. Information Pertaining to All Games

1.1 Games

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

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 either that results of a phase are currently being automatically generated by the judge (or in the case of extra phases unimplemented in the DPjudge code, manually generated by the Master). 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

IMPORTANT: The DPjudge will automatically change the PHASE from FORMING to (for example) SPRING 1901 MOVEMENT when the final needed player JOINs, 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.

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 FLOW from the game's map file is used. 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.)

DEADLINE yyyymmddhhmm

This line specifies the time and date of the current deadline. The system will automatically update this line when a move processes, if and only if the game is being run on the DPjudge (if run on the Ken Lowe judge, this line should not appear, and will be ignored).

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

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

Specifies the time-of-day at which all deadlines should occur. The hour is specified using a 24-hour clock, and based at the DPjudge's timezone. If a deadline is to be set less than 24 hours in the future, AT is ignored. Otherwise, all deadlines will fall at the next occuring specified time-of-day after the requisite delay period (see below).

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.

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). If not given, the game will use 3D for its NEXT control.

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, use:
         TIMING NEXT 1D MOVE 3D

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

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 (-). Multiple vacations can be listed by separating them from each other with a comma (and no whitespace). For example:
     TIMING NOT 19990831,19990920-19990927
specifies that no deadline should occur on 31 August 1999 or between 20 September and 27 September (inclusive) of 1999. Vacations are removed automatically whenever a deadline is set beyond the end of the vacation.

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.

JUDGE judgeAddr [otherInfo]

Specifies the Ken Lowe judge on which the game is being run. If the game is not being run on a Ken Lowe judge, this line should not appear in the status file. The judgeAddr is the e-mail address of the judge, and any otherInfo on the line is ignored but will appear on the Web in the description table for the game.

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.

MAP 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. The map file syntax description should be consulted to create any new map.

terrainType mapSpace [ABUTS [abut...]]

Modifies the terrain type and adjacency information of any given space on the map. The terrainType must be LAND, COAST, WATER, PORT, or SHUT. If a mapSpace appears in more than one such line in the status file, only the last terrain type modification is obeyed. Note that the mapSpace must identify a pre-existing space on the map, and that all the rules concerning the use of upper- and lower-case letters in the location abbreviations will apply (see the map file syntax documentation).

VICTORY supplyCount...

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). If this line is omitted, the victory condition is taken from the MAP file.

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|[email protected]|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.

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.

SIGNON kenLoweJudgeSignonParameters

Parameters to be sent along with the SIGNON command to the Ken Lowe judge for the game (for example: crowded gunboat. Completely ignored, but will show up on the Web page in the information table for any forming game that is using a Ken Lowe judge.

DESC gameDescription

Description of the game. Multiple DESC lines may be used if needed. Completely ignored, but will show up on the Web page in the information table for the game.

NAME gameNameOrigin

Origin of the game's name. 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 CEO 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

Used to specify available (abandoned or otherwise unfilled) positions. The data given in availablePowers is automatically generated. For a game that is forming, it will consist of a single number (for example, 3 or 4) that specifies how many powers are yet to JOIN. (The Master may lower this number to cause some of the powers to be unplayed.) For a game that is active, each word will begin with the name of an abandoned power, with its unit and center count provided -- for example, GERMANY-(8/9).

1.2 Powers

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 with the leading word POWER and with a powerID that is either the powerName that the player will be assigned, or an identifier of the form POWER#1, POWER#2, etc. After a game is no longer FORMING, all such players will automatically be re-listed as simply each specific powerName (without the leading word POWER).

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|[email protected]|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|[email protected]|Joe_Blow S1911R NO-ID|[email protected]|
would indicate that [email protected] (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|[email protected]|
If the first word on a PLAYER line is RESIGNED or DUMMY, the player is not e-mailable. DUMMY is used when the Master will enter orders for the power or if the power is in CIVIL_DISORDER (if the appropriate RULE is in effect). RESIGNED is used when a position is either in need of replacement or (again, if the appropriate RULE is in effect) will be played in CIVIL_DISORDER.

Note that while a player may change his ADDRESS information through use of the SET ADDRESS e-mail directive, he cannot change the PLAYER information.

PASSWORD password

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

CEO powerName

Specifies another player who is serving as "chief executive officer" of the power. This line may not appear for any power that has a PASSWORD. Powers with CEOs rather than PASSWORDs are not shown in the list of powers as whom a player can "log on" but if a player is the CEO of a power will be able to log in as that power from his own page.

VOTE YES -or-
VOTE LOSS -or-
VOTE SOLO -or-
VOTE nWAY

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.

WAIT

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 retreatOrder

Specifies a retreat order to be issued. A retreatOrder is either "DISBAND" or has the form "- location".

BUILD unit -or-
BUILD WAIVED

Specifies a build order to be issued.

REMOVE unit

Specifies a remove order to be issued.

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.

OMNISCIENT

If this line appears, the power's password can be used for read-only viewing of all other power's Web pages (except the Master), and the player will receive a copy of all press messages.

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.

2. Information Pertaining To Standard Games

2.1 Powers

ORDERS

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

order

A (movement phase) order to be issued by the player.

3. Information Pertaining To Payola Games

3.1 Games

TAX center value

Specifies a silver piece amount to be awarded annually for possession of a supply center.

3.2 Powers

ACCEPT acceptList

Specifies the power's current acceptance list.

offer

A bribe offer.

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

GAIN amount

Specifies the amount of money received by a power's units as bribe income during the current game-year (to be deposited into the player's treasury at the end of the year). This is used only if the game is a ZEROSUM variant game.

4. Information Pertaining To Crystal Ball Games

4.1 Powers

SOONER -or-
LATER

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.

order

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