CMSI 698 SS:NVE Summer I 2004 - The Protocol

Message Format

The protocol used for our NVE project is one designed to operate over both a stream and a datagram oriented protocol.

Each message begins with one or more bytes specifying the length of the current message. This length is encoded using the UTF-8 variable-length encoding scheme treating the length as the codepoint to be encoded. This means that lengths of less than 128 are encoded as a single byte. The length field contains the number of bytes following the lenght field, but does not include any bytes that make up the length field itself.

Following the length field, there is a 1 byte type field specifying the type of the message. For unknown types, implmementations MUST ignore the message and SHOULD log a notice with at a minimum the type of the message that was unknown and the sender of the message.

It is important to note that a length of 0 is legal and would not be followed by a type field. This scheme enables arbitrary padding to be inserted into the message stream or block.

Changes and updates for Milestone III are noted like this.

Defined Message Types

There are 256 possible type fields, this is the current set of type assignments. The contents of each type field are documented below.

Basic Entity State Message (Type 1)

The Basic Entity State message type (BES) provides a minimal rigid body channel of data. There are 8 data fields, all in network byte order.

Message Length: 29

Hello Message (Type 2)

This packet serves to announce the existence of a client to a Zone Manager. It SHOULD be sent once upon client initialization. This will open the floodgates of data from that zone manager to the transmitter of this message. It intentionally has no 'content' other than its type.

Zone Managers MUST treat the sender of this message as a 'locally connected' client and add it to the database of clients for future updates. Zone Managers MUST NOT rely solely upon Hello Messages, which are easily lost, to manage additions to the local client set.

This message SHOULD NOT be forwarded by the Zone Manager across a peer link (it would have no meaning if done so)

Message Length: 1, no data bytes

Heartbeat Message (Type 3)

If a client has no reason to transmit within any given 30s period, it SHOULD use this to ensure that its zone manager does not drop the client from its list of local clients. The zone manager would have to miss three consecutive heartbeats to incorrectly drop a still existent but relatively inactive client.

Message Length: 1, no data bytes

Goodbye Message (Type 4)

If a client is shutting down, it SHOULD transmit a goodbye message to enable the Zone Manager to remove it from the list of local clients. Upon recipt, a Zone Manager SHOULD flush (delete) any outbound queue of messages destined for this client and MUST remove it from its list of local clients.

To minimize network utilization, when changing from one Zone Manager to another Clients SHOULD send this Message once they have positive confirmation that the new Zone Manager has begun transmitting messages to the client.

Message Length: varies

Zone Announcement Message (Type 5)

This MUST be the first message sent by the connector to a connectee when establishing a TCP session with another Zone Manager. When received, the Zone Manager replies with its own Zone Announcement for itself using all zeroes for the port, and protocol fields, and zero address bytes.

Message Length: varies, typically 33

Zone Query Message (Type 6)

This is a query for all zones that have jurisdiction over the given point in the space. The special query of the origin (0,0,0) performed over TCP is a request for all known zone managers to be transmitted.

All Clients MUST issue this query to the Zone Manager given at application initialization. They MUST specify the coordinates of any Entities that the Client wishes to control will begin at. Clients SHOULD NOT transmit any location-dependent (i.e. Entity Specific) details to a Zone Manager not responsible for the Entity's location (as listed in the Zone Query Response Message).

All Clients MUST NOT use the global zone manager unless there is no other Zone Manager available for the location of an Entity under its control. In such case, Clients MUST re-query the Zone Manager at least every 300 seconds but not more often than every 60 seconds for new Zone Managers available for Entities under their control. All Clients using a global Zone Manager MUST respond to unsolicited Zone Query Response Messages as though they were solicted.

When multiple Zone Managers are available for a given Entity Location, Clients MUST first choose those that are completely nested within all other candidates. If candidate Zone Managers are overlapping and not nested, Clients MAY use whatever algorithm they desire to optimize Zone Manager selection.

Message Length: 13

Zone Query Response Message (Type 7)

In response to a Zone Query, a Zone Manager will compute all known zones managers that have jurisdiction over the point in the query and reply with a ZQRM containing the zone boxes and address information for those zone managers.

Message Length: varies, typically 1+32n

Entity Model Query Message (Type 8)

