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

2 stratego - Interface to manage games of stratego between AI programs and/or human players

3

6 SYNOPSIS

7 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} }

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 -I

105 stratego can output image files in the BMP format, when built with graphics.

106 If this option is supplied, a directory indicated will be used, and a .bmp image will be saved to the directory after each move.

107 The images will be numbered from 0.bmp (before the game starts) with increasing integers for each move.

108 Note that the image number corresponds to the move number, not the turn number.

109 The move number is odd after RED has moved, and even after BLUE has moved.

110

111 NOTE: The -I switch will automatically enable graphics, even if the -g switch is not supplied.

112

113 -v

114 If you have ffmpeg on your system, you can use this to quickly create a video.

115 When this option is supplied, stratego first outputs image files to a temporary directory in BMP format.

116 After the game is finished, these files are used to create an mp4 movie with the specified name:

117

118 $ ffmpeg -r 10 -b 1024k -i tmp/%d.bmp filename

119

120 The temporary images will then be deleted.

121

122 -h, --help

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

124

125

126

127 GAME RULES

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

129

130 Piece Name Rank Number Abilities

131 1 Marshal 1 1 Dies if attacked by Spy

132 2 General 2 1

133 3 Colonel 3 2

134 4 Major 4 3

135 5 Captain 5 4

136 6 Lieutenant 6 4

137 7 Sergeant 7 4

138 8 Miner 8 5 Destroys Bombs

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

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

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

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

143

144 Additional pieces, not controlled by the player:

145 Piece Name Number Notes

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

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

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

149

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

151

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

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

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

155 If the moved piece (attacker) has the lower rank, the stationary piece (defender) does _not_ move into the attacker's square.

156

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

158

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

160

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

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

163

164 Since 9/04/2012 An AI must place ALL 40 pieces listed above, or its setup will be declared illegal

165

166

167

168 PROTOCOL

169 WARNING: This is quite a wordy section. To avoid being scared off, try just copying a sample AI program. They obey the protocol already.

170

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

172 The protocol has been grouped into several sections. It is suggested that you read and implement the below sections in order.

173

174 In the "Synopsis" of each section, a line beginning with the three characters ">> " indicates information sent to the AI.

175 a line beginning with the three characters "<< " indicates the form of the expected response.

176 Each line is always terminated with a new line character '\n'.

177

178 A vertical bar '|' indicates that the line may have the form shown either to the left, or the right.

179 Fields in square brackets '[' and ']' are optional. The default value will be shown within the brackets after a '=' character.

180

181 Any words preceeded by a '$' character are not to be interpreted literally; in the actual protocol, these words are replaced with information.

182 The information will not contain any whitespace unless otherwise stated.

183 The meaning of these words is explained below the "Synopsis" under the "Explanation" subheading for each section of the protocol.

184

185 Words not preceeded by a '$' character should be interpreted literally;

186 >> START

187 Means that "START", followed by a new line, is printed to the AI.

188

189

190 1. Setup

191 ---------------------------------------------------

192 Description

193 ---------------------------------------------------

194 Setup only occurs once; during the setup phase, AI are provided with information about their colour and opponent.

195 They must then respond with four lines detailing their setup.

196

197 Setup occurs before the first move; your AI should expect to recieve and respond to Setup messages immediately after starting.

198 Immediately after the setup phase, the AI should expect to recieve messages desribed by the Turn section of the protocol.

199 ---------------------------------------------------

200 Synopsis:

201 ---------------------------------------------------

202 >> $COLOUR $OPPONENT $WIDTH $HEIGHT

203 << $ROW1

204 << $ROW2

205 << $ROW3

206 << $ROW4

207 ---------------------------------------------------

208 Explanation:

209 ---------------------------------------------------

210

211 COLOUR - The colour assigned to the AI. Will be either "RED" or "BLUE"

212 - Colour is important, because "RED" is always at the top of the board, and "BLUE" at the bottom.

213

214 OPPONENT - Your AI may identify its opponents through this string

215

216 WIDTH - The width of the board. This will always be 10

217 HEIGHT - The height of the board. This will always be 10

218

219 ROW1 - The highest row on the board of the AI's setup.

220 - For RED, this is the back row, but for BLUE, it is the front row.

221 ROW2 - The next highest row

222 ROW3 - The next highest row

223 ROW4 - The lowest row on the board of the AI's setup

224 - For RED, this is the front row, but for BLUE, it is the back row.

225

226 Each row, ROW1 -> ROW4, should consist of WIDTH characters. Each character identifies a piece, as shown under "GAME RULES" above.

227

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

229 However, note that an AI program with no mobile pieces will immediately lose.

230 ---------------------------------------------------

231 Example:

