[ViewVC] Contents of: cvs/deliantra/server/doc/Developers/protocol

Updated $Date$ by $Author$:

Outline:

 This section contains a brief outline of the document.

 Background: List some of the background for client/server, and current state
        of affairs.
 General Socket Notes: How sockets are presently used.
 Protocol:  Commands that are sent back and forth.
 Example Session:  A brief example of what protocol commands would be sent
        back and forth.
 Programming notes: A few notes that can be useful for people writing clients
        are extending the server.
 Todo: Things to do in the future.

 Note:  each section is seperated by a line of dashes. This should make finding
a specific section easier.

 In order to make things a little for people doing porting, I have
added SUMMARY comments in some of the sections.  These contain a very
brief summary of some aspect that is needed for writing the code.  A more
detailed explanation of the SUMMARY can be determined by reading the
section.

------------------------------------------------------------------------------
Background:

  Originally, the communications plan was set to be a text based system.
These messages are what is originally detailed below (now removed).  It was
up to the server and client to parse these messages and determine what to
do.  These messages were assumed to be 1 line per message.

At a reasonably early stage of developement, Eric Anderson wrote a fairly
(but not totally) complete client/server that used his eutl package.  This
package pretty much set up packets with subpackets - these subpackets would
have a tag for the data type, then the data itself.  Thus, you could any many
types, and after transmission, the other end could decode these commands.

This works fairly well, but I think the creation of numerous sub packets has
some performance hit.  Also, the eutl was not especially well documented,
so writing a client for a different platform became more difficult (you
needed to first port over eutl.)  An example such of this is the Java client
currently in production.  Also, Eric left to work on other products shortly
after writing his client, which didn't really leave anyone with a full
understanding.

I have decided to remove the eutl dependancy.  At least one advantage is
that having this network related code directly in the client and server
makes error handling a bit easier/cleaner.

However, instead of a straight text method, the outside packet method is:
<size (2 bytes)><data (size bytes)>  The <size> is the size of the data
packet, the 2 byte size for the size information is not included here.

Eutl originally used 4 bytes for the size - to me, 2 bytes seems plenty (gives
a maximum packet of 32767 - I can't see ever going beyond a few thousand,
simply because in a fast action game, transmission size of such a packet would
probably not make things playable.)  While saving 2 bytes might not be much,
it makes a least some sense.

The actual data is something of the nature of the commands listed below.  It
is a text command, followed by possible other data.  The remaining data can
be binary - it is up to the client and server to decode what it sent.

The commands as described below is just the data portion of the packet.  If
writing a new client, remember that you must take into account the size of
the packet.  there is no termination of packets, other than knowing how long
it should be.

For now, most everything that is sent is text.  This is more or less how
things worked under eutl, except it packed the ints into 4 bytes in a known
order.  In some cases, we handle ints as strings, in others, they are
sent as binary information.  How any command handles it is detailed
below in the command description.

The S and C represent the direction of the data (S->C represents something 
the server sends to the client, C->S represents something the client sends
to the server.)

In terms of all binary values, we use MSB order (same as eutl used).  This
includes the initial length information, as well as any ints or shorts that
get sent inside the packets.  All packets are defined to have at least one
word of text, followed by a space, then followed by optional data (which can
be binary.)

Side note:  Generally, the data the client sends to the server is text,
but a fair amount of data the server sends to the client is binary.  This
has somewhat to do with who wrote what code, and also has to do that the
S->C bandwidth is going to more the more serious limitation - the client
generally won't be sending so much data that the its flow is much problem.

Note that all the commands as detailed below are up to date descriptions
I removed a lot of the old notes on this file, because they were
out of date, and while might be good ideas, were not all that relevent to
how things currently work.

Summary: Packets sent back and forth have a 2 byte header (MSB order)
which contains the length of the rest of the packet.

------------------------------------------------------------------------------
General socket notes:

We are using a TCP/IP socket.  Other methods could be used, but the
present protocol does not make very good provisions for missing data, so
it needs to be something that corrects errors/does resends automatically
(or just doesn't get errors in the first place.)

For now, we set non blocking output on the server side.  This means we don't
have to worry about internal buffering.

If the connection is lost (which will also happen if the output buffer
overflowing), it looks like we just terminate the connection without saving
(meaning last save takes effect.)  This can certainly be abused the same way
that currently killing the server (ie, go to treasure chamber, get all the
treasure, kill server, wait for map to reset, play again, with you starting
in the treasure chamber.)

I don't know if there is a really good way to handle it.  The other method
would be to save the player back in town.  But this then gets the situation
of 'oops, I'm trapped', lose connection, start back in town.

 This is probably preferable - all you really gained there is a word of
recall spell/scroll.  Also, it doesn't really hurt the honest players who
lost their connection for various reasons (and in fact, could be a disadvantage
if they can't connect again until after the map resets, and they lost all
the loot they were working on..)

The server only reads data from the socket if the player has an action.
This isn't really good, since many of the commands below might not be actual
commands for the player.  The alternative is to look at the data, and if it
is a player command and there isn't time, store it away to be processed later.
But this increases complexity, in that the server must start buffering the
commands.  Fortunately, for now, there are few such client commands.

If it becomes a case where the client is requesting images/sounds, dual
channels could probably be used, since requesting that data is not related
to the actual playing of the game (or a special daemon that serves those
requests could also be done.)

SUMMARY: TCP/IP sockets are used for exchange data.  Server uses non
blocking i/o when writing to the socket, and the server only reads from the
socket when the player actually has time for an action.

------------------------------------------------------------------------------
Protocol:

Object tags:  Many of the commands below refer to 'object tags'.  Whenever
the server creates an object, it creates a unique tag for that object
(starting at 1 when the server is first run, and ever increasing.)  Tags
are unique, but are not consistent between runs.  Thus, the client can
not store tags when it exits and hope to re-use them when it joins the
server at a later time - tags are only valid for the current connection.

 I have decided to break the protocol into various sections which based
somewhat on what the commands are for (ie, item related commands,
map commands, image commands, etc.)

******************************************************************************
COMMANDS RELATING TO ESTABLISHING THE INITIAL CONNECTION AND CLOSING THE
CONNECTION

C->S: version <csval> [scval [vinfo]] 
S->C: version <csval> [scval [vinfo]]
        Through the version command, the client and server exchange what
        version of the protocol they understand.  Neither send this
        in response to the other - they should both send this
        shortly after a connection is established.

        csval is the version level of C->S communications.
        scval is the version level of S->C communications.
        vinfo is a string that is purely for informative that general
        client/server info (ie, javaclient, x11client, winclient, sinix server,
        etc).  It is purely of interest of server admins who can see what
        type of clients people are using.

        If a new command is added to the protocol in the C->S direction, then
        the version number in csval will get increased.  Likewise, the same
        is true for the scval.

        As far as the client is concerned, its scval must be at least equal
        to the server, and its csval should not be newer than the server.

        The server does not care about the version command it receives right
        now - all it currently does is log mismatches.  In theory, the
        server should keep track of what the client has, and adjust the
        commands it sends respectively in the S->C direction.  The server is
        resilant enough that it won't crash with a version mistmach
        (however, client may end up sending commands that the server just
        ignores).  It is really up to the client to enforce versioning and
        quit if the versions don't match.

        scval and vinfo was added starting in 1020.  Before that version,
        there was only one version sent in the version command.

        The version are currently integers, in the form ABCD.  
        A = 1, and will likely for quite a while.  This will only really change
        if needed from rollover of B.

        B represents major protocol changes - if B mismatches, the clients
        will be totally unusable.  Such an example would be change of map or
        item sending commands (either new commands or new format.)

        C represents more minor but still significant changes - clients might 
        still work together, but some features that used to work may now fail
        due to the mismatch.  An example may be a change in the meaning
        of some field in some command - providing the field is the same size,
        it still should be decoded properly, but the meaning won't be processed
        properly.

        D represents very minor changes or new commands.  Things should work no
        worse if D does not match, however if they do match, some new features
        might be included.  An example of the would be the C->S mark command
        to mark items.  Server not understanding this just means that the
        server can not process it, and will ignore it.

        Note:  Since all 'packets' have the length as the first 2 bytes, all
        that either the client or server needs to be able to do is look at
        the first string and see if it understands it.  If not, it knows how
        many bytes it can skip.  As such, exact version matches should not
        be necessary for proper operation - however, both the client and
        server needs to be coded to handle such cases.

        Note 2: For the most part, this has been obsoleted by the
        setup command which always return status and whether it
        understood the command or not.  However there are still some cases
        where using this versioning is useful - an example it the
        addition of the requestinfo/replyinfo commands - the client
        wants to wait for acknowledge of all the replyinfo commands
        it has issued before sending the addme command.  However, if the
        server doesn't understand these options, the client will never
        get a response.  With the versioning, the client can look at
        the version and know if it should wait for a response or if
        the server will never send back.

C->S: addme
    Tells the server that it should add me (the client) to the game.  
    Generally, the client will always send this command, but I suppose there
    can be actions the client wants to do before being added.

S->C: addme_failed 
S->C: addme_success

        This are responses to the last addme command.  I really think these
        should be discontinued, as they are one of the few messages which is
        just a confirmation of a previous messsage.  The addme_failed should
        really be replaced with a terminate type of of message (player quits
        game, server could inform us nicely and exit out).  addme_success is
        really of no use - client just throws it away.

S->C: goodbye (Added in SC protocol version 1022)
        Informs the client that the server has finished transmitting data
        to the client.  This is a bit cleaner than the client detecting
        a read error.  In theory, a C->S of the same type could be done,
        but I don't think it would make a big difference for the server (is
        going to do the same thing regardless of a clean conection drop
        or a bad one).  

