Added build option to build "stratego" without graphics
[progcomp2012.git] / web / doc / 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. The graphical interface for human players is... basic. Deal with it.
23         blue_player
24                 As red_player, except for controlling the Blue player.
25
26 A WARNING ABOUT BUFFERING
27         The AI programs must unbuffer their stdin and stdout streams, otherwise it will be seen to be non-responsive.
28         If you C and you know a way to force the process started by exec() to have unbuffered stdin/stdout, please email the author.
29
30         In C or C++, unbuffering is accomplished with the following lines, which should appear near the start of main()
31                 setbuf(stdin, NULL);
32                 setbuf(stdout, NULL);
33         In python, unbuffering is accomplished by passing the -u switch to the interpreter, ie: The first line of a script reads:
34                 #!/usr/bin/python -u
35         
36         
37 OPTIONS
38         -g
39                 NOTE: This switch only functions if stratego is built with graphics enabled. See BUILDING for more information.
40
41                 By default, graphics are disabled. If the -g switch is present, stratego will draw the game as it is played using SDL/OpenGL
42                 
43         -p
44                 By default, even if graphics are disabled, the board state is not printed. If -p is present, the board will be printed to stdout.
45                 If the system supports colour, the characters will be in colour.
46                 Yes, If -p and -g are both present you will see both behaviours (overkill)!
47         -i
48                 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.
49                 That is, the move will not be made (effectively the player making the illegal move loses a turn).
50
51                 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.
52                 This is intended to prevent fits of rage due to the horrible graphical interface causing humans to make illegal moves.
53         -r
54                 By default, the identities of all pieces are shown. If the -r switch is present, and graphics are enabled, red pieces will be disguised.
55                 If graphics are disabled, the -r switch has no effect.
56
57                 Pieces which have previously taken part in combat (and survived) will be revealed.
58         -b
59                 As -r, except blue pieces will be disguised.
60                 NOTE: Both -r and -b may be used together.
61         -o
62                 By default, stratego does not log moves. If the -o switch is present, the result of each move is printed to a file. 
63                 If output_file is "stdout" then stdout will be used instead of a text file.
64         -t
65                 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
66                 between each move.
67                 
68                 If stall_time is negative or "inf", stratego will wait for the user to press enter before moving to the next move.
69                 
70                 It is tentatively planned to allow the user to enter various commands to alter the game or proceed to specified turns.
71                 However this is slightly complicated. So it might never be done.
72         -m
73                 By default, the game is declared a Draw after 5000 turns have ellapsed.
74                 Use this option to change the maximum number of turns.
75                 To play for an infinite number of turns, supply "inf" as max_number. This is not recommended for obvious reasons.
76
77         -f
78                 By default, stratego requires red_player and blue_player to enact a game.
79                 If this option is supplied, a file previously produced by using the -o switch is read, and the game reenacted.
80                 All switches function as normal with -f.
81                 NOTE: It is recommended that -g is used with -f.
82
83         -h, --help
84                 If the -h switch is used, this page will be printed and stratego will exit.
85                 
86                 
87
88 GAME RULES
89                 Each player controls up to 40 pieces on the Board. The pieces are represented by the following characters:
90
91                 Piece   Name            Rank    Number  Abilities
92                 1       Marshal         1       1       Dies if attacked by Spy
93                 2       General         2       1       
94                 3       Colonel         3       2       
95                 4       Major           4       3       
96                 5       Captain         5       4       
97                 6       Lieutenant      6       4
98                 7       Sergeant        7       4
99                 8       Miner           8       5       Destroys Bombs
100                 9       Scout           9       8       May move more through multiple empty squares
101                 s       Spy             10      1       If the Spy attacks the Marshal, the Marshal dies
102                 B       Bomb            NA      6       Immobile. If any piece (except a Miner) attacks an enemy Bomb, that piece is destroyed.
103                 F       Flag            NA      1       Immobile. If any piece attacks the enemy Flag, the controlling player wins.
104
105                 Additional pieces, not controlled by the player:
106                 Piece   Name                    Number  Notes
107                 +       Obstacle                8       Immobile. Do not belong to either player. Can't be passed through.
108                 #       Enemy Piece             0 - 40  Indicates that the position on the board is occupied by an enemy piece.
109                 .       Empty                   NA      Indicates that the position on the board is empty.
110                 
111                 Players take turns to move their pieces. RED begins the game.
112
113                 Pieces may only move one square horizontally or vertically unless otherwise stated.
114                 Pieces may not move through squares occupied by allied pieces, or Obstacle (+) pieces.
115                 Pieces may move into squares occupied by Enemy Pieces (#), in which case the piece with the lower rank (higher number) is destroyed.
116
117                 Each player's pieces are hidden from the other player. When two pieces encounter each other, the ranks will be revealed.
118
119                 The objective is to destroy all Enemy Pieces (#) or capture the Enemy Flag (also #).
120
121                 Since 20/12 Bombs reflect the traditional rules; they are only destroyed by Miners.
122                 In previous versions contact of an attacker other than a Miner with a Bomb destroyed the Bomb as well as the attacking piece.
123                 
124
125 PROTOCOL
126         In order to interface with stratego, an AI program must satisfy the following protocol. 
127         Each query is followed by a newline, and responses are expected to be followed with a newline.
128         The queries are recieved through stdin, and responses should be written to stdout.
129         
130         1. SETUP
131                 QUERY: YOUR_COLOUR OPPONENT_ID BOARD_WIDTH BOARD_HEIGHT
132
133                 RESPONSE: 4 lines, each of length BOARD_WIDTH, of characters. Each character represents a piece. The characters are shown above.
134
135                 RED's pieces are placed at the top of the board, and BLUE's pieces are placed at the bottom.
136
137                 An AI program does not have to place all 40 pieces, but must at least place the flag ('F').
138
139         2. TURN
140                 QUERY:  START | CONFIRMATION
141                         BOARD_STATE
142
143                         On the first turn, "START" is printed to the Red player.
144                         On subsequent turns, the CONFIRMATION of the opponent's last turn is printed (see below).
145
146                         BOARD_STATE consists of a BOARD_HEIGHT lines of length BOARD_WIDTH characters, each of which represents a single piece
147                         as described in the GAME_RULES section. Each line ends with the newline character.
148                         
149
150                 RESPONSE: X Y DIRECTION [MULTIPLIER=1] | NO_MOVE
151                         X and Y are the coords (starting from 0) of the piece to move
152                         DIRECTION is either UP, DOWN, LEFT or RIGHT
153                         MULTIPLIER is optional and only valid for units of type Scout. Scouts may move through any number of unblocked squares
154                         in one direction.
155
156                         The AI program should print "NO_MOVE" if it is unable to determine a move.
157                         This will typically occur when the only pieces belonging to the AI program are Bombs and the Flag.
158
159                 CONFIRMATION: X Y DIRECTION [MULTIPLIER=1] OUTCOME | NO_MOVE {OK | ILLEGAL} | QUIT [RESULT]
160
161                         OUTCOME may be either OK, ILLEGAL, KILLS or DIES
162                                 OK - Move was successful
163                                 ILLEGAL - Move was not allowed. If stratego was not started with the -i switch, the game will end.
164                                 KILLS ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and killed the defender.
165                                 DIES ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and was killed by the defender.
166
167                         Most turns will be confirmed with: "X Y DIRECTION [MULTIPLIER=1] OUTCOME"
168
169                         A confirmation of "NO_MOVE OK" occurs when the AI program made no move for a legitimate reason.
170                         "NO_MOVE ILLEGAL" is printed if the AI program made no move for an illegitimate reason.
171
172                         If both AI programs successively make a "NO_MOVE" response, then the game will end.
173                         The player with the highest piece value will win, or a draw will be declared if the values are equal.
174
175         3. END GAME
176                 If the CONFIRMATION line is of the form:
177                         QUIT [RESULT]
178                 Then the game is about to end.
179         
180                 If present, RESULT will be a direct copy of the message to stdout described in the EXIT/OUTPUT section below.
181                 
182         
183         4. TIMEOUTS
184                 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.
185                 Human players are not subject to the timeout restriction.
186                 
187                         
188
189 EXIT/OUTPUT
190         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.
191
192         NAME COLOUR OUTCOME TURN_NUMBER OUTCOME RED_PIECE_VALUE BLUE_PIECE_VALUE
193
194         Where:
195                 NAME is the name of the player on whose turn the game ended,
196                 COLOUR is the colour of that player,
197                 OUTCOME is one of the following:
198                         VICTORY - The indicated player won
199                         DEFEAT - The indicated player lost
200                         SURRENDER - The indicated player surrendered
201                         DRAW - The game ended in a draw because neither player moved
202                         DRAW_DEFAULT - The game ended in a draw because the maximum number of moves was exceeded
203                         ILLEGAL - The indicated player loses due to an Illegal move/response
204                         DEFAULT - The indicated player wins by default due to the other player making an Illegal move/response
205                         BOTH_ILLEGAL - Both players made an Illegal move/response. Usually occurs due to simultaneous setup errors, or bad executable paths.
206                         INTERNAL_ERROR - The game ended, even though it shouldn't have.
207                         
208                 TURN_NUMBER is the number of turns that elapsed before the game ended
209
210                 RED_PIECE_VALUE and BLUE_PIECE_VALUE are the summed piece values of the pieces of RED and BLUE respectively.
211                 Bombs and Flags are worth zero, and the ranked pieces (Spys -> Marshal) are worth (11 - rank).
212                 So the Spy is worth 1 point, ... the Marshal is worth 10.
213
214                 (The initial piece values can be determined by running with -m 0)
215                 
216
217         stratego will then return exit code 0.
218
219         If an error occurs within stratego itself, an error message will be printed to stderr and return exit code 1.
220         If possible, stratego will print the message "QUIT" to both AI programs, and they should exit as soon as possible.
221
222 BUILDING
223         To build from source, simply run make in the source directory.
224
225         stratego can be built with or without graphics enabled. By default, graphics are disabled.
226
227         To enable graphics, ensure that the first line of the source file "graphics.h" reads:
228
229         #define BUILD_GRAPHICS
230
231         To disable graphics, comment out the first line of "graphics.h" i.e ensure that it reads:
232
233         //#define BUILD_GRAPHICS
234
235         If you intend to build with graphics enabled, you will need the SDL and OpenGL developement libraries installed first.
236         If you intend to use graphics, please ensure the "images" directory is located in the executable's run directory.
237
238         
239         
240
241 BUGS    
242         Occasionally the result is not printed at the end of the game. 
243         So far this has only been observed to occur when RED wins the game by Flag capture.
244
245         stratego is still a work in progress. Report another bug to the AUTHOR (see below).
246
247
248 AUTHORS
249         Sam Moore (for the UCC Programming Competition 2012) <matches@ucc.asn.au>
250
251 NOTES
252         0. This program is still a work in progress and subject to changes.
253         
254         1. UCC Programming Competition 2012 Description
255            http://matches.ucc.asn.au/stratego/
256
257         2. UCC Programming Competition 2012 Git repository
258            git://git.ucc.asn.au/progcomp2012.git
259
260  
261         3. IRC Channel
262            irc://irc.ucc.asn.au #progcomp
263
264 THIS PAGE LAST UPDATED
265         23/12/11 by Sam Moore
266         

UCC git Repository :: git.ucc.asn.au