--- /dev/null
+ 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
+
+
projects / ttt / commitdiff