This is a general purpose query requesting that the model details about the given entity be transmitted. This message SHOULD be sent in the same packet as another more important message (e.g. BES), if possible, to reduce network overhead.

The Version Held field is used to support caching. Each Entity Model Announcement contains a version number which SHOULD only be updated when the entity's model changes. If a client has reconnected to the system, it SHOULD use the version held field to inform the sender what version of the model is currently held so that needless retransmits do not have to occur.

Upon recipt by the owner of the named entity, a Model Announcement Message MUST be sent and an Entity Model Message (if appropriate) SHOULD be sent, provided the Version Held is not the latest. Entity owners SHOULD delay announcments for a short period of time (not to exceed 5 seconds) in case multiple requests arrive that can be satisfied simultaneously. Entity owners SHOULD send along an Entity Detail message as well for the benefit of those needing model data.

This message SHOULD NOT be transmitted to query details of an Entity which is beyond the reasonable view of a client. Conversely, this message SHOULD be transmitted whenever necessary to support the display of an Entity within a client's field of view.

Message Length: 11

Entity Model Announcement Message (Type 9)

This message contains the information about where an entity's model may be found. One or more format/length/url fields may be transmitted and identify where the model may be downloaded in a variety of formats.

An SMDv1 format model MUST be provided and MUST be the first URL in the list.

For Entities with Model Type 0 (see Entity Model Detail Message), an Entity Model Announcement MUST be transmitted at least every 300 seconds, and in response to Entity Model Query Messages, as appropriate.

Message Length: varies, minimum 23

Entity Model Message (Type 10)

This is a simple way to disseminate small, crude models (less than 200 polys) within the NVE protocol. The data is in the SMD format which supports more than 200, however it MUST NOT contain a model larger than 200 polygons. This has a nice side effect of guaranteeing that the model fits in at most 3 ethernet frames in all but the most degenerate cases.

Message Length: varies, MAX 4415

Entity Detail Message (Type 11)

This message is very infrequently transmitted. Ideally not more than once every 120 seconds. It contains lots of infrequent or unchanging details of an entity and its associated model.

This message MUST be transmitted at least once every 300 seconds.

Clients controlling entities SHOULD transmit this upon initial connection to the system in the same packet as their initial BES message. Whenever possible, this message SHOULD be included with another more important message rather than being sent in its own packet.

The entity title is a utf8 encoded string which MUST be at least one character long and MUST NOT begin or end with any whitespace. This message MUST be sent whenever the entity's title changes. The title is a useful text string identifying the entity.

All applications controlling an Entity MUST provide a means to set, and modify without restarting, the Title attached to the controlled Entity.

There is no currently specified maximum time between transmissions of this message. It provides valuable information that implementors ought consider for inclusion along with any Entity Model Announcement message.

Message Length: varies, min 59, max 165

The entity class field provides some overall categorization information to clients about what sort of entity is being dealt with. A primary entity is the main entity being controlled by an active user agent. A secondary entity is an entity being controlled by a user agent, but not necessarily the one that represents the user themselves (e.g. a backpack being worn). A ground surface entity is one that is a ground surface mesh (nearly invariant terrain, e.g. a hill). A fixture is an object that is not natural terrain, but not someting that is easily or commonly moved (e.g. a door). Finally, an interactive entity is terrain that may move at any time and for extended periods of time (e.g. a ball, a chair, a table).

It is important to note that an entity's class may change at any time.

Entity Class Field

Model Type Field

The Model Type field is used to inform the client what type of model should be used to render the entity. Type 0 means that a custom model unique to this entity is provided by an Entity Model Announcement and/or Entity Model message. Type 1 is a 1m x 1m x 1m 75% Grey cube, with an origin centered on the entity's position. All other entity types are reserved.

For Entities with Model Type 0, an Entity Model Announcement MUST be transmitted at least every 300 seconds, and in response to Entity Model Query Messages, as appropriate.

Time Of Day Message (Type 12)

This Message specifies what the current simulation 'time' is for those clients displaying environmental effects.

In graphical clients, between the simulated hours of 'night', (18:00 - 06:00), illumination could be dimmed and the 'sky' could be blueish-black. During dusk/dawn the sky could be lighter, while during the day (08:00 - 16:00) the sky could be bright and blue.

