-----------------------

ATOM-4 Network Protocol
Version: 2.0

-----------------------


I. Protocol Definitions

The ATOM-4 network protocol is a line-based, ASCII text protocol. It is
assumed to be transmitted over a reliable, connection-based transport protocol
(such as TCP). This protocol governs the communications between the "server",
an implementation of the protocol that hosts the ATOM-4 game server, and a
"client", representing a prospective player of the game, possibly providing a
user interface to a human player. 

A "line" is defined to be any sequence of bytes which are not
line-terminators, followed by one or more delimiting characters. A
line-terminator is any character from ASCII 0x00 to ASCII 0x1F.

Under this protocol, a "message" is equivalent to a "line".


I.A. Line Length Limit

This protocol recommends a line length limit of 1024 characters (not counting
any line-terminators), although it does not preclude implementations which
support arbitrary-length lines. Longer lines may be subject to Truncation; 
hence implementations supporting long lines must have provision for dealing
with servers or clients that enforce the 1024 character limit. 

Implementations may perform Truncation at a higher line-length limit than 1024
characters. However, implementations MUST NOT perform truncation at less than
1024 characters.


I.B. Truncation

Truncation is the state the recipient of a transmission enters, when it
encounters a line longer than 1024 characters. In the Truncation state, the
recipient should treat the first 1024 characters of the line as though it were
terminated immediately after the 1024th character. Subsequent characters
received from the communications line will be completely ignored until the
first line-terminator is found, at which point, the recipient must exit
Truncation mode and resume normal protocol communications.


I.C. General Packet Structure

Under this protocol, packets (lines) are a sequence of "words", delimited by
one or more space characters (ASCII 32). Implementations are required to
treat multiple consecutive spaces as a single space. The first and last words
in a packet may be surrounded with extra spaces as well. Implementations are
required to handle this correctly.

A "word" is any consecutive sequence of characters which are neither spaces
nor terminators.


I.D. Game Objects

I.D.1. Board Cell Representation

The cells transmitted via the BPOS and BROW server connected state messages
are single space-delimited characters, each representing a single cell on the
game board. Because of protocol limitations on the characters that are
permissible in a packet, the internal game board representation is not used;
instead, the following mapping is used:

	Game Object	Representation
	-----------	--------------
	Empty cell	.
	Black ball	K
	Red ball	r
	Green ball	g
	Blue ball	b
	Cyan ball	c
	Purple ball	p
	Yellow ball	y
	White ball	W


II. Protocol Overview

The protocol can be divided into two main stages: the Initial Handshake and
the Connected State. The Initial Handshake consists of the exchange of a fixed
sequence of protocol messages. The Connected State is a state where the
Connected State messages may be freely exchanged, in any sequence.

Unexpected messages during the Initial Handshake is valid grounds for
terminating the communications channel. However, implementations should be
prepared to handle Connected State messages in any order once in the Connected
State.


III. Initial Handshake

The Initial Handshake occurs immediately after a client establishes a
communications channel to the server.


III.A. Server Greeting

Once the client has established the connection, the server must sent an
initial message, of the form:

	ATOM4 SERV <game-version> <protocol-version>

where <game-version> is the version number, in the form <n>.<m> where <n> and
<m> are positive integers, of the ATOM-4 game engine it is running; and
<protocol-version> is the version of this protocol that it is using.


III.B. Client Response

The client, upon receipt of the initial server message, must determine if the
given version numbers are compatible with it. If not, it must immediately
terminate the connection. Otherwise, it must respond to the server with a
message of this form:

	ATOM4 CLNT <game-version> <protocol-version>

where <game-version> is the version number of the ATOM-4 game it is designed
to interact with, and <protocol-version> is the version of this protocol that
it is using.


III.C. Server Confirmation

Upon receiving the client's response, the server must determine if the
client's version numbers are compatible with it. If it does not support the
client's version of the ATOM-4 game or the protocol version, it must terminate
the connection (possibly sending an error message---see the section describing
protocol error messages).

Otherwise, possibly after adjusting its own protocol so as to be maximally
compatible with the client, the server must send a confirmation to the client
in a message of the form:

	ATOM4 CONN <message>

where <message> is an arbitrary welcome message, which the client may
optionally display to its user.

Upon transmission of this message, the server should immediately enter the
Connected State. Upon receipt of this message, the client should also enter
the Connected State.


IV. Connected State

In the Connected State, the server may freely transmit any Server Message to
the client; and the client may freely transmit any Client Message to the
server, in any order, until the communications channel is terminated. 

