X-Git-Url: https://git.cworth.org/git?p=ttt;a=blobdiff_plain;f=PROTOCOL;h=91c8545b88ac96f482ca5c27893a3715ce10ba07;hp=a97a176c5f7f87afbc4bedb050261007723d624a;hb=HEAD;hpb=7e5b08180753d07354b2d586b8c78fd4d51c5e0f

diff --git a/PROTOCOL b/PROTOCOL
index a97a176..91c8545 100644
--- a/PROTOCOL
+++ b/PROTOCOL
@@ -1,19 +1,20 @@
-		 Ricochet Robots Game Protocol (RRGP)
-			   Version 0.1.2
-			     2003-5-31
+		     Tic-tac-toe Protocol (TTTP)
+			   Version 0.0.1
+			     2005-11-05
 		
-		  Keith Packard         Carl Worth
-		keithp@keithp.com   carl@theworths.org
+       Carl Worth           Richard Worth           Kevin Worth
+   carl@theworths.org   richard@theworths.org   kevin@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
+TTTP is a network protocol for playing the game tic-tac-toe. 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
+TTTP borrows heavily from RRGP (Ricochet Robot Game Protocol) by Keith
+Packard and indirectly from other network protocols like SMTP using a
 synchronous command interface.
 
 Document Conventions
@@ -30,46 +31,51 @@ Document Conventions
 	<response> is one of:
 
 	<command> <args>
-	ERROR <message>
+	ERROR <error-code>
 
 1. Requests
 
-1.1 Connection setup
+1.1. Connection setup
 
-    The RRGP server has no well defined port; agreement on which port to
+    The TTTP 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 <username>
     
     ->
     
-    HELO <servername> <username> <server-addr> <server-port>
+    HELO <username> <server-addr> <server-port>
 
-    If the client doesn't supply <username>, the server will compute
-    one and return it.
-
-    Possible errors: INVALIDNAME
+    Possible errors: INVALID_NAME
 
 1.2. Global commands
 
-    1.2.1 Listing available users
+    1.2.1. Listing available users
 
 	WHO
 
 	->
 
-	WHO <username1> <games1> <username2> <games2> ...
+	WHO <username1> <username2> ...
+
+	Lists connected users.
 
-	lists connected users and the number of games they've won.
+	Possible errors: NO_NAME_SET
 
-    1.2.2. Listing available games
+    1.2.2. STATISTICS
 
-	GAMES
+	STATISTICS <username>
 
 	->
 
-	GAMES <game1> <game2> ...
+	STATISTICS <username> "
+	TICTACTOE WINS <wins>
+	"
+
+	Lists the statistics for the specified user.
+
+	Possible errors: NO_NAME_SET, NO_USER
 
     1.2.3. Message
 
@@ -79,10 +85,22 @@ Document Conventions
 	
 	MESSAGE
 
+	Sends a message to all connected users. The text must be a
+	single token. Use a quoted-string to include spaces in the
+	message text.
+
+	Possible errors: NO_NAME_SET
+
     1.2.4. Help
 
 	HELP { <command> }
 
+	->
+
+	HELP { <command> } "
+	<overview or detailed help>
+	"
+
 	Displays help.  If <command> is provided, displays more
 	detailed help on a specific command, otherwise displays an
 	overview of all commands.
@@ -95,6 +113,8 @@ Document Conventions
 
 	QUIT
 
+	Disconnects the client from the server.
+
     1.2.6. Version
 
 	VERSION <client-version-number>
@@ -111,283 +131,108 @@ Document Conventions
 
 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.1. Inviting a player to play a game
 
-    1.3.2. Listing watchers of a game
-
-	WATCHERS <game>
+	INVITE <username>
 
 	->
 
-	WATCERS <username1> <username2> ...
+	INVITE
 
-	Possible errors: NOGAME
+	Possible errors: NO_NAME_SET, NO_USER, BUSY
 
-    1.3.3. Get game information
+    1.3.2. Accepting an invitation
 
-	GAMEINFO <game>
+	ACCEPT <username>
 
 	->
 
-	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
+	ACCEPT
 
-    1.3.4. Creating a new game
+	Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
 
-	NEW <game-suggestion>
+    1.3.3. Retracting an invitiation
 
-	->
-
-	NEW <game>
-
-    1.3.5. Joining an existing game
-
-	JOIN <game>
+	RETRACT <username>
 
 	->
 
-	JOIN
+	RETRACT
 
-	Possible errors: NOGAME
+	Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
 
-    1.3.6. Watching an existing game
+    1.3.3. Declining an invitation
 
-	WATCH <game>
+	DECLINE <username>
 
 	->
 
-	WATCH
-
-	The client will monitor the game, but not be listed in the
-	userlist nor be allowed to make moves.
+	DECLINE
 