For non-graphical clients wishing to display time, an inexact measure SHOULD be used. Since time will not necessarily change uniformly, exact representations SHOULD be avoided. Good: Sun/Moon clock approximating time of day. Bad: Digital HH:MM:SS clock. Good: Analog clock face with Hour and minute hands. Bad: Analog clock with Hour, Minute and Second hands.

Message Length: 3

Articulated Entity State Message (Type 13)

The Articulated Entity State messages contain articulation details about an Entity and serve as the Articulated Body Channel of information.

All Clients controlling an Entity MUST use this message to transmit Entity information to the Zone Manager. Messages for Entities without articulation vectors are effectively the same as a BES message.

Zone Managers MUST NOT forward AES Messages across peer links. They MUST convert AES messages to BES messages for forwarding.

Transmission Schedule

This message MUST be transmitted at least according to the following schedule based upon Entity Class (see Entity Detail Message).

Clients MUST NOT timeout an Entity from its local database until three times the maximum Entity State transmission period has passed. If the Entity Class is unknown, Clients MUST assume a base period equal to the largest currently defined or 120 seconds, whichever is larger.

Message Structure

Message Length: 29 - 539

Entity Control Request Message (Type 14)

An Entity Control Request Message is a request that temporary control of an Entity be transferred to the owner of a Primary Client Entity.

Control may only be requested for Secondary Client Entities and Interactive Entities.

Message Length: 21

Entity Control Grant Message (Type 15)

An Entity Control Grant Message transfers temporary control of an Interactive or Secondary Client Entity to a Primary Client Entity. As long as a Client has control of an Entity it does not Own, the Controlling Client MUST consider it to be a Secondary Client Entity when determining update periods. All other Clients MUST continue to consider the transferred object to be of the same class as the class has not, in fact changed.

Owners of a controllable entity (secondary client and interactive class) MUST respond to ECRMs with either a Grant or a Revocation message.

After the given number of milliseconds has elapsed, the right to post AES messages for the given Entity is revoked and a Client MUST NOT transmit further messages implying control over the object. A Client MAY submit a subsequent ECRM in order to extend and/or shorten the transfer of control.

A Client MUST continue to maintain responsibility of an entity until its ownership duration has expired and/or an ownership revocation message is received.

Message Length: 21

Entity Control Revocation Message (Type 16)

Owners of a controllable entity MUST send this message to terminate control of an Entity or to reject a request to control.

Controllers of an Entity MUST stop transmitting Entity updates upon receipt of this message even if the duration of the original grant has not yet expired.

Message Length: varies

Collision Message (Type 17)

This message SHOULD be sent whenever any Entity under your control collides with another object. This message MUST NOT be sent regarding any collisions not involving an entity under your control (for that see the Promiscuous Collision type).

Clients receiving this message with an entity under their control listed in the 'Their Entity ID' field SHOULD verify whether a collision occurred and then react accordingly.

Clients receiving this message regarding entities not under their control who are not doing n-way collision detection SHOULD treat the collision as though it were detected locally at the given time.

Message Length: 53

Promiscuous Collision Notification Message (Type 18)

Clients MAY transmit this message if they are performing n-way collision detection and they notice a collision involving an entity not under their control.

Obviously, clients MUST NOT transmit this message unless they have a legitimate reason to believe the collision occured where and when the message says.

Clients who receive this message regarding entities under their control and who are not performing their own collision detection SHOULD use them to recognize that a collision has occurred.

Message Length: 59

Collision Denial Message (Type 19)

If a client has received either a Promiscuous Collision Notification or an ordinary Collision notification message regarding an entity under its control, and the client has reason to believe that a collision has not, in fact occurred, it SHOULD use this message to inform the rest of the NVE participants of that fact.

Clients receiving this message MAY use the information in it to update their local model and advise their prediction algorithms.

Message Length: 71

Message Message (Type 254)

The Message Message is a simple text message which SHOULD be logged and MAY be displayed to the user.

Message Length: varies, minimum 1

Error Message (Type 255)

The Error Message is used to signal some sort of fault in the system or in the client detected by the other end. There are two code fields, whose contents are as yet undefined. The text message MUST be displayed to the user and SHOULD be logged if appropriate.

Message Length: varies, minimum 3

Version: 1.7