Collectively, Server Messages and Client Messages are referred to as Connected
State messages. Neither server nor client should fail upon receiving a
Connected State message in an order it does not expect. However, Client
Messages sent at inappropriate times may be ignored by the server.


IV.A Client Modes

During the Connected State, the client may be either a Player, or a Watcher. 
A Player is a client who participates in an ongoing game; a Watcher is a
client who is connected to the server, and receiving the server's
informational updates, but not directly participating in the current game.

By default, once the client receives the server's "ATOM4 CONN" confirmation
message, it should assume itself to be a Watcher until the server specifies
otherwise with a PNUM message. Although the server will ignore any attempt by
a Watcher to take direct part in the game, this is not recommended client
behaviour.

Once the client has received the appropriate PNUM message (see section V), it
should switch to Player mode. The player number argument in the PNUM message
will indicate to the client which Player it is, in the game. As a Player, the
client should expect to receive a TURN message, which the server will send to
indicate which player is to move next. The client MUST recognize its player
number and respond to it with an appropriate MOVE message, after potentially
prompting the user to make a move. The client should NOT respond to a TURN
message if the argument to the message does not match its player number (i.e.,
it should not try to move if it's not its turn to do so).

Clients that persistently attempt to respond to TURN messages not addressed to
them may be considered abusive by the server; the server may forcefully
terminate communications with such clients.

While in Player mode, if the server sends a PNUM message with a 'W' parameter
(see section V), the client should switch back to Watcher mode, and refrain
from sending any gameplay messages.


V. Connected State Messages

V.A. Server Messages

Server Messages can be grouped into the following categories:

- Offers: messages sent by the server to ask the client for a response.

- Notifications: messages sent by the server to update the client about game
  events, the state of the game board, etc..

- Non-fatal errors: warnings or other game-related informational messages
  sent to the client. Non-fatal errors should not cause the server to
  terminate the client's connection.

- Fatal errors: error messages caused by protocol errors, server internal
  errors, or other problems. The client should expect to be disconnected by
  the server upon receiving a fatal error message.


V.A.1. Offers

V.A.1.a. POW?

This message is an invitation to the client to join in a new game. The format
of this message is:

	POW?

The client should respond with a WATCH or a PLAY. Note that this message does
NOT guarantee the client will become a Player, since another client may
respond first and occupy all existing positions. The client MUST wait for a
PNUM message before entering Player mode.

"POW?" stands for "Play Or Watch?".


V.A.1.b. TURN

This message is a notification from the server to a *particular client*, which
may not necessarily be the recipient of the message, that it is its turn to
make a move. The format of this message is:

	TURN <p> <c>

where <p> is the player number and <c> is the piece the player is currently
playing. Clients MUST remember which player number they were assigned by the
server, and MUST NOT respond to a TURN message unless their player number is
<p>.

If the client which this offer is directed at does not respond, the server
may, after a reasonable timeout, withdraw the offer by disconnecting the
client and aborting the current game.

Upon receiving this message, if <p> matches the client's assigned player
number, it should prompt its user to make a move, and forward the move to the
server in the form of a MOVE message. Clients should NOT send multiple MOVE
messages to a single TURN message. If the move was invalid, it is the
responsibility of the server to indicate this with an appropriate (non-fatal)
error message, and to send another TURN message.

If <p> does not match the client's assigned player number, it should inform
its user that the game is waiting for player <p> to make a move.

The server should ignore MOVE messages from clients which it did not send the
corresponding TURN message to. It may optionally disconnect the client for
abusive behaviour if the client persists in doing this.

Note the client MAY send other messages to the server (such as requests for
updated game board information) between receiving a TURN message and sending a
MOVE message. The server should honor such requests, and MUST NOT repeat the
TURN message unnecessarily in such cases.


V.A.2. Notifications

V.A.2.a. PNUM

This message is sent to the client to indicate whether it should enter Player
mode or Watcher mode. The format of this message is:

	PNUM <p>

where <p> may be one of 1, 2, or W. If <p> is 1 or 2, this is the client's
assigned player number, and the client MUST from this point on recognize TURN
messages carrying the same number, and should respond to them appropriately.

If <p> is W, then the client MUST switch into Watcher mode, and refrain from
sending MOVE messages to the server until notified otherwise by another PNUM
message from the server.

The server MUST NOT assign the same number to two different clients during the
same game.


V.A.2.b. BDIM

This message is sent by the server to inform the client of the dimensions of
the game board. The format of this message is:

	BDIM <width> <height>

where <width> and <height> are positive integers represented as sequences of
ASCII digits in decimal.

This message invalidates any previous game board updates the server has sent
to the client. The client should assume that the game board is now completely
empty, and should update all local copies of the game board accordingly. It
should also update any visual representation of the game board presented to
the user.

The server MUST send a full game board update following this message if the
game board is not empty. The server should not send this message while a game
is in progress. The server MUST send this message at least once, BEFORE
sending the first BPOS or BROW message.

The client should refrain from responding to this message by requesting a full
game board update, since the server is obligated to send an update unless the
game board is now empty.


V.A.2.c. BPOS

This message is sent by the server to inform the client of the current
contents of the game board. The client should update its local copy of the
board as indicated in the message. The format of this message is:

	BPOS <x> <y> <c>

where <x> and <y> are the coordinates of the board cell concerned, and <c>
is a board cell specification.

Note that game board coordinates start counting from 0, up to 1 less than the
dimension given in a BDIM message.

When large portions of the game board have changed, the server SHOULD use the
BROW message to update the client instead.

Note that BPOS and BROW messages from the server are authoritative of the
state of the game board. Clients should update any local copies of the game
board and any visual representation of it accordingly upon receiving these
updates.

The server MUST NOT send this message before sending a BDIM message to the
same client. If the client receives a BPOS before it receives a BDIM, it
should ignore the message.


V.A.2.d. BROW

This message is sent by the server to inform the client of the current
contents of the game board. The format of this message is:

	BROW <y> <c1> <c2> ...

where <y> is the number of the row (counting from 0), and each of <c1> <c2>
...  is a board cell specification. Each of the <pn>'s represents a cell in
row <y> of the game board, in order, from leftmost column to rightmost.

The server MUST send the same number of <pn>'s as there are columns in the
game board, as specified by a previous BDIM message. The server MUST NOT send
this message until it has sent a BDIM message to the same client.

The client should update any local copies or visual representations of the
game board upon receiving this message.


V.A.2.e. BEND

This message is sent by the server to inform the client that it has finished
sending game board updates via BPOS and BROW. THe format of this message is

	BEND

This message is intended to provide hints to the client as to when to actually
update the visual representation of the game board to the user. The client may
choose to ignore this message and update the game board after every BPOS or
BROW message.


V.A.2.f. NAME

This message is a broadcast message that supplies additional information about
a client to other clients. The server should broadcast this message to all
existing clients. The format of this message is:

	NAME <id> <p> <nick> [<message> ... ]

where <id> is a server-assigned identifier for the client; <p> is 0, 1, or 2;
<nick> is a one-word nickname for the client;  and the optional <message>
supplies any additional information about the client.

If <p> is 1 or 2, it refers to the two players playing the current game. If it
is 0, it refers to one of the Watcher clients. Note that all Watcher clients
will have <p> = 0; clients receiving this message should not blindly assume
there is only one Watcher.

Generally, <id> is assigned by the server and <nick> and <message> are set by
the client.  However, the server is free to override any client-supplied
<nick> or <message>. The <id> assigned by the server should be unique among
all existing clients. It is suggested that the server incorporate the network
address of the client as part of <id>.

Clients are not required to display any information in this message to the
user. Clients may choose to completely ignore this message. It is purely for
informational purposes.

Servers are not required to send any NAME messages. However, it is recommended
that the server send a list of all existing clients to a newly-connected
client, once it enters Connected State.


V.A.2.g. CONN

This message is a broadcast message that informs currently connected clients
about a newly connected client. The server should broadcast this message to
all existing clients. The format of this message is:

	CONN <id> [<message> ...]

where <id> is a server-assigned identifier for the client, and <message> is
an optional informational message.

Clients are not required to display any information in this message to the
user. Clients may choose to completely ignore this message. It is purely for
informational purposes.


V.A.2.h. GONE

This message is a broadcast message indicating that a particular client has
disconnected from the server. The format of this message is:

	GONE <id> <p> [<nick>]

where <id> is a server-assigned identifier for the client; <p> is 0, 1, or 2;
and <nick> is a one-word nickname for the client (if any).

If <p> is 1 or 2, it indicates that one of the players currently playing the
game has been disconnected, intentionally or otherwise. If <p> is 0, it
indicates that one of the Watcher clients have left.

The server MUST send a GONE message if one of the players in the current game
has disconnected. However, the server is not obligated to send a GONE message
for Watcher clients who left.


V.A.2.i. WIN

This message indicates that the current game has ended, and has been won by
one of the players. The format of this message is:

	WIN <p>

where <p> is the player number of the winner.

The server MUST send this message to at least both Player clients involved in
the current game. The server should also broadcast this message to Watcher
clients as well.

All Player clients receiving this message MUST switch back to Watcher mode.

It is recommended that the server pause after sending this message before
starting a new game.


V.A.2.j. DRAW

This message indicates that the current game has ended, but with neither
player as the winner. The format of this message is:

	DRAW [<reason> ...]

where <reason> is an optional human-readable message explaining why the game
was a draw. The most likely cause is that the game board has become full.

The server MUST send this message to at least both Player clients involved in
the current game. The server should also broadcast this message to Watcher
clients as well.

All Player clients receiving this message MUST switch back to Watcher mode.

It is recommended that the server pause after sending this message before
starting a new game.


V.A.2.k. ABRT

This message indicates that the current game has been prematurely aborted,
possibly due to one of the players disconnecting or resigning, a server
problem, or some other reason. The format of this message is:

	ABRT [<reason> ...]

where <reason> is an optional human-readable message indicating why the game
was aborted.

The server MUST send this message to any remaining Player clients involved in
the aborted game. The server should also broadcast this message to Watcher
clients.

All Player clients receiving this message MUST switch back to Watcher mode.

It is recommended that the server pause after sending this message before
starting a new game.


V.A.2.l. CHAT

This message is an optional message the server may relay from any of the
currently connected clients to all other clients. The format of this message
is:

	CHAT <id> <p> <nick> <message ... >

Where <id> is a server-assigned identifier, <p> is the player number of the
client sending the message, and <nick> is the client's chosen nick. Clients
receiving this message should display the message to the user; however,
clients are not required to implement this feature if they so choose.


V.A.2.m. INFO

This message is an optional informational message sent by the server. The
format of this message is:

	INFO <message ...>

Where <message> is any informational message. This protocol does not define
the syntax of such messages.

The client may display the message to the user for informational purposes;
however, clients are allowed to completely ignore INFO messages.


V.A.3. Non-fatal errors

Non-fatal error messages from the server all have the general form:

	GRR <errornum> [<message> ...]

where <errornum> is an error number, and <message> is an optional
human-readable error message.

Error numbers may be one of the following:

	101	Not playing. This error is sent to clients who attempted to
		make a move while not a player in the current game.

	102	Not Your Turn. Sent to Player clients who attempted to move
		when it's not yet their turn.

	103	Bad move attempted. This error is sent in response to a MOVE
		message which indicated an invalid move. The <message> should
		explain why it was an invalid move.

	104	Finish Playing First. This error is sent in response to a
		WATCH message while the client is still an active player in
		the current game. The client should send the RSGN message
		rather than a WATCH message if it wishes to resign from the
		current game.

	201	Bad nick. The server dislikes the nick the client has
		requested for itself, and has NOT changed the client's nick.
		Note that the server is NOT obligated to respond with this
		error in such cases; it may silently strip away unwanted
		characters from the requested nick and assigned the result to
		the client.

	802	Minor protocol error: the server could not understand the
		message the client sent; however, no fatal problems are
		anticipated, so clients may choose to continue normally.

(Yes, "GRR" is a lame pun on "Game eRRor".)


V.A.4. Fatal errors

Fatal error messages from the server all have the general form:

	ERR <errornum> [<message> ...]

where <errornum> is an error number, and <message> is an optional
human-readable error message.

Error numbers may be one of the following:

	901	Incompatible versions. The server is disconnecting the client
		because it uses an incompatible game/protocol version. The
		server should disconnect the client immediately after sending
		this message.

	902	Protocol error. The server received a garbled message from
		the client which it could not understand.

	903	Server is full. The server cannot accomodate any more clients.
		This is usually caused by too many Watcher clients being
		connected at once.

	911	Internal server error. A (potentially fatal) error has
		occurred in the server. Clients ought to disconnect.

	999	Bad client behaviour. The server is disconnecting the client
		because it has persisted in abusive behaviour, probably also
		consistently violating this protocol.


V.B. Client Messages

V.B.1. NAME

This message is sent by the client to request for the server to set
information about it which is potentially broadcast to other clients. The
format of this message is:

	NAME <nick> [<message> ...]

where <nick> is a one-word nickname the client wishes to be known as, and
<message> is an optional one-line description about the client.

The server may impose arbitrary restrictions on what constitutes a valid
<nick>. The server may respond with a GRR 201 (bad nick) if it has any
objections to the requested nick. However, the server is NOT obligated to do
so; it may quietly strip away unwanted characters from <nick> and/or alter it
so that it conforms to server rules.

The server is not obligated to do anything with this message, and is free to
completely ignore it. However, if the server does store the information about
the client, it should broadcast this fact to all existing clients via the NAME
server message.

Note that <nick> is purely informational; it is not intended to be an
identification handle to the server.


V.B.2. REQU

This message is sent by the client to request a game board update. The format
of this message is:

	REQU

Upon receiving this message, the server should update the client with a series
of BROW messages containing the full information about the current state of
the game board.


V.B.3. MOVE

This message is sent by the client to make a move in the game. This message
should only be sent when the client has received a TURN message carrying its
previously-assigned player number. The format of this message is:

	MOVE <x> <y>

where <x> and <y> specify the game board coordinates where the user has
decided to make the next move.

Clients should not update their local copy of the game board immediately after
sending a MOVE message; they should wait for the server's response.

The server should send a BPOS message to the client once the move is made. If
the move is invalid, the server should send a GRR 103, and should include a
human-readable message explaining why the move was invalid.


V.B.4. RSGN

This message is sent by a Player client when it wishes to resign from the
current game. The format of this message is:

	RSGN

Upon receiving this message, the server may either terminate the game with an
ABRT message explaining why the game was terminated, or may end the game by
having the other Player client win the game (sending WIN messages as
appropriate).

Client should not send this message unless they are one of the players in the
current game. The server MUST NOT terminate the game if this message comes
from a client who is not one of the players in the current game.


V.B.5. CHAT

This message is sent by a client to the server when it wishes to chat with
other connected clients. The format of this message is:

	CHAT <message>

Typically, <message> comes from whatever the user typed at the client.

This is an optional feature; the server may choose to completely ignore CHAT
messages. If the server does implement this feature, it should relay CHAT
messages to other connected clients using the server's CHAT message (see
V.A.2.k.).