Also see the setfacemode command below.

******************************************************************************
COMMANDS RELATING TO PLAYER INPUT AND OUTPUT IN THE INFO WINDOW

C->S: command [count] <txt>
    command is the protocol command.  It is the <txt> segment which actually
    includes the command (ie, north, fire, etc.)  There should not be any
    binary data in the <txt> segment.

    count is an optional value for the number of objects/repeat count
    (ie, typically used for dropping, but count can be used in other
    cases)

    Client sends a command to the server.  Ordinary commands (ie, north,
    west, apply, maps, etc), might be sent, commands with options may be sent
    (ie, 'invoke create food of booze', 'cast medium fireball').  There are a
    few special commands that can also be sent.

    'fire' command is a special case.  The server will handle repeat firing. 

    'fire_stop' will be sent to inform the server to stop firing.  A
    different command name has been chosen to make things easier on the
    server ('fire_stop' should be a 0 time command, with the rest of the
    fire commands actually taking some time.)  In some cases, 'fire_stop'
    may be sent almost immediately after the first fire (in cases where the
    player only wants to fire once).

C->S: ncom <packet> <repeat> <command>
     (ncom = new command)
     This is a replacement for the 'command' above.  packet is a 16
     bit value which represents what command this is (used is 
     command below). At current time, only the lowest 8 bits should
     be used (255 should be a plenty large window) - the other 8 bits
     are reserved for future flags

     repeat is a 32 bit value and is the repeat value.

     command is the actual command data (north, whatever).  Notes
     under command above also apply here.

S->C: comc <packet> <time>
     (comc = completed command)
     This is used in the window of the ncom command above.  packet is
     the command number we just executed (16 bit binary), and time
     is a 32 bit value represent how many milliseconds the player is
     currently taking to execute commands.  This information can be
     used by the client to do some throttling.

C->S: reply <text>
    Sends <text> as a reply to the last query command sent.


S->C: drawinfo <color> <text>
        Tell the client to draw whatever text in color.  Color are specified
        in newclient.h, and is sent as a string.  The client is free to do
        whatever it wants with the color information (which may very well
        mean ignore it.)
        
S->C: query <flags> [text]
        Asks the client program for input.  This is only used in a few places -
        mostly in creating a character and login, but in fact anyplace in the
        server that changes the input state (pl->contr->state, ST_*), should
        send a query.

        <flags> are detailed in the <newclient.h> file, which is common to both
        the client and server.  The flags of relevance to this command are the
        CS_QUERY flags.  <flags> are sent in plaintext form.

        The client is free to ignore the flags.  However, if the server just
        wants a single character as a reply, that is all it uses, even if the
        client sends a long string (Server will use the first character.)

        [text] is the question/prompt that should be printed.  Right now, it is
        typically just a ':'.  Client should display it no matter what is is,
        however.  Text is an optional field.  Note - as of 0.94.2, text may
        be multi line, delimited by newlines.  Client should handle this
        appropriately.

C->S: toggleextendedtext <type>
        Ask the server to send extended text information for a given type.
        type is the decimal representation of an int.
        Currently supported/reserved values for types are described in drawextinfo

S->C: ExtendedTextSet <type1> <type2> .... <typen>
        Tell client what actually are the extended infos server may
        send to the client when this is needed. All those infos will
        be related to the map and send through mapextended command.
        Each string represent an info which is enabled. Look
        at toggleextendedinfos and drawextinfo for details.

S->C: drawextinfo <color> <type> <subtype> message
        Tell the client to draw specific text.  Color are specified
        in newclient.h, and is sent as a string.  The client is free to do
        whatever it wants with the color information (it may very well ignore it.)
        
        color   same as color infor from S->C drawinfo
        type    is an int in decimal representation, giving the type of message
        subtype is an int in decimal representation, giving subtype 
                (flavor) of message.  
        message is a string representation of textual message. content of message may
                very well vary depending on the type.
        
        The server will never send a message to a client with a message type not
        requested at setup by a toggleextendedinfo. Client is however encouraged to handle 
        those case to catch bugs in protocols which may arise in future.
        
        It is possible a client handles a given message type but not a given subtype.
        The server does not care about the client subtype (flavors) and, so, client
        should have a 'generic representation' for each supported type, which will be
        used when a given subtype is not supported. The type are made a way subtypes 
        can be considered as just visual variations (eg a scroll,a card, a letter
        and a book will share the same type)
        
        Values for types and description:
                0       reserved
                1       books
                       books contains media tags in their body (TODO: document media tags)
                       message has the form <title>\n<body>
                       subtype represent the style of book.
                       MSG_TYPE_BOOK_CLASP_1    1
               MSG_TYPE_BOOK_CLASP_2    2
               MSG_TYPE_BOOK_ELEGANT_1  3
               MSG_TYPE_BOOK_ELEGANT_2  4
               MSG_TYPE_BOOK_QUARTO_1   5
               MSG_TYPE_BOOK_QUARTO_2   6
               MSG_TYPE_BOOK_SPELL_EVOKER    8
               MSG_TYPE_BOOK_SPELL_PRAYER    9
               MSG_TYPE_BOOK_SPELL_PYRO      10
               MSG_TYPE_BOOK_SPELL_SORCERER  11
               MSG_TYPE_BOOK_SPELL_SUMMONER  12
                2       cards
                3       papers
                4       signs
                5       monuments
                6       scripted dialogs
                7   motd
                       no subtype, content of message is the media tag enabled motd

******************************************************************************
ITEM MANIPULATION RELATED COMMANDS

 Client requests to server:

C->S: move <to> <tag> <nrof>
    All parameters are integers sent in string format.  <to> is where to move
    the object to, tag is the object tag, nrof is how many to move.  This
    command is used to pickup/drop objects.  If <to> or <tag> is zero, the 
    object is being moved from/to the ground.  This command is used to move
    items from a container into inventory and vice versa.  if nrof
    is zero, all objects will be moved.

