A quick draft of a preliminary proposal for a possible version of the crossfire protocol

["Carl Edman" <cedman@cedman.remote.Princeton.EDU>]

This is the basic idea of how I think the crossfire protocol should  
look.  I've only been thinking about it a few days, so what you see is  
completely in a state of flux.  I post it only to give a concrete image  
to some of the basis ideas I've expounding here in the last few days  
and not in the expectation that it will be adopted in a form even  
similar to this.  It is certainly not complete though it covers most  
common game situations.  You have been warned.

	Carl Edman

GENERALITIES
============

A bi-directional 8-bit wide clean error-free channel of some form  
exists between the client and the server.  Absolutely all communication  
between them occurs on this channel and a client can receive everything  
it needs to run through it.  Typically this channel will be a TCP/IP  
connection, but it may very well in some situations be a high speed  
modem connection or a UN*X pipe or some completely different network  
protocol.

In practice the up channel (from client to server) and the down channel  
(from server to client) function as two independent uni-directional  
chutes.  If one side has something to tell to the other it just drops a  
packet into its send channel and forgets about it.  Confirmations are  
not given or expected.  The sender just assumes that the receiver will  
handle the packet or it will complain in another packet.  At the same  
time the two chutes may be communicating about two entirely different  
subjects.

Each packet consists out of one line of text terminated by a newline  
(0x0a) character.  Line lengths of up to 4096 characters (including the  
terminating newline) are guaranteed to work.  The receiver may  
correctly interpret longer packets, silently drop them or send an error  
message (see below) depending on what makes sense for the receiver.   
All characters are case sensitive. 


Every packet begins with a word terminated either by a space (0x20) or  
the end of the packet.  The interpretation of the rest of the line  
depends on the initial word.

VALID COMMANDS FROM THE SERVER TO THE CLIENT
============================================
MAP <locx1> <locy1> <image1> <locx2> <locy2> <image2> ...
Using one of these commands the server may tell the client that it sees  
the map at a series of location given by coordinate pairs.  The name  
refers to the image to use for the particular map location.  If the  
client doesn't know that particular name, it asks the server for it  
(see REQUEST/TRANSMIT).

UNMAP <locx1> <locy1> <locx2> <locy2> ...
This command tells the client that a certain series locations isn't any  
longer in the LOS of the player.  The client may respond to this by  
erasing the squares in question, shading them to indicate to the user  
that they aren't any longer directly visible or just by doing nothing.

CLEAR
Erases the entire map.

ITEM <number> <locx> <locy> <image> <text>
Tells the client that the player seen an item with the tag <number> at  
the location <locx>,<locy>.  <image> indicates the name of the image  
file to use for the item and <text> is the full name of the item.  In  
addition, <locx> may also be the string "IN".  In that case <locy> is  
the tag number of the item within which the item at hand is located or  
<locy> is the string "VOID" which means that the item has disappeared.

VIEW <number>
After this command the client considers the item with the tag <number>  
to be the viewpoint item and will always try to center the map around  
it.  This is typically the item which is the player object.

TEXT ...
This commands instructs the client to display the remainder of the line  
(after the space character terminating the TEXT command) verbatim in  
some sort of text area.  The client may word wrap the text.

PLAY <sound>
Instructs the client to play the sound with the specified name.  If the  
client doesn't know the sound by that name it requests it from the  
server (see REQUEST/TRANSMIT).

STAT <stat> <current> [<maximum>]
This tells the client that the value of the player statistic called  
<stat> is <current>.  If given <maximum> indicates the maximum value of  
that stat.  The client could simply print out this message in the text  
area, but it is encouraged to recognize at least a few commonly used  
stats like hp or sp or food and make up some cute graphical  
representation for them which the player sees at all times.

REQUEST <name> <type>
Ask the client to send the the binary file called <name> of type <type>  
using the TRANSMIT command.

TRANSMIT <name> <type> <length>
This command is followed by binary data of the length <length> bytes  
which describes the binary object of name <name> of type <type>  
(typically either IMG or SND).  All other command interpretation is  
suspended while the binary data streams in.  After the binary data has  
been received normal command interpretation resumes immediately.

ERROR <...>
This command is used to indicate that a real error has occured.  The  
remainder of the line is some free form text describing that error.   
What the client does with that message is up to it.  This command is  
only used to indicate actual program errors which point to  
bugs/incompatibilities between it and the server such as malformed  
packets and the like.  Player errors (like trying to take something  
which isn't there) are handled by normal TEXT messages.

QUERY <...>
Ask the user a question with the text <...>.  Some clients may want to  
pop up a requestor for this.  Others may not.  The answer is taken from  
the next REPLY packet sent by the client.

VALID COMMANDS FROM THE CLIENT TO THE SERVER
============================================
LOGIN <client-version> <name> <password>
Typically this will be the first command sent by the client.  If it is  
sent during a session, the effect is the same as if the session had  
been terminated and a new connection had been established with this  
command.  <client-version> is a string created by the client at compile  
time.  The server is not encouraged to treat different clients  
differently.  This string is just there to be able to gather statistics  
(and to correlate with ERROR packets).  <name> and <password> are  
self-explanatory.

REQUEST
TRANSMIT
ERROR
These three commands are valid in this direction as well with the same  
syntax and semantics.

MOVE <number> <locx> <locy>
This is probably the most frequently used command.  In it the client  
asks the server to move the item with tag <number> to be moved to  
location <locx>, <locy>.  As with ITEM (see above) <locx> can also be  
the string "IN" in which case <locy> is the tag of an item into which  
the item at hand should be moved.  A player would use this command to  
pick up items, to drop them, to throw them, to steal them and most  
importantly to move himself around the map (with <number> == the tag  
number which the client was told by the VIEW command).  Clients may  
want to take single steps or can ask to run as far as possible in one  
direction by giving huge values for <locx> or <locy>.

APPLY <number>
The player tries to apply the item with tag <number>.

INVOKE <spell> <locx> <locy>
The player actually casts the spell with name <spell> at <locx>,<locy>  
(as with MOVE, <locx> can be "IN" and <locy> an item tag number to cast  
a spell at an item).

SAY <...>
The player says whatever the free-form text which follows on the line  
is.  Other players would see this by means of some TEXT message.

REPLY [YES|NO]
The response to the most recent QUERY command.

There are more fine points to be explained about how this protocol  
handles certain events, but I'm sure those will come up in questions  
anyway. :-)