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

[Kjetil Torgrim Homme <kjetilho>]

(plenty of disclaimers in the Subject, eh? :-)

+--- Carl Edman:
| 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.

Seems like a a good design goal. QUERY/REPLY doesn't fit into this,
though, see below.

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

Of course, "packet" here is in the meaning "command" - one command can
consume several TCP-packets (or whatever) or the other way around. A
TCP-packet can contain one and a half command, and the first command
must then be processed before the other half of the second command
arrives. (Obvious, but I think it needs saying)

+---
| All characters are case sensitive. 

Good! I'd like to add something like "whitespace is not ignored and
not allowed in arguments except where indicated. Control characters
(0-31, 128-159) are only allowed in binary data."

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

You haven't defined coordinate, but I assume it is relative to the top
left corner of the map, and that the axes runs from top to bottom and
left to right.

This doesn't seem cater for seeing several objects at a spot in the
map, though. Suggested solution: Default number of objects is 1. The
client can send a SET command.

SET GRAPHICSLEVEL 3

The server will then send

MAP <locx1> <locy1> <image1a> <image1b> <image1c> <locx2> ...

An empty string for an image name means no object in that position.
Note: --------+
              v
MAP 1 1 grass  1 2 grass orc 1 3 ...

Images are sent in bottom up order, ie. last image in list should
(partly) obscure the others. For GRAPHICSLEVEL 1, only the top-most
image is sent. For higher graphics levels, as many floor objects as
possible are sent in addition, and then objects from the top of the
stack.

There will be more SET commands to control client/server
communication, for example "SET IMAGEFORMAT XPM". Unimplemented SET
commands should be ignored by the server. A companion command "SETF"
should be used if failure to recognize the command is fatal to the
client. The server will then send an ERROR packet in reply.

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

Should the view change immedietely, or is it reasonable for the client
to wait until it receives a new ITEM for that tag? In general, how
much caching/state _must_ the client have? MOVE seems to assume some
state, but it is not clear to me.

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

It should be made clear that for a given <stat>, <maximum> will either
always be sent or never (<stat> == "weight").

+---
| 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. 
| 
| [...]
| 
| REPLY [YES|NO]
| The response to the most recent QUERY command.

This won't do. My suggestion:

QUERY <ref> <response type> <text>

Ask the user a question with the text <text>. No parsing is done on
the string after <response type>. <ref> may be reused as soon as the
server has received a reply for it. <response type> is one of the
following:

"BOOL"
    - reply with <number>, 0 for NO and 1 for YES
"NUMBER"
    - reply with <number>
"RANGE <start> <end>"
    - reply with <number> which is in the range
"MULTIPLE <sep>Choice 1<sep>Choice 2<sep><sep>"
    <sep> is a single character (may be SPACE), list is terminated by
    an empty choice.
    - reply with the sequence number of the choice made.
"TEXT"
    - reply with free form text, with the exception of newline.


With the above extensions to QUERY/REPLY, you can code the login
sequence. We also need

EXAMINE <locx> <locky>
If <locx> is "IN", the server sends a description with REPLY <locy>
<text>.  If <locx> is a real coordinate, a sequence of ITEM packets
for all objects at that coordinate is returned in bottom up order,
terminated by an automatic REPLY <tag> <description> for the topmost
object.

Maybe also
COMMAND <command>
This should be used for things like "who" and "pickup" unless we
decide to put _everything_ into the protocol.

I can't think of anything more missing right now (well, except shout :-).


Kjetil T.