git@UCC - progcomp2012.git/blob - web/doc/manager

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.

7 SYNOPSIS

8 stratego {[-gpirb] [-o output_file ] [-t stall_time] [-T timeout_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" or "@network[:IP_ADDRESS]"

19

20 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.

21

22 If player is @network, then commands will be read from another copy of stratego accross the network.

23 In addition, commands from the other player will be sent accross the network to the connected stratego program.

24

25 If no IP_ADDRESS is given, the program acts as the server, and accepts the first connection it receives.

26 If an IP_ADDRESS is given, the program attempts to connect as the client to the specified address.

27

28 Each player uses a different port; both players may be network controlled.

29

30 blue_player

31 As red_player, except for controlling the Blue player.

32

33 A WARNING ABOUT BUFFERING

34 The AI programs must unbuffer their stdin and stdout streams, otherwise it will be seen to be non-responsive.

35 If you C and you know a way to force the process started by exec() to have unbuffered stdin/stdout, please email the author.

36

37 In C or C++, unbuffering is accomplished with the following lines, which should appear near the start of main()

38 setbuf(stdin, NULL);

39 setbuf(stdout, NULL);

40 In python, unbuffering is accomplished by passing the -u switch to the interpreter, ie: The first line of a script reads:

41 #!/usr/bin/python -u

42

43

44 OPTIONS

45 -g

46 NOTE: This switch only functions if stratego is built with graphics enabled. See BUILDING for more information.

47

48 By default, graphics are disabled. If the -g switch is present, stratego will draw the game as it is played using SDL/OpenGL

49

50 -p

51 By default, even if graphics are disabled, the board state is not printed. If -p is present, the board will be printed to stdout.

52 If the system supports colour, the characters will be in colour.

53 Yes, If -p and -g are both present you will see both behaviours (overkill)!

54 -i

55 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.

56 That is, the move will not be made (effectively the player making the illegal move loses a turn).

57

58 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.

59 This is intended to prevent fits of rage due to the horrible graphical interface causing humans to make illegal moves.

60 -r

61 By default, the identities of all pieces are shown. If the -r switch is present, and graphics are enabled, red pieces will be disguised.

62 If graphics are disabled, the -r switch has no effect.

63

64 Pieces which have previously taken part in combat (and survived) will be revealed.

65 -b

66 As -r, except blue pieces will be disguised.

67 NOTE: Both -r and -b may be used together.

68 -o

69 By default, stratego does not log moves. If the -o switch is present, the result of each move is printed to a file.

70 If output_file is "stdout" then stdout will be used instead of a text file.

71 -t

72 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

73 between each move.

74

75 If stall_time is negative or "inf", stratego will wait for the user to press enter before moving to the next move.

76

77 It is tentatively planned to allow the user to enter various commands to alter the game or proceed to specified turns.

78 However this is slightly complicated. So it might never be done.

79

80 -T

81 By default, stratego allows AI programs 2 seconds to respond before declaring their move ILLEGAL due to a timeout.

82 If the -T switch is present, AI programs will be allowed timeout_time to respond before their move is declared ILLEGAL.

83

84 If timeout_time is negative or "inf", stratego will never declare moves illegal due to timeouts.

85

86 Human players are never subject to timeouts.

87

88 -m

89 By default, the game is declared a Draw after 5000 turns have ellapsed.

90 Use this option to change the maximum number of turns.

91 To play for an infinite number of turns, supply "inf" as max_number. This is not recommended for obvious reasons.

92

93 -f

94 By default, stratego requires red_player and blue_player to enact a game.

95 If this option is supplied, a file previously produced by using the -o switch is read, and the game reenacted.

96 All switches function as normal with -f.

97 NOTE: It is recommended that -g is used with -f.

98

99 -h, --help

100 If the -h switch is used, this page will be printed and stratego will exit.

101

102

103

104 GAME RULES

105 Each player controls up to 40 pieces on the Board. The pieces are represented by the following characters:

106

107 Piece Name Rank Number Abilities

108 1 Marshal 1 1 Dies if attacked by Spy

109 2 General 2 1

110 3 Colonel 3 2

111 4 Major 4 3

112 5 Captain 5 4

113 6 Lieutenant 6 4

114 7 Sergeant 7 4

115 8 Miner 8 5 Destroys Bombs

116 9 Scout 9 8 May move more through multiple empty squares

117 s Spy 10 1 If the Spy attacks the Marshal, the Marshal dies

118 B Bomb NA 6 Immobile. If any piece (except a Miner) attacks an enemy Bomb, that piece is destroyed.

119 F Flag NA 1 Immobile. If any piece attacks the enemy Flag, the controlling player wins.

120

121 Additional pieces, not controlled by the player:

122 Piece Name Number Notes

123 + Obstacle 8 Immobile. Do not belong to either player. Can't be passed through.

124 # Enemy Piece 0 - 40 Indicates that the position on the board is occupied by an enemy piece.

125 . Empty NA Indicates that the position on the board is empty.

126

127 Players take turns to move their pieces. RED begins the game.

128

129 Pieces may only move one square horizontally or vertically unless otherwise stated.

130 Pieces may not move through squares occupied by allied pieces, or Obstacle (+) pieces.

131 Pieces may move into squares occupied by Enemy Pieces (#), in which case the piece with the lower rank (higher number) is destroyed.

132

133 Each player's pieces are hidden from the other player. When two pieces encounter each other, the ranks will be revealed.

134

135 The objective is to either destroy all enemy pieces except the Bombs and Flag, or to capture the Flag.

136

137 Since 20/12 Bombs reflect the traditional rules; they are only destroyed by Miners.

138 In previous versions contact of an attacker other than a Miner with a Bomb destroyed the Bomb as well as the attacking piece.

139

140

141

142 PROTOCOL

143 In order to interface with stratego, an AI program must satisfy the following protocol.

144 Each query is followed by a newline, and responses are expected to be followed with a newline.

145 The queries are recieved through stdin, and responses should be written to stdout.

146

147 "QUERY" describes the information sent to a program's stdin stream.

148 "RESPONSE" describes the form of the information that the program should immediately respond with, to stdout.

149 "CONFIRMATION" describes more information sent to the program's stdin stream, that the program should NOT respond to.

150

151 1. SETUP

152 QUERY: YOUR_COLOUR OPPONENT_ID BOARD_WIDTH BOARD_HEIGHT

153

154 RESPONSE: 4 lines, each of length BOARD_WIDTH, of characters. Each character represents a piece. The characters are shown above.

155

156 RED's pieces are placed at the top of the board, and BLUE's pieces are placed at the bottom.

157

158 An AI program does not have to place all 40 pieces, but must at least place the flag ('F').

159

160 2. TURN

161 QUERY: START | CONFIRMATION

162 BOARD_STATE

163

164 On the first turn, "START" is printed to the Red player.

165 On subsequent turns, the CONFIRMATION of the opponent's last turn is printed (see below).

166

167 BOARD_STATE consists of a BOARD_HEIGHT lines of length BOARD_WIDTH characters, each of which represents a single piece

168 as described in the GAME_RULES section. Each line ends with the newline character.

169

170

171 RESPONSE: X Y DIRECTION [MULTIPLIER=1]

172 X and Y are the coords (starting from 0) of the piece to move

173 DIRECTION is either UP, DOWN, LEFT or RIGHT

174 MULTIPLIER is optional and only valid for units of type Scout. Scouts may move through any number of unblocked squares

175 in one direction.

176

177

178 CONFIRMATION: X Y DIRECTION [MULTIPLIER=1] OUTCOME | QUIT [RESULT]

179

180 OUTCOME may be either OK, ILLEGAL, KILLS or DIES

181 OK - Move was successful

182 ILLEGAL - Move was not allowed. If stratego was not started with the -i switch, the game will end.

183 KILLS ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and killed the defender.

184 DIES ATTACKER_RANK DEFENDER_RANK - The piece moved into an occupied square and was killed by the defender.

185

186 QUIT will only be sent when the game is about to end.

187 3. END GAME

188 If the CONFIRMATION line is of the form:

189 QUIT [RESULT]

190 Then the game is about to end.

191

192 If present, RESULT will be a direct copy of the message to stdout described in the EXIT/OUTPUT section below.

193

194

195 4. TIMEOUTS

196 If a program fails to respond to a query, the game will end and that AI will be sent the ILLEGAL result.

197 Human players are not subject to the timeout restriction.

198

199 Please see the information on the -T switch.

200

201

202

203 EXIT/OUTPUT

204 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.

205

206 NAME COLOUR OUTCOME TURN_NUMBER OUTCOME RED_PIECE_VALUE BLUE_PIECE_VALUE

207

208 Where:

209 NAME is the name of the player on whose turn the game ended,

210 COLOUR is the colour of that player,

211 OUTCOME is one of the following:

212 VICTORY - The indicated player won

213 DEFEAT - The indicated player lost

214 SURRENDER - The indicated player surrendered

215 DRAW - The game ended in a draw because neither player moved

216 DRAW_DEFAULT - The game ended in a draw because the maximum number of moves was exceeded

217 ILLEGAL - The indicated player loses due to an Illegal move/response

218 DEFAULT - The indicated player wins by default due to the other player making an Illegal move/response

219 BOTH_ILLEGAL - Both players made an Illegal move/response. Usually occurs due to simultaneous setup errors, or bad executable paths.

220 INTERNAL_ERROR - The game ended, even though it shouldn't have.

221

222 TURN_NUMBER is the number of turns that elapsed before the game ended

223

224 RED_PIECE_VALUE and BLUE_PIECE_VALUE are the summed piece values of the pieces of RED and BLUE respectively.

225 Bombs and Flags are worth zero, and the ranked pieces (Spys -> Marshal) are worth (11 - rank).

226 So the Spy is worth 1 point, ... the Marshal is worth 10.

227

228 (The initial piece values can be determined by running with -m 0)

229

230

231 stratego will then return exit code 0.

232

233 If an error occurs within stratego itself, an error message will be printed to stderr and return exit code 1.

234 If possible, stratego will print the message "QUIT" to both AI programs, and they should exit as soon as possible.

235

236 BUILDING

237 To build from source, simply run make in the source directory.

238 You will need the C pthread library (which should come with gcc)

239

240 stratego can be built with or without graphics enabled. By default, graphics are disabled.

241

242 To enable graphics:

243 1. Ensure that the first line of the source file "graphics.h" reads:

244 #define BUILD_GRAPHICS

245 2. In "Makefile", uncomment the line "LIBRARIES = -lSDL -lGL -lpthread"

246 and comment out the line "LIBRARIES = -lpthread"

247

248 To disable graphics:

249 1. Comment out the first line of "graphics.h" i.e ensure that it reads:

250 //#define BUILD_GRAPHICS

251 2. In "Makefile", uncomment the line "LIBRARIES = -lpthread"

252 and comment out the line "LIBRARIES = -lSDL -lGL -lpthread"

253

254 If you intend to build with graphics enabled, you will need the SDL and OpenGL developement libraries installed first.

255 If you intend to use graphics, please ensure the "images" directory is located in the executable's run directory.

256

257

258

259

260 BUGS

261 Occasionally the result is not printed at the end of the game.

262 So far this has only been observed to occur when RED wins the game by Flag capture.

263

264 stratego is still a work in progress. Report another bug to the AUTHOR (see below).

265

266

267 AUTHORS

268 Sam Moore (for the UCC Programming Competition 2012) <[email protected]>

269

270 NOTES

271 0. This program is still a work in progress and subject to changes.

272

273 1. UCC Programming Competition 2012 Description

274 http://progcomp.ucc.asn.au

275

276 2. UCC Programming Competition 2012 Git repository

277 git://git.ucc.asn.au/progcomp2012.git

278

279

280 3. IRC Channel

281 irc://irc.ucc.asn.au #progcomp

282

283 THIS PAGE LAST UPDATED

284 2/02/12 by Sam Moore

285