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

diff --git a/PROTOCOL b/PROTOCOL
index a97a176..fe8905b 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
@@ -36,7 +37,7 @@ Document Conventions
 
 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:
     
@@ -44,7 +45,7 @@ Document Conventions
     
     ->
     
-    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.
@@ -63,15 +64,7 @@ Document Conventions
 
 	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
+    1.2.2. Message
 
 	MESSAGE <text>
 
@@ -79,7 +72,7 @@ Document Conventions
 	
 	MESSAGE
 
-    1.2.4. Help
+    1.2.3. Help
 
 	HELP { <command> }
 
@@ -87,7 +80,7 @@ Document Conventions
 	detailed help on a specific command, otherwise displays an
 	overview of all commands.
 
-    1.2.5. Quit
+    1.2.4. Quit
 
 	QUIT
 
@@ -95,7 +88,7 @@ Document Conventions
 
 	QUIT
 
-    1.2.6. Version
+    1.2.5. Version
 
 	VERSION <client-version-number>
 
@@ -111,283 +104,82 @@ Document Conventions
 
 1.3. Game management commands
 
-    1.3.1. Listing players in a game
-
-	PLAYERS <game>
+    1.3.1. Inviting a player to play a game
 
-	->
-
-	PLAYERS <username1> <score1> <username2> <score2> ...
-
-	Possible errors: NOGAME
-
-    1.3.2. Listing watchers of a game
-
-	WATCHERS <game>
+	INVITE <username>
 
 	->
 
-	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>
-
-	->
+	INVITE
 
-	NEW <game>
+	Possible errors: NOUSER, BUSY
 
-    1.3.5. Joining an existing game
+    1.3.2. Accepting an invitation
 
-	JOIN <game>
+	ACCEPT <username>
 
 	->
 
-	JOIN
+	ACCEPT
 
-	Possible errors: NOGAME
+1.4. In-game commands
 
-    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
+    1.4.1. Get the game contents
     
-	USERINFO <username>
+	SHOW
     
 	->
     
-	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 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 "
+	_|X|O 
+        _|X|_
+        X|O|O"
     
-	    The goal robot and target (color and shape) are indicated with
-	    capital letters.
+	Possible errors: NOTINGAME
     
-	    For example:
+    1.4.2. Part
     
-	    SHOW "
-	     ===         
-	    |R.. ... .gs 
-	                 
-	     byc|... .RT|
-	     ===     === "
+	PART
     
-	    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 current game
 
-	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
+	Possible errors: NOTINGAME
     
-	    ->
-    
-	    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
-
-	    ->
+    1.4.3. Making a move
 
-	    NOBID
-
-	    Possible errors: NOTINGAME, NOTBIDDING
+	MOVE <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:
+
+	1|2|3
+	4|5|6
+	7|8|9
     
-	    PASS
+	Possible errors: NOTINGAME, NOTYOURMOVE, NOTGRID
     
-	    Possible errors: NOTINGAME
-	
 2. Asynchronous notification.  
 
     The server will send notices to each user in a game whenever
@@ -413,9 +205,9 @@ Document Conventions
     
 	NOTICE QUIT <username>
     
-    2.1.3. New games
+    2.1.3. Game invitation
     
-	NOTICE GAME <game>
+	NOTICE INVITE <username>
     
     2.1.4. Terminated games
     
@@ -432,133 +224,25 @@ Document Conventions
 
     2.2.1. Global game notices
 
-	2.2.1.1. Board layout change
+	2.2.1.1. New game begins
 
-	    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 NEWGAME <username> <username>
 
-	    Game state has changed to <state>.  <state> is one
-	    of "NEW", "BID", "SHOW" or "DONE".
+	    The first username listed will go first
 
-	2.2.1.3. Next turn (game)
+	2.2.1.2. Game over, and winner
 
-	    NOTICE TURN <color> <shape>
+	    NOTICE GAMEOVER <outcome> <username>
 
-	    Note that the game state is implicitly changed to New
+	    <outcame> is either WON in which case <username> indicates
+	    the winner or CATSGAME in which case <username> is "".
 
-	2.2.1.4. Next game (game)
+    2.2.2. Move notices
 
-	    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)
+	2.2.2.1. Move
 	
-	    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>
+	    NOTICE MOVE <username> <number>
 
-	    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.
@@ -603,24 +287,12 @@ Document Conventions
     
 	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.4. Not a grid number
     
-    3.2.5. Not shape
+	ERROR NOTGRID
     
-	ERROR NOTSHAPE
+	The number specified in the command was not a valid grid number
     
-	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
@@ -629,18 +301,12 @@ Document Conventions
 
     Errors from game management commands
     
-    3.3.1. No such game
+    3.4.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
@@ -660,8 +326,7 @@ Document Conventions
 	    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.
+	    Possibly returned by: MOVE
 
 	3.6.1.2. Not playing
 
@@ -669,64 +334,13 @@ Document Conventions
 
 	    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. Moving errors 
     
-	3.6.2.1. Not bidding
+	3.6.2.1. Not your turn
 
-	    ERROR NOTBIDDING
+	    ERROR NOTYOURTURN
     
-	    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
+	    A move was submitted during the other player's turn
 
-	    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
-	
-