232 ---------------------------------------------------

233 >> RED ../../agents/vixen/vixen.py 10 10

234 << FB8sB479B8

235 << BB31555583

236 << 6724898974

237 << 967B669999

238

239 In this example, the AI will be playing as "RED". It's opponent is the "vixen" sample AI.

240 The board width and height will always be 10.

241

242 The AI responds with a sensible setup for the "RED" player, putting the flag in the back corner.

243

244 2. Turn

245 ---------------------------------------------------

246 Description

247 ---------------------------------------------------

248 After the Setup phase, a number of Turns occur, until the game ends.

249

250 Warning: The game may end between turns, in which case a "QUIT" message is sent.

251 The "QUIT" message will be sent in place of the first line in the synopsis shown below.

252 Read "3. End Game" below.

253 ---------------------------------------------------

254 Synopsis

255 ---------------------------------------------------

256 For the AI with colour "RED" only, and only on the very first turn:

257 >> START

258 >> $ROW1

259 >> $ROW2

260 >> $ROW3

261 >> $ROW4

262 >> $ROW5

263 >> $ROW6

264 >> $ROW7

265 >> $ROW8

266 >> $ROW9

267 >> $ROW10

268 << $X $Y $DIRECTION [$MULTIPLIER=1]

269 >> $X $Y $DIRECTION [$MULTIPLIER=1] $OUTCOME

270

271 For the AI with colour "RED" on every subsequent turn, and the AI with colour "BLUE" on all turns:

272 >> $LASTMOVE $OUTCOME

273 >> $ROW1

274 >> $ROW2

275 >> $ROW3

276 >> $ROW4

277 >> $ROW5

278 >> $ROW6

279 >> $ROW7

280 >> $ROW8

281 >> $ROW9

282 >> $ROW10

283 << $X $Y $DIRECTION [$MULTIPLIER=1]

284 >> $X $Y $DIRECTION [$MULTIPLIER=1] $OUTCOME | QUIT [$RESULT]

285 ---------------------------------------------------

286 Explanation:

287 ---------------------------------------------------

288

289 [Recieved data 1]

290

291 LASTMOVE - The last move made

292 - That is, the move made by the opponent AI, immediately before this move

293 - It is a direct copy of the opponent AI's response

294 - On the very first turn, since no move has been made, "START" is printed to the RED AI

295

296 OUTCOME - The interpretation of the move by the manager program; will be one of the following

297 - Successful, uneventful move: "OK"

298 - Illegal move: "ILLEGAL"

299 - The moved piece attacked and destroyed an opponent piece: "KILLS $ATTACKER_RANK $DEFENDER_RANK"

300 - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively

301 - The moved piece was destroyed by an opponent piece that it attacked: "DIES $ATTACKER_RANK $DEFENDER_RANK"

302 - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively

303 - The moved piece attacked an opponent piece, and both pieces were destroyed: "BOTHDIE $ATTACKER_RANK $DEFENDER_RANK"

304 - ATTACKER_RANK and DEFENDER_RANK are the ranks of the attacking and defending piece respectively

305 - Game ended due to the attacker capturing a flag: "VICTORY_FLAG"

306 - Game ended due to the destruction of a player's last mobile piece (either attacker or defender): "

307

308 ROW1 -> ROW10 - The state of the board will be printed

309 - Each line represents a row on the board, from the top downwards

310 - The characters are as desribed above in "GAME RULES"

311 - Enemy pieces will NOT be revealed, even if they have been involved in combat. They are always shown as '#'.

312 - It is recommended that AI's rely on the LASTMOVE and OUTCOME results to keep state

313 - Interpreting these lines is not necessary, or recommended

314 - They still exist because I say so. GET OVER IT.

315

316 [Sent data]

317

318 X - The x coordinate of the piece to be moved. Ranges from 0 (zero) to 9 (nine) (left to right)

319 Y - The y coordinate of the piece to be moved. Ranges from 0 (zero) to 9 (nine) (top to bottom)

320 DIRECTION - The direction to move the piece in. May be either "LEFT", "RIGHT", "UP" or "DOWN"

321 MULTIPLIER - Scouts may move more than one square.

322 - To move a scout multiple spaces, print an integer indicating the number of spaces immediately after DIRECTION

323

324 [Recieved data 2]

325

326 The manager program will check the validity of the move, and respond by repeating it back to the AI, followed by OUTCOME.

327 OUTCOME is as described above.

328 ---------------------------------------------------

329 Example:

330 ---------------------------------------------------

331

332 First turn for RED:

333 -------------------

334 >> START

335 >> FB8sB479B8

336 >> BB31555583

337 >> 6724898974

338 >> 967B669999

339 >> ..++..++..