C->S: examine <val>
    Tells the server that I want to examine object <val>, where <val> is a
    text string that represents that objects tag.  Objects tags are unique
    for each object.

C->S: apply <val>
    Tells the server that I want to apply the object <val>.  Like examine,
    <val> is a text representation of an integer tag.

C->S: lock <val><tag>
    Tells to server to set the inventory lock flag of item tag to val.
    val of 1 means that the item should be locked, 0 means unlocked.
    val is 1 byte binary, tag is 4 byte binary.  The server should send
    and upditem command with new flags to reflect this change.

C->S: mark <tag>
        'marks' and item for secondary usage.  Some actions in crossfire
        require an action that uses another item (improvement scrolls, flint
        & steel).  In order not to rely on inventory ordering or other
        gimmicks, this 'marked' item is used.  Only one item can be marked
        at a time - server will only keep track of the latest mark sent.
        <tag> is a 4 byte binary value.  The server will generally send a
        drawinfo command informing the player, but there is no especially
        easy way for the client to know what the marked item is (although,
        client knowing this is not strictly needed)

Server updates to client:

S->C: item1 <location><tag1><flags1><weight1><face1><name1><anim1>
        <animspeed1><nrof1><object2....>

S->C: item2 <location><tag1><flags1><weight1><face1><name1><anim1>
        <animspeed1><nrof1><type1><object2....>

        Sends item information to the client.  All parameters are sent as 4
        byte ints, except for name, anim, animspeed and (in the case of the 
        item2 command) type.

        The item1 command is an extension of the item command.  It includes
        additional fields.  It has replaced the item command, which is no
        longer detailed here.

        location is where the object is located (0=ground, any other value
        means is the tag of the object (either player or container)).  This
        value is sent as 4 bytes. 

        tag is the item tag - unique for each item (however, a tag might
        be resend, to tell the client to update some object.)

        flags are various flags on the item (curse, applied, etc).  They are
        detailed in newclient.h   It is 4 bytes

        weight is the weight of single one of these objects (in grams).
        The client will need to figure the total weight on its own.

        face is the face number.  These are not guaranteed to be the same
        across different runs of the game (however, in reality, they will
        only change on the one server if they make changes to the archetypes
        and rebuild.)  Some face information will be sent from the server
        to the client before actually sending a face number.

        name is the name of the object.  The first byte of this field is the
        text length of the name.  Starting at SC 1024, this name is two
        strings, with a null seperation.  The first byte (length) is the
        length for both of these strings.  This name information is just
        the information of what the object is called.  It does not include
        how many of the items there are.

        anim:  This is the animation sequence id to use.  It is 2 bytes.
        The server will send an 'anim' command for this before sending an
        item1 command with this anim command.

        animspeed:  How often the object should be animated.  This is 1
        byte, and is the number of ticks that should pass between each
        animation (a value of 1 means it should be animated every tick.)
        1 byte limits this to once every 255 ticks - I can't see anything
        being animated slower than that.

        nrof:  How many objects comprise this item.  This is used for
        the name field and calculating total weight.  It is 4 bytes.

        item2 is an extension, and adds the following information:

        type: A numeric type id for the item.  The only meaining of this
        value is really for sorting - all armors will have type values
        the same or near that each other.  The client is free to ignore
        this. This value is 2 bytes.

S->C: upditem <flags><tag><vals>+

        This updates some item (of tag) with new values.  flags determines
        what values are sent and to be updated (for a definition of the flag
        values, see the UPD_ flags in newclient.h file.)  The order of the
        vals is the same as in the item command - however, as additional
        values are added (and the <flags> extended), the order will remain
        the LSB order of the flags - that is, the value associated with bit
        1 set is sent first, then bit 2, etc.

        The format of the values is same as the item command above.

        Only one item can be updated with the upditem command.  An item
        command should have been sent by the server before an upditem
        command is set.

S->C: delitem <tag1><tag2>...
        Tells the client to delete items with the tag values.

S->C delinv <tag>
        Tells the client to delete items carried in/by the object <tag>.
        <tag> is sent as plaintext numbers.  Tag of 0 means to delete
        all items on the space teh character is standing on.  This command
        only affects the inventory of the object.  To fully delete a
        container object, a delinv followed by a delitem should be issued.

S->C addspell <tag1> <level1> <casting time1> <mana1> <grace1> <damage1> <skill>
        <path1> <name1> <display name1> <message1> <spell2 ....>
        Tells the client to add the spell(s) listed to the list of spells 
        the client knows about. This will be sent at login, and again whenever
        new spells are sent.

        The fields are;
        <tag> - (4 bytes - int) The ID number for the spell item. This is 
                going to be unique, for each spell and will be used to refer 
                to it henceforth. The string form of this should also be
                appended to the cast/invoke commands in order to cast the spell.
        
        <level> (2 bytes, signed int)
                The level of the spell.

        <casting time> (2 bytes, signed int)
                The time it will take to cast the spell, in server ticks.

        <mana>  (2 bytes, signed int)
                The mana cost to cast the spell (may be zero)

        <grace> (2 bytes, signed int)
                The grace cost to cast the spell (may be zero)

        <damage> (2 bytes, signed int)
                The current damage done by the spell. Note that the meaning of
                this number is to a large part spell dependent, what damage it
                actually does will depend on how the spell works.

        <skill> (1 byte, unsigned int)
                The skill that the spell uses to be cast, if zero, no skill is
                used in the casting of this spell.
                The numbers are the same as for request_info skill_info

        <path>  (4 bytes, unsigned integer)
                The path that the spell belongs to.
                The client should determine the effect of this by comparing 
                these values to both the spell_paths request_info data and the
                stats info concerning attunement/repulsion, etc.

        <face>  (4 bytes, signed int) 
                The number of the face that corresponds to the spell, the client
                can request this facenumber if they want to show a graphical spell
                representation.

        <name> (1 (non-zero) length byte, followed by that many bytes of ascii text)
                This is a name to identify the spell, which the client can use
                for display purposes, it should /NOT/ be used with the 'cast' 
                command, whilst it might work, no such guarentee is made by the
                server. - Use tag instead.
        
        <message> (2 length bytes (which may be zero) followed by that many 
                bytes of ascii text)
                The description of the spell. Note that this has an extra length
                byte because the messages may well be longer than 256 bytes in 
                length.
        
S->C updspell <flags><tag><vals>+

        This updates some spell (of tag) with new values. The flags are 1 byte
        and determine which values have been updated, and should be re-read. 
        Not all fields may be updated by this command, only those that can be
        changed.

        If new fields are added in future, they will extend the flags bitmask
        and the order will remain the LSB order of the flags - that is, the 
        value associated with bit 1 set is sent first, then bit 2, etc.

        The format of the values is same as the addspell command above.

        Only one spell can be updated with the updspell command.  A spell
        command should have been sent by the server before an updspell
        command is set.

S->C delspell <tag>
        Tells the client to remove its information about the spell Tag is a 4 
        byte value, the same as the one sent when the spell was added.

******************************************************************************
COMMANDS RELATING TO THE PLAYER OBJECT/STATS

S->C: player <tag><weight><face><name>
        All fields are the same as described in item above.  The only
        difference is that player tells the client that this is the central
        object it needs to care about.

