[ttt] / PROTOCOL

                     Tic-tac-toe Protocol (TTTP)
                           Version 0.0.1
                             2005-11-05
                
       Carl Worth           Richard Worth           Kevin Worth
   carl@theworths.org   richard@theworths.org   kevin@theworths.org

Introduction

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.

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

        All commands include a response (yeah, synchronous protocols are
        bad.  tough)

        <command> <args> 

        ->

        <response>

        <response> is one of:

        <command> <args>
        ERROR <error-code>

1. Requests

1.1. Connection setup

    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> <server-addr> <server-port>

    Possible errors: INVALID_NAME

1.2. Global commands

    1.2.1. Listing available users

        WHO

        ->

        WHO <username1> <username2> ...

        Lists connected users.

        Possible errors: NO_NAME_SET

    1.2.2. STATISTICS

        STATISTICS <username>

        ->

        STATISTICS <username> "
        TICTACTOE WINS <wins>
        "

        Lists the statistics for the specified user.

        Possible errors: NO_NAME_SET, NO_USER

    1.2.3. Message

        MESSAGE <text>

        ->
        
        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.

    1.2.5. Quit

        QUIT

        ->

        QUIT

        Disconnects the client from the server.

    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. Inviting a player to play a game

        INVITE <username>

        ->

        INVITE

        Possible errors: NO_USER, BUSY, NO_NAME_SET

    1.3.2. Accepting an invitation

        ACCEPT <username>

        ->

        ACCEPT

        Possible errors: NO_NAME_SET

1.4. In-game commands

    1.4.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:
    
        c|c|c
        c|c|c
        c|c|c
    
        c = '_' for empty or 'X' or 'O' for a played space
    
        For example:
    
        SHOW "
        _|X|O 
        _|X|_
        X|O|O"
    
        Possible errors: NOT_IN_GAME, NO_NAME_SET
    
    1.4.2. Part
    
        PART
    
        ->
    
        PART
    
        Departs the current game

        Possible errors: NOT_IN_GAME, NO_NAME_SET
    
    1.4.3. Making a move

        MOVE <number>
    
        ->
    
        MOVE

        <number> indicates a number in the tic-tac-toe grid as
        follows:

        0|1|2
        3|4|5
        6|7|8
    
        Possible errors: NOT_IN_GAME, NOT_YOUR_MOVE, NOT_GRID, NO_NAME_SET
    
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. Game invitation
    
        NOTICE INVITE <username>
    
    2.1.4. Terminated games
    
        NOTICE DISPOSE <game>
    
    2.1.5. Message

        NOTICE MESSAGE <username> <text>

        where <text> is a quoted-string. Quotes escaped with '\"'

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. New game begins

            NOTICE NEWGAME <username> <username>

            The first username listed will go first

        2.2.1.2. Game over, and winner

            NOTICE GAMEOVER <outcome> <username>

            <outcome> is either WON in which case <username> indicates
            the winner or CATSGAME in which case <username> is "".

    2.2.2. Move notices

        2.2.2.1. Move
        
            NOTICE MOVE <username> <number>

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 NO_NAME_SET
    
        'helo' must be sent before any command other than 'help',
        'version', 'quit'.

        Possibly returned by: WHO MESSAGE INVITE ACCEPT SHOW PART MOVE
    
    3.1.2. Invalid name
    
        ERROR INVALID_NAME
    
        All names must be of non-zero length and 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 NOT_NUMBER
    
        A non-numeric value was supplied where a number was required
        
    3.2.4. Not a grid number
    
        ERROR NOT_GRID
    
        The number specified in the command was not a valid grid number
    
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.4.1. No such game
        
        ERROR NO_GAME
        
        A game name was provided that does not exist.
        
3.5. User information errors

    3.5.1. No such user
    
        ERROR NO_USER

        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 NOT_IN_GAME
    
            A game playing command was made, but the user is not a
            particpant of any game.
    
            Possibly returned by: MOVE

        3.6.1.2. Not playing

            ERROR NOT_PLAYING

            A command was executed by a watching user that is
            permitted only to players
    
    3.6.2. Moving errors 
    
        3.6.2.1. Not your turn

            ERROR NOT_YOUR_TURN
    
            A move was submitted during the other player's turn

            Possibly returned by: MOVE