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:
TIMING NEXT 1D MOVE 2D
- 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-
MORPH mapFileLines END MORPH -
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-
DESC[RIPTION] gameDescription END DESC[RIPTION] -
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-
NAME gameNameOrigin END NAME -
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 [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
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,
ROTATE BEFORE MOVE
indicates that control will change before each and every movement
phase. As a second example,
ROTATE BEFORE MOVE FOR RETREAT
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
- POWER POWER#1
- PLAYER DUMMY
(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:
CONTROL AUSTRIA FRANCE ITALY RUSSIA
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:
MORPH
DUMMY ITALY GERMANY
POWER ITALY
CONTROL ENGLAND FRANCE RUSSIA TURKEY AUSTRIA
POWER GERMANY
CONTROL TURKEY AUSTRIA ENGLAND FRANCE RUSSIA
END MORPH
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.
- 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
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).
- 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 - location
-
Specifies a retreat order to be issued.
- DISBAND unit
-
Specifies a disband order to be issued in a retreat phase.
- BUILD unit -or-
BUILD WAIVED -
Specifies a build order to be issued in an adjustment phase.
- REMOVE unit
-
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.
- OMNISCIENT -or-
OMNISCIENT! -
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.
|
|