2005-11-15 Carl Worth <cworth@cworth.org>

[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 <message>

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

        MESSAGE <text>

        ->
        
        MESSAGE

    1.2.3. 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.4. Quit

        QUIT

        ->

        QUIT

    1.2.5. 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: NOUSER, BUSY

    1.3.2. Accepting an invitation

        ACCEPT <username>

        ->

        ACCEPT

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: NOTINGAME
    
    1.4.2. Part
    
        PART
    
        ->
    
        PART
    
        Departs the current game

        Possible errors: NOTINGAME
    
    1.4.3. Making a move

        MOVE <number>
    
        ->
    
        MOVE

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

        1|2|3
        4|5|6
        7|8|9
    
        Possible errors: NOTINGAME, NOTYOURMOVE, NOTGRID
    
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>

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>

            <outcame> 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 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 a grid number
    
        ERROR NOTGRID
    
        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 NOGAME
        
        A game name was provided that does not exist.
        
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: MOVE

        3.6.1.2. Not playing

            ERROR NOTPLAYING

            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 NOTYOURTURN
    
            A move was submitted during the other player's turn

            Possibly returned by: MOVE