This file contains text for dip.exe help menu options.

%Overview

Program DIP enables a game of Diplomacy to be edited and adjudicated. Options exist for setting up a game situation, entering orders and determining the outcome of the orders.

Orders are entered and executed in three separate stages as moves, retreats (for units dislodged during moves) and adjustments (in Autumn moves only). These stages are controlled by the options in the game menu.

This help text does not contain the full rules of Diplomacy. It is assumed that the user is familiar with this game before using the program.

%-

%File menu

The File menu contains the usual Windows file options. "Blank" sets up a game situation with no units on the map. "New" resets the situation to Spring 1901. "Open", "Save" and "Save As" manage files in which the game situation is saved. The default file extension for a game situation is .dip, and if you associate dip.exe with this file type, you can start the program by double-clicking a .dip file.

"Print" sends the map and text for the current move to a printer. When printing in colour, use "Text/Graph" setting rather than a photographic setting in the printer driver if available. Transferring the map to the printer as a bitmap takes some time.

The File menu contains two options for reporting results. "Export bitmap" enables the current map to be written to a Windows .bmp file. "Export text" gives a report of all the moves, retreats and adjustments done so far in the current season.

Finally, the File menu contains an "Animate move" option which animates the current move and an "Animate game" option which enables all the files for a single game of Diplomacy to be displayed in sequence. These options can only be used if a file is already open. For "Animate game" the program searches for all other files making up the game which the current open file belongs to, by trying to find a string of the form "Snn" or "Ann" within the file name where "nn" are digits. E.g. if the file "xyz_a05.dip" is already open, the program will search for files "xyz_s01.dip", "xyz_a01.dip", "xyz_s02.dip"... and assume that these all belong to the same game. All the files found are then displayed in sequence to give an impression of the whole game. Only turns which have been saved at the "Season finished" stage can be fully animated.

Three toolbar buttons are provided, for quick access to the "File - Open", "File - Save" and "File - Export text" menu items.

%Edit menu

The Edit menu only contains one option, "Copy", which causes the currently displayed map to be copied to the clipboard as a bitmap. It may then be pasted into other applications.

%Map menu

The Map menu controls the display of the map on screen.

There are four settings giving colour with 3D pieces, colour, grey levels or black and white.

If the option to "Show centre count" is checked, the numbers of supply centres owned by the players are displayed at the right hand side of the map. Selecting the option again unchecks it.

If the option to "Show centre owners" is checked, all supply centres are given rectangular labels showing which country owns them. Selecting the option again unchecks it.

If the option to "View only" is checked, the program functions only as a viewer. The Game menu is disabled and no controls for entering orders are displayed. Selecting the option again unchecks it.

The "Unit colours" option enables the user to alter the colours used to display units and supply centre ownerships on the map.

Settings from the Map menu are stored in the file dip.ini, so they are retained from one run of the program to the next.

%Game menu

If the Map menu option "View only" is checked, the Game menu is disabled.

The Game menu controls progress through the game. At the start of a season the "Enter moves" option is checked, showing that the user can use the map and controls on the left to input orders, (see "Entering orders"). When the move orders are resolved, the game is moved on to the next stage of the season. If there are dislodged units, the "Enter retreats" option will be checked, and retreat orders may be entered, (see "Entering retreats"). After retreats, in a Autumn season the "Enter adjustments" option will be checked, and adjustments may be entered, (see "Entering adjustments"). Finally the end of the season will be reached. Save the game at this point if you wish to retain the game situation with its map and text. Then select the "Next season" option to move the game on to the start of the next season.

Two important things happen when the game is advanced to the next season. All text for moves, retreats and adjustments is cleared, and the file name is also cleared, so that a new name must be given before saving the situation again.

Also in the Game menu are options to "Edit units", "Edit provinces", "Edit season", "Edit title" and "Edit names". Selecting these enables editing of the game situation. See "Editing units", "Editing provinces", "Editing season", "Editing title" and "Editing names" for details.

The Game menu contained an "Undo move" option in previous versions. This has been removed as it could not be made to work correctly in all situations.

%Toolbar buttons

Three toolbar buttons are provided, for quick access to the "File - Open", "File - Save" and "File - Export text" menu items.

%-

%Entering orders

When orders for moves are being entered, a list of the orders entered so far is shown to the right of the map. Below this is a text box for entering a new order, together with some buttons to assist the typing.

Orders may be entered in two ways:-
(1) By simply typing them into the text box and clicking the "Enter" button.
(2) By clicking on the map to indicate the units being ordered. This is a fairly intuitive process. E.g., to order F(Lon)-NTH click once on F(Lon) and once in NTH; the order will then have been constructed in the text box and clicking "Enter" will add it to the list.

Note: when clicking on the map, bear in mind that there are two "hot spots" in each province. These are where the name is located and where a piece is shown (when one is present). When you click the map, the province selected is the one which has a "hot spot" nearest the mouse pointer. Provinces with more than one coast have multiple "hot spots". Clicking in irregular shaped provinces far from the name and piece location can cause the wrong province to be selected.

