PROTOCOL

This document describes the network protocol for the "Glass Plate Game".

WARNING: This protocol is currently *unstable* and prone to radical change.

DOUBLE WARNING: This protocol has not been peer-reviewed and is probably sucky.

0. Definitions

This section contains metadata of various constants defined for the GLS
protocol.

0.1 Colors

Colors are defined by a 32-bit unsigned integer.  The value '0' is special and
means "no color".  The other colors are specified as follows:

  1: red
  2: orange
  3: yellow
  4: green
  5: blue
  6: purple

The names GLS_COLOR_MIN and GLS_COLOR_MAX refer to "red" and "purple",
respectively.  The name GLS_COLOR_NULL refers to the "no color" value (0).
Colors greater than GLS_COLOR_MAX are considered invalid.

0.2 Die Numbers

Die numbers are defined by a 32-bit unsigned integer.  They must be less than
the value 25, which has name GLS_DIE_MAX.

1. Packets

All GLS packets are prefixed by an unsigned 32-bit integer which denotes the
"event type" for the data proceeding it.  The amount of data suffixing the
header is a fixed amount that depends on the event type.  The event type is
in network byte order (big endian), as are all integers.

1.1 Protocol Version Exchange ("Protover")

The Protocol Version Exchange is sent by the client to the server in order to
identify what version of the Glass Plate Game Protocol it supports.  There are
three fields to the Protocol Version Exchange:

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  | Magic |           Version             |       Software        >
  >                                       |-+-+-+-+-+-+-+-+-+-+-+-+
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  Magic:  4 bytes

    C-string containing "GLS" and a NUL byte.

  Version:  16 bytes

    C-string containing the protocol version used by the client.

  Software:  32 bytes

    C-string containing the name of the software used by the client.

The Magic field identifies the byte stream as belonging to the GLS protocol,
the Version field identifies which protocol version the client uses, and the
Software field exists for informational purposes only.

1.2 Protocol Version Exchange Acknowledgement ("Protoverack")

The Protocol Version Exchange Acknowledgement is sent from the server to the
client after receiving and processing the client's Protocol Version Exchange
(see previous subsection).  There are five fields:

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |ACK|                        Reason                             >
  >                                                               >
  >   | Magic |           Version             |       Software    >
  >                                           |-+-+-+-+-+-+-+-+-+-+
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  ACK:  2 bytes

    A 16-bit byte (in network byte order) representing whether or not the
    server accepts the client's protocol version.  A nonzero value indicates
    acceptance, a zero value indicates rejection.

  Reason:  64 bytes

    If the ACK field is false, the Reason field MUST contain a C-string
    describing the reason for rejection.

  The following fields are the same as the Protocol Version Exchange (see
  previous subsection), except their data corresponds to the server.

The ACK and Reason field allow the client to determine whether its protocol
has been accepted by the server, and why it may have been rejected; the
subsequent fields show exactly which protocol version the server desires.

1.3 Nick Request

The Nick Request packet allow the client to request a new nickname from the
server.

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                            Nick                               |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  Nick:  32 bytes

    A C-string containing the name requested by the client.  The string
    MUST consist of a series of alphanumeric characters of nonzero length.

1.4 Nick Set

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                            Nick                               |
  |                           Reason                              >
  >                                                               |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  Nick:  32 bytes

    A C-string containing the name requested by the client.  The string MUST
    consist of a series of alphanumeric characters, possibly of zero length.

  Reason:  64 bytes
  
    A C-string containing the reason why a nickname was rejected by the server.
    If Nick is of length zero this field MUST contain the reason why a nickname
    was rejected by the server; otherwise this field MUST be an empty string.

Note that there is currently no way for the server to specify which nickname
it is rejecting, but it should be obvious enough from the context.  The server
can also choose to force-set a nickname in this manner.

1.5 Nick Change

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                          Old Nick                             |
  |                          New Nick                             |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


  Old Nick:  32 bytes

    A C-string containing the old nickname of the player whose nickname has
    changed.

  New Nick:  32 bytes

    A C-string containing the new nickname of the player whose nickname has
    changed.

This packet informs players when another player's nickname has changed.

