[ttt] / PROTOCOL

                 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