Double-clicking a unit enters a hold order for it. Holding SHIFT while clicking a unit enters the start of a support order for it. Holding CTRL while clicking a unit enters the start of a convoy order for it.

Clicking "Cancel" at any time clears the text box.
The "hold", "-", "S" and "C" buttons are typing aids for entering these character strings.

Syntax of orders is best understood from a few examples. The only unusual feature is that a three letter abbreviation for each country name must precede every order (so that the program knows who is giving the order). If orders are entered by clicking the map, these abbreviations are automatically included.
  RUS A(Mos) hold                  (a hold)
  ENG A(Lon) - NTH                 (a move)
  ENG F(Edi) S A(Lon) - NTH        (a support)
  ENG F(NTH) S GER A(Bel) - Hol    (a multinational support)
  ITA F(IOS) C A(Nap) - Tun        (a convoy)

If an incorrect order has already been entered, it may be deleted by clicking it in the main list and then clicking the "Delete" button.

Orders can be imported from a text file such as a previous .dip file directly into the list using the "Import" button, and the orders already in the list can be written to a text file using the "Export" button or copied to the clipboard using the "Copy" button. When "Import" is used, only lines which "look like" valid orders are imported, although the checking carried out is fairly simple.

Orders can also be pasted from the clipboard using the "Paste" button. Using this option it is first necessary to specify the country for which orders are being pasted in a dialog box. Then lines of text from the clipboard are processed (using more intelligence than in the "Import" case) and interpreted into orders. If a line of text cannot be completely interpreted, it will be displayed and may be edited by the user.

Right-clicking a supply centre shows who owns it.

Once all orders have been entered, click the "Resolve" button to resolve all the moves. The game situation is then advanced to the next stage.
    
%Entering retreats

Entering retreats is similar to entering moves. After the moves have been resolved, dislodged units are shown smaller. Only retreat orders for these can be given.

The orders can again be entered either by typing in the text box or by clicking on the map. E.g., to order "RUS A(StP) retreat Mos" click once on A(StP) and once on Mos. To order "RUS A(StP) disband" click once on A(StP) and once on the "disband" button. Double-clicking a unit also enters a disband order for it.

Provinces which are not open for retreats because of stand-offs during the move are indicated by a crossed swords symbol.

Right-clicking a unit shows the move order it was given. Right-clicking a supply centre shows who owns it.

After entering all the retreats, click the "Resolve" button. The game situation is then advanced to the next stage.

%Entering adjustments

Entering adjustments is similar to entering moves and retreats. The numbers of supply centres owned by each country and numbers of adjustments required (positive or negative) are listed. Valid adjustment orders are:-
  GER build A(Kie)
  ENG disband F(NTH)

Clicking a unit on the map places a disband order for it in the text box. Clicking a vacant home supply centre places a build order for an army in the text box; this can be changed into an order for a fleet by clicking the "A/F" button. Double-clicking a unit is equivalent to clicking it once and then clicking the "A/F" button.

Right-clicking a unit shows the order it was given.  Right-clicking a supply centre shows who owns it.

After entering all the adjustments, click the "Resolve" button. The game season is then finished.

%Finishing the season

Once the "Season Finished" message appears, clicking the "Next season" button advances the game to a new season. Note that this clears all the text stored for moves etc. carried out in the present season, so if you wish to export this text, or save the game situation with it preserved, this must be done before clicking the "Next season" button.

Right-clicking a unit shows the order it was given.  Right-clicking a supply centre shows who owns it.

%Saving results

Several methods can be used to save or output results from the program. The "Save" or "Save As" options in the "File" menu write a data file containing all information about the current position and the moves made in the current season. The default file extension for this file is ".dip", and it contains only ASCII text, so it can be examined with editors such as Notepad. If the file type ".dip" has been associated, DIP can be run just by double clicking a ".dip" file.

The current game situation can also be exported to other files or applications by the following methods:-

The "Export bitmap" option in the "File" menu allows the map on screen to be written to a standard Windows ".bmp" file.

The "Export text" option in the "File" menu allows all the text for moves, retreats and adjustments done so far this season to be written to a ".txt" file. This is useful for a game report.

The "Copy" option in the "Edit" menu copies the map on screen to the Clipboard as a bitmap image. It may then be pasted into another Windows application.

%-

%Editing units

Editing units is done directly on the map, after selecting the "Edit units" option from the "Game" menu. The left mouse button may be used to drag units to new locations. Right-clicking a unit or empty space opens a "Properties" window, in which the unit's nationality, type and status can be changed. This window can also be used to create and delete units.

%Editing provinces

After selecting the "Edit provinces" option from the "Game" menu, province settings can be altered. Clicking any province causes a "Properties" window to be opened. Within this window, the user can change supply centre ownership if the province is a supply centre, and also whether the province is open for retreat. (In a retreats stage, provinces where stand-offs took place in the moves stage are not open for retreat).

