1 $Id: robot_desc,v 1.4 1999/05/16 06:56:30 mhw Exp $
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.
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.
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
18 Netris will also ignore commands which it doesn't recognize, for the same
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.
28 Next, Netris sends "GameType <type>", there <type> is either OnePlayer
29 or ClassicTwo. There may be other games in the future.
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.
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".
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
44 Next, Netris sends "TickLength <seconds>", where <seconds> is the number
45 of seconds between pieces stepping down.
47 Finally, a "BeginGame" command is sent to the robot.
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.
57 This is always sent to the robot when the game is over, for any reason.
58 The robot should exit immediately.
62 This command is never sent in "fair" robot mode.
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.
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
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".
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.
86 <col0> ... <coln> are integers separated by spaces, one for each column.
87 "0" indicates an empty square. Positive integers indicate 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
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
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.
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.
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>".
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.
119 You may actually receive this command even when neither of the flags change.
122 NORMAL GAME (robot --> Netris)
123 ==============================
124 Here's a list of commands recognized by Netris from the robot:
134 These commands perform the equivalent of typing the corresponding command
135 on the keyboard, if you weren't in robot mode.
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.
141 These commands (except "Pause") are also ignored if the game is paused.
145 <message> is printed on the messages part of the display. Messages too
146 long to fit on the screen may be truncated.
148 <message> may contain spaces and printable characters only.
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" option is given
155 to sr (eg "netris -r 'sr -l'").
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 "> ".
169 RowUpdate 0 19 0 0 0 0 0 -1 -1 0 0 0
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
174 > Message Goal 0 : ** :** : : :
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
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
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
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
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
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
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
206 > Message Goal 3 :*** : * : : :
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
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
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