1.6 Player Join

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                             Nick                              |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


  Nick:  32 bytes

    A C-string containing the nickname of the player who has joined the game.

This packet informs players when another player has joined the game.

1.7 Player Part

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                             Nick                              |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


  Nick:  32 bytes

    A C-string containing the nickname of the player who has parted the game.

This packet informs players when another player has parted (left) the game.

1.8 Shutdown

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                            Reason                             >
  >                                                               |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  Reason:  64 bytes

    A C-string containing the reason for the server shutdown.

This packets informs player when the server shuts down, and the reason field
specifies why the server shutdown.

1.9 Say1

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                                                               >
  >                                                               >
  >                                                               >
  >                           Message                             >
  >                                                               >
  >                                                               >
  >                                                               >
  >                                                               |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  Message:  256 bytes

    A C-string containing the message that the player wishes to send. The
    string MUST consist of only printable ASCII characters.

This packet is sent from the player to the server when the player wishes to
send a message to the players.

1.10 Say2

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                             Nick                              |
  |       Time      |                                             >
  >                                                               >
  >                                                               >
  >                            Message                            >
  >                                                               >
  >                                                               >
  >                                                               >
  >                                                               >
  >                 |-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  +-+-+-+-+-+-+-+-+-+

  Nick:  32 bytes

    A C-string containing the name of the user which sent the message.

  Time:  8 bytes

    A unisgned 64-bit integer representing the time that the message was sent
    as seconds since the UNIX Epoch.

  Message:  256 bytes

    A C-string containing the message that the user sent.  The string MUST
    consist of only printable ASCII characters.

This packet is sent from the server to each player in order to inform each
player of another's player's message.

1.11 Sync End

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  >                                                               >
  >                                                               >
  >                                                               >
  >                            MotD                               >
  >                                                               >
  >                                                               >
  >                                                               >
  >                                                               >
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  MotD:  256 bytes

    A C-string containing the server's Message of the Day.  The string MUST
    consist of only printable ASCII characters.

This packet is sent from the server to the player when the player has entered
the AUTHENTICATED state.

1.12 Plate Place

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  > Abbrev| Description                                           >
  >                                                               >
  >                                                               >
  >                                                               >
  >                                                               >
  >                                                               >
  >                                                               >
  >                                                               >
  >       | Name                                                  >
  >                                                               >
  >       | Loc | Flags |-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  +-+-+-+-+-+-+-+-+-+-+-+

  Abbrev:  4 bytes

    A C-string containing a three-letter abbreviation name for the plate.  The
    string MUST consist of only printable ASCII characters.

  Description:  256 bytes

    A C-string containing a description of the plate's concept.  May be empty,
    but if non-empty MUST consist of only printable ASCII characters.

  Name:  64 bytes

    A C-string containing the name of the plate.  The string MUST consist of
    only printable ASCII characters.

  Loc:  3 bytes

    A C-string containing the location of the plate on the game board.  The
    string MUST be within the range of "A1"-"H8".

  Flags:  4 bytes

    A 32-bit unsigned integer containing various flags for the plate.  Unused
    flags MUST NOT be set.  Flags are in network byte order.  Currently used
    flags:

      0x00000001  GLS_PLATE_FLAG_EMPTY
        No plate exists at the specified location.

This packet is sent from the server to the client when the client is
synchronizing game state with the server; the packet denotes a plate that has
been placed on the board at the specified location.

1.13 Die Place Try

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  | Loc | Color |-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  +-+-+-+-+-+-+-+

  Loc:  3 bytes

    A C-string containing the location of the plate on the game board.  The
    string MUST be within the range of "A1"-"H8".

  Color:  4 bytes

    A 32-bit unsigned integer representing the color to be used for the die.
    This number MUST be either GLS_COLOR_NULL or less than GLS_COLOR_MAX.

This packet is sent from the client to the server when the client wishes to
place a die (without a connection) on the specified plate.

1.14 Die Place Reject

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  | Loc | Color |                                                 >
  >                           Reason                              >
  >             |-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  +-+-+-+-+-+-+-+

  Loc:  3 bytes

    A C-string containing the location of the plate on the game board.  The
    string MUST be within the range of "A1"-"H8".

  Color:  4 bytes

    A 32-bit unsigned integer representing the color to be used for the die.
    This number MUST be either GLS_COLOR_NULL or less than GLS_COLOR_MAX.

  Reason:  64 bytes

    A C-string specifying the reason why the die could not be placed on the
    board.

