Merge branch 'upstream'
[pkg/netris.git] / robot_desc
1 $Id: robot_desc,v 1.4 1999/05/16 06:56:30 mhw Exp $
2
3
4 GENERAL PROTOCOL
5 ================
6 When you pass the "-r <robot>" option to Netris, it launches
7 "/bin/sh -c <robot>" as a subprocess and communicates to it via pipes.
8
9 The robot reads events from Netris through stdin, and writes commands to
10 stdout.  All exchanges are ASCII lines composed of tokens separated by
11 spaces.  The first token in a line is the name of the command.
12
13 The robot should ignore commands which it doesn't recognize.  The protocol
14 may be extended by adding extra commands without incrementing the version
15 number.  The version number will only be increased when a command cannot
16 be safely ignored.
17
18 Netris will also ignore commands which it doesn't recognize, for the same
19 reason.
20
21
22 INITIALIZATION
23 ==============
24 The initial exchange between Netris and the robot is Version negotiation.
25 Each sends a "Version <num>" line to the other, and the lowest version is
26 used.  Currently, the robot protocol version is 1.
27
28 Next, Netris sends "GameType <type>", there <type> is either OnePlayer
29 or ClassicTwo.  There may be other games in the future.
30
31 Then Netris sends "BoardSize <player> <height> <width>" for each player.
32 <player> is 0 for the computer player and 1 for the opponent, if any.
33 Other numbers may be used in the future.
34
35 For each opponent, Netris sends "Opponent <player> <username> <host>".
36 <host> is not necessarily a fully qualified host name, unfortunately.
37 It might even be something like "localhost".  
38
39 For each opponent, Netris may send 0 or more flags associated with the
40 opponent.  For each flag which is true, Netris sends
41 "OpponentFlag <player> <flag>".  Currently, the flags are "robot" and
42 "fairRobot".
43
44 Next, Netris sends "TickLength <seconds>", where <seconds> is the number
45 of seconds between pieces stepping down.
46
47 Finally, a "BeginGame" command is sent to the robot.
48
49
50 NORMAL GAME (Netris --> robot)
51 ==============================
52 Here's a list of commands sent from Netris to the robot, and a brief
53 description of each one.
54
55 Exit
56 ----
57 This is always sent to the robot when the game is over, for any reason.
58 The robot should exit immediately.
59
60 NewPiece <num>
61 --------------
62 This command is never sent in "fair" robot mode.
63
64 Every time a new piece is created, this command is sent to the robot.
65 <num> is a positive integer uniquely identifying the piece.  <num> should
66 be sent as a parameter to each movement command (sent to Netris) in
67 order to prevent accidental movement of the wrong piece.
68
69 TimeStamp <seconds>
70 -------------------
71 This command may be sent to the robot at any time.  <seconds> is
72 a floating point number of seconds since the beginning of the game.
73 One is always sent immediately after "BeginGame" and "RowUpdate" commands.
74 One will be sent at least every tick (see "TickLength") unless the game
75 is paused.
76
77 RowUpdate <player> <row> <col0> <col1> <col2> ... <coln>
78 --------------------------------------------------------
79 Whenever the screen changes, a group of these commands is sent to the
80 robot followed by a "TimeStamp".  After a "RowUpdate" command, the robot's
81 view of the board is incorrect until the "TimeStamp".
82
83 <player> is 0 for the computer player and positive numbers for opponents.
84 <row> is an integer from 0 to boardHeight-1.  0 is the bottom row.
85
86 <col0> ... <coln> are integers separated by spaces, one for each column.
87 "0" indicates an empty square.  Positive integers indicates blocks.
88 Currently only "1" is used, but in the future there may be special kinds of
89 blocks indicated by higher numbers.  Negative integers indicate part of
90 the currently falling piece.  For each block, the absolute value of the
91 number indicates the type of piece, and the sign indicates whether it is
92 currently falling.
93
94 If Netris is in "fair robot" (-F) mode, Netris will not highlight the
95 falling piece with negative numbers.  In this case, all numbers will
96 be non-negative.
97
98 UserKey <key> <keyname>
99 -----------------------
100 Whenever the user presses a key, this command is sent to the robot.  The
101 key is not automatically interpreted by Netris.
102
103 <key> is the ascii value of the key, from 0 to 255.  <keyname> is one
104 of the following strings: "Left", "Rotate", "Right", "Drop", "Down",
105 "ToggleSpy", "Pause", or "?".  When possible, you should use <keyname>,
106 since it will pay attention to keyboard remappings.
107
108 For each possible <keyname> (other than "?"), there's an equivalent
109 command recognized by Netris from the robot which performs the equivalent
110 of the key.  Therefore, if you want give the user "manual" control, you
111 can send Netris "<keyname> <piecenum>".
112
113 Pause <pausedByMe> <pausedByThem>
114 ---------------------------------
115 <pausedByMe> is 0 or 1, indicating whether the game is currently paused by
116 our side.  <pausedByThem> is 0 or 1, indicating whether any player other
117 than our side has paused the game.  If either is 1, the game is paused.
118
119 You may actually receive this command even when neither of the flags change.
120
121
122 NORMAL GAME (robot --> Netris)
123 ==============================
124 Here's a list of commands recognized by Netris from the robot:
125
126 Left <num>
127 Rotate <num>
128 Right <num>
129 Drop <num>
130 Down <num>
131 ToggleSpy <num>
132 Pause <num>
133 ---------------
134 These commands perform the equivalent of typing the corresponding command
135 on the keyboard, if you weren't in robot mode.  
136
137 <num> is checked against the current piece number (the value sent along
138 with "NewPiece" commands).  If it doesn't match, the command is ignored.
139 However, in "fair robot" mode, the <num> is ignored.
140
141 These commands (except "Pause") are also ignored if the game is paused.
142
143 Message <message>
144 -----------------
145 <message> is printed on the messages part of the display.  Messages too
146 long to fit on the screen may be truncated.
147
148 <message> may contain spaces and printable characters only.
149
150
151 EXAMPLE
152 =======
153 Here's a portion of an example log generated by the sample robot.  The
154 sample robot generates a log file in "log" if the "-l" is given to sr
155 (eg "netris -r 'sr -l'").
156
157 In this log file, every line is preceeded by two characters.  Lines
158 sent from Netris to the robot are preceeded by two spaces "  ", and
159 lines sent to Netris are preceeded by "> ".
160
161 > Version 1
162   Version 1
163   GameType OnePlayer
164   BoardSize 0 20 10
165   TickLength 0.300
166   BeginGame
167   TimeStamp 0.009
168   NewPiece 1
169   RowUpdate 0 19 0 0 0 0 0 -1 -1 0 0 0
170   TimeStamp 0.010
171   RowUpdate 0 19 0 0 0 0 -1 -1 0 0 0 0
172   RowUpdate 0 18 0 0 0 0 0 -1 -1 0 0 0
173   TimeStamp 0.314
174 > Message Goal 0 : ** :**  :    :    :
175 > Left 1
176   TimeStamp 0.352
177   RowUpdate 0 19 0 0 0 -1 -1 0 0 0 0 0
178   RowUpdate 0 18 0 0 0 0 -1 -1 0 0 0 0
179   TimeStamp 0.362
180 > Left 1
181   RowUpdate 0 19 0 0 -1 -1 0 0 0 0 0 0
182   RowUpdate 0 18 0 0 0 -1 -1 0 0 0 0 0
183   TimeStamp 0.375
184 > Left 1
185   RowUpdate 0 19 0 -1 -1 0 0 0 0 0 0 0
186   RowUpdate 0 18 0 0 -1 -1 0 0 0 0 0 0
187   TimeStamp 0.387
188 > Left 1
189   RowUpdate 0 19 -1 -1 0 0 0 0 0 0 0 0
190   RowUpdate 0 18 0 -1 -1 0 0 0 0 0 0 0
191   TimeStamp 0.399
192 > Drop 1
193   RowUpdate 0 19 0 0 0 0 0 0 0 0 0 0
194   RowUpdate 0 18 0 0 0 0 0 0 0 0 0 0
195   RowUpdate 0 1 -1 -1 0 0 0 0 0 0 0 0
196   RowUpdate 0 0 0 -1 -1 0 0 0 0 0 0 0
197   TimeStamp 0.413
198   NewPiece 2
199   RowUpdate 0 19 0 0 0 0 0 -1 0 0 0 0
200   RowUpdate 0 1 1 1 0 0 0 0 0 0 0 0
201   RowUpdate 0 0 0 1 1 0 0 0 0 0 0 0
202   TimeStamp 0.715
203   RowUpdate 0 19 0 0 0 0 -1 -1 -1 0 0 0
204   RowUpdate 0 18 0 0 0 0 0 -1 0 0 0 0
205   TimeStamp 1.014
206 > Message Goal 3 :*** : *  :    :    :
207 > Rotate 2
208   TimeStamp 1.053
209   RowUpdate 0 19 0 0 0 0 0 -1 -1 0 0 0
210   RowUpdate 0 18 0 0 0 0 0 -1 0 0 0 0
211   TimeStamp 1.062
212   RowUpdate 0 19 0 0 0 0 0 -1 0 0 0 0
213   RowUpdate 0 18 0 0 0 0 0 -1 -1 0 0 0
214   RowUpdate 0 17 0 0 0 0 0 -1 0 0 0 0
215   TimeStamp 1.314
216 > Rotate 2
217   RowUpdate 0 19 0 0 0 0 0 -1 0 0 0 0
218   RowUpdate 0 18 0 0 0 0 -1 -1 -1 0 0 0
219   RowUpdate 0 17 0 0 0 0 0 0 0 0 0 0
220   TimeStamp 1.326
221 [...]
222   Exit
223
224
225 # vi: tw=70 ai