- 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
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>
-
- If the client doesn't supply <username>, the server will compute
- one and return it.
+ HELO <username> <server-addr> <server-port>
Possible errors: INVALIDNAME
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>
MESSAGE
- 1.2.4. Help
+ 1.2.3. Help
HELP { <command> }
detailed help on a specific command, otherwise displays an
overview of all commands.
- 1.2.5. Quit
+ 1.2.4. Quit
QUIT
QUIT
- 1.2.6. Version
+ Disconnects the client from the server.
+
+ 1.2.5. Version
VERSION <client-version-number>
1.3. Game management commands
- 1.3.1. Listing players in a game
+ 1.3.1. Inviting a player to play a game
- PLAYERS <game>
+ INVITE <username>
->
- PLAYERS <username1> <score1> <username2> <score2> ...
+ INVITE
- Possible errors: NOGAME
+ Possible errors: NOUSER, BUSY
- 1.3.2. Listing watchers of a game
+ 1.3.2. Accepting an invitation
- WATCHERS <game>
+ ACCEPT <username>
->
- WATCERS <username1> <username2> ...
-
- Possible errors: NOGAME
-
- 1.3.3. Get game information
-
- GAMEINFO <game>
-
- ->
+ ACCEPT
- 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>
-
- ->
+1.4. In-game commands
- 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
+ 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 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
+ SHOW <game-board>
- 1.5.1.2. Next turn
+ <game-board> is a quoted multi-line string containing an
+ diagram of the tic-tac-toe board, which is a 3x3 array of
+ cells:
- TURN
+ c|c|c
+ c|c|c
+ c|c|c
- ->
+ c = '_' for empty or 'X' or 'O' for a played space
- TURN
+ For example:
- 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
+ SHOW "
+ _|X|O
+ _|X|_
+ X|O|O"
- 1.5.1.3. Part
+ Possible errors: NOTINGAME
- PART
+ 1.4.2. 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
+ Possible errors: NOTINGAME
- 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
+ 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
NOTICE QUIT <username>
- 2.1.3. New games
+ 2.1.3. Game invitation
- NOTICE GAME <game>
+ NOTICE INVITE <username>
2.1.4. Terminated games
2.2.1. Global game notices
- 2.2.1.1. Board layout change
+ 2.2.1.1. New game begins
- NOTICE BOARD <game-board>
+ NOTICE NEWGAME <username> <username>
- 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>
+ The first username listed will go first
- Game state has changed to <state>. <state> is one
- of "NEW", "BID", "SHOW" or "DONE".
+ 2.2.1.2. Game over, and winner
- 2.2.1.3. Next turn (game)
+ NOTICE GAMEOVER <outcome> <username>
- NOTICE TURN <color> <shape>
+ <outcame> is either WON in which case <username> indicates
+ the winner or CATSGAME in which case <username> is "".
- Note that the game state is implicitly changed to New
+ 2.2.2. Move notices
- 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.1. Move
- 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 MOVE <username> <number>
- 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.
ERROR INVALIDNAME
- All names must be unique.
+ All names must be of non-zero length and must be unique.
Possibly returned by: HELO
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
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
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
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
-
-
projects / ttt / blobdiff