----------------------- 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 where is the version number, in the form . where and are positive integers, of the ATOM-4 game engine it is running; and 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 where is the version number of the ATOM-4 game it is designed to interact with, and 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 where 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

where

is the player number and 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

. 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

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

does not match the client's assigned player number, it should inform its user that the game is waiting for player

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

where

may be one of 1, 2, or W. If

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

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 where and 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 where and are the coordinates of the board cell concerned, and 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 ... where is the number of the row (counting from 0), and each of ... is a board cell specification. Each of the 's represents a cell in row of the game board, in order, from leftmost column to rightmost. The server MUST send the same number of '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

[ ... ] where is a server-assigned identifier for the client;

is 0, 1, or 2; is a one-word nickname for the client; and the optional supplies any additional information about the client. If

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

= 0; clients receiving this message should not blindly assume there is only one Watcher. Generally, is assigned by the server and and are set by the client. However, the server is free to override any client-supplied or . The 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 . 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 [ ...] where is a server-assigned identifier for the client, and 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

[] where is a server-assigned identifier for the client;

is 0, 1, or 2; and is a one-word nickname for the client (if any). If

is 1 or 2, it indicates that one of the players currently playing the game has been disconnected, intentionally or otherwise. If

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

where

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 [ ...] where 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 [ ...] where 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

Where is a server-assigned identifier,

is the player number of the client sending the message, and 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 Where 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 [ ...] where is an error number, and 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 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 [ ...] where is an error number, and 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 [ ...] where is a one-word nickname the client wishes to be known as, and is an optional one-line description about the client. The server may impose arbitrary restrictions on what constitutes a valid . 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 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 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 where and 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 Typically, 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.