Commit RRGP protocol document as a starting point.
authorCarl Worth <carl@theworths.org>
Sat, 5 Nov 2005 14:57:56 +0000 (14:57 +0000)
committerCarl Worth <carl@theworths.org>
Sat, 5 Nov 2005 14:57:56 +0000 (14:57 +0000)
PROTOCOL [new file with mode: 0644]

diff --git a/PROTOCOL b/PROTOCOL
new file mode 100644 (file)
index 0000000..a97a176
--- /dev/null
+++ b/PROTOCOL
@@ -0,0 +1,732 @@
+                Ricochet Robots Game Protocol (RRGP)
+                          Version 0.1.2
+                            2003-5-31
+               
+                 Keith Packard         Carl Worth
+               keithp@keithp.com   carl@theworths.org
+
+Introduction
+
+RRGP is a network protocol for playing the Ricochet Robots game.  It permits
+a single server to host multiple games with named participants.  The
+protocol is designed so that people can play using only telnet, but it is
+expected that graphical interfaces will be able to drive the protocol as
+well.
+
+RRGP borrows ideas from other network protocols like SMTP using a
+synchronous command interface.
+
+Document Conventions
+
+       All commands include a response (yeah, synchronous protocols are
+       bad.  tough)
+
+       <command> <args> 
+
+       ->
+
+       <response>
+
+       <response> is one of:
+
+       <command> <args>
+       ERROR <message>
+
+1. Requests
+
+1.1 Connection setup
+
+    The RRGP server has no well defined port; agreement on which port to
+    use must be done through some external mechanism.  Once connected,
+    the client must identify itself:
+    
+    HELO [<username>]
+    
+    ->
+    
+    HELO <servername> <username> <server-addr> <server-port>
+
+    If the client doesn't supply <username>, the server will compute
+    one and return it.
+
+    Possible errors: INVALIDNAME
+
+1.2. Global commands
+
+    1.2.1 Listing available users
+
+       WHO
+
+       ->
+
+       WHO <username1> <games1> <username2> <games2> ...
+
+       lists connected users and the number of games they've won.
+
+    1.2.2. Listing available games
+
+       GAMES
+
+       ->
+
+       GAMES <game1> <game2> ...
+
+    1.2.3. Message
+
+       MESSAGE <text>
+
+       ->
+       
+       MESSAGE
+
+    1.2.4. Help
+
+       HELP { <command> }
+
+       Displays help.  If <command> is provided, displays more
+       detailed help on a specific command, otherwise displays an
+       overview of all commands.
+
+    1.2.5. Quit
+
+       QUIT
+
+       ->
+
+       QUIT
+
+    1.2.6. Version
+
+       VERSION <client-version-number>
+
+       ->
+
+       VERSION <server-version-number>
+
+       Negotiates version number between client and server.  The server
+       will respond with a version no higher than the client version
+       number, but it may be lower.  Version numbers are integers.
+
+       This document describes protocol version 1.
+
+1.3. Game management commands
+
+    1.3.1. Listing players in a game
+
+       PLAYERS <game>
+
+       ->
+
+       PLAYERS <username1> <score1> <username2> <score2> ...
+
+       Possible errors: NOGAME
+
+    1.3.2. Listing watchers of a game
+
+       WATCHERS <game>
+
+       ->
+
+       WATCERS <username1> <username2> ...
+
+       Possible errors: NOGAME
+
+    1.3.3. Get game information
+
+       GAMEINFO <game>
+
+       ->
+
+       GAMEINFO <turn> <color> <shape> <state> <time> <bid> <active>
+
+       <turn> is a number from 1 to 17 indicating the current turn
+       <color> <shape> indicate the active piece
+       <state> is one of:
+               new     Turn just started, no bids yet
+               bid     Bidding opened.  <time> indicates time remaining,
+                       <bid> indicates the minimum bid
+               show    Bidding closed and solution being demonstrated
+                       <active> indicates the person demonstrating
+               done    Current turn is over.  Either a solution
+                        was demonstrated or the players have all
+                       given up trying to find a solution.
+       <time> is valid only in BID state, else it's 0
+       <bid> is valid in all but NEW state where it's 0
+       <active> is valid in SHOW state, else it's ""
+
+       Possible errors: NOGAME
+
+    1.3.4. Creating a new game
+
+       NEW <game-suggestion>
+
+       ->
+
+       NEW <game>
+
+    1.3.5. Joining an existing game
+
+       JOIN <game>
+
+       ->
+
+       JOIN
+
+       Possible errors: NOGAME
+
+    1.3.6. Watching an existing game
+
+       WATCH <game>
+
+       ->
+
+       WATCH
+
+       The client will monitor the game, but not be listed in the
+       userlist nor be allowed to make moves.
+
+       Possible errors: NOGAME
+
+    1.3.7. Dispose an empty game
+
+       DISPOSE <game>
+
+       ->
+
+       DISPOSE
+
+       Disposes <game> unless it still has players associated.
+
+       Possible errors: NOGAME NOTEMPTY
+
+1.4. User information commands
+
+    1.4.1. Get user information
+    
+       USERINFO <username>
+    
+       ->
+    
+       USERINFO <game> <playing> <score> <bid>
+    
+       <game> is any currently associated game, else "".  If the user
+       is not associated with any game, the remaining fields are
+       false 0 0.
+       
+       <playing> is true if the user is playing and false if watching.
+    
+       <score> is a number from 0 to 17 indicating this players score
+    
+       <bid> is either "0" indicating no bid or a number indicating
+       the users minimum bid.
+           
+1.5. In-game commands
+
+    1.5.1. Global game commands
+
+       1.5.1.1 Get the game contents
+    
+           SHOW
+    
+           ->
+    
+           SHOW <game-board>
+    
+           <game-board> is a quoted multi-line string containing an
+           diagram of the game contents, (an array of cells). A single
+           cell and its surrounding are indicated as:
+    
+            HHH 
+           VrcsV
+            HHH
+    
+           H = ' ' or '='
+           V = ' ' or '|'
+           r = '.' or <robot-color>  (one of 'r', 'g', 'b', or 'y')
+           c = '.' or <target-color> (one of 'r', 'g', 'b', or 'y')
+           s = '.' or <target-shape> (one of 'c', 's', 'o', or 't')
+    
+           The goal robot and target (color and shape) are indicated with
+           capital letters.
+    
+           For example:
+    
+           SHOW "
+            ===         
+           |R.. ... .gs 
+                        
+            byc|... .RT|
+            ===     === "
+    
+           R.. =       Red robot (goal robot)
+           .gs =       Green square target
+           byc =       Blue robot on yellow circle target
+           .RT =       Red triangle (goal target)
+    
+           Possible errors: NOTINGAME
+    
+       1.5.1.2. Next turn
+    
+           TURN
+    
+           ->
+    
+           TURN
+    
+           Advance the game to the next turn, (which will have a new
+           target square).  TURN is valid only when the game is in
+           the DONE state
+                   
+           Possible errors: NOTINGAME, NOTDONE
+    
+       1.5.1.3. Part
+    
+           PART
+    
+           ->
+    
+           PART
+    
+           Departs the current game
+    
+    1.5.2. Bidding commands 
+
+       1.5.2.1 Bid
+    
+           BID <number>
+    
+           ->
+    
+           BID
+    
+           Possible errors: NOTINGAME, NOTBIDDING, NOTNUMBER, NOTLOWER
+    
+       1.5.2.2. Revoke
+    
+           REVOKE
+    
+           ->
+    
+           REVOKE
+    
+           Possible errors: NOTINGAME, NOTBIDDING, NOBID
+    
+       1.5.2.3. Abandon
+    
+           ABANDON
+    
+           ->
+    
+           ABANDON
+    
+           Possible errors: NOTINGAME, NOTBIDDING
+    
+           Mark this user as having abandoned this turn.  If all users
+           abandon, then the game state is switched to DONE.
+
+       1.5.2.4. No more bids
+
+           NOBID
+
+           ->
+
+           NOBID
+
+           Possible errors: NOTINGAME, NOTBIDDING
+    
+           Mark this user as done bidding.  If all users NOBID, then
+           the game state is switched to SHOW.
+    
+    1.5.3. Solving commands
+
+       1.5.3.1. Move
+    
+           MOVE <color> <dir1> <dir2> ...
+    
+           ->
+    
+           MOVE <count>
+    
+           <color> is one of 'R', 'Y', 'G' or 'B', <dir> is one of 'N',
+           'E', 'S' or 'W'.
+    
+           Possible errors: NOTINGAME, NOTACTIVE, BLOCKED, TOOMANYMOVES
+    
+       1.5.3.2. Undo
+    
+           UNDO
+    
+           ->
+    
+           UNDO
+    
+           Undoes the last move
+    
+           Possible errors: NOTINGAME, NOTACTIVE
+    
+           XXX: Do we add another error code for no further undo?
+    
+       1.5.3.3. Reset
+    
+           RESET
+    
+           ->
+    
+           RESET
+    
+           Resets robot positions to that at the start of the turn.
+    
+           Possible errors: NOTINGAME, NOTACTIVE
+    
+       1.5.3.4. Pass the demonstration to the next lowest bidder
+    
+           PASS
+    
+           ->
+    
+           PASS
+    
+           Possible errors: NOTINGAME
+       
+2. Asynchronous notification.  
+
+    The server will send notices to each user in a game whenever
+    there is a move. It will also send notices to every connected
+    client when additional people join or new games are
+    started. These are of the form:
+
+       NOTICE <notice-code> <args>
+
+    Game-specific notices are sent to users involved in the related
+    game, other notices are sent to all users.  Note that even the user
+    originating the notice receives a copy.
+
+2.1. Global notices
+
+    These notices are sent to all connected clients
+
+    2.1.1. New users
+    
+       NOTICE USER <username>
+    
+    2.1.2. Disconnected user
+    
+       NOTICE QUIT <username>
+    
+    2.1.3. New games
+    
+       NOTICE GAME <game>
+    
+    2.1.4. Terminated games
+    
+       NOTICE DISPOSE <game>
+    
+    2.1.5. Message
+
+       NOTICE MESSAGE <username> <text>
+
+2.2. Game notices
+
+    These notices are sent to all players and watchers in
+    the affected game
+
+    2.2.1. Global game notices
+
+       2.2.1.1. Board layout change
+
+           NOTICE BOARD <game-board>
+
+           The layout of the game board has changed. <game-board> is
+           formatted as in the reply to the SHOW request.
+       
+       2.2.1.2. Game state change
+       
+           NOTICE GAMESTATE <state>
+
+           Game state has changed to <state>.  <state> is one
+           of "NEW", "BID", "SHOW" or "DONE".
+
+       2.2.1.3. Next turn (game)
+
+           NOTICE TURN <color> <shape>
+
+           Note that the game state is implicitly changed to New
+
+       2.2.1.4. Next game (game)
+
+           NOTICE GAMEOVER
+
+       2.2.1.5. Join game (game)
+       
+           NOTICE JOIN <username>
+       
+       2.2.1.6. Watch game (game)
+       
+           NOTICE WATCH <username>
+       
+       2.2.1.7. User departed game (game)
+       
+           NOTICE PART <username>
+
+    2.2.2. Bid notices
+
+       Notices sent duing the bidding phase of a turn
+    
+       2.2.2.1. Bids (game)
+       
+           NOTICE BID <username> <number>
+       
+       2.2.2.2. Revoke (game)
+       
+           NOTICE REVOKE <username>
+
+           The specific user has revoked their bid. If there
+           are no other bids outstanding, the game state is
+           returned to New.
+       
+       2.2.2.3. Timer (game)
+       
+           NOTICE TIMER <seconds>
+    
+           Timer ticks are sent every 10 seconds after the first
+           bid has been made
+
+       2.2.2.4. Abandon request
+
+           NOTICE ABANDON <username>
+    
+           <username> has requested that the current turn be abandoned
+           before bidding has closed.  If all players make such
+           a request, the TURN command may be used to move to the next
+           turn.
+
+       2.2.2.5. Nobid request
+
+           NOTICE NOBID <username>
+
+           <username> has announced that they plan on making no more bids
+           in the current turn.  If all players make such a request,
+           the game moves to the SHOW state.
+
+   2.2.3. Solving notices
+
+       Notices sent during the solving phase of a turn
+               
+       2.2.3.1. Select active player (game)
+
+           NOTICE ACTIVE <username> <bid>
+
+           Only the active player may move the robots
+
+       2.2.3.2. Move notice (game)
+
+           NOTICE MOVE <count> <color> <dir>
+
+       2.2.3.3. Undo (game)
+
+           NOTICE UNDO
+
+       2.2.3.4. Reset (game)
+
+           NOTICE RESET
+
+       2.2.3.5. Position (after move/undo/reset)
+
+           NOTICE POSITION <color> <x> <y>
+
+           The indicated robot has moved to the indicated position.
+           The board is 0-based with the origin in the upper left
+           corner.
+
+       2.2.3.6. Score (game)
+
+           NOTICE SCORE <username> <score>
+
+           The indicated user has demonstrated a solution and
+           received a point.
+
+2.3. User notices
+
+     These notices are sent to a single user
+
+     2.3.1. Solving notices
+
+       Notices sent during the solving phase of a turn
+               
+       2.3.1.1. Notify active player (user)
+
+           NOTICE ACTIVATE <bid>
+
+           Sent to the player which has just become active
+           
+3. Errors
+
+    The following error codes may be returned.
+
+3.1. Connection setup errors
+
+    These errors occur during connection setup.
+
+    3.1.1. No name set
+    
+       ERROR NONAMESET
+    
+       'helo' must be sent before any command other than 'quit'.
+    
+    3.1.2. Invalid name
+    
+       ERROR INVALIDNAME
+    
+       All names must be unique.
+
+       Possibly returned by: HELO
+
+3.2. Command format errors
+
+    Errors caused by ill-formed commands
+    
+    3.2.1. Command
+    
+       ERROR COMMAND
+    
+       An invalid command was specified
+    
+    3.2.2. Syntax
+    
+       ERROR SYNTAX
+    
+       A syntax error was detected
+    
+    3.2.3. Not number
+    
+       ERROR NOTNUMBER
+    
+       A non-numeric value was supplied where a number was required
+       
+    3.2.4. Not color
+    
+       ERROR NOTCOLOR
+    
+       The color name specified in the command was invalid
+    
+    3.2.5. Not shape
+    
+       ERROR NOTSHAPE
+    
+       The shape name specified in the command was invalid
+    
+    3.2.6. Not direction
+    
+       ERROR NOTDIRECTION
+    
+       The direction name specified in the command was invalid
+
+3.3. Global command errors.
+
+    There are no errors from any of the global commands
+
+3.4. Game management errors.
+
+    Errors from game management commands
+    
+    3.3.1. No such game
+       
+       ERROR NOGAME
+       
+       A game name was provided that does not exist.
+       
+    3.3.2. Not empty
+       
+       ERROR NOTEMPTY
+       
+       DISPOSE was requested for a game with active players
+       
+3.5. User information errors
+
+    3.5.1. No such user
+    
+       ERROR NOUSER
+
+       A user name was provided that does not exist.
+
+3.6. In-game errors
+
+    3.6.1. Global game errors
+    
+       3.6.1.1. Not in game
+    
+           ERROR NOTINGAME
+    
+           A game playing command was made, but the user is not a
+           particpant of any game.
+    
+           Possibly returned by: SHOW, MOVE, RESET, UNDO, TURN, PASS,
+           MESSAGE.
+
+       3.6.1.2. Not playing
+
+           ERROR NOTPLAYING
+
+           A command was executed by a watching user that is
+           permitted only to players
+
+       3.6.1.3. Not done
+    
+           ERROR NOTDONE
+    
+           TURN was requested and the game is not in DONE state.
+    
+    3.6.2. Bidding errors 
+    
+       3.6.2.1. Not bidding
+
+           ERROR NOTBIDDING
+    
+           A bid was submitted after the bidding closed
+    
+           Possibly returned by: BID
+    
+       3.6.2.2. Not lower
+
+           ERROR NOTLOWER
+    
+           A bid was submitted that was higher than previous bid.
+    
+           Possibly returned by: BID
+    
+       3.6.2.3. No bid
+
+           ERROR NOBID
+    
+           A revoke was requested when no bid had been entered
+    
+           Possibly returned by: REVOKE
+           
+    3.6.3. Solving mode errors
+    
+       3.6.3.1. Not active
+
+           ERROR NOTACTIVE
+       
+           A move, undo or reset was submitted by other than the
+           active user.
+           
+           Possibly returned by: MOVE, RESET, UNDO
+       
+       3.6.3.2. Blocked
+       
+           ERROR BLOCKED
+       
+           The robot cannot move the requested direction.
+       
+           Possibly returned by: MOVE
+       
+       3.6.3.3. TOOMANYMOVES
+       
+           ERROR TOOMANYMOVES
+       
+           An attempt was made to make more moves than the users bid
+       
+           Possibly returned by: MOVE
+       
+