This packet is sent from the server to the client when a die placement requested
by the client was rejected by the server.

1.15 Die Place

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  | Loc | Color |              Nick                               >
  >             |  Die  |-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  +-+-+-+-+-+-+-+-+-+-+-+

  Loc:  3 bytes

    A C-string containing the location of the plate on the game board.  The
    string MUST be within the range of "A1"-"H8".

  Color:  4 bytes

    A 32-bit unsigned integer representing the color to be used for the die.
    This number MUST be either GLS_COLOR_NULL or less than GLS_COLOR_MAX.

  Nick:  32 bytes

    A C-string containing the name of the user which placed the die.

  Die:  4 bytes

    A 32-bit unsigned integer representing which die number was placed on the
    board.  This number MUST be less than GLS_DIE_MAX.

This packet is sent from the server to the client when a die has been placed on
the board.

2. Client States

Clients have various states as they connect to and exchange data across the
socket.

  DISCONNECTED

    The client is not currently connected to the game.

  CONNECTED
  
    The client is connected via TCP and needs to exchange protovers.

  PROTOVEROKAY

    The client has an acceptable protover and must now choose a nickname.

  SYNCHRONIZING

    The client has successfully chosen a nickname and must now receive game
    state information from the server.

  AUTHENTICATED

    Client has authenticated to the server (by selecting a nickname).

These states are important for the following sections, which describe what
packets may be transmitted based on the client's state.

3. Server

3.1 DISCONNECTED

Clients are initially in the DISCONNECTED state.  Upon accepting a connection
the client is moved to the CONNECTED state.

If the server has no more room for players, it MAY choose to drop the connection
and reset the client to the DISCONNECTED state without any other response. If a
client is moved to the DISCONNECTED state then its TCP connection is closed.

3.2 CONNECTED

In the CONNECTED state, the client MUST send a protover packet.  The server
then confirms that the Version field of the client matches its own Version
field; if they do not match then the server MUST respond with a protoverack
packet with the ACK field unset and Reason field set to a human-readable reason
for the rejection and return the client to the DISCONNECTED state; otherwise, if
the Version field matches, the server MUST respond with with a protoverack with
the ACK field set and move the client to the AUTHENTICATED state.  In addition,
in both cases the server sets the protover subfields of the protoverack to the
appropriate Magic number, the server's supported Version, and the name of the
server's software.

3.3 PROTOVEROKAY

The server has authenticated the client's protover and is now waiting on the
client to request a nickname.  The client MUST send the server a Nick Req
packet, otherwise the server MUST return the client to the DISCONNECTED state.
If the server chooses to reject a nickname, it MUST inform the client with a
Nick Set packet with the Reason field set appropriately, then wait for another
Nick Req packet from the client.  A server MUST reject the client's nickname if
it is already in use and MAY reject a nickname at its own discretion.  If the
server accepts the client's nickname, the client is moved to the SYNCHRONIZING
state and the server MUST send the client a Nick Set packet with the client's
requested nickname.

3.4 SYNCHRONIZING

The server has authenticated the client and must now send the game state to
the client.  In order to send the game state to the client, the server MUST
send a Plate Place packet for each plate that is on the game board.

When the game state has been sent to the client, the server MUST send a Sync
End packet to the client, at which point the client is moved to the
AUTHENTICATED state.

3.5 AUTHENTICATED

In the AUTHENTICATED state the server responds to various client packets
corresponding to the actual playing of the game.  If the server receives an
unexpected event type, the client MUST be immediately disconnected and moved
to the DISCONNECTED state.  If the server receives a remote hang-up, it MUST
disconnect the client and move it to the DISCONNECTED state.  If the server
receives a malformed packet it MUST disconnect the client and move it to the
DISCONNECTED state.

3.5.1 Nick Request

Client requests a nickname change to the specified nickname.  The server MUST
reply with a Nick Set packet indicating either that the client now has the
specified nickname or a reason why the client will retain their current
nickname. If the client's nickname is changed, the server MUST also send a Nick
Change packet to every other client in the AUTHENTICATED state.