-	Possible errors: NOGAME
+	Possible errors: NO_NAME_SET, NO_USER, NO_INVITE
 
-    1.3.7. Dispose an empty game
+1.4. In-game commands
 
-	DISPOSE <game>
+    <game> is a game id generated by the server and first returned in
+    NOTICE NEWGAME
 
-	->
-
-	DISPOSE
-
-	Disposes <game> unless it still has players associated.
-
-	Possible errors: NOGAME NOTEMPTY
-
-1.4. User information commands
-
-    1.4.1. Get user information
+    1.4.1. Get the game contents
     
-	USERINFO <username>
+	SHOW <game>
     
 	->
     
-	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> <game-board>
     
-	    ->
+	<game-board> is a quoted multi-line string containing an
+	diagram of the tic-tac-toe board, which is a 3x3 array of
+	cells:
     
-	    SHOW <game-board>
+	c|c|c
+        c|c|c
+        c|c|c
     
-	    <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:
+	c = '_' for empty or 'X' or 'O' for a played space
     
-	     HHH 
-	    VrcsV
-	     HHH
+	For example:
     
-	    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')
+	SHOW <game> "
+	_|X|O 
+        _|X|_
+        X|O|O"
     
-	    The goal robot and target (color and shape) are indicated with
-	    capital letters.
+	Possible errors: NO_NAME_SET, NO_GAME
     
-	    For example:
+    1.4.2. Part
     
-	    SHOW "
-	     ===         
-	    |R.. ... .gs 
-	                 
-	     byc|... .RT|
-	     ===     === "
+	PART <game>
     
-	    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
+	PART
     
-    1.5.2. Bidding commands 
+	Departs the specified game
 
-	1.5.2.1 Bid
+	Possible errors: NO_NAME_SET, NO_GAME
     
-	    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
+    1.4.3. Making a move
 
-	    Possible errors: NOTINGAME, NOTBIDDING
+	MOVE <game> <number>
     
-	    Mark this user as done bidding.  If all users NOBID, then
-	    the game state is switched to SHOW.
+	->
     
-    1.5.3. Solving commands
+	MOVE
 
-	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
-    
-	    ->
+	<number> indicates a number in the tic-tac-toe grid as
+	follows:
+
+	0|1|2
+	3|4|5
+	6|7|8
     
-	    PASS
+	Possible errors: NO_NAME_SET, NO_GAME, NOT_PLAYING,
+	NOT_YOUR_MOVE, NOT_GRID, NOT_VALID_MOVE
     
-	    Possible errors: NOTINGAME
-	
 2. Asynchronous notification.  
 
     The server will send notices to each user in a game whenever
@@ -413,152 +258,65 @@ Document Conventions
     
 	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.1.3. Game invitation
 
-	2.2.1.1. Board layout change
+	2.1.3.1. Invitation is made
 
-	    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>
+		NOTICE INVITE <username1> <username2>
 
-	    Game state has changed to <state>.  <state> is one
-	    of "NEW", "BID", "SHOW" or "DONE".
+	2.1.3.2. Invitation is accepted
 
-	2.2.1.3. Next turn (game)
+		NOTICE ACCEPT <username2> <username1>
 
-	    NOTICE TURN <color> <shape>
+	2.1.3.3. Invitation is retracted
 
-	    Note that the game state is implicitly changed to New
+		NOTICE RETRACT <username1> <username2>
 
-	2.2.1.4. Next game (game)
+	2.1.3.4. Invitation is declined
 
-	    NOTICE GAMEOVER
+		NOTICE DECLINE <username2> <username1>
 
-	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>
+	The first username listed is the one performing the action.
 
-    2.2.2. Bid notices
+    2.1.4. New games
 
-	Notices sent duing the bidding phase of a turn
+	NOTICE NEWGAME <game> <username> <username>
     
-	2.2.2.1. Bids (game)
-	
-	    NOTICE BID <username> <number>
-	
-	2.2.2.2. Revoke (game)
-	
-	    NOTICE REVOKE <username>
+	The first username listed will go first.
 
-	    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>
+    2.1.5. Terminated games
     
-	    Timer ticks are sent every 10 seconds after the first
-	    bid has been made
-
-	2.2.2.4. Abandon request
-
-	    NOTICE ABANDON <username>
+	NOTICE DISPOSE <game>
     
-	    <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.1.6. Message
 
-	2.2.3.4. Reset (game)
-
-	    NOTICE RESET
-
-	2.2.3.5. Position (after move/undo/reset)
+	NOTICE MESSAGE <username> <text>
 
-	    NOTICE POSITION <color> <x> <y>
+	where <text> is a quoted-string. Quotes escaped with '\"'
 
-	    The indicated robot has moved to the indicated position.
-	    The board is 0-based with the origin in the upper left
-	    corner.
+2.2. Game notices
 
