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