S->C: stats <stat1><val1><stat2><val2>...  
        The is a server message that tells the client values of the various
        stats.  All values are binary.  that <stat> values are listed in the
        newclient.h file.  All the values sent are 16 bits with these
        exceptions:  
        -weight limit:
                data is 32 bits.  
        -speed, weapon_sp is converted to an int first by multiply by
                FLOAT_MULTI (as defined innewclient.h) and then sent as 
                32 bits.  
        -range, title are sent as strings with their length preceded.  The
                length is 1 byte.
        -experience: If the client uses the 'exp64' setup flag, this is sent
         as 64 bit data, otherwise, 32 bit data (with appropriate loss of
         information.  To make tracking of this easier, a different stat
         type is used for 64 bit data (CS_STAT_EXP64) compared to 32 bit -
         thus, the client can know what to do based on stat type.  However,
         for the run of the session, either CS_STAT_EXP64 of CS_STAT_EXP will
         get used, never both.

        -skill experience:  this is only set if exp64 is set.  This is sent
         as the skill level, followed by the skill exp (thus, 9 bytes + 
         the stat type byte)

        -spell paths: if spellmon is set in setup, the bitmask of attuned, 
         repelled and denied paths is sent. These are all 32bits

******************************************************************************
COMMANDS RELATING TO IMAGE INFORMATION TRANSMISSION

S->C: anim <num><flags><face1><face2>...
        Informs the client of an animation sequence.  The client is responsible
        for animating the objects in the inventory window, and upditem
        and other items command will refer to the animation number with
        num above.  All values are 2 byte binary values.

        <num> is the animation number we are defining.  The server will only
        send the anim command for a particular <num> once per run - the
        client needs to keep track what has been sent.  On new runs,
        anim commands will be resent.

        <flags> is currently unused, but is included because I think there
        may end up being cases were more about the animation than just the
        num and faces are needed.

        <face1>... is the various faces that comprise the animation
        sequence.  The number of faces can be determined by checking the
        length of the packet.  These values correspond in the same
        way as all referances to face do.

        Note that how fast the object is animated is contained in the
        item commands.

S->C: pixmap <face><len><data>
        Sends xpm version of an image to the client.  All data is in binary
        form (4 byte for face & len).  <face> is the face number.  <len> is
        the length of data, and <data> is the xpm data itself.

S->C: bitmap <face><fg><bg><data>
        Sends a bitmap version of an image to the client.  <face> is the face
        number (4 bytes), <fg> and <bg> are 1 byte, and determine the
        foreground and background colors.  <data> is 72 bytes of data.
        (Images are 24x24, but you get 8 bits/byte, so 24*24/8 = 72)

S->C: image <face><len><data>
S->C: image2 <face><set><len><data>
        Command added in SC version 1023.
        This command is much the same as the pixmap command above. face
        and len are 4 binary bytes.  Data is the png data used to
        the image.

        If the client has requested a specific faceset, then the
        image2 command will be used.  This includes the faceset the
        image belongs to (8 bit data).

        There is no image1 command.  Image2 was used to keep the versionin
        in sync with the face2 command below.  It is also more intuitive
        as in the server, the image2 flag is used to determine if we are
        using these new commands.

S->C: face <num><name>
S->C: face1 <num><checksum><name>
S->C: face2 <num><setnum><checksum><name>
        Informs the client that <num> (binary short) is associated with
        <name>.  This is used when the client is caching images.  In normal
        operation, when the server runs accross a face that it hasn't sent
        the client, it sends a pixmap or bitmap for that face.  If the face
        mode is none, the server then sends this command.  The client can
        then check to see if it might have cached this face, and if not,
        should then request it from the server.  Note that the num to name
        mappings can change between server and different runs of the
        server.  For this reason, this data needs to be sent each
        time run.  The client should be able to load/determine what face
        to load via the name.

        In sc version 1026 and later, the server will use the face1 command
        which include a checksum that is a 32 bit value.  This can be used by
        the client to know if its face is up to date.  The checksum is a 32
        bit unsigned value.  If the client reports a sc_version of 1025
        or earlier, the server will use the face command not not face1.

        The face2 command is used if the client has sent used the
        faceset setup command.  This is the same as the face1 command,
        except we also include what faceset the image belongs to.  This
        lets the client has multiple image sets installed and still
        be able to cache properly.  setnum is 8 bit binary data.

C->S: setfacemode <val>
        This tells the server what type of display mode the client is using.
        <val> is a plaintext integer.  0=no faces, 1=bitmap, 2=xpm (pixmap).
        3=png (added in CS version 1022)
        If the 5'th bit is true (ie, 0x10 & val is true), that then informs
        the server that client is caching the images, and only send image
        names.
        This command is depreciated, as the only type of images currently
        supported is PNG.  The client should instead use the setup command
        to request if it wants to cache images or not.

C->S: askface <num>
        Requests that the server send the client face <num>.  It will rely
        on the previous set facemode to determine what facetype to send.
        num is a plaintext integer.

S->C: smooth <facenbr><smoothpic>
        All parameters are short int in binary form (2 bytes each)
        This command informs the client on how to smooth a face, when it will need it.
        Following are the facenbr of the picture involved in the
        smoothing algorithm. See doc on smoothing on how to use them.
        This info may be send automatically from server if client has
    smoothing enabled but may also be requested by client using
    the asksmooth command below
C->S: asksmooth <facenbr>
        Parameters is a plain text integer.
        Ask server to send a smooth sequence. Server will respond with a smooth command.
        <facenbr> is an integer telling server which face we want smooth informations on.

******************************************************************************
MAP UPDATE COMMANDS

S->C: map <ecell1><ecell2>...<255>[<face1><cell1...><face2><cell2...>]
        Sends a map to the client.  All cell type values are stored as 
        x*mapy+y. Thus, we can fit the map coordinates into 1 byte up to
        a mapsize of 11x11. (this size is limited by needing to set
        the high bit)

        <ecell1><ecell2>... is a list of cells that are empty.  This list
        could be empty.  255 is used to mark the end of this list, whether
        anything is included or not.  Note that the max xy hash value is
        121, so we never need to worry about this value appearing as a map
        cell.

        the face values are 16 bit values representing the face for that
        space.  Like other data, they are stored MSB first.  The MSB of
        the last face in a layer has the high bit set.  this makes the max
        theoretical face number that is supported to 32767 (old code says
        16383, but that certainly does not seem right).  It would seem that
        a marker of 0xff could be put at the end of a layer, and only cost
        a byte, but at present, that doesn't seem really important.

        <cell1...> is a list of cells that use this face.  The last face in
        this list has the high bit set.  Being the max cell value is 121,
        this does does not pose a problem.  This cell list is only for the
        current layer.

        The section in brackets ([]) represent data that is sent for each
        layer.  At present time, only 3 layers are supported, but in theory,
        any number could be.  It is up to the client to detect the end of
        one layer, and know to put the next information a layer down.

        Note:  The server does try to do some intelligence in only sending data
        that has changed and packing repetative data.  Thus, the server doesn't
        send a full map each tick, only a portion of the map.  Worst case
        data scenario right now is roughly 1100 bytes of data sent (a very
        unlikely scenario - it assumes 3 images per space and no redundant
        images.

        Note: The map command may get depreciated and instead replaced by
        the map1 command below.  While the map1 command needs 2 bytes for
        coordinates, it is smarter for other updates, so may not in
        face use more bandwidth.

S->C: map1 <coord1>[darkness1][face1a][face1b][face1c]<coord2>[darkness2][face2a]...
S->C: map1a <coord1>[darkness1][face1a][face1b][face1c]<coord2>[darkness2][face2a]...

        This is an update of the map command to support large map sizes.
        The old map command supported a maximum map size of 15x15 -
        anything larger than that required a new command.

        Given that this larger map now needs 2 bytes for the coordinates -
        the same as for the images, trying to optimize one vs the other
        does not makes much sense.

        The map1a is an enhancement to the map1 command.

        All data is in standard binary form.

        the coord values are flags + x + y values.  The value itself, but
        the data represented looks like this:
        first 6 bits: The x coordinate
        next 6 bits: the y coordinate
        last 4 bits: MSB - true if we send darkness
                     MSB-1 - will send floor face
                     MSB-2 - will send intermediate face
                     MSB-3 (aka LSB) - will send top face

        6 bits is enough for 63x63 maps.  For the time being, it should
        be a safe assumption that we won't be sending anything larger
        than that.

        Through the use of this bitmasks, any and all of the following values
        may be optional.  This allows the update of one face on the space
        without needing to send the others (in the old map command, this is
        not possible, so as an arrow flies over a space, the floor + arrow
        needs to get resent - this allows just the arrow to get sent).
        This should conserve bandwidth when spells are cast (we have an
        extra byte for the coordinate, but save 2 bytes for the image
        itself, plus another 2 potential bytes if there is something on the
        space.)

        If all the flag values are 0, this then means the space is considered
        blocked from view, and should be drawn as black.  This conserves
        bandwidth for sending blocked spaces, which occur pretty frequently.
        Once a space is marked as block, if it re-appears within view, the 3
        layers should be marked is blank.

        For spaces that are empty, one or more of the faces will be sent as
        blank faces (exactly how many will depend on what was on the floor
        before - for example, if a floor disappears, then only the floor needs
        to get updated, but if there was stuff on the floor, then that face
        will also need to get cleared).  There may be cases where
        transitioning from the blocked to empty space occurs, in which case
        the server will send the floor as an empty space.

        The darkness value is a single byte - 0 is pitch black, while 255 is
        fully illuminated.  It is up to the client to figure out what it wants
        to do with this (use masking to reduce visibility, or actually do a
        real light reduction on the image).

        The face values are 16 bit values, as before.  They will be sent
        in MSB order of the flag (ie, floor, then intermediate, then
        top, presuming the bit in the flag is set that says that layer
        is being sent).  Blank faces may get sent if an object disappears -
        in the example of the flying arrow, for the space the arrow
        leaves, a blank face will be sent in place of the arrow.  Blank faces
        will be sent as face 0.

        Map1a refinements:

        The main addition to the map1a command is handling of big images.  Big
        images are those images that do not fit in one space, eg, if a store
        is combined into 1 64x64 image, this falls into a big image.  The
        archetype/object of a big image has the same face for all the spaces.

        When the server detects such an object, it only sends the face for the
        lower right corner.  The client then needs to extrapolate where this
        should be drawn.  By only sending the lower right, the client can much
        more easily handle tall objects.  The sending of a big image face is
        no different in either the map1 or map1a command.

        The main difference in the map1a command is what to do when the lower
        right corner would not normally be visible to the client (blocked,
        darkness, or off the edge of the map).  The map1 command will just not
        send any data - thus, even if some part is visible, it won't be sent.
        The map1a command will send this big face for such squares even if
        that square is not visible.  It only sends this information if some
        other part of the object is visible (eg, top portion).  Also, for such
        spaces, it only sends the big face number, and not any other faces
        that may be on that space.  The map1a command will also send
        coordinates outside the normal map size.  For example, the player
        selected a 25x25 map size.  There is a big image (3x3) whose left side
        is just at the edge of the players map (upper corner of it at 25,18).
        The server will send this face at 27,20 - the lower right space of
        this big image.

        The server tries to keep the same layer for the head as what appears
        on the map.  Thus, a 2x2 store would normally be on layer 2 (with
        layer 1 being the grass, stone, whatever).  In such a case, even if
        the lower right corner was not visible, it will send the big face at
        layer 2 on that space.  There can be spaces in which a big image is on
        different layers on different spaces - in that case, if the lower
        right is visible, the layer it appears on there will be used.
        Otherwise, the layer of the first visible space it appears on
        (starting from upper left) will be used.

        The server does remember the heads for out of normal map bounds.
        However, these values are not shifted but cleared when the map scrolls.
        Taking the example of an image at 27,20 above, if the player moves to
        the east, the server will send the map scroll command, send the face at
        26,20, and send neither a clear nor update for 27,20.  When the player
        moves east again, the image is now on the normal map at 25,20, and
        will once again get sent, no delete for 26,20 will be sent.
        OTOH, if the object was a living object and was partially off the
        map when killed, an update removing that face for the object it was
        standing on will be sent by the server.
                
        Various notes about the map1 command:

        this implementation is much simpler than the map command
        because it now works on spaces rather than layers, and most all the
        code also works on spaces.

        The downside of this is that this will need to get redone
        if we want to put more than 3 faces on a space (as we are then
        out of bits).  It would be trivial to do something different, like
        send as many faces as desired and just have a marking tag at the
        end - the problem with this is that if something changes,
        then once again, you need to send the entire space as there is
        no way to say 'face xyz has disappeared'.  And in any case, to
        support more faces will require more work on the server.


S->C: map2 <coord1><len1/type1><data1><len2/type2><data2>...<coord2>

        NOTE: THIS IS ONLY A PROPOSAL.  This is not currently implemented.
        Mail has been sent to the mailing list

        This is an update of the map1 commands above.  It is meant to be
        extensible.  It is also meant to incorporate the ideas of the
        extended map info command.

        All data is in standard binary form.

        The coord value is 16 bites.

        the coord values are length + x + y values.
        The data represented looks like this:

        first 5 bits: The x coordinate (0-31)
        next 5 bits: the y coordinate (0-31)
        last 6 bits: the number of type/data pairs to follow (0-63).  While
        a limit of 63 data encodings is hard coded, I can't forsee reaching
        that limit anytime soon - remember, this is the number of type/data
        pairs that are sent for this space - there could be cases where there
        are 300 things on the space, but if we are only sending 63 of them
        this is also fine.

        <len/type> This is a single byte of data.
        This describes the data that is to follow.

        The top 3 bits (len) denote the number of bytes that follow - it is
        possible that this is zero, to denote all the relevant information is
        included in the type.  If this is 7 (all bits set) then the following
        byte is an additive length value.

        The bottom 5 bits is the type of data - this allows for 31 different
        types of data (0-31/0x0-0x1f).  The meaning of the data itself depends
        on what the type is.  List of various types:

        0x0: Denotes this space should be cleared.  Length in this case should
        also be zero, as there is no data that follows.

        0x1: Darkness information - typically a single byte follows that
            denotes how dark the square is.

        0x2: Sound?

        0x10-0x17: Image information - 2 or 3 bytes follow, which is the image
            for the particular layer.  Layer 0x10 is the lowest, 0x17 is the
            highest.  If 3 bytes follow, the first byte is smoothing
            information, followed by 2 bytes for the face.  If only 2 bytes
            follow, then this is only the face.  The number of bytes that
            follow is determined by the len field above.

        Some notes:
        
        Coordinates outside the viewable map may
        be sent.  In these cases, it means that a big image that extends onto
        the viewable map is on that space.  For big images, only the bottom
        right coordinate is sent - this is why it may be off the viewable
        coordinates.  For such spaces, only the actual big image itself will
        be sent for that space.

        Note that unless the 0x0 code to clear the space is sent, all
        operations are considered updates to the space (eg, new image, new
        light level, etc)

        Relative to the map1/map1a commands, this is more bandwidth intensive -
        basically, an additional byte is needed for each piece of data sent.
        Thus, on a 25x25 map, if we presume 1.5 objects/space, this is
        an extra 940 bytes to send.  OTOH, typically the entire map
        is not being sent - only those bits that change, so this may not
        be as costly as that.

        If the player is using smoothing, this may actually save bytes,
        as the redundant coordinates and type/length information
        does not need to be sent.  With the map2 command, the mapextend
        command is deprecated and is not used.

        
S->C: map_scroll <dx> <dy>
        This tells the client to scroll the map dx and dy direction.  dx and
        dy will typically be -1, 0, or 1, depending on how the player moved.
        <dx> and <dy> are sent as plaintext.  positive values are down and to
        the right respectively, negative values are opposite.

C->S: mapredraw
        Requests that the server resend the entire map to the client -
        can be useful if the client or client player knows that the map
        is out of date/corrupted.

S->C: newmap
        This tells the client to clear the map state. This command will be sent
        only if negotiated by the newmapcmd option.

S->C: magicmap <width> <height> <px> <py> <data>
        This gives the client information from a magic map command.
        <width> <height> and text integers of the size.  <px> <py> is
        the players location, and data is binary data of the
        appropriate color.  It is 1 byte per space, with the low
        nibble containing the color information, and the high nibble
        containing extra flags, like the existance of walls and floors.
        See the FACE_FLOOR and FACE_WALL values.
        The string of data represents the space from left to right,
        then up to down.

C->S: toggleextendedinfos <string1> <string2> .... <stringn>
        Ask the server to send some additionnal informations about the map.
        This command is followed by 1 or more strings. String are separated
        with spaces. Each string toggle an info. The server will respond
        with the command ExtendedInfoSet telling client what actual
        extended infos will be send to the client.
        Valid extended infos are as follow:
                smooth
                        send smoothlevel informations to the client.

S->C: ExtendedInfoSet <string1> <string2> .... <stringn>
        Tell client what actually are the extended infos server may
        send to the client when this is needed. All those infos will
        be related to the map and send through mapextended command.
        Each string represent an info which is enabled. Look
        at toggleextendedinfos and mapextended for details.
        
S->C: mapextended <what><length><coord1>[data1a][data1b][data1c]<coord2>...
        This command is send from server when there is at least
        1 ExtendedInfo activated using toggleextendedinfos and
        the client called setup extendedMapInfos 1 (see setup command).
        Basically this command is made of a block telling what infos comes
        with this command, a block telling what length this info is and then
        the infos themselfes. Here is described more in details those blocks.
        <what> (uses N bytes)
                How to know N?
                In each byte, if the highest bit (bit 7) is set, this mean
                another byte will follow. This would allow easy extension of protocol
                without breaking client and needing a new command.
                Here is described, for each byte, the signifiance of the bits:
                Byte 0:
                        bit 0 EMI_NOREDRAW
                                        Tells the client it's useless to redraw screen immediatly,
                                        another map command will follow.
                        bit 1 EMI_SMOOTH
                                        Tells the client there is datas in the [datas] blocks about
                                        smoothing.
                        bit 7 EMI_HASMOREBITS
                                        Tells the client to read the next byte as part of the <what>
                                        block too. See above signifiance of higher bit.
        <length> (uses 1 byte)
                A one byte info describing the size (in bytes) of each data block. So
                each data block may have a size of 0 to 255 bytes. Note that all data blocks
                send in one mapextended command have the same size but different
                mapextended commands may have different blocksize, even with same datas
                present.
        Following is a set of blocks made of a <coord> and 0 to 3 <data>
        <coord> (uses 2 bytes)
                This is the same as for the map1 and map1a commands, except the darkness bit
                is reserved for future use. If it is set to 1, the next byte will be part
                of the coords too (for larger visible map, but not used yet).
        <data> (uses <length> bytes)
                the coord block tells the client which square is concerned and which layers
                in this square are concerned. According to this there may be up to 3 <data>
                blocks following the <coord> block (same as for map1 and map1a). Ok, now
                what stand in those <data>?
                First each <data> block has a length determined by the <length> block. So
                if ther are parts of the data the client may not understand, it's ok, he will
                skip to the end of the <data> block, jumoing to the next. Should help add
                additionnal informations. Since the protocol evolved as on timeline basis.
                If a client can't understand a data type cause it is too old, he won't
                understand the next one too, etc, until the next <data> block is reached.
                So to prevent problem, the server take care to put informations in the data
                block following the order of protocol evolution. If server need to
                say to the client A BB C, assuming that A was defined in the
                protocol before BB was defined which was before C was defined, it would say
                ABBC and never ACBB. Now let's say later a developper want to extend BB to BBB,
                the server should put the datas in the following order: ABBCB  cause the last B
                is more recent in protocol than the 2 first BB and the C. All this make sure
                there will be no mistakes or conflict between different protocol versions.
                Ok, following is the informations which may be present in a <data> block if
                the corresponding flags are put.

                if EMI_SMOOTH is present in <WHAT>
                        1 byte telling the smoothlevel of the object at <coord>
                                see developper notes on smoothing to know what this means. (TODO)

                <data> stops here for now. Later there will be datas for sending text from
                a specific location, telling client to play special effects, etc.
                gime some time
                                                                        Tchize.


******************************************************************************
SOUND RELATED COMMANDS:

C->S: setsound <val>
        <val> is a plaintext integer.  Current supported values are 0 and 1.
        0 says that the client does not want sounds, 1 says it does want
        sound information.  By default, the server does not send sound
        information.
        Note that the player can use the 'sound' command once the game
        is started to control future sound transmissions.  However, if 
        the client was not started with sound support, the necessary
        initialization of the sound device might not have happened.
        However, if the client started with sounds enabled, the user can
        certainly disable future sounds.

S->C: sound <x><y><num><type>
        Informs the client to play a sound.  All arguments are binary data.
        x,y are signed 1 byte values which are offsets from the player.
        num is the sound number stored as a short (16 bit).
        (IT is up to client to determine which sound to
        play based on that.)  Since sound numbers seldom change (and in fact,
        new sounds will have a higher number than the old sounds - old
        sounds numbers will not change in meaning like what can happen with
        the images), this should not be much of a problem.
        type is a 1 byte value which determines sound type.  Currently, 0
        is normal sound, 1 is spell sound.  This may be extended in the
        future.

******************************************************************************
MISC COMMANDS:

C->S: lookat <dx> <dy>
        Client (player) is looking at space dx,dy.  dx and dy are delta
        offsets from the player (client doesnt know where the player is
        on the map, so this is the only real way to deal with it.)  dx
        and dy plaintext integers.  This is only a request to the
        server - a response will typically come back in drawinfo commands.

C->S
S->C: setup <option1> <value1> <option2> <value2>
        Client first sends a setup command to the server to request a change
        in some value (option1).

        The following options are supported:

        sound
            Set to true if the client wants to get sent sound information.
            This is an integer in string form (0/1).

        exp64: If true, client can handle the 64 bit exp values that
            are now used.  Otherwise, values are sent as 32 bit.  Setting
            this flag also means that skill exp will be sent, and it will
            be sent in revised method as described in the stats command.
            Value is an integer in string format.

        sexp (send skill experience):
            Obsolete - was used to denote that client wanted skill exp
            sent.  Under revised skill system, this info just doesn't
            exist anymore in the same form.

        map1cmd: parameter is an integer in string form like above.
           this requests the server to use/not use the map1 protocol
           command.  Note that if the map size is greater than 11 in either
           direction, the server will use the map1 protocol command no
           matter what.  This parameter can be useful if the client wants
           the map1 protocol command for smaller maps because of the
           the additional information provided.
           Note that the server will return the mode it will be using
           when it sends back the setup command, and not necessarily
           what the client requests.  Thus, if the mapsize is 15x15,
           and the client does a 'setup map1cmd 0', the server will
           send back a 'setup map1cmd 1' because it will still end up
           using the map1cmd due to the map size.

        itemcmd (1/2):
            Defines the revision of the item command that will be used to send
            information about objects. If set to 1 (the default) item1 commands
            will be sent. If set to 2, item2 commands will be sent. This may in
            future accept extra values beyond these two. 

        darkness (0/1 value):
            If set to 1 (default), the server will send darkness information
            in the map protocol commands.  If 0, the server will not
            include darkness, thus saving a minor amount of bandwidth.
            Since the client is free to ignore the darkness information,
            this does not allow the client to cheat.  In the case of the
            old 'map' protocol command, turning darkness off will result
            in the masking faces not getting sent to the client.

        mapsize x X y
            Sets the map size to x X y.  Note the spaces here are only for
            clarity - there should be no spaces when actually sent (it
            should be 11x11 or 25x25).  The default map size unless changed
            is 11x11.  The minimum map size the server will allow is 9x9
            (no technical reason this could be smaller, but I don't think
            the game would be smaller).  The maximum map size supported in the
            current protocol is 63x63.  However, each server can have its
            maximum map size sent to most any value.

            If the client sends a mapsize command out of valid range, the
            server will respond with a mapsize with the maximum size
            the server supports.  Thus, if the client wants to know the maximum
            map size, it can just do a 'mapsize 0x0' and it will get the
            maximum size back.

            The server will only set the mapsize for the client if both x & y values
            are valid.  For example, if the maximum map size is 25x25, and the
            client sends a 31x23 mapsize request, the mapsize will remain at
            11x11 (default) and the server will send back a mapsize 25x25
            setup command.

            When the values are valid, the server will send back a mapsize
            XxY setup command.  Note that this is from its parsed values,
            so it may not match stringwise with what the client sent, but will
            match 0 wise.  For example, the client may send a 'mapsize 025X025'
            command, in which case the server will respond with a
            'mapsize 25x25' command - the data is functionally the same.

            While the server in theory supports non square viewing regions,
            this has not be tested.

        newmapcmd (0/1)
            This tells the server if the client understands the newmap
            protocol command.  This is used by the client in the fog
            of war mode to receive newmap commands from the server each time
            the player changes maps.

        facecache (0/1)
            Determines if the client is caching images (1) or wants the
            images sent to it without caching them.  This replaces the
            setfacemode command.

        faceset (8 bit)
            Faceset the client wishes to use.  If the faceset is not
            valid, the server returns the faceset the client will be
            using (default 0).

        extendedMapInfos (0/1)
                Toggle sending from server of extended map informations.
                What lies in this extended info depended on what extended
                infos the client asked. See ToggleExtendedInfos command for details.

        extendedTextInfos (0/1)
                Toggle sending from server of extended text informations.
                What lies in this extended info depended on what extended
                infos the client asked. See toggleextendedtext command for details.

        spellmon (0/1)
            If set to 1 the client has indicated that it wishes to be
            sent the spell list and updated when it changes.

        All data in the setup command is in ascii text form.  options and
        values can not have whitepace - the client and server use whitspace
        to split the options and values.

        Currently (2001-05-28), the server only sends a setup in response to
        client first having sent a setup command.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
This section describes the requestinfo and replyinfo commands.
Because these commands may handle different types of data with different
return formats, this section is formatted a bit differently to make
it easier to read the different structures.

C->S: requestinfo <info_type>[options]
S->C: replyinfo <info_type>[options]<data>

    The requestinfo command is a general purpose way for the client to request
    some piece of data the server may have.  The server still needs to be
    coded to respond to the specific info_type, but if the passed info_type is
    not supported, the server will still respond with the replyinfo, but with
    an empty data list.

    This mechanism allows the client to send requests for data and not need to
    do complicated checking if the server would understand the specific
    request - if the server understands it, the data gets sent back.  If the
    server doesn't understand it, the client gets no data, but does get the
    replyinfo so that it knows that the server does not support that
    particular aspect.

    Only one info_type is allowed for each requestinfo.  If the client
    requests many pieces of information (say image sets available, spell
    listings, etc), it should send multiple requestinfos.

    [options] is specific to the info_type - it could be a range of values, or
    empty.

    Requestinfo requests will not change any data on the server - the setup
    command should be used for that.  The requestinfo just requests data.
    Note that since the requests can be made before a player logs in, the
    requestinfo command will not generally support getting information related
    to the player object.

    The following info_types are supported:

    image_info:
        'image_info' (no options):

        Request basic image information the server has.  The data is sent in
        text format - the replyinfo is newline terminated.  Since the packet
        length is sent in the header, that is used to figure out the length of
        returned data.

        Line 1: The last image number the server has.  Note that there is
        no image 0, so this also amounts to the number of images
        if you start counting from one.

        Line 2: checksum of all the image name information.  This can
        basically be used to determine if the number to name mapping is
        the same, eg, if on server 1 the total is 123456, and the player
        goes to server 2 and the total is the same, we can say with a high
        degree of confidence that the name to number mappings are the name.
        If instead the numbers differ, we know we can't rely on using the
        same mappings.

        Line 3+:The image set information the client has.  The format
        is the same as the format in the image_info file, sans comments.
        The server will ignore any parameters the client sends.

        An examply response:

        replyinfo image_info
        3512
        1169234
        0:base:standard:0:32x32:none:The standard image set.
        1:clsc:classic:0:32x32:none:Classic and new styling.


    image_sums <start> <stop>

        Request the image number to name (and checksum) values - in this way,
        the client can build all images before play starts and also request
        any missing images.  The returned data is

        image_sums <start> <stop> <imagenum><checksum><faceset><namelength><name>

        There is an initial space after the stop value, but no spaces after
        that point.  The <start> and <stop> values are ascii text (same
        format as it is sent to the server in).  The start and stop
        values are inclusive - thus, if the start is 0 and the stop
        is 100, 101 checksums will be set.

        imagenum is 16 bit binary data.
        checksum is 32 bit binary data.  It contains the checksum for
        the image in the current selected set, and will use whatever
        fallback logic the imagesets specify.
        faceset is 8 bit binary data.
        namelength is 8 bit binary data.  It is the length of the
        name field below, including the null terminator.
        name is chraracter data.  It is null terminated to make processing
        easier - in this way, the client doesn't need to copy the data
        to make it null terminated.

        Note that due to possible OS system constraints on the maximum single
        write supported to a socket, the complete set can not be requested at
        once - instead, the images information should be requested in blocks
        of less than 1000.  The server will not process a block larger than
        1000 at a time.  Smaller blocks may be desired if the client wants to
        try to reduce the potential lag caused.

        Multiple requests for all the information can be sent at once, as the
        server will buffer the response data, but constraints prevent the
        server from sending the entire data back in one replyinfo (one being
        that the data would be beyond 65535 bytes, so the length information
        in the packet would not be accurate.)

        If the client sends invalid data (stop is less than start, missing
        stop paremeter, stop is beyond the number of images, or asking for
        more than 1000 at a time), the reply will just be an empty list.

        Note that the server will track that it has sent the face
        information for the requested images, and thus will not send
        it again (unless requested via requestinfo).  Thus, this
        request should always do the right thing with the
        returned information.

    skill_info (no parameters)
        This returns the skill number to skill name mappings.  In this
        way, new skills can be added in the server, and the client 
        can use this new skill information with no changes to the code.

        All data below is in text format.  Format is:

        stat number:skill name

        Where stat number is the number that will be used to send
        that skill information.  Example:
        141:lockpicking
        142:hiding
        143:smithery

    spell_paths (no parameters)
        This returns a list of all spell paths in the game, along with the
        number associated with them. This should be used to parse spell_path
        data in the stats command. The number is a bitmask but is sent as a 
        decimal value.

        All data is sent in text format. Format is:
        
        number:name
        
        eg
        
        16:missiles

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

Example Session:

The client first opens a connection to the server.

S->C: version 1001
C->S: version 1001

 The client/server are exchanging version information, to verify that
they can both properly communicate with each other.  If there is 
a mismatch, one or both of the sides might close the connection.


C->S: setfacemode 2

 The client is informing the server that is wants to use XPM images.  Note
that setfacemode is an optional command - if the client wants to live with
the default (XPM) mode, it doesn't need to send this.

C->S: addme
S->C: addme_success

 Client is informing the server it wants to be added to the game.  Server
is telling client that the command has succeeded, and it will then
be added.

NOTE: I am not sure if this is the exact order of the next few commands,
since a whole bunch of stuff is being done at once.

S->C: pixmap (All that the map command uses wil lbe sent.)
S->C: map (display starting town map.)
S->C: stats (display default character stats)
S->C: drawinfo (display motd)
S->C: query (get player name)
C->S: reply (return player name)
S->C: drawinfo (inform player to enter password)
S->C: query (request password)
C->S: reply (return player password.)

 At this point, things could deviate two ways - player could be
starting a new character, in which case, numerous draw infos, query's 
(stat rolling), replys, stats (change stats that were just
rolled), map updates (player changing clasS) could be sent.  However,
we will assume that the player actually entered the proper password
and an existing character is rejoining the game.

Once again, I am not positive this is the correct order or not.

S->C: player (send player object.)
S->C: stats (send player stats)
S->C: pixmap (assuming on different map and we haven't sent some of
                the images before)
S->C: map (map player was saved on)
S->C: pixmap (assuming we have not sent image for item before)
S->C: item (item in players inventory or where he is standing)


After that is established, a loop is established that typically will result
in these commands being sent at various times:

S->C: stats - to inform the client when stats go up or down.
S->C: map_scroll (when the player moves)
S->C: map (update after map_scroll, or when player changes maps.)
S->C: pixmap/bitmap (with maps commands) to update faces.
S->C: drawinfo (Tell about hitting creatures, applying, etc.)
S->C: item (tell what objects are in players inventory, or space he is standing
        on.
C->S: command (general commands, like north, fire, cast, etc.)
C->S: apply (applying and object.)
C->S: move (moving and object)
C->S: examine (examine an object.)

S->C: query (keypress for shop listing, some other areas)
C->S: reply (from last query)

------------------------------------------------------------------------------
Programming Notes:

 These are a few quick notes on how things work.  Note that they really
only apply to the code in the standard distribution, most of the direct
i/o is handled by functions that are talked about.  IF writing a client
from scratch, you will need to port this over (or write your own - it
isn't very complicated.)

 For the server and the C client, a SockList structure is used for basic
data handling.  Basically, this is just a structure that has an unsigned
character buffer and a length field (which contains the length of data in
the buffer, not the actual buffer length.)

 As a side note, when sending a packet, you can supply the length of the
data and the sending routines will take care of sending the 2 bytes of
length information.

 When getting a packet, these 2 bytes are at the start of the buffer and
not removed.

 There is a file called newsocket.c - this file is shared between the`
client and server distribution, but except for the SockList data type,
it could probably be used by itself.  The newsocket.c file contains
some routines to pack ints, shorts, and single chars into SockList
structs, as well as functions for the reverse.  IT also contains a 
function to send socklists, as well as read them.  The Add??? functions
increase the len field of the socklist, the Get??? functions do not
change the pointer in anyways.  Thus, to get and int and move the buffer,
you do something like:
   int = GetIntString(data); data+=4
As a side note, if you malloc the data for the buffer, make sure to free
it when done.

 There is also the newclient.h file which is shared between the client and
server.  This file contains the definition of the SockList, as well as
many defined values for constants of varying means (ie, that in the
stats command, a stat value of 1 is hit points, etc.)  When porting to
a new system, you will need to grab these constant values for yourself.

 A few other notes:
 The item command lists the weight for an individual item of that type.  It
thus becomes the responsibility of the client to parse the name to see how
many there are, and then multiply the weight by that nrof for an accurate
value.  This should probably be changed, with the item command including
an nrof, with that being removed from the string we send.  Also, the client
is responsible for computing the weight of containers, and thus the player
itself.

------------------------------------------------------------------------------
Image caching:

 Image caching has been implemented on the client, with necessary server
support to handle it.  This section will briefly describe how image
caching works on the protocol level, as well as how the current client does
it.

 First, the client checks for an option denoting the image caching
is desired.  If so, we initialize all the images to a default value - this
means we don't need to put special checks into the drawing code to see if
we have an image - we just draw the default images (I use a question mark
pixmap, since that makes it very easy to see what stuff is cached.)  We
also initialize an array which will hold the number to name mapping so
that when we actually get the image, we know what filename to store it
as.

 Second, we request the server to do image caching.  This is done
by oring the cache directive to the image mode we want.

C->S: setfacemode 18

 Then, when the server finds an image number that it has not send to the
client, it sends us a name command information us the number to name mapping:

S->C: face 65 CSword.115

 Note that this is not exactly how the send - the number is actually send
in binary form, and there is no space between that the and the name.  Such
formating is difficult here, but the above example illustrates the
data is sent.

 The client then checks for the existence of the image locally.  Note that it
is up to the client to apply any extensions based on display type (ie,
add .xpm or .gif or whatever.)  The current client stores images in
~/.crossfire/images, and then splits them into sub directories based on
the first 2 letters - in the above example, the file would be 
~/.crossfire/images/CS/CSword.115

 If the client does not have the image or otherwise needs a copy from the
server, it then requests it:

C->S: askface 65

 The server will then send the image via the normal bitmap/pixmap
routines. 

S->C: pixmap <data>

Because the pixmap/bitmap routines do include the image name,
we must store the name & number mapping someplace before sending the
askface.  I just used an array of character pointers, so then in
position 65, we do a strdup of the name, store it, then use it when
the pixmap/bitmap command comes in, and free that data.

 Also, the client does occasional redraws of all data if it has received
new images and is running in cached mode.  Otherwise, the map can remain
out of date indefinately (although, once the player moves, things will get
redrawn.)

 This has the effect that first time running in cached mode, performance
will actually be a little bit worse for the client (after all, it needs
to still request all the images, but isstill doing pretty constand redraws
of the data.)  But times after that, performance is greatly improved.

------------------------------------------------------------------------------
Changes:

This area documents changes in the protocol version and what happened between
them.  Note that this is not a complete list, as the setup command
is used to control many cases.:

CS version 1022 -> 1023: just to sync version with server

CS version 1021 -> 1022: Client supports sending of verbal image type
questions.

SC version 1022 -> 1023: Server supports sending png images (addition of
image command).

SC version 1023 -> 1024: Server will send two part names (described in
item command) which contains the singular & plural form of the name)

SC version 1024 -> 1025: Support for sending all resistance
values in the stats command.

SC version 1025 -> 1026: Add face1 command that includes the image
checksum.

SC version 1026 -> 1027: Add requestinfo/replyinfo commands - client
can check this to know if it should expect a replyinfo to its requestinfo.

------------------------------------------------------------------------------
Todo:

 It probably makes more sense to do a more preemptive handling of socket
events.  That is, instead of sleeping 120 ms, then checking all the 
sockets, we do a select on all the file descriptors with an appropriate
sleep time.

 If we get input, we handle it at that time if the player has an action.  In
this way, instead of handling all the actions after sleeping for the 120ms,
we can instead spread them out more.  Only when the 120ms expire do we
then do all the actions like move the monsters, regenerate HP, etc.

 The only potential problem I see with this right now is that select will
return immediately if there is data on the socket (player has used up all
their time, are paralyzed, etc.)  This would probably mean that the server
needs to do internal buffering, which complicates things some.  The
potential advantage with this is that we could peek at the data, and
if the command is not a player action (ie, maybe requesting an image, or
a misc command like who), we could still execute it.  Actually, we can
get around the select problem by only adding the file descriptors from
sockets that actually have time to perform actions.

 It probably also makes sense to look at the map at the end of each tick
and determine what needs to be sent (same for the look window.)  If a player
is moving really fast (speed > 1), they could in theory move 2 spaces in
1 tick - what is the point then of sending a map and the items for the space
the skip over quickly?

 However, what might also make more sense (but becomes a bit more complicated)
is adjust the players speed by these smaller amounts.  Thus, if the player
has speed of 2.0, every (half a tick) we add 1 point or something.  What
might be smarter is if we do set up the sleep system above, then anytime
we get an event that we see how much time has passed and increase all the
players speed by that amount.  Thus, if a player is running, they will move
whenever they have proper speed - this may make things feel a bit snappier.
Revision:	1.3
Committed:	Thu Sep 7 21:42:50 2006 UTC (17 years, 8 months ago) by pippijn
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.2:	+0 -0 lines
State:	*FILE REMOVED*
Log Message:	Moved documents to doc/historic