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 {[-girb] [-o= output_file ] [-t= stall_time] red_player blue_player | {-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 -h, or --help 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         -i
  31                 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.
  32                 That is, the move will not be made (effectively the player making the illegal move loses a turn).
  33         -r
  34                 By default, the identities of all pieces are shown. If the -r switch is present, and graphics are enabled, red pieces will be disguised.
  35                 If graphics are disabled, the -r switch has no effect.
  36         -b
  37                 As -r, except blue pieces will be disguised.
  38                 NOTE: Both -r and -b may be used.
  39         -o
  40                 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"
  41                 then stdout will be used instead of a text file.
  42         -t
  43                 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
  44                 between each move.
  45         -h, --help
  46                 If the -h switch is present, this page will be printed and stratego will exit.
  47
  48 GAME RULES
  49                 Each player sets up 40 pieces on the Board. The pieces consist of the following:
  50
  51                 Piece   Name            Rank    Number  Abilities
  52                 1       Marshal         1       1       Dies if attacked by Spy
  53                 2       General         2       1
  54                 3       Colonel         3       2
  55                 4       Major           4       3
  56                 5       Captain         5       4
  57                 6       Lieutenant      6       4
  58                 7       Sergeant        7       4
  59                 8       Miner           8       5       Destroys Bombs without being killed
  60                 9       Scout           9       8       May move more through multiple empty squares
  61                 s       Spy             10      1       If the Spy attacks the Marshal, the Marshal dies
  62                 B       Bomb            NA      6       Immobile. If an enemy piece (except a Miner) encounters a Bomb, both pieces are destroyed
  63                 F       Flag            NA      1       Immobile. If any enemy piece encounters the Flag, the controlling player wins.
  64
  65                 Pieces may move one square horizontally or vertically unless otherwise stated.
  66                 Pieces may not move through squares occupied by allied pieces.
  67                 Pieces may move into squares occupied by enemy pieces, in which case the piece with the lower rank (higher number) is destroyed.
  68
  69                 Each player's pieces are hidden from the other player. When two pieces encounter each other, the ranks will be revealed.
  70
  71                 The objective is to destroy all enemy pieces or capture the Flag.
  72
  73
  74 PROTOCOL
  75         In order to interface with stratego, an AI program must satisfy the following protocol.
  76         Each query is followed by a newline, and responses are expected to be followed with a newline.
  77         The queries are recieved through stdin, and responses should be written to stdout.
  78
  79         1. SETUP
  80                 QUERY: YOUR_COLOUR OPPONENT_ID BOARD_WIDTH BOARD_HEIGHT
  81
  82                 RESPONSE: 4 lines, each of length BOARD_WIDTH, of characters. Each character represents a piece. The characters are shown above.
  83
  84         2. TURN
  85                 QUERY: START | CONFIRMATION
  86                         On the first turn, "START" is printed to the Red player.
  87                         On subsequent turns, the CONFIRMATION of the opponent's last turn is printed (see below).
  88
  89                 RESPONSE: X Y DIRECTION [MULTIPLIER=1]
  90                         X and Y are the coords (starting from 0) of the piece to move
  91                         DIRECTION is either UP, DOWN, LEFT or RIGHT
  92                         MULTIPLIER is optional and only valid for units of type Scout. Scouts may move through any number of unblocked squares
  93                         in one direction.
  94
  95                 CONFIRMATION: X Y DIRECTION [MULTIPLIER=1] OUTCOME
  96                         OUTCOME may be either OK, ILLEGAL, KILLS or DIES
  97                                 OK - Move was successful
  98                                 ILLEGAL - Move was not allowed. If stratego was not started with the -i switch, the game will end.
  99                                 KILLS ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and killed the defender.
 100                                 DIES ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and was killed by the defender.
 101
 102         3. END GAME
 103                 QUERY: VICTORY | DEFEAT | ILLEGAL | DEFAULT
 104                         VICTORY - This player won the game
 105                         DEFEAT - The other player won the game
 106                         ILLEGAL - Game ended because this player made a bad response or timed out
 107                                 (NOTE: Even if the -i option is provided, the game may end with an ILLEGAL signal if a bad response is made)
 108                         DEFAULT - Game ended because the other player made a bad response.
 109
 110                         No response is necessary; the program should exit or it will be sent a SIGKILL signal.
 111
 112         4. TIMEOUTS
 113                 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.
 114                 Human players are not subject to the timeout restriction.
 115
 116
 117
 118 EXIT/OUTPUT
 119         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.
 120
 121         1.
 122                 WINNING_NAME WINNING_COLOUR TURNS
 123         2.
 124                 DRAW TURNS
 125                 When the result was a draw
 126
 127         3.
 128                 NONE TURNS
 129                 When for some reason both the AI programs failed to respond or crashed.
 130
 131         stratego will then return exit code 0.
 132
 133         If an error occurs within stratego itself, an error message will be printed to stderr and return exit code 1.
 134         If possible, stratego will print the message "QUIT" to both AI programs, and they should exit as soon as possible.
 135
 136
 137 BUGS
 138         There are no known bugs at this time. However, stratego is still a work in progress. Report a bug to the AUTHOR (see below).
 139
 140 AUTHORS
 141         Sam Moore (for the UCC Programming Competition 2012) <[email protected]>
 142
 143 NOTES
 144         0. This program is still a work in progress and subject to changes.
 145
 146         1. UCC Programming Competition 2012 Description
 147            http://matches.ucc.asn.au/stratego/
 148
 149         2. UCC Programming Competition 2012 Git repository
 150            git://git.ucc.asn.au/progcomp2012.git
 151
 152
 153         3. IRC Channel
 154            irc://irc.ucc.asn.au #progcomp
 155