V.B.6. NEXT

This message is sent by the client to request that the game proceed to the
next round. The format of this message is:

	NEXT

The server should wait for both players to send NEXT before starting the next
round of the game. This message MUST only be sent after the current game has
been finished by a WIN message or an ABRT message from the server. The server
should ignore NEXT messages sent in the middle of a game.


V.B.7. PLAY

This message is sent by the client in response to the server's POW? message.
The format of this message is:

	PLAY

This message indicates that the client wishes to participate in the current
game. The server should respond with the appropriate PNUM message depending
on whether current game still has available slots for players.

The server may choose to ignore this message if the client was not sent a
POW? message previously. The server may also ignore this message if a previous
PNUM message has already been sent to the client, and a POW? message has not
been sent to the client since. However, the server MUST respond to at least
one PLAY or WATCH message after sending the client a POW? message.

Sending this message does not guarantee the client will become a player; the
slot may have already been assigned to another client by the time this message
reaches the server. Clients MUST wait for a PNUM message before entering
player mode.

Clients should interpret the lack of response to this message from the server
as an implicit indication that the client is to remain in watcher mode.


V.B.8. WATCH

This message is sent by the client in response to the server's POW? message.
The format of this message is:

	WATCH

This message indicates that the client does NOT wish to participate in the
current game. The server should respond with a "PNUM W" message to indicate
that the client is now a watcher.

The server may choose to ignore this message if the client was not sent a
POW? message previously. The server may also ignore this message if a previous
PNUM message has already been sent to the client, and a POW? message has not
been sent to the client since. However, the server MUST respond to at least
one PLAY or WATCH message after sending the client a POW? message.

Clients should interpret the lack of response to this message from the server
as an implicit indication that the client is to remain in watcher mode.


V.B.9. QUIT

This message is sent by the client to indicate that it is disconnecting. The
format of this message is:

	QUIT

Upon receiving this message, the server should close the client connection and
free up any resources allocated for the client, including cancelling any game
the client might be currently participating in.

V.B.10. WHO?

This message requests that the server update the client with information about
other clients currently connected to the server. The format of this message
is:

	WHO?

Upon receiving this message, the server should send a series of NAME messages
containing information about currently-connected clients. However, the server
may choose to respond with a GRR 802 (not implemented) non-fatal error
instead.