manual.txt 7.38 KB
Newer Older
1
2
3
4
5
6
7
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
8
	stratego {[-gpirb] [-o output_file ] [-t stall_time] [-m max_turns] {red_player blue_player | -f input_file} | {-h | --help} }
9
10
11
12
13
14

DESCRIPTION
	stratego manages a game of Stratego. It stores the state of the board, and uses a simple protocol to interface with AI programs.
	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 
	various AI strategies, written in any programming language. It will be used for the UCC Programming Competition 2012.

15
	Unless the -h (--help) or -f switch is given, both red_player and blue_player must be supplied.
16
17
18
19
20
21
22
23
24
25
26
27
28
29

	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. As of writing, human players must use stdin. A graphical interface may be added later.

	blue_player
		As red_player, except for controlling the Blue player.
	
OPTIONS
	-g
		By default, graphics are disabled. If the -g switch is present, stratego will draw the game as it is played using OpenGL
30
31
32
33
	-p
		By default, even if graphics are disabled, the board state is not printed. If -p is present, the board will be printed to stdout.
		If the system supports colour, the characters will be in colour.
		If -p and -g are both present you will see both behaviours (overkill)!
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
	-i
		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.
		That is, the move will not be made (effectively the player making the illegal move loses a turn).
	-r
		By default, the identities of all pieces are shown. If the -r switch is present, and graphics are enabled, red pieces will be disguised.
		If graphics are disabled, the -r switch has no effect.
	-b
		As -r, except blue pieces will be disguised.
		NOTE: Both -r and -b may be used.
	-o
		By default, stratego is silent. If the -o switch is present, the result of each move is printed to a file. If output_file is "stdout"
		then stdout will be used instead of a text file.
	-t
		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
		between each move.
49
50
51
52
53
54
55
56
57
58
59
60

	-m
		By default, the game is declared a Draw after 5000 turns have ellapsed.
		Use this option to change the maximum number of turns.
		To play for an infinite number of turns, supply "inf" as max_number.

	-f
		By default, stratego requires red_player and blue_player to enact a game.
		If this option is supplied, a file previously produced by using the -o switch is read, and the game reenacted.
		All switches function as normal with -f.
		NOTE: It is recommended that -g is used with -f.

61
	-h, --help
62
63
64
		If the -h switch is used, this page will be printed and stratego will exit.
		
		
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173

GAME RULES
		Each player sets up 40 pieces on the Board. The pieces consist of the following:

		Piece	Name		Rank	Number	Abilities
		1	Marshal		1	1	Dies if attacked by Spy
		2	General		2	1	
		3	Colonel 	3	2	
		4	Major		4	3	
		5	Captain		5	4	
		6	Lieutenant 	6	4
		7	Sergeant   	7	4
		8	Miner		8	5	Destroys Bombs without being killed
		9	Scout		9	8	May move more through multiple empty squares
		s	Spy		10	1	If the Spy attacks the Marshal, the Marshal dies
		B	Bomb		NA	6	Immobile. If an enemy piece (except a Miner) encounters a Bomb, both pieces are destroyed
		F	Flag		NA	1	Immobile. If any enemy piece encounters the Flag, the controlling player wins.

		Pieces may move one square horizontally or vertically unless otherwise stated.
		Pieces may not move through squares occupied by allied pieces.
		Pieces may move into squares occupied by enemy pieces, in which case the piece with the lower rank (higher number) is destroyed.

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

		The objective is to destroy all enemy pieces or capture the Flag.
		

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.

	2. TURN
		QUERY: START | CONFIRMATION
			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).

		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.

		CONFIRMATION: X Y DIRECTION [MULTIPLIER=1] OUTCOME
			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.

	3. END GAME
		QUERY: VICTORY | DEFEAT | ILLEGAL | DEFAULT
			VICTORY - This player won the game
			DEFEAT - The other player won the game
			ILLEGAL - Game ended because this player made a bad response or timed out
				(NOTE: Even if the -i option is provided, the game may end with an ILLEGAL signal if a bad response is made)
			DEFAULT - Game ended because the other player made a bad response.

			No response is necessary; the program should exit or it will be sent a SIGKILL signal.
	
	4. TIMEOUTS
		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.
		Human players are not subject to the timeout restriction.
		
			

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.

	1.
		WINNING_NAME WINNING_COLOUR TURNS
	2.
		DRAW TURNS
		When the result was a draw

	3.
		NONE TURNS
		When for some reason both the AI programs failed to respond or crashed.

	stratego will then return exit code 0.

	If an error occurs within stratego itself, an error message will be printed to stderr and return exit code 1.
	If possible, stratego will print the message "QUIT" to both AI programs, and they should exit as soon as possible.
	

BUGS
	There are no known bugs at this time. However, stratego is still a work in progress. Report a bug to the AUTHOR (see below).

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

NOTES
	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/

	2. UCC Programming Competition 2012 Git repository
	   git://git.ucc.asn.au/progcomp2012.git

 
	3. IRC Channel
	   irc://irc.ucc.asn.au #progcomp