%Editing season

After selecting the "Edit season" option from the "Game" menu, the season ("Spring" or "Autumn"), year number and stage ("before moves", "before retreats", "before adjustments" or "season finished") can be altered. 

Be careful changing these, as impossible situations can be set up. E.g., "before adjustments" in a "Spring" move, or "season finished" when there are still dislodged units present.

%Editing title

Selecting the "Edit title" option from the "Game" menu enables the game title shown in the top left corner of the map to be altered.

%Editing names

Selecting the "Edit names" option from the "Game" menu enables the names of the players controlling the countries in the current game to be entered. These names will appear on exported text when moves for the countries are reported.

%-

%Province names

The default province names are unambiguous three letter abbreviations. Land province names contain lower case letters. Sea province names are fully upper case.

If you wish to use different name abbreviations, this can be done by editing the file fixnames.dat (or creating it if it is not already present in the same folder as dip.exe). Each line of this file should contain the default name and your new name, separated by a comma. Both names should have three characters, be case specific and unambiguous. Your new names will be used when the game situation is stored in a file, so if you distribute game situation files to other players make sure they have the same fixnames.dat file.

Removing name changes from the fixnames.dat file can cause problems when reading previously saved game situations containing the new names. For example, if you have previously used the change "IOS,ION" in fixnames.dat and then you cease to use this change, the program will report ION as an unknown province when you try to open a previously saved game situation. This can be overcome by explicitly specifying the change "ION,IOS" in fixnames.dat.

The default province names can be seen in the file prov.dat, which defines all the province locations, and the files conna.dat and connf.dat, which define connections between these provinces. Editing these files is not recommended.

%Algorithms

The most complex algorithm required in DIP is for the resolution of move orders. This is done by a method based on the observation that, when you adjudicate a move yourself, you don't evaluate whether the moves succeed one by one. Instead, you start by assuming that all the moves work and then look for contradictions.

After parsing the orders, checking for syntax errors, invalid orders and unordered units, DIP works through the following stages:-

(1) All non-convoyed moves are allowed to cut supports.

(2) All moves against convoying fleets are resolved.

(3) If any convoying fleets have been dislodged, the convoy moves fail.

(4) Convoyed moves which have not failed are allowed to cut supports.

(5) All moves not against convoying fleets are resolved.

Actual resolution of moves is split into stages (2) and (5), because of the rule that convoyed armies are not allowed to protect the convoying fleets. If a convoy fails, the convoyed army has no effect on its destination. In stages (2) and (5), resolution requires the following steps:-

(a) Determine the "force" of all moves and holds. "Force" is defined as 1 for a single unit, 2 for a unit with one support, etc.

(b) Resolve moves whose destination contains a unit moving the opposite way. Neither must be convoyed.
* If the opposing unit is of the same nationality, the move fails.
* If the opposing unit is of different nationality, the move succeeds only if it has more "force" than the opposing unit and all other moves into the province. The opposing unit is then dislodged, its "force" is set to zero and if it was supporting another move into the attacker's space, that move has its "force" reduced by 1. ("A dislodged unit has no effect on the space its attacker came from"). If the move does not succeed, it fails. (Possible dislodgement will be considered when resolving other moves).

(c) Resolve moves whose destination contains a non-moving unit. If the opposing unit tried to move out and failed, its "force" is set to 1 (it cannot receive support to hold).
* If the opposing unit is of the same nationality, the move fails.
* If the opposing unit is of different nationality, the move succeeds only if it has more "force" than the opposing unit and all other moves into the province. The opposing unit is then dislodged, its "force" is set to zero and if it was supporting another move into the attacker's space, that move has its "force" reduced by 1. ("A dislodged unit has no effect on the space its attacker came from"). If the move does not succeed, it fails. (Possible dislodgement will be considered when resolving other moves).

(d) Now all remaining unresolved moves are into spaces which are either empty or have units trying to move out. For each move:
* If the destination is empty, the move succeeds if it has more "force" than all other moves into the destination, otherwise it fails.
* If the destination is occupied by another unit trying to move out, and that unit's move is already resolved:
  - If the other unit's move succeeded, this move succeeds if it has
    more "force" than all other moves into the destination, otherwise
    it fails.
  - If the other unit's move failed, this move succeeds if it has more
    "force" than all other moves in, and it exceeds the occupying
    unit's holding "force" of 1. The occupying unit is then dislodged.
    Otherwise the move fails.
* If the destination is occupied by another unit trying to move out, and that unit's move is not already resolved:
  - The move fails if it does not have enough "force" to exceed other
    moves into the destination. Otherwise the move cannot be resolved
    yet.

(e) Any moves which could not be resolved in step (d) are involved in "convoy loops". They can be assumed to succeed.

%About DIP

!version
(C) 2000 R.W.Wills.