-	2.2.3.6. Score (game)
+    These notices are sent to all players and watchers in
+    the affected game.
 
-	    NOTICE SCORE <username> <score>
+    <game> is a game id generated by the server and first returned in
+    NOTICE NEWGAME
 
-	    The indicated user has demonstrated a solution and
-	    received a point.
+    2.2.1. Global game notices
 
-2.3. User notices
+	2.2.1.1. Game over, and winner
 
-     These notices are sent to a single user
+	    NOTICE GAMEOVER <game> <outcome> <username>
 
-     2.3.1. Solving notices
+	    <outcome> is either WON in which case <username> indicates
+	    the winner or CATSGAME in which case <username> is "".
 
-	Notices sent during the solving phase of a turn
-	    	
-	2.3.1.1. Notify active player (user)
+    2.2.2. Move notices
 
-	    NOTICE ACTIVATE <bid>
+	2.2.2.1. Move
+	
+	    NOTICE MOVE <game> <username> <number>
 
-	    Sent to the player which has just become active
-	    
 3. Errors
 
     The following error codes may be returned.
@@ -569,15 +327,20 @@ Document Conventions
 
     3.1.1. No name set
     
-	ERROR NONAMESET
+	ERROR NO_NAME_SET
     
-	'helo' must be sent before any command other than 'quit'.
+	'helo' must be sent before any command other than 'help',
+	'version', 'quit'.
+
+	Possibly returned by: WHO, STATISTICS, MESSAGE, INVITE,
+	ACCEPT, RETRACT, DECLINE, SHOW, PART, MOVE
     
     3.1.2. Invalid name
     
-	ERROR INVALIDNAME
+	ERROR INVALID_NAME
     
-	All names must be unique.
+	All names must be of non-zero length and must be unique,
+	though case-insensitive.
 
 	Possibly returned by: HELO
 
@@ -589,144 +352,95 @@ Document Conventions
     
 	ERROR COMMAND
     
-	An invalid command was specified
-    
+	An invalid command was specified.
+
     3.2.2. Syntax
     
 	ERROR SYNTAX
     
-	A syntax error was detected
+	A syntax error was detected.
     
     3.2.3. Not number
     
-	ERROR NOTNUMBER
+	ERROR NOT_NUMBER
     
-	A non-numeric value was supplied where a number was required
+	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
+	Possibly returned by: MOVE
+
+    3.2.4. Not a grid number
     
-	ERROR NOTDIRECTION
+	ERROR NOT_GRID
     
-	The direction name specified in the command was invalid
+	The number specified in the command was not a valid grid
+	number.
+
+	Possibly returned by: MOVE
 
 3.3. Global command errors.
 
-    There are no errors from any of the global commands
+    There are no global command 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
+    3.4.1. No invitiation from/for specified user
+
+	ERROR NO_INVITE
+
+	An invitiation action was attempted where no invitation
+	exists.
+
+	Possibly returned by: ACCEPT, RETRACT, DECLINE
+
+    3.4.2. No such game
 	
-	ERROR NOTEMPTY
+	ERROR NO_GAME
 	
-	DISPOSE was requested for a game with active players
+	A game id was provided that does not exist.
+
+	Possibly returned by: SHOW, PART, MOVE
 	
 3.5. User information errors
 
     3.5.1. No such user
     
-	ERROR NOUSER
+	ERROR NO_USER
 
 	A user name was provided that does not exist.
 
+	Possibly returned by: STATISTICS, INVITE, ACCEPT, RETRACT,
+	DECLINE
+
 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
+	3.6.1.1. Not playing
 
-	    ERROR NOTPLAYING
+	    ERROR NOT_PLAYING
 
 	    A command was executed by a watching user that is
-	    permitted only to players
+	    permitted only to players.
 
-	3.6.1.3. Not done
-    
-	    ERROR NOTDONE
-    
-	    TURN was requested and the game is not in DONE state.
+	    Possibly returned by: MOVE
     
-    3.6.2. Bidding errors 
+    3.6.2. Moving errors 
     
-	3.6.2.1. Not bidding
+	3.6.2.1. Not your turn
 
-	    ERROR NOTBIDDING
+	    ERROR NOT_YOUR_TURN
     
-	    A bid was submitted after the bidding closed
-    
-	    Possibly returned by: BID
-    
-	3.6.2.2. Not lower
+	    A move was submitted during the other player's turn.
 
-	    ERROR NOTLOWER
-    
-	    A bid was submitted that was higher than previous bid.
-    
-	    Possibly returned by: BID
-    
-	3.6.2.3. No bid
+	    Possibly returned by: MOVE
 
-	    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
+    	3.6.2.2. Not a valid move
 
-	    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
-	
+	    ERROR NOT_VALID_MOVE
 
+	    A move was submitted for a cell that is occupied.
+
+	    Possibly returned by: MOVE