1 Ricochet Robots Game Protocol (RRGP)
5 Keith Packard Carl Worth
6 keithp@keithp.com carl@theworths.org
10 RRGP is a network protocol for playing the Ricochet Robots game. It permits
11 a single server to host multiple games with named participants. The
12 protocol is designed so that people can play using only telnet, but it is
13 expected that graphical interfaces will be able to drive the protocol as
16 RRGP borrows ideas from other network protocols like SMTP using a
17 synchronous command interface.
21 All commands include a response (yeah, synchronous protocols are
39 The RRGP server has no well defined port; agreement on which port to
40 use must be done through some external mechanism. Once connected,
41 the client must identify itself:
47 HELO <servername> <username> <server-addr> <server-port>
49 If the client doesn't supply <username>, the server will compute
52 Possible errors: INVALIDNAME
56 1.2.1 Listing available users
62 WHO <username1> <games1> <username2> <games2> ...
64 lists connected users and the number of games they've won.
66 1.2.2. Listing available games
72 GAMES <game1> <game2> ...
86 Displays help. If <command> is provided, displays more
87 detailed help on a specific command, otherwise displays an
88 overview of all commands.
100 VERSION <client-version-number>
104 VERSION <server-version-number>
106 Negotiates version number between client and server. The server
107 will respond with a version no higher than the client version
108 number, but it may be lower. Version numbers are integers.
110 This document describes protocol version 1.
112 1.3. Game management commands
114 1.3.1. Listing players in a game
120 PLAYERS <username1> <score1> <username2> <score2> ...
122 Possible errors: NOGAME
124 1.3.2. Listing watchers of a game
130 WATCERS <username1> <username2> ...
132 Possible errors: NOGAME
134 1.3.3. Get game information
140 GAMEINFO <turn> <color> <shape> <state> <time> <bid> <active>
142 <turn> is a number from 1 to 17 indicating the current turn
143 <color> <shape> indicate the active piece
145 new Turn just started, no bids yet
146 bid Bidding opened. <time> indicates time remaining,
147 <bid> indicates the minimum bid
148 show Bidding closed and solution being demonstrated
149 <active> indicates the person demonstrating
150 done Current turn is over. Either a solution
151 was demonstrated or the players have all
152 given up trying to find a solution.
153 <time> is valid only in BID state, else it's 0
154 <bid> is valid in all but NEW state where it's 0
155 <active> is valid in SHOW state, else it's ""
157 Possible errors: NOGAME
159 1.3.4. Creating a new game
161 NEW <game-suggestion>
167 1.3.5. Joining an existing game
175 Possible errors: NOGAME
177 1.3.6. Watching an existing game
185 The client will monitor the game, but not be listed in the
186 userlist nor be allowed to make moves.
188 Possible errors: NOGAME
190 1.3.7. Dispose an empty game
198 Disposes <game> unless it still has players associated.
200 Possible errors: NOGAME NOTEMPTY
202 1.4. User information commands
204 1.4.1. Get user information
210 USERINFO <game> <playing> <score> <bid>
212 <game> is any currently associated game, else "". If the user
213 is not associated with any game, the remaining fields are
216 <playing> is true if the user is playing and false if watching.
218 <score> is a number from 0 to 17 indicating this players score
220 <bid> is either "0" indicating no bid or a number indicating
221 the users minimum bid.
223 1.5. In-game commands
225 1.5.1. Global game commands
227 1.5.1.1 Get the game contents
235 <game-board> is a quoted multi-line string containing an
236 diagram of the game contents, (an array of cells). A single
237 cell and its surrounding are indicated as:
245 r = '.' or <robot-color> (one of 'r', 'g', 'b', or 'y')
246 c = '.' or <target-color> (one of 'r', 'g', 'b', or 'y')
247 s = '.' or <target-shape> (one of 'c', 's', 'o', or 't')
249 The goal robot and target (color and shape) are indicated with
261 R.. = Red robot (goal robot)
262 .gs = Green square target
263 byc = Blue robot on yellow circle target
264 .RT = Red triangle (goal target)
266 Possible errors: NOTINGAME
276 Advance the game to the next turn, (which will have a new
277 target square). TURN is valid only when the game is in
280 Possible errors: NOTINGAME, NOTDONE
290 Departs the current game
292 1.5.2. Bidding commands
302 Possible errors: NOTINGAME, NOTBIDDING, NOTNUMBER, NOTLOWER
312 Possible errors: NOTINGAME, NOTBIDDING, NOBID
322 Possible errors: NOTINGAME, NOTBIDDING
324 Mark this user as having abandoned this turn. If all users
325 abandon, then the game state is switched to DONE.
327 1.5.2.4. No more bids
335 Possible errors: NOTINGAME, NOTBIDDING
337 Mark this user as done bidding. If all users NOBID, then
338 the game state is switched to SHOW.
340 1.5.3. Solving commands
344 MOVE <color> <dir1> <dir2> ...
350 <color> is one of 'R', 'Y', 'G' or 'B', <dir> is one of 'N',
353 Possible errors: NOTINGAME, NOTACTIVE, BLOCKED, TOOMANYMOVES
365 Possible errors: NOTINGAME, NOTACTIVE
367 XXX: Do we add another error code for no further undo?
377 Resets robot positions to that at the start of the turn.
379 Possible errors: NOTINGAME, NOTACTIVE
381 1.5.3.4. Pass the demonstration to the next lowest bidder
389 Possible errors: NOTINGAME
391 2. Asynchronous notification.
393 The server will send notices to each user in a game whenever
394 there is a move. It will also send notices to every connected
395 client when additional people join or new games are
396 started. These are of the form:
398 NOTICE <notice-code> <args>
400 Game-specific notices are sent to users involved in the related
401 game, other notices are sent to all users. Note that even the user
402 originating the notice receives a copy.
406 These notices are sent to all connected clients
410 NOTICE USER <username>
412 2.1.2. Disconnected user
414 NOTICE QUIT <username>
420 2.1.4. Terminated games
422 NOTICE DISPOSE <game>
426 NOTICE MESSAGE <username> <text>
430 These notices are sent to all players and watchers in
433 2.2.1. Global game notices
435 2.2.1.1. Board layout change
437 NOTICE BOARD <game-board>
439 The layout of the game board has changed. <game-board> is
440 formatted as in the reply to the SHOW request.
442 2.2.1.2. Game state change
444 NOTICE GAMESTATE <state>
446 Game state has changed to <state>. <state> is one
447 of "NEW", "BID", "SHOW" or "DONE".
449 2.2.1.3. Next turn (game)
451 NOTICE TURN <color> <shape>
453 Note that the game state is implicitly changed to New
455 2.2.1.4. Next game (game)
459 2.2.1.5. Join game (game)
461 NOTICE JOIN <username>
463 2.2.1.6. Watch game (game)
465 NOTICE WATCH <username>
467 2.2.1.7. User departed game (game)
469 NOTICE PART <username>
473 Notices sent duing the bidding phase of a turn
477 NOTICE BID <username> <number>
479 2.2.2.2. Revoke (game)
481 NOTICE REVOKE <username>
483 The specific user has revoked their bid. If there
484 are no other bids outstanding, the game state is
487 2.2.2.3. Timer (game)
489 NOTICE TIMER <seconds>
491 Timer ticks are sent every 10 seconds after the first
494 2.2.2.4. Abandon request
496 NOTICE ABANDON <username>
498 <username> has requested that the current turn be abandoned
499 before bidding has closed. If all players make such
500 a request, the TURN command may be used to move to the next
503 2.2.2.5. Nobid request
505 NOTICE NOBID <username>
507 <username> has announced that they plan on making no more bids
508 in the current turn. If all players make such a request,
509 the game moves to the SHOW state.
511 2.2.3. Solving notices
513 Notices sent during the solving phase of a turn
515 2.2.3.1. Select active player (game)
517 NOTICE ACTIVE <username> <bid>
519 Only the active player may move the robots
521 2.2.3.2. Move notice (game)
523 NOTICE MOVE <count> <color> <dir>
529 2.2.3.4. Reset (game)
533 2.2.3.5. Position (after move/undo/reset)
535 NOTICE POSITION <color> <x> <y>
537 The indicated robot has moved to the indicated position.
538 The board is 0-based with the origin in the upper left
541 2.2.3.6. Score (game)
543 NOTICE SCORE <username> <score>
545 The indicated user has demonstrated a solution and
550 These notices are sent to a single user
552 2.3.1. Solving notices
554 Notices sent during the solving phase of a turn
556 2.3.1.1. Notify active player (user)
558 NOTICE ACTIVATE <bid>
560 Sent to the player which has just become active
564 The following error codes may be returned.
566 3.1. Connection setup errors
568 These errors occur during connection setup.
574 'helo' must be sent before any command other than 'quit'.
580 All names must be unique.
582 Possibly returned by: HELO
584 3.2. Command format errors
586 Errors caused by ill-formed commands
592 An invalid command was specified
598 A syntax error was detected
604 A non-numeric value was supplied where a number was required
610 The color name specified in the command was invalid
616 The shape name specified in the command was invalid
622 The direction name specified in the command was invalid
624 3.3. Global command errors.
626 There are no errors from any of the global commands
628 3.4. Game management errors.
630 Errors from game management commands
636 A game name was provided that does not exist.
642 DISPOSE was requested for a game with active players
644 3.5. User information errors
650 A user name was provided that does not exist.
654 3.6.1. Global game errors
660 A game playing command was made, but the user is not a
661 particpant of any game.
663 Possibly returned by: SHOW, MOVE, RESET, UNDO, TURN, PASS,
670 A command was executed by a watching user that is
671 permitted only to players
677 TURN was requested and the game is not in DONE state.
679 3.6.2. Bidding errors
685 A bid was submitted after the bidding closed
687 Possibly returned by: BID
693 A bid was submitted that was higher than previous bid.
695 Possibly returned by: BID
701 A revoke was requested when no bid had been entered
703 Possibly returned by: REVOKE
705 3.6.3. Solving mode errors
711 A move, undo or reset was submitted by other than the
714 Possibly returned by: MOVE, RESET, UNDO
720 The robot cannot move the requested direction.
722 Possibly returned by: MOVE
724 3.6.3.3. TOOMANYMOVES
728 An attempt was made to make more moves than the users bid
730 Possibly returned by: MOVE