manager/manual.txt

   1 NAME
   2         stratego - Interface to manage games of stratego between AI programs and/or human players
   3
   4 WARNING
   5         This program is still a work in progress. Consider it a Beta version.
   6
   7 SYNOPSIS
   8         stratego {[-gpirb] [-o output_file ] [-t stall_time] [-m max_turns] {red_player blue_player | -f input_file} | {-h | --help} }
   9
  10 DESCRIPTION
  11         stratego manages a game of Stratego. It stores the state of the board, and uses a simple protocol to interface with AI programs.
  12         By itself, stratego does not "play" the game. An external AI program must be used. stratego is intended to be used for the testing of
  13         various AI strategies, written in any programming language. It will be used for the UCC Programming Competition 2012.
  14
  15         Unless the -h (--help) or -f switch is given, both red_player and blue_player must be supplied.
  16
  17         red_player
  18                 Should be either a path to an executable file which will control the Red player, or "human".
  19                 If set to "human", stratego will request the user to make moves for the Red player using stdin.
  20                 NOTES
  21                         1. There is no plan to support AI programs named "human". Deal with it.
  22                         2. As of writing, human players must use stdin. A graphical interface may be added later.
  23
  24         blue_player
  25                 As red_player, except for controlling the Blue player.
  26
  27 OPTIONS
  28         -g
  29                 By default, graphics are disabled. If the -g switch is present, stratego will draw the game as it is played using OpenGL
  30         -p
  31                 By default, even if graphics are disabled, the board state is not printed. If -p is present, the board will be printed to stdout.
  32                 If the system supports colour, the characters will be in colour.
  33                 If -p and -g are both present you will see both behaviours (overkill)!
  34         -i
  35                 By default, stratego will exit if a move which is deemed "illegal" is made. If the -i switch is present, illegal moves will be ignored.
  36                 That is, the move will not be made (effectively the player making the illegal move loses a turn).
  37         -r
  38                 By default, the identities of all pieces are shown. If the -r switch is present, and graphics are enabled, red pieces will be disguised.
  39                 If graphics are disabled, the -r switch has no effect.
  40         -b
  41                 As -r, except blue pieces will be disguised.
  42                 NOTE: Both -r and -b may be used.
  43         -o
  44                 By default, stratego is silent. If the -o switch is present, the result of each move is printed to a file. If output_file is "stdout"
  45                 then stdout will be used instead of a text file.
  46         -t
  47                 By default, stratego executes moves as fast as they are recieved. If the -t switch is present, a delay of stall_time will be introduced
  48                 between each move.
  49
  50         -m
  51                 By default, the game is declared a Draw after 5000 turns have ellapsed.
  52                 Use this option to change the maximum number of turns.
  53                 To play for an infinite number of turns, supply "inf" as max_number.
  54
  55         -f
  56                 By default, stratego requires red_player and blue_player to enact a game.
  57                 If this option is supplied, a file previously produced by using the -o switch is read, and the game reenacted.
  58                 All switches function as normal with -f.
  59                 NOTE: It is recommended that -g is used with -f.
  60
  61         -h, --help
  62                 If the -h switch is used, this page will be printed and stratego will exit.
  63
  64
  65
  66 GAME RULES
  67                 Each player controls up to 40 pieces on the Board. The pieces consist of the following:
  68
  69                 Piece   Name            Rank    Number  Abilities
  70                 1       Marshal         1       1       Dies if attacked by Spy
  71                 2       General         2       1
  72                 3       Colonel         3       2
  73                 4       Major           4       3
  74                 5       Captain         5       4
  75                 6       Lieutenant      6       4
  76                 7       Sergeant        7       4
  77                 8       Miner           8       5       Destroys Bombs without being killed
  78                 9       Scout           9       8       May move more through multiple empty squares
  79                 s       Spy             10      1       If the Spy attacks the Marshal, the Marshal dies
  80                 B       Bomb            NA      6       Immobile. If any piece (except a Miner) encounters an enemy Bomb, both pieces are destroyed
  81                 F       Flag            NA      1       Immobile. If any piece encounters the enemy Flag, the controlling player wins.
  82
  83                 Additional pieces, not controlled by the player:
  84                 Piece   Name                    Number  Notes
  85                 +       Obstacle                8       Immobile. Do not belong to either player. Can't be passed through.
  86                 #       Enemy Piece             0 - 40  Indicates that the position on the board is occupied by an enemy piece.
  87                 .       Empty                   NA      Indicates that the position on the board is empty.
  88
  89                 Players take turns to move their pieces. RED begins the game.
  90
  91                 Pieces may only move one square horizontally or vertically unless otherwise stated.
  92                 Pieces may not move through squares occupied by allied pieces, or Obstacle (+) pieces.
  93                 Pieces may move into squares occupied by Enemy Pieces (#), in which case the piece with the lower rank (higher number) is destroyed.
  94
  95                 Each player's pieces are hidden from the other player. When two pieces encounter each other, the ranks will be revealed.
  96
  97                 The objective is to destroy all Enemy Pieces (#) or capture the Enemy Flag (also #).
  98
  99
 100 PROTOCOL
 101         In order to interface with stratego, an AI program must satisfy the following protocol.
 102         Each query is followed by a newline, and responses are expected to be followed with a newline.
 103         The queries are recieved through stdin, and responses should be written to stdout.
 104
 105         1. SETUP
 106                 QUERY: YOUR_COLOUR OPPONENT_ID BOARD_WIDTH BOARD_HEIGHT
 107
 108                 RESPONSE: 4 lines, each of length BOARD_WIDTH, of characters. Each character represents a piece. The characters are shown above.
 109
 110         2. TURN
 111                 QUERY:  START | CONFIRMATION
 112                         BOARD_STATE
 113
 114                         On the first turn, "START" is printed to the Red player.
 115                         On subsequent turns, the CONFIRMATION of the opponent's last turn is printed (see below).
 116
 117                         BOARD_STATE consists of a BOARD_HEIGHT lines of length BOARD_WIDTH characters, each of which represents a single piece
 118                         as described in the GAME_RULES section. Each line ends with the newline character.
 119
 120
 121                 RESPONSE: X Y DIRECTION [MULTIPLIER=1] | NO_MOVE
 122                         X and Y are the coords (starting from 0) of the piece to move
 123                         DIRECTION is either UP, DOWN, LEFT or RIGHT
 124                         MULTIPLIER is optional and only valid for units of type Scout. Scouts may move through any number of unblocked squares
 125                         in one direction.
 126
 127                         The AI program should print "NO_MOVE" if it is unable to determine a move.
 128                         This will typically occur when the only pieces belonging to the AI program are Bombs and the Flag.
 129
 130                 CONFIRMATION: X Y DIRECTION [MULTIPLIER=1] OUTCOME | NO_MOVE | QUIT RESULT
 131                         OUTCOME may be either OK, ILLEGAL, KILLS or DIES
 132                                 OK - Move was successful
 133                                 ILLEGAL - Move was not allowed. If stratego was not started with the -i switch, the game will end.
 134                                 KILLS ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and killed the defender.
 135                                 DIES ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and was killed by the defender.
 136
 137                         A confirmation of "NO_MOVE" occurs when the AI program made no move for a legitimate reason.
 138                         "NO_MOVE ILLEGAL" is printed if the AI program made no move for an illegitimate reason.
 139
 140                         If both AI programs successively make a "NO_MOVE" response, then the game will end.
 141                         The player with the highest piece value will win, or a draw will be declared if the values are equal.
 142
 143
 144         3. END GAME
 145                 If the CONFIRMATION line is of the form:
 146                         QUIT RESULT
 147                 Then the game is about to end.
 148
 149                 If present, RESULT will be a direct copy of the message to stdout described in the EXIT/OUTPUT section below.
 150
 151
 152         4. TIMEOUTS
 153                 If a program fails to respond to a query within 2 (two) seconds, the game will end and that AI will be sent the ILLEGAL result.
 154                 Human players are not subject to the timeout restriction.
 155
 156
 157
 158 EXIT/OUTPUT
 159         If the game ends due to a player either winning, or making an illegal move, stratego will print one of the following result messages to stdout.
 160
 161         NAME COLOUR OUTCOME TURN_NUMBER OUTCOME RED_PIECE_VALUE BLUE_PIECE_VALUE
 162
 163         Where:
 164                 NAME is the name of the player on whose turn the game ended,
 165                 COLOUR is the colour of that player,
 166                 OUTCOME is one of the following:
 167                         VICTORY - The indicated player won
 168                         DEFEAT - The indicated player lost
 169                         SURRENDER - The indicated player surrendered
 170                         DRAW - The game ended in a draw because neither player moved
 171                         DRAW_DEFAULT - The game ended in a draw because the maximum number of moves was exceeded
 172                         ILLEGAL - The indicated player loses due to an Illegal move/response
 173                         DEFAULT - The indicated player wins by default due to the other player making an Illegal move/response
 174                         BOTH_ILLEGAL - Both players made an Illegal move/response. Usually occurs due to simultaneous setup errors, or bad executable paths.
 175                         INTERNAL_ERROR - The game ended, even though it shouldn't have.
 176
 177                 TURN_NUMBER is the number of turns that elapsed before the game ended
 178
 179                 RED_PIECE_VALUE and BLUE_PIECE_VALUE are the summed piece values of the pieces of RED and BLUE respectively.
 180                 Bombs and Flags are worth zero, and the ranked pieces (Spys -> Marshal) are worth (11 - rank).
 181                 So the Spy is worth 1 point, ... the Marshal is worth 10.
 182
 183                 (The initial piece values can be determined by running with -m 0)
 184
 185
 186         stratego will then return exit code 0.
 187
 188         If an error occurs within stratego itself, an error message will be printed to stderr and return exit code 1.
 189         If possible, stratego will print the message "QUIT" to both AI programs, and they should exit as soon as possible.
 190
 191
 192 BUGS
 193         There are no known bugs at this time. However, stratego is still a work in progress. Report a bug to the AUTHOR (see below).
 194
 195 AUTHORS
 196         Sam Moore (for the UCC Programming Competition 2012) <[email protected]>
 197
 198 NOTES
 199         0. This program is still a work in progress and subject to changes.
 200
 201         1. UCC Programming Competition 2012 Description
 202            http://matches.ucc.asn.au/stratego/
 203
 204         2. UCC Programming Competition 2012 Git repository
 205            git://git.ucc.asn.au/progcomp2012.git
 206
 207
 208         3. IRC Channel
 209            irc://irc.ucc.asn.au #progcomp
 210