3.5.2 Say1

Client sends server a message that the client wishes to send to all of the
other players.  The server MAY choose to modify the message for propriety
before sending, but ought to avoid evil modifications.  The server MUST then
send the message as a Say2 packet to all clients in the AUTHENTICATED state,
including the one that sent the original message (the message is echo'd back
to the client).

3.5.3 Die Place Try

Client attempts to place a die on the specified plate and optionally with a
specified color.  The server MUST reply to the client with either a Die Place
Reject packet if the server rejects the placement or send a Die Place packet
to all clients in the AUTHENTICATED state if the server accepts the placement.

The server MUST reject the placement if there are no dies or colors left, or if
the specified plate is empty.  If the specified color is GLS_COLOR_NULL then the
server MUST select a valid color (if possible) before sending a Die Place
packet.

4. Client

4.1 DISCONNECTED

A Client starts out in the DISCONNECTED state.  A client MAY choose to move to
the CONNECTED state by establishing a TCP connection with a remote server and
having that connection accepted.

4.2 CONNECTED

In the CONNECTED state the client MUST send the server a protover packet
containing the appropriate Magic, Version, and Software fields.  The server
MAY disconnect the client without a response, probably because it has no more
player slots available, in which case the client returns to the DISCONNECTED
state.  The client MUST then listen for a protoverack packet from the server;
when the packet is received, if the ACK field is unset, the client MUST print
the reason to the client, disconnect from the server, and return the the
DISCONNECTED state.  If the ACK field is set, then the client moves to the
AUTHENTICATED state.

4.3 PROTOVEROKAY

The client MUST send the server a Nick Req packet with the client's desired
nickname.  The server MAY reject the nickname, in which case the client MUST
choose another nickname or return to the DISCONNECTED state.  If the server
accepts the nickname then the client is moved to the SYNCHRONIZING state.

4.4 SYNCHRONIZING

In the SYNCHRONIZING state the client must prepare to receive the game state
from the server.  The following packets MUST be accepted by the client, any
others are an error and the client MUST disconnect from the server and return
to the DISCONNECTED state.

4.4.1 Plate Place
The specified plate is placed at the specified location on the game board.

4.4.2 Die Place
The specified die is placed at the specified location on the game board.

4.4.3 Sync End
The game state has been synchronized and the client MUST move to the
AUTHENTICATED state and MUST display the packet's MotD.

4.5 AUTHENTICATED

In this state the client must be ready to respond to events from the server
and be prepared to forward any input from the user to the server.

4.5.1 Nick Request
The user may choose to request a new nickname, in which case the client MUST
send a Nick Request packet to the server with the requested nickname.

4.5.2 Nick Set
The server may choose to send a Nick Set packet to the client.  If the packet
contains a non-empty nickname, the client MUST inform the user that their
nickname has been set to the specified nickname; otherwise, if the packet
contains an empty nickname, the client MUST inform the user that a previous
Nick Request was rejected for the reason listed in the Reason field of the
packet.

4.5.3 Nick Change
The server will send the client a Nick Change packet when another client's
nickname has changed.  The client MUST inform the user of the change.

4.5.4 Player Join
The server will send the client a Player Join packet when another client has
joined the game.  The client MUST inform the user of the new client.

4.5.5 Player Part
The server will send the client a Player Part packet when another client has
left the game.  The client MUST inform the user of the departed client.

4.5.6 Shutdown
The server sends the shutdown packet when it shuts down.  The client MUST
display the reason (if available) for the shutdown to the user and the client
MUST move itself back to the DISCONNECTED state.

4.5.7 Say2
The server sends a Say2 packet when another player has sent a message.  The
client MUST display the sender's nick and message to the user and MAY display
the time of the message.

4.5.8 Die Place Reject
The server sends a Die Place Reject packet when the server has rejected a die
placement requested by the client.  The client MUST display both the location
and reason to the client.

4.5.9 Die Place
The server sends a Die Place packet when a die is placed on the game board. The
client MUST inform the user of placement and MUST update its internal
representation of the game board appropriately.