web/doc/manager_manual.txt

   1 NAME
   2         stratego - Interface to manage games of stratego between AI programs and/or human players
   3
   4
   5
   6 SYNOPSIS
   7         stratego {[-gpirb] [-o output_file ] [-t stall_time] [-T timeout_time] [-m max_turns] {red_player blue_player | -f input_file} | {-h | --help} }
   8
   9 QUICK EXAMPLE - Play against a sample AI, using graphics, hiding the AI's pieces
  10         stratego -g -b @human ../../agents/vixen/vixen.py
  11
  12 QUICK EXAMPLE - Play two sample AI, using graphics, and a delay of 1 second between moves
  13         stratego -g -t 1 ../../agents/vixen/vixen.py ../../agents/basic_python/basic_python.py
  14
  15 DESCRIPTION
  16         stratego manages a game of Stratego. It stores the state of the board, and uses a simple protocol to interface with AI programs.
  17         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
  18         various AI strategies, written in any programming language. It will be used for the UCC Programming Competition 2012.
  19
  20         Unless the -h (--help) or -f switch is given, both red_player and blue_player must be supplied.
  21
  22         red_player
  23                 Should be either a path to an executable file which will control the Red player, or "@human" or "@network[:IP_ADDRESS]"
  24
  25                 If player is @human, then control will be given to a human, via stdin if graphics is disabled, or via "point and click" if graphics is enabled.
  26
  27                 If player is @network, then commands will be read from another copy of stratego accross the network.
  28                 In addition, commands from the other player will be sent accross the network to the connected stratego program.
  29
  30                 If no IP_ADDRESS is given, the program acts as the server, and accepts the first connection it receives.
  31                 If an IP_ADDRESS is given, the program attempts to connect as the client to the specified address.
  32
  33                 Each player uses a different port; both players may be network controlled.
  34
  35         blue_player
  36                 As red_player, except for controlling the Blue player.
  37
  38 A WARNING ABOUT BUFFERING
  39         The AI programs must unbuffer their stdin and stdout streams, otherwise it will be seen to be non-responsive.
  40         If you C and you know a way to force the process started by exec() to have unbuffered stdin/stdout, please email the author.
  41
  42         In C or C++, unbuffering is accomplished with the following lines, which should appear near the start of main()
  43                 setbuf(stdin, NULL);
  44                 setbuf(stdout, NULL);
  45         In python, unbuffering is accomplished by passing the -u switch to the interpreter, ie: The first line of a script reads:
  46                 #!/usr/bin/python -u
  47
  48
  49 OPTIONS
  50         -g
  51                 NOTE: This switch only functions if stratego is built with graphics enabled. See BUILDING for more information.
  52
  53                 By default, graphics are disabled. If the -g switch is present, stratego will draw the game as it is played using SDL/OpenGL
  54
  55         -p
  56                 By default, even if graphics are disabled, the board state is not printed. If -p is present, the board will be printed to stdout.
  57                 If the system supports colour, the characters will be in colour.
  58                 Yes, If -p and -g are both present you will see both behaviours (overkill)!
  59         -i
  60                 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.
  61                 That is, the move will not be made (effectively the player making the illegal move loses a turn).
  62
  63                 NOTE: If -i is not given and a human player accidentally(?) makes an illegal move, they will be asked to make a different move. The game will continue.
  64                 This is intended to prevent fits of rage due to the horrible graphical interface causing humans to make illegal moves.
  65         -r
  66                 By default, the identities of all pieces are shown. If the -r switch is present, and graphics are enabled, red pieces will be disguised.
  67                 If graphics are disabled, the -r switch has no effect.
  68
  69                 Pieces which have previously taken part in combat (and survived) will be revealed.
  70         -b
  71                 As -r, except blue pieces will be disguised.
  72                 NOTE: Both -r and -b may be used together.
  73         -o
  74                 By default, stratego does not log moves. If the -o switch is present, the result of each move is printed to a file.
  75                 If output_file is "stdout" then stdout will be used instead of a text file.
  76         -t
  77                 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
  78                 between each move.
  79
  80                 If stall_time is negative or "inf", stratego will wait for the user to press enter before moving to the next move.
  81
  82                 It is tentatively planned to allow the user to enter various commands to alter the game or proceed to specified turns.
  83                 However this is slightly complicated. So it might never be done.
  84
  85         -T
  86                 By default, stratego allows AI programs 2 seconds to respond before declaring their move ILLEGAL due to a timeout.
  87                 If the -T switch is present, AI programs will be allowed timeout_time to respond before their move is declared ILLEGAL.
  88
  89                 If timeout_time is negative or "inf", stratego will never declare moves illegal due to timeouts.
  90
  91                 Human players are never subject to timeouts.
  92
  93         -m
  94                 By default, the game is declared a Draw after 5000 turns have ellapsed.
  95                 Use this option to change the maximum number of turns.
  96                 To play for an infinite number of turns, supply "inf" as max_number. This is not recommended for obvious reasons.
  97
  98         -f
  99                 By default, stratego requires red_player and blue_player to enact a game.
 100                 If this option is supplied, a file previously produced by using the -o switch is read, and the game reenacted.
 101                 All switches function as normal with -f.
 102                 NOTE: It is recommended that -g is used with -f.
 103
 104         -h, --help
 105                 If the -h switch is used, this page will be printed and stratego will exit.
 106
 107
 108
 109 GAME RULES
 110                 Each player controls up to 40 pieces on the Board. The pieces are represented by the following characters:
 111
 112                 Piece   Name            Rank    Number  Abilities
 113                 1       Marshal         1       1       Dies if attacked by Spy
 114                 2       General         2       1
 115                 3       Colonel         3       2
 116                 4       Major           4       3
 117                 5       Captain         5       4
 118                 6       Lieutenant      6       4
 119                 7       Sergeant        7       4
 120                 8       Miner           8       5       Destroys Bombs
 121                 9       Scout           9       8       May move more through multiple empty squares
 122                 s       Spy             10      1       If the Spy attacks the Marshal, the Marshal dies
 123                 B       Bomb            NA      6       Immobile. If any piece (except a Miner) attacks an enemy Bomb, that piece is destroyed.
 124                 F       Flag            NA      1       Immobile. If any piece attacks the enemy Flag, the controlling player wins.
 125
 126                 Additional pieces, not controlled by the player:
 127                 Piece   Name                    Number  Notes
 128                 +       Obstacle                8       Immobile. Do not belong to either player. Can't be passed through.
 129                 #       Enemy Piece             0 - 40  Indicates that the position on the board is occupied by an enemy piece.
 130                 .       Empty                   NA      Indicates that the position on the board is empty.
 131
 132                 Players take turns to move their pieces. RED begins the game.
 133
 134                 Pieces may only move one square horizontally or vertically unless otherwise stated.
 135                 Pieces may not move through squares occupied by allied pieces, or Obstacle (+) pieces.
 136                 Pieces may move into squares occupied by Enemy Pieces (#), in which case the piece with the lower rank (higher number) is destroyed.
 137
 138                 Each player's pieces are hidden from the other player. When two pieces encounter each other, the ranks will be revealed.
 139
 140                 The objective is to either destroy all enemy pieces except the Bombs and Flag, or to capture the Flag.
 141
 142                 Since 20/12 Bombs reflect the traditional rules; they are only destroyed by Miners.
 143                 In previous versions contact of an attacker other than a Miner with a Bomb destroyed the Bomb as well as the attacking piece.
 144
 145
 146
 147 PROTOCOL
 148         WARNING: This is quite a wordy section. To avoid being scared off, try just copying a sample AI program. They obey the protocol already.
 149
 150         In order to interface with stratego, an AI program must satisfy the following protocol.
 151         The protocol has been grouped into several sections. It is suggested that you read and implement the below sections in order.
 152
 153         In the "Synopsis" of each section, a line beginning with the three characters ">> " indicates information sent to the AI.
 154                           a line beginning with the three characters "<< " indicates the form of the expected response.
 155         Each line is always terminated with a new line character '\n'.
 156
 157         A vertical bar '|' indicates that the line may have the form shown either to the left, or the right.
 158         Fields in square brackets '[' and ']' are optional. The default value will be shown within the brackets after a '=' character.
 159
 160         Any words preceeded by a '$' character are not to be interpreted literally; in the actual protocol, these words are replaced with information.
 161         The information will not contain any whitespace unless otherwise stated.
 162         The meaning of these words is explained below the "Synopsis" under the "Explanation" subheading for each section of the protocol.
 163
 164         Words not preceeded by a '$' character should be interpreted literally;
 165                 >> START
 166         Means that "START", followed by a new line, is printed to the AI.
 167
 168
 169         1. Setup
 170                 ---------------------------------------------------
 171                 Description
 172                 ---------------------------------------------------
 173                 Setup only occurs once; during the setup phase, AI are provided with information about their colour and opponent.
 174                 They must then respond with four lines detailing their setup.
 175
 176                 Setup occurs before the first move; your AI should expect to recieve and respond to Setup messages immediately after starting.
 177                 Immediately after the setup phase, the AI should expect to recieve messages desribed by the Turn section of the protocol.
 178                 ---------------------------------------------------
 179                 Synopsis:
 180                 ---------------------------------------------------
 181                 >> $COLOUR $OPPONENT $WIDTH $HEIGHT
 182                 << $ROW1
 183                 << $ROW2
 184                 << $ROW3
 185                 << $ROW4
 186                 ---------------------------------------------------
 187                 Explanation:
 188                 ---------------------------------------------------
 189
 190                 COLOUR - The colour assigned to the AI. Will be either "RED" or "BLUE"
 191                             - Colour is important, because "RED" is always at the top of the board, and "BLUE" at the bottom.
 192
 193                 OPPONENT - Your AI may identify its opponents through this string
 194
 195                 WIDTH - The width of the board. This will always be 10
 196                 HEIGHT - The height of the board. This will always be 10
 197
 198                 ROW1 - The highest row on the board of the AI's setup.
 199                      - For RED, this is the back row, but for BLUE, it is the front row.
 200                 ROW2 - The next highest row
 201                 ROW3 - The next highest row
 202                 ROW4 - The lowest row on the board of the AI's setup
 203                      - For RED, this is the front row, but for BLUE, it is the back row.
 204
 205                 Each row, ROW1 -> ROW4, should consist of WIDTH characters. Each character identifies a piece, as shown under "GAME RULES" above.
 206
 207                 An AI program does not have to place all 40 pieces, but must at least place the flag ('F').
 208                 However, note that an AI program with no mobile pieces will immediately lose.
 209                 ---------------------------------------------------
 210                 Example:
 211                 ---------------------------------------------------
 212                 >> RED ../../agents/vixen/vixen.py 10 10
 213                 << FB8sB479B8
 214                 << BB31555583
 215                 << 6724898974
 216                 << 967B669999
 217
 218                 In this example, the AI will be playing as "RED". It's opponent is the "vixen" sample AI.
 219                 The board width and height will always be 10.
 220
 221                 The AI responds with a sensible setup for the "RED" player, putting the flag in the back corner.
 222
 223         2. Turn
 224                 ---------------------------------------------------
 225                 Description
 226                 ---------------------------------------------------
 227                 After the Setup phase, a number of Turns occur, until the game ends.
 228
 229                 Warning: The game may end between turns, in which case a "QUIT" message is sent.
 230                         The "QUIT" message will be sent in place of the first line in the synopsis shown below.
 231                         Read "3. End Game" below.
 232                 ---------------------------------------------------
 233                 Synopsis
 234                 ---------------------------------------------------
 235                 For the AI with colour "RED" only, and only on the very first turn:
 236                 >> START
 237                 >> $ROW1
 238                 >> $ROW2
 239                 >> $ROW3
 240                 >> $ROW4
 241                 >> $ROW5
 242                 >> $ROW6
 243                 >> $ROW7
 244                 >> $ROW8
 245                 >> $ROW9
 246                 >> $ROW10
 247                 << $X $Y $DIRECTION [$MULTIPLIER=1]
 248                 >> $X $Y $DIRECTION [$MULTIPLIER=1] $OUTCOME
 249
 250                 For the AI with colour "RED" on every subsequent turn, and the AI with colour "BLUE" on all turns:
 251                 >> $LASTMOVE $OUTCOME
 252                 >> $ROW1
 253                 >> $ROW2
 254                 >> $ROW3
 255                 >> $ROW4
 256                 >> $ROW5
 257                 >> $ROW6
 258                 >> $ROW7
 259                 >> $ROW8
 260                 >> $ROW9
 261                 >> $ROW10
 262                 << $X $Y $DIRECTION [$MULTIPLIER=1]
 263                 >> $X $Y $DIRECTION [$MULTIPLIER=1] $OUTCOME | QUIT [$RESULT]
 264                 ---------------------------------------------------
 265                 Explanation:
 266                 ---------------------------------------------------
 267
 268                 [Recieved data 1]
 269
 270                 LASTMOVE - The last move made
 271                          - That is, the move made by the opponent AI, immediately before this move
 272                          - It is a direct copy of the opponent AI's response
 273                          - On the very first turn, since no move has been made, "START" is printed to the RED AI
 274
 275                 OUTCOME - The interpretation of the move by the manager program; will be one of the following
 276                         - Successful, uneventful move: "OK"
 277                         - Illegal move: "ILLEGAL"
 278                         - The moved piece attacked and destroyed an opponent piece: "KILLS $ATTACKER_RANK $DEFENDER_RANK"
 279                                 - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively
 280                         - The moved piece was destroyed by an opponent piece that it attacked: "DIES $ATTACKER_RANK $DEFENDER_RANK"
 281                                 - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively
 282                         - The moved piece attacked an opponent piece, and both pieces were destroyed: "BOTHDIE $ATTACKER_RANK $DEFENDER_RANK"
 283                                 - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively
 284
 285                 ROW1 -> ROW10 - The state of the board will be printed
 286                               - Each line represents a row on the board, from the top downwards
 287                               - The characters are as desribed above in "GAME RULES"
 288                               - Enemy pieces will NOT be revealed, even if they have been involved in combat. They are always shown as '#'.
 289                               - It is recommended that AI's rely on the LASTMOVE and OUTCOME results to keep state
 290                               - Interpreting these lines is not necessary, or recommended
 291                               - They still exist because I say so. GET OVER IT.
 292
 293                 [Sent data]
 294
 295                 X - The x coordinate of the piece to be moved. Ranges from 0 (zero) to 9 (nine) (left to right)
 296                 Y - The y coordinate of the piece to be moved. Ranges from 0 (zero) to 9 (nine) (top to bottom)
 297                 DIRECTION - The direction to move the piece in. May be either "LEFT", "RIGHT", "UP" or "DOWN"
 298                 MULTIPLIER - Scouts may move more than one square.
 299                            - To move a scout multiple spaces, print an integer indicating the number of spaces immediately after DIRECTION
 300
 301                 [Recieved data 2]
 302
 303                 The manager program will check the validity of the move, and respond by repeating it back to the AI, followed by OUTCOME.
 304                 OUTCOME is as described above.
 305                 ---------------------------------------------------
 306                 Example:
 307                 ---------------------------------------------------
 308
 309                 First turn for RED:
 310                 -------------------
 311                 >> START
 312                 >> FB8sB479B8
 313                 >> BB31555583
 314                 >> 6724898974
 315                 >> 967B669999
 316                 >> ..++..++..
 317                 >> ..++..++..
 318                 >> ##########
 319                 >> ##########
 320                 >> ##########
 321                 >> ##########
 322                 << 0 3 DOWN
 323                 >> 0 3 DOWN OK
 324                 -------------------
 325                 Continuing from the Setup example, the RED AI is told to start, and then the board is printed.
 326                 Note that only RED's pieces are revealed. The obstacles are always in the same place, as shown.
 327                 Refer to the "GAME RULES" section for an explanation of each piece character.
 328
 329                 The AI decides to move its scout (9) at (0,3) downwards by one place.
 330
 331                 The manager reports that this move was successful.
 332
 333                 Second Turn for RED:
 334                 -------------------
 335                 >> 9 6 UP 3 BOTHDIE 9 9
 336                 >> FB8sB479B8
 337                 >> BB31555583
 338                 >> 6724898974
 339                 >> .67B66999.
 340                 >> 9.++..++..
 341                 >> ..++..++..
 342                 >> #########.
 343                 >> ##########
 344                 >> ##########
 345                 >> ##########
 346                 << 9 2 DOWN
 347                 >> 9 2 DOWN OK
 348                 -------------------
 349                 The next message recieved by the RED AI tells it that BLUE has moved its piece at (9,6) up by 3.
 350                 This brought the piece into contact with RED's scout (9) at (9,3)
 351                 Since BLUE's piece was also a scout (9), both pieces die, indicated by "BOTHDIE" followed by their ranks (9 and 9)
 352
 353                 The board is printed again. Note that RED's first move is reflected
 354                         (the scout (9) at (0,4)), and BLUE's last move (both (9,6) and (9,3) are now empty).
 355
 356                 The RED AI decides to move its major (4) at (9,2) downwards. This move is OK, because there is now nothing occupying (9,3).
 357                 ---------------------------------------------------
 358                 WARNING:
 359                 ---------------------------------------------------
 360                 It is recommended that you ignore the board state lines, except for the first turn.
 361                 Remember that an AI may not place all its pieces, so assuming its initial setup is a bad idea.
 362                 On subsequent turns, the board state lines provide no information that can't be processed from the move confirmation lines.
 363                 ---------------------------------------------------
 364
 365         3. End Game
 366                 ---------------------------------------------------
 367                 Description:
 368                 ---------------------------------------------------
 369                 A message of "QUIT" at any time signals to an AI that the game is about to end.
 370                 This will be sent immediately after an AI makes a move of the form "$X $Y $DIRECTION [$MULTIPLIER=1]" which ends the game
 371                 It may also be sent at any time in case of errors
 372
 373                 The AI should immediately exit if a QUIT message is recieved.
 374                 ---------------------------------------------------
 375                 Synopsis:
 376                 ---------------------------------------------------
 377                 >> QUIT [RESULT]
 378                 ---------------------------------------------------
 379                 Explanation:
 380                 ---------------------------------------------------
 381                 RESULT - Usually not present; it may contain debug information if it is.
 382                 ---------------------------------------------------
 383
 384         4. Timeouts
 385                 ---------------------------------------------------
 386                 Description:
 387                 ---------------------------------------------------
 388                 If a program fails to respond to a query, the game will end and that AI will be sent the ILLEGAL result.
 389                 Human players are not subject to the timeout restriction.
 390                 ---------------------------------------------------
 391                 Please see the information on the -T switch, and the "End Game" section above.
 392
 393
 394
 395 EXIT/OUTPUT
 396         If the game ends due to a player either winning, or making an illegal move, stratego will print one the following result message to stdout.
 397
 398         $NAME $COLOUR $OUTCOME $TURN  $RED_PIECE_VALUE $BLUE_PIECE_VALUE
 399
 400         Where:
 401                 NAME is the name of the player on whose turn the game ended,
 402
 403                 COLOUR is the colour of that player,
 404
 405                 OUTCOME is one of the following:
 406                         VICTORY - The indicated player won
 407                         DEFEAT - The indicated player lost
 408                         SURRENDER - The indicated player surrendered
 409                         DRAW - The game ended in a draw because neither player moved
 410                         DRAW_DEFAULT - The game ended in a draw because the maximum number of moves was exceeded
 411                         ILLEGAL - The indicated player loses due to an Illegal move/response
 412                         DEFAULT - The indicated player wins by default due to the other player making an Illegal move/response
 413                         BOTH_ILLEGAL - Both players made an Illegal move/response. Usually occurs due to simultaneous setup errors.
 414                                         - May occur due to bad AI path names
 415                         INTERNAL_ERROR - The game ended, even though it shouldn't have.
 416
 417                 TURN is the number of turns that elapsed before the game ended
 418
 419                 RED_PIECE_VALUE and BLUE_PIECE_VALUE are the summed piece values of the pieces of RED and BLUE respectively.
 420                 Bombs and Flags are worth zero, and the ranked pieces (Spys -> Marshal) are worth (11 - rank).
 421                 So the Spy is worth 1 point, ... the Marshal is worth 10.
 422
 423                 (The initial piece values can be determined by running with -m 0)
 424
 425
 426         stratego will then return exit code 0.
 427
 428         If an error occurs within stratego itself, an error message will be printed to stderr and return exit code 1.
 429         If possible, stratego will print the message "QUIT" to both AI programs, and they should exit as soon as possible.
 430
 431 BUILDING
 432         To build from source, simply run make in the source directory.
 433         You will need the C pthread library (which should come with gcc)
 434
 435         stratego can be built with or without graphics enabled. By default, graphics are disabled.
 436
 437         To enable graphics:
 438         1. Ensure that the first line of the source file "graphics.h" reads:
 439                 #define BUILD_GRAPHICS
 440         2. In "Makefile", uncomment the line "LIBRARIES = -lSDL -lGL -lpthread"
 441                 and comment out the line "LIBRARIES = -lpthread"
 442
 443         To disable graphics:
 444         1. Comment out the first line of "graphics.h" i.e ensure that it reads:
 445                 //#define BUILD_GRAPHICS
 446         2. In "Makefile", uncomment the line "LIBRARIES = -lpthread"
 447                 and comment out the line "LIBRARIES = -lSDL -lGL -lpthread"
 448
 449         If you intend to build with graphics enabled, you will need the SDL and OpenGL developement libraries installed first.
 450         If you intend to use graphics, please ensure the "images" directory is located in the executable's run directory.
 451
 452
 453
 454
 455 BUGS
 456         Occasionally the result is not printed at the end of the game.
 457         So far this has only been observed to occur when RED wins the game by Flag capture.
 458
 459         stratego is still a work in progress. Report another bug to the AUTHOR (see below).
 460
 461
 462 AUTHORS
 463         Sam Moore (for the UCC Programming Competition 2012) <[email protected]>
 464
 465 NOTES
 466         0. This program is still a work in progress and subject to changes.
 467
 468         1. UCC Programming Competition 2012 Description
 469            http://progcomp.ucc.asn.au
 470
 471         2. UCC Programming Competition 2012 Git repository
 472            git://git.ucc.asn.au/progcomp2012.git
 473
 474
 475         3. IRC Channel
 476            irc://irc.ucc.asn.au #progcomp
 477
 478 THIS PAGE LAST UPDATED
 479         3/03/12 by Sam Moore
 480