Hover Carnage





Mailing List


Hosted by Sourceforge

RFC 424242

This file describes the protocol used in Hover Carnage for communications
between the client and the server. This RFC (though not the protocol)
is modelled very loosely after the DNS RFC (?number?).
			(Copyleft '((Reverse(C)) MattHelsley 2000))

Oh this RFC is incomplete. What's more, it's not really an official
RFC. Don't go asking any standards organization about RFC 424242!

This RFC assumes that all packet formats have been converted to host
endian from network endian. Any other significant endians will be 
mentioned where necessary.

The Server:
    Is responsible for AUTHORATATIVE simulation of the physics,
    management of game state, and player statistics.

The Client:
    Is responsible for providing the user with an interface to
    the server.

The client and server communicate over a datagram protocol known
as UDP. They build on the knowledge the designer gained at UCLA in
his networking course work with the Duh(tm) protocol- so this protocol
should be relatively plain/simplistic.

On top of the datagram protocol, a simple connection protocol is
required. The protocol does not ensure reliable or sequential
delivery, only reliable connections/disconnections.

    Like streaming sound from internet servers, the nature of the
data is such that if out of order data is received, chances are that
the older data is no longer of use to the user.

    Dropped packets are another problem which must be dealt with.
However, there are many instances where dropped packets consume more
time to recover than is allowed.

     While the protocol itself does not claim to be reliable, it is
important to note that in the interest of remaining syncronized with
the server, the protocol does define "snapshots". These snapshots
are guaranteed by the protocol to be reliably delivered. Snapshots
are sent from the server to the client, but not vice versa. Only
acknowledgements to the snapshots are guaranteed by the client.

The connection handshake is the standard 3-way handshake:

	client		server
	------		------
	  5		  5
SYN	  1-----_____     5
	  1	     ---->1 SYN     -\
	  1     _____-----1 SYN/ACK --+- handle_connect()
SYN/ACK	  4<----          1
ACK	  4-----_____     1
	  4          ---->4 ACK
	  4               4
	  4		  4

If a message other than SYN/ACK is received by the client, it is
assumed that there is a version mismatch between the client and
server. Specifically, if the message sent is a DIE message, then
the connection attempt failed for some reason other than a network
error (only reason as of this writing is DIE_VERSION_MISMATCH).

SYN/ACK packets contain the following information:

Protocol Version
	The protocol version is composed of two fields. The high order 16
(host endian) bits is the interface number. It describes what interface
version the sender of the SYN can handle. The low order 16 bits are the
revision number. These reflect changes in the underlying code base, but
do not relfect protocol compatability information.
   Both parts of the protocol version are not generally usefull to code
which is not concerned with following the protocol. While the version
may be furnished to higher level abstractions, it is generally advised
that the version numbers not be changed from that compiled into an
implementation. (i.e. don't mess around with the version numbers, or
you could be sorry)

	The ack_num field of the SYN/ACK packet allows the packet format
to double simultaneously as a SYN and an ACK. On packets that are
purely SYN packets, this field indicates the TCP port number where
non-realtime traffic can be obtained. Use as a TCP port number is only
valid during the construction phase of a connection.

The disconnection by the client is:

	client		server
	------		------
	  4		  4
SYN	  1 ----_____     4
	  1	     ---->1 SYN
	  1     _____---- 1 SYN/ACK-\
SYN/ACK	  1<----          1          |
ACK	  5 ----_____     1          |
	  5          ---->5 ACK      > MAX RTT
	  5               5          |
	  5		  5	     |
	  5		  5        _/

Disconnection by the server merely lacks the originating SYN
packet from the client.

The server sends a client messages in one of 3 cases:

1) A differential change from the last state needs to
   be conveyed.
2) A snapshot needs to be sent.
3) Other data is being sent.

Bytes are 8 bits long. Refrain from using the "word" concept,
since "word" is a platform dependent term.

Each packet has the following header:
|  msg   | sequence number| ..

The header is 3 bytes long. The remainder of the packet
follows immediately after the sequence number. The remainder
of the packet is a:
   1. SYN/ACK
   2. DIE
   3. ACK
   4. DIFF
   5. SNAP

The first 4 bytes are the protocol version field.
The last  2 bytes are either a sequence number (in the
case of a SYN/ACK), or a port number (in the case of a SYN).

| Interface Ver|    Revision     |
| Ack/Port Num |

The die format is sent from the server when an attempted
connection fails. A die packet contains one additional field
beyond that of a header:
|             Reason		 |

The reason field allows the client to report to the user/higher layer
the reason the server refused to accept the connection. Currently,
3 possible reasons are:

1) VERSION_MISMATCH - incompatable protocol versions encountered.
2) MAX_PLAYERS      - no more clients are being allowed as players.
3) GOT_DAH_BOOT     - you got "dah boot" cuz you was bad!

Despite its limited use, an ACK format has been defined.
An ack simply contains the sequence number following that
of the packet it is acknowledging.

| Sequence Number|

This is one of the two most important packet formats when it
comes to realtime traffic. As such, this is probably where most
of the code revisions and interface changes are likely to occur.

| Snapshot ID  XX| Chunks | Offset |
|      Chunk Value (32 bits)	   |
|  Object Flags  |
|       Linear  Force I (optional) |
|	Linear  Force J	(optional) |
|	Linear  Force K (optional) |
|	Angular Force I	(optional) |
|	Angular Force J	(optional) |
|	Angular Force K	(optional) |
|       New Mass	(optional) |

Chunks of the global bitvector are sent in diff packets.
These chunks record the IDs of the objects being changed.
A bit set at a certain position in the bit vector means that
object is being changed with this diff packet.

Chunks themselves are 32-bits in size.
The first bit set corresponds the the first object in the packet.

Each object is represented by a 16-bit flag field, followed by
a series of 0 or more optional values. The order of the values
will be preserved, even if some are missing.

bit 0: Linear  force component I is present.
bit 1: Linear  force component J is present.
bit 2: Linear  force component K is present.
bit 3: Angular force component I is present.
bit 4: Angular force component J is present.
bit 5: Angular force component K is present.
bit 6: New Mass                  is present.
bit 7: This is a spawning object. Fields are mapped:
       Linear Force -> Position
       Angular Force -> Orientation

A clear set of flags indicate object death. No optional
fields are present.

This is the second of the two most important packet formats relating
to realtime traffic. It is intricately tied with the diff format.

| Snapshot ID |CV|   Vector Size  |
| Vector bits ...
         +-----     --------     -----------     --------     ------+
         | Mass ... Position ... Orientation ... Velocity ... Omega |
	 +-----     --------     -----------     --------     ------+

Snapshot ID - 14 bit number

c           - A single bit indicating that this is a collision snapshot
	      This is exclusive of the V bit.

v           - A single bit indicating if the optional bit vector is 
	      present. This is exclusive of the C bit.

Vector size - Number of bits used by the bit vector.
	      Vectors are a multiple of 32 bits in length, though fewer
	      bits may be used that actually are in the vector.

Vector bits - A bitvector describing which objects are being described
	      in this snapshot.

Mass        - A IEEE 754 floating point number describing the mass, in
	      some "universal" scale (default might be kilograms).

Position    - Absolute position of the object.

Orientation - Absolute orientation of the object.

Velocity    - Absolute velocity of the object.

Omega	    - Absolute angular velocity of the object.