NAME
stratego - Interface to manage games of stratego between AI programs and/or human players
-WARNING
- This program is still a work in progress. Consider it a Beta version.
+
SYNOPSIS
- stratego {[-gpirb] [-o output_file ] [-t stall_time] [-T timeout_time] [-m max_turns] {red_player blue_player | -f input_file} | {-h | --help} }
+ stratego {[-gpirb] [-o output_file ] [-t stall_time] [-T timeout_time] [-m max_turns] [-I image_directory] {red_player blue_player | -f input_file} | {-h | --help} }
+
+QUICK EXAMPLE - Play against a sample AI, using graphics, hiding the AI's pieces
+ stratego -g -b @human ../../agents/vixen/vixen.py
+
+QUICK EXAMPLE - Play two sample AI, using graphics, and a delay of 1 second between moves
+ stratego -g -t 1 ../../agents/vixen/vixen.py ../../agents/basic_python/basic_python.py
DESCRIPTION
stratego manages a game of Stratego. It stores the state of the board, and uses a simple protocol to interface with AI programs.
Unless the -h (--help) or -f switch is given, both red_player and blue_player must be supplied.
red_player
- Should be either a path to an executable file which will control the Red player, or "human".
- If set to "human", stratego will request the user to make moves for the Red player using stdin.
- NOTES
- 1. There is no plan to support AI programs named "human". Deal with it.
- 2. The graphical interface for human players is... basic. Deal with it.
+ Should be either a path to an executable file which will control the Red player, or "@human" or "@network[:IP_ADDRESS]"
+
+ 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.
+
+ If player is @network, then commands will be read from another copy of stratego accross the network.
+ In addition, commands from the other player will be sent accross the network to the connected stratego program.
+
+ If no IP_ADDRESS is given, the program acts as the server, and accepts the first connection it receives.
+ If an IP_ADDRESS is given, the program attempts to connect as the client to the specified address.
+
+ Each player uses a different port; both players may be network controlled.
+
blue_player
As red_player, except for controlling the Blue player.
All switches function as normal with -f.
NOTE: It is recommended that -g is used with -f.
+ -I
+ stratego can output image files in the BMP format, when built with graphics.
+ If this option is supplied, a directory indicated will be used, and a .bmp image will be saved to the directory after each move.
+ The images will be numbered from 0.bmp (before the game starts) with increasing integers for each move.
+ Note that the image number corresponds to the move number, not the turn number.
+ The move number is odd after RED has moved, and even after BLUE has moved.
+
+ NOTE: The -I switch will automatically enable graphics, even if the -g switch is not supplied.
+
+ -v
+ If you have ffmpeg on your system, you can use this to quickly create a video.
+ When this option is supplied, stratego first outputs image files to a temporary directory in BMP format.
+ After the game is finished, these files are used to create an mp4 movie with the specified name:
+
+ $ ffmpeg -r 10 -b 1024k -i tmp/%d.bmp filename
+
+ The temporary images will then be deleted.
+
-h, --help
If the -h switch is used, this page will be printed and stratego will exit.
PROTOCOL
- In order to interface with stratego, an AI program must satisfy the following protocol.
- Each query is followed by a newline, and responses are expected to be followed with a newline.
- The queries are recieved through stdin, and responses should be written to stdout.
-
- 1. SETUP
- QUERY: YOUR_COLOUR OPPONENT_ID BOARD_WIDTH BOARD_HEIGHT
-
- RESPONSE: 4 lines, each of length BOARD_WIDTH, of characters. Each character represents a piece. The characters are shown above.
-
- RED's pieces are placed at the top of the board, and BLUE's pieces are placed at the bottom.
-
- An AI program does not have to place all 40 pieces, but must at least place the flag ('F').
-
- 2. TURN
- QUERY: START | CONFIRMATION
- BOARD_STATE
-
- On the first turn, "START" is printed to the Red player.
- On subsequent turns, the CONFIRMATION of the opponent's last turn is printed (see below).
+ WARNING: This is quite a wordy section. To avoid being scared off, try just copying a sample AI program. They obey the protocol already.
- BOARD_STATE consists of a BOARD_HEIGHT lines of length BOARD_WIDTH characters, each of which represents a single piece
- as described in the GAME_RULES section. Each line ends with the newline character.
-
+ In order to interface with stratego, an AI program must satisfy the following protocol.
+ The protocol has been grouped into several sections. It is suggested that you read and implement the below sections in order.
- RESPONSE: X Y DIRECTION [MULTIPLIER=1]
- X and Y are the coords (starting from 0) of the piece to move
- DIRECTION is either UP, DOWN, LEFT or RIGHT
- MULTIPLIER is optional and only valid for units of type Scout. Scouts may move through any number of unblocked squares
- in one direction.
+ In the "Synopsis" of each section, a line beginning with the three characters ">> " indicates information sent to the AI.
+ a line beginning with the three characters "<< " indicates the form of the expected response.
+ Each line is always terminated with a new line character '\n'.
+ A vertical bar '|' indicates that the line may have the form shown either to the left, or the right.
+ Fields in square brackets '[' and ']' are optional. The default value will be shown within the brackets after a '=' character.
- CONFIRMATION: X Y DIRECTION [MULTIPLIER=1] OUTCOME | QUIT [RESULT]
+ Any words preceeded by a '$' character are not to be interpreted literally; in the actual protocol, these words are replaced with information.
+ The information will not contain any whitespace unless otherwise stated.
+ The meaning of these words is explained below the "Synopsis" under the "Explanation" subheading for each section of the protocol.
- OUTCOME may be either OK, ILLEGAL, KILLS or DIES
- OK - Move was successful
- ILLEGAL - Move was not allowed. If stratego was not started with the -i switch, the game will end.
- KILLS ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and killed the defender.
- DIES ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and was killed by the defender.
+ Words not preceeded by a '$' character should be interpreted literally;
+ >> START
+ Means that "START", followed by a new line, is printed to the AI.
+
+
+ 1. Setup
+ ---------------------------------------------------
+ Description
+ ---------------------------------------------------
+ Setup only occurs once; during the setup phase, AI are provided with information about their colour and opponent.
+ They must then respond with four lines detailing their setup.
+
+ Setup occurs before the first move; your AI should expect to recieve and respond to Setup messages immediately after starting.
+ Immediately after the setup phase, the AI should expect to recieve messages desribed by the Turn section of the protocol.
+ ---------------------------------------------------
+ Synopsis:
+ ---------------------------------------------------
+ >> $COLOUR $OPPONENT $WIDTH $HEIGHT
+ << $ROW1
+ << $ROW2
+ << $ROW3
+ << $ROW4
+ ---------------------------------------------------
+ Explanation:
+ ---------------------------------------------------
+
+ COLOUR - The colour assigned to the AI. Will be either "RED" or "BLUE"
+ - Colour is important, because "RED" is always at the top of the board, and "BLUE" at the bottom.
+
+ OPPONENT - Your AI may identify its opponents through this string
+
+ WIDTH - The width of the board. This will always be 10
+ HEIGHT - The height of the board. This will always be 10
+
+ ROW1 - The highest row on the board of the AI's setup.
+ - For RED, this is the back row, but for BLUE, it is the front row.
+ ROW2 - The next highest row
+ ROW3 - The next highest row
+ ROW4 - The lowest row on the board of the AI's setup
+ - For RED, this is the front row, but for BLUE, it is the back row.
+
+ Each row, ROW1 -> ROW4, should consist of WIDTH characters. Each character identifies a piece, as shown under "GAME RULES" above.
- QUIT will only be sent when the game is about to end.
- 3. END GAME
- If the CONFIRMATION line is of the form:
- QUIT [RESULT]
- Then the game is about to end.
+ An AI program does not have to place all 40 pieces, but must at least place the flag ('F').
+ However, note that an AI program with no mobile pieces will immediately lose.
+ ---------------------------------------------------
+ Example:
+ ---------------------------------------------------
+ >> RED ../../agents/vixen/vixen.py 10 10
+ << FB8sB479B8
+ << BB31555583
+ << 6724898974
+ << 967B669999
+
+ In this example, the AI will be playing as "RED". It's opponent is the "vixen" sample AI.
+ The board width and height will always be 10.
+
+ The AI responds with a sensible setup for the "RED" player, putting the flag in the back corner.
+
+ 2. Turn
+ ---------------------------------------------------
+ Description
+ ---------------------------------------------------
+ After the Setup phase, a number of Turns occur, until the game ends.
+
+ Warning: The game may end between turns, in which case a "QUIT" message is sent.
+ The "QUIT" message will be sent in place of the first line in the synopsis shown below.
+ Read "3. End Game" below.
+ ---------------------------------------------------
+ Synopsis
+ ---------------------------------------------------
+ For the AI with colour "RED" only, and only on the very first turn:
+ >> START
+ >> $ROW1
+ >> $ROW2
+ >> $ROW3
+ >> $ROW4
+ >> $ROW5
+ >> $ROW6
+ >> $ROW7
+ >> $ROW8
+ >> $ROW9
+ >> $ROW10
+ << $X $Y $DIRECTION [$MULTIPLIER=1]
+ >> $X $Y $DIRECTION [$MULTIPLIER=1] $OUTCOME
+
+ For the AI with colour "RED" on every subsequent turn, and the AI with colour "BLUE" on all turns:
+ >> $LASTMOVE $OUTCOME
+ >> $ROW1
+ >> $ROW2
+ >> $ROW3
+ >> $ROW4
+ >> $ROW5
+ >> $ROW6
+ >> $ROW7
+ >> $ROW8
+ >> $ROW9
+ >> $ROW10
+ << $X $Y $DIRECTION [$MULTIPLIER=1]
+ >> $X $Y $DIRECTION [$MULTIPLIER=1] $OUTCOME | QUIT [$RESULT]
+ ---------------------------------------------------
+ Explanation:
+ ---------------------------------------------------
+
+ [Recieved data 1]
+
+ LASTMOVE - The last move made
+ - That is, the move made by the opponent AI, immediately before this move
+ - It is a direct copy of the opponent AI's response
+ - On the very first turn, since no move has been made, "START" is printed to the RED AI
+
+ OUTCOME - The interpretation of the move by the manager program; will be one of the following
+ - Successful, uneventful move: "OK"
+ - Illegal move: "ILLEGAL"
+ - The moved piece attacked and destroyed an opponent piece: "KILLS $ATTACKER_RANK $DEFENDER_RANK"
+ - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively
+ - The moved piece was destroyed by an opponent piece that it attacked: "DIES $ATTACKER_RANK $DEFENDER_RANK"
+ - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively
+ - The moved piece attacked an opponent piece, and both pieces were destroyed: "BOTHDIE $ATTACKER_RANK $DEFENDER_RANK"
+ - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively
+
+ ROW1 -> ROW10 - The state of the board will be printed
+ - Each line represents a row on the board, from the top downwards
+ - The characters are as desribed above in "GAME RULES"
+ - Enemy pieces will NOT be revealed, even if they have been involved in combat. They are always shown as '#'.
+ - It is recommended that AI's rely on the LASTMOVE and OUTCOME results to keep state
+ - Interpreting these lines is not necessary, or recommended
+ - They still exist because I say so. GET OVER IT.
+
+ [Sent data]
+
+ X - The x coordinate of the piece to be moved. Ranges from 0 (zero) to 9 (nine) (left to right)
+ Y - The y coordinate of the piece to be moved. Ranges from 0 (zero) to 9 (nine) (top to bottom)
+ DIRECTION - The direction to move the piece in. May be either "LEFT", "RIGHT", "UP" or "DOWN"
+ MULTIPLIER - Scouts may move more than one square.
+ - To move a scout multiple spaces, print an integer indicating the number of spaces immediately after DIRECTION
+
+ [Recieved data 2]
+
+ The manager program will check the validity of the move, and respond by repeating it back to the AI, followed by OUTCOME.
+ OUTCOME is as described above.
+ ---------------------------------------------------
+ Example:
+ ---------------------------------------------------
+
+ First turn for RED:
+ -------------------
+ >> START
+ >> FB8sB479B8
+ >> BB31555583
+ >> 6724898974
+ >> 967B669999
+ >> ..++..++..
+ >> ..++..++..
+ >> ##########
+ >> ##########
+ >> ##########
+ >> ##########
+ << 0 3 DOWN
+ >> 0 3 DOWN OK
+ -------------------
+ Continuing from the Setup example, the RED AI is told to start, and then the board is printed.
+ Note that only RED's pieces are revealed. The obstacles are always in the same place, as shown.
+ Refer to the "GAME RULES" section for an explanation of each piece character.
+
+ The AI decides to move its scout (9) at (0,3) downwards by one place.
+
+ The manager reports that this move was successful.
+
+ Second Turn for RED:
+ -------------------
+ >> 9 6 UP 3 BOTHDIE 9 9
+ >> FB8sB479B8
+ >> BB31555583
+ >> 6724898974
+ >> .67B66999.
+ >> 9.++..++..
+ >> ..++..++..
+ >> #########.
+ >> ##########
+ >> ##########
+ >> ##########
+ << 9 2 DOWN
+ >> 9 2 DOWN OK
+ -------------------
+ The next message recieved by the RED AI tells it that BLUE has moved its piece at (9,6) up by 3.
+ This brought the piece into contact with RED's scout (9) at (9,3)
+ Since BLUE's piece was also a scout (9), both pieces die, indicated by "BOTHDIE" followed by their ranks (9 and 9)
+
+ The board is printed again. Note that RED's first move is reflected
+ (the scout (9) at (0,4)), and BLUE's last move (both (9,6) and (9,3) are now empty).
- If present, RESULT will be a direct copy of the message to stdout described in the EXIT/OUTPUT section below.
+ 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).
+ ---------------------------------------------------
+ WARNING:
+ ---------------------------------------------------
+ It is recommended that you ignore the board state lines, except for the first turn.
+ Remember that an AI may not place all its pieces, so assuming its initial setup is a bad idea.
+ On subsequent turns, the board state lines provide no information that can't be processed from the move confirmation lines.
+ ---------------------------------------------------
+
+ 3. End Game
+ ---------------------------------------------------
+ Description:
+ ---------------------------------------------------
+ A message of "QUIT" at any time signals to an AI that the game is about to end.
+ This will be sent immediately after an AI makes a move of the form "$X $Y $DIRECTION [$MULTIPLIER=1]" which ends the game
+ It may also be sent at any time in case of errors
+ The AI should immediately exit if a QUIT message is recieved.
+ ---------------------------------------------------
+ Synopsis:
+ ---------------------------------------------------
+ >> QUIT [RESULT]
+ ---------------------------------------------------
+ Explanation:
+ ---------------------------------------------------
+ RESULT - Usually not present; it may contain debug information if it is.
+ ---------------------------------------------------
- 4. TIMEOUTS
+ 4. Timeouts
+ ---------------------------------------------------
+ Description:
+ ---------------------------------------------------
If a program fails to respond to a query, the game will end and that AI will be sent the ILLEGAL result.
Human players are not subject to the timeout restriction.
-
- Please see the information on the -T switch.
+ ---------------------------------------------------
+ Please see the information on the -T switch, and the "End Game" section above.
EXIT/OUTPUT
- 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.
+ 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.
- NAME COLOUR OUTCOME TURN_NUMBER OUTCOME RED_PIECE_VALUE BLUE_PIECE_VALUE
+ $NAME $COLOUR $OUTCOME $TURN $RED_PIECE_VALUE $BLUE_PIECE_VALUE
Where:
NAME is the name of the player on whose turn the game ended,
+
COLOUR is the colour of that player,
+
OUTCOME is one of the following:
VICTORY - The indicated player won
DEFEAT - The indicated player lost
DRAW_DEFAULT - The game ended in a draw because the maximum number of moves was exceeded
ILLEGAL - The indicated player loses due to an Illegal move/response
DEFAULT - The indicated player wins by default due to the other player making an Illegal move/response
- BOTH_ILLEGAL - Both players made an Illegal move/response. Usually occurs due to simultaneous setup errors, or bad executable paths.
- INTERNAL_ERROR - The game ended, even though it shouldn't have.
-
- TURN_NUMBER is the number of turns that elapsed before the game ended
+ BOTH_ILLEGAL - Both players made an Illegal move/response. Usually occurs due to simultaneous setup errors.
+ - May occur due to bad AI path names
+ INTERNAL_ERROR - The game ended, even though it shouldn't have.
+
+ TURN is the number of turns that elapsed before the game ended
RED_PIECE_VALUE and BLUE_PIECE_VALUE are the summed piece values of the pieces of RED and BLUE respectively.
Bombs and Flags are worth zero, and the ranked pieces (Spys -> Marshal) are worth (11 - rank).
0. This program is still a work in progress and subject to changes.
1. UCC Programming Competition 2012 Description
- http://matches.ucc.asn.au/stratego/
+ http://progcomp.ucc.asn.au
2. UCC Programming Competition 2012 Git repository
git://git.ucc.asn.au/progcomp2012.git
irc://irc.ucc.asn.au #progcomp
THIS PAGE LAST UPDATED
- 3/01/12 by Sam Moore
+ 3/03/12 by Sam Moore
git.ucc.asn.au / progcomp2012.git / blobdiff
UCC git Repository :: git.ucc.asn.au