340 >> ..++..++..

341 >> ##########

342 >> ##########

343 >> ##########

344 >> ##########

345 << 0 3 DOWN

346 >> 0 3 DOWN OK

347 -------------------

348 Continuing from the Setup example, the RED AI is told to start, and then the board is printed.

349 Note that only RED's pieces are revealed. The obstacles are always in the same place, as shown.

350 Refer to the "GAME RULES" section for an explanation of each piece character.

351

352 The AI decides to move its scout (9) at (0,3) downwards by one place.

353

354 The manager reports that this move was successful.

355

356 Second Turn for RED:

357 -------------------

358 >> 9 6 UP 3 BOTHDIE 9 9

359 >> FB8sB479B8

360 >> BB31555583

361 >> 6724898974

362 >> .67B66999.

363 >> 9.++..++..

364 >> ..++..++..

365 >> #########.

366 >> ##########

367 >> ##########

368 >> ##########

369 << 9 2 DOWN

370 >> 9 2 DOWN OK

371 -------------------

372 The next message recieved by the RED AI tells it that BLUE has moved its piece at (9,6) up by 3.

373 This brought the piece into contact with RED's scout (9) at (9,3)

374 Since BLUE's piece was also a scout (9), both pieces die, indicated by "BOTHDIE" followed by their ranks (9 and 9)

375

376 The board is printed again. Note that RED's first move is reflected

377 (the scout (9) at (0,4)), and BLUE's last move (both (9,6) and (9,3) are now empty).

378

379 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).

380 ---------------------------------------------------

381 WARNING:

382 ---------------------------------------------------

383 It is recommended that you ignore the board state lines, except for the first turn.

384 Remember that an AI may not place all its pieces, so assuming its initial setup is a bad idea.

385 On subsequent turns, the board state lines provide no information that can't be processed from the move confirmation lines.

386 ---------------------------------------------------

387

388 3. End Game

389 ---------------------------------------------------

390 Description:

391 ---------------------------------------------------

392 A message of "QUIT" at any time signals to an AI that the game is about to end.

393 This will be sent immediately after an AI makes a move of the form "$X $Y $DIRECTION [$MULTIPLIER=1]" which ends the game

394 It may also be sent at any time in case of errors

395

396 The AI should immediately exit if a QUIT message is recieved.

397 ---------------------------------------------------

398 Synopsis:

399 ---------------------------------------------------

400 >> QUIT [$RESULT]

401 ---------------------------------------------------

402 Explanation:

403 ---------------------------------------------------

404 RESULT - Usually not present; it may contain debug information if it is.

405 ---------------------------------------------------

406

407 4. Timeouts

408 ---------------------------------------------------

409 Description:

410 ---------------------------------------------------

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

412 Human players are not subject to the timeout restriction.

413 ---------------------------------------------------

414 Please see the information on the -T switch, and the "End Game" section above.

415

416 5. Resignation

417 ---------------------------------------------------

418 Description:

419 ---------------------------------------------------

420 Instead of making a move, an AI program may resign.

421 ---------------------------------------------------

422 Synopsis:

423 ---------------------------------------------------

424 << SURRENDER

425 >> QUIT SURRENDER

426 ---------------------------------------------------

427 Explanation:

428 ---------------------------------------------------

429

430 ---------------------------------------------------

431

432

433 EXIT/OUTPUT

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

435

436 $NAME $COLOUR $OUTCOME $TURN $RED_PIECE_VALUE $BLUE_PIECE_VALUE

437

438 Where:

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

440

441 COLOUR is the colour of that player,

442

443 OUTCOME is one of the following:

444 VICTORY - The indicated player won

445 DEFEAT - The indicated player lost

446 SURRENDER - The indicated player surrendered

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

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

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

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

451 BOTH_ILLEGAL - Both players made an Illegal move/response. Usually occurs due to simultaneous setup errors.

452 - May occur due to bad AI path names

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

454

455 TURN is the number of turns that elapsed before the game ended

456

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

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

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

460

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

462

463

464 stratego will then return exit code 0.

465

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

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

468

469 BUILDING

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

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

472

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

474

475 To enable graphics:

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

477 #define BUILD_GRAPHICS

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

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

480

481 To disable graphics:

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

483 //#define BUILD_GRAPHICS

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

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

486

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

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

489

490

491

492

493 BUGS

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

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

496

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

498

499

500 AUTHORS

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

502

503 NOTES

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

505

506 1. UCC Programming Competition 2012 Description

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

508

509 2. UCC Programming Competition 2012 Git repository

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

511

512

513 3. IRC Channel

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

515

516 THIS PAGE LAST UPDATED

517 09/04/12 by Sam Moore

518