MXP over UDP Specification Draft 0.4One of the MXP over UDP key concepts is to have a small set of UDP messages concentrated on connectivity, transport and distributed virtual environment scene graph synchronization which form the core of the protocol. All application specific information is transmitted as payload over the core UDP messages encoded in MXMP format. MXMP is designed to be XML but defined only to skeletal level as it is application specific in nature. Another key concept is to multiplex all the data (except binary assets) through one UDP port to simplify the session handling and networking like firewall and nat penetration. Each UDP packet may contain one or more frames. Most messages will have length of just one frame. All coordinates are always given in the coordinate system of the sending party. Bubbles can be referenced with the following URI type: mxp://<address>:<port>/<bubble-name>/<location> or with default values: mxp://<address>/
Changes
TODO for Next Version
Byte orderinghttp://en.wikipedia.org/wiki/Endianness Little-endian byte ordering is used. Floating Point EncodingThe IEEE Standard for Binary Floating-Point Arithmetic (IEEE 754) is used for floating point encoding. http://en.wikipedia.org/wiki/IEEE_754-1985 Universally Unique Identifier Encodinghttp://www.ietf.org/rfc/rfc4122.txt Typesdouble: signed 64 bit float udouble: unsigned 64 bit float float: signed 32 bit float ufloat: unsigned 32 bit float long: signed 64 bit integer ulong: unsigned 64 bit integer int: signed 32 bit integer uint: unsigned 32 bit integer short: signed 16 bit integer ushort: unsigned 16 bit integer string: UTF8 encoded string byte: unsigned 8 bit integer uuid: 16 byte Universally Unique Identifier time: 64 bit timestamp. How to encode?
data: Binary data. If data consists of binary encoded primitive values then they should be encoded as defined here. Data may also contain for example XML-fragment. UDP Packet DataUDP packet data length is maximum of (1500-48(IPv6))=1452 bytes which consists of header bytes and as many frames as fit in the remaining bytes. PACKET packet header (14 bytes) - message frames (mxa 1438 bytes) PACKET HEADER 4 : uint : session_id /* Session id assigned by answering party. */ 4 : uint : packet id /* Id of the packet. */ 4 : time : first send time /* Time the packet was sent for the first time. */ 1 : byte : quaranteed /* Whether this is guaranteed and ACK is expected. */ 1 : byte : resend count /* Count of resends. */ Message Frame (maximum 256 bytes)Largest message data sizes are limited to by maximum frame count and frame data size to ~15Mbytes. Could this protocol be used for transmitting larger amounts of data on background? If so another message type can be specified for large file transfers where each message transmit part of the file. MESSAGE FRAME frame header (10 bytes) - frame data (maximum 246 bytes) FRAME HEADER 1 : byte : type /* Type index from message type table. */ 4 : uint : message_id /* Message id assigned by the sender. */ 2 : short : frame_count /* Number of frames in this message. */ 2 : short : frame_index /* Index of the message part for long messages spanning over multiple packets. */ 1 : byte : frame_data_size (0-245) Connection Control MessagesACKNOWLEDGE 1 (not quaranteed) 1-64 X 4 : uint : acknowledged_packet_id /* Repeated 1-64 times */ KEEPALIVE 2 THROTTLE 3 4 : uint : transfer_rate /* Bytes per second sender is ready to receive */ Implementation Validation MessagesCHALLENGE REQUEST 4 64 : data : challenge_request_data CHALLENGE RESPONSE 5 64 : data : challenge_response_data Reusable FragmentsRESPONSE FRAGMENT 4 : uint : request_message_id 1 : byte : failure_code // 0 == success PROGRAM FRAGMENT 40 : string : program_name 1 : byte : program_major_version 1 : byte : program_minor_version 1 : byte : protocol_major_version 1 : byte : protocol_minor_version 4 : uint : protocol_source_revision OBJECT FRAGMENT 16 : uuid : object_id /* Universally unique identifier of the object. */ 4 : uint : object_index /* One based index to table of objects known to bubble. */ 16 : uuid : type_id /* Type id of the object. */ 16 : uuid : parent_object_id /* Universally unique identifier of the parent object or empty uuid. */ 20 : string : object_name 20 : string : type_name 16 : uuid : owner_id /* Owner participant id. */ 12 : vector3f : location 12 : vector3f : velocity 12 : vector3f : acceleration 16 : vector4f : orientation 16 : vector4f : angular_velocity 16 : vector4f : angular_acceleration 4 : float : bounding_sphere_radius 4 : float : mass 4 : string : extension_dialect 1 : byte : extension_dialect_major_version 1 : byte : extension_dialect_minor_version 4 : uint : extension_length X : data : extension_data INTERACTION FRAGMENT 20 : string : interaction_name 16 : uuid : source_participant_id 16 : uuid : source_object_id 16 : uuid : target_participant_id 16 : uuid : target_object_id 4 : string : extension_dialect 1 : byte : extension_dialect_major_version 1 : byte : extension_dialect_minor_version 4 : uint : extension_length X : data : extension_data BUBBLE FRAGMENT 16 : uuid : bubble_id 40 : string : bubble_name 51 : string : bubble_asset_cache_url /* Url for accessing binary assets for bubble objects. */ 16 : uuid : owner_id /* Participant who owns the bubble. */ 40 : string : bubble_server_address 4 : uint : bubble_server_port 12 : vector3f : bubble_center /* This is expecetionally given in receiver coordinate space. */ 4 : float : bubble_range 4 : float : bubble_perception_range 4 : time : bubble_realtime CommandsParticipant to Bubble CommandsJOIN REQUEST 10 16 : uuid : bubble_id 40 : string : bubble_name /* empty bubble name means default bubble */ 32 : string : location_name /* this could be parsed by human interface from uri */ 32 : string : participant_name 32 : string : participant_passphrase 4 : time : participant_realtime 51 : string : identity_provider_url /* for example OpenId provider url */ PROGRAM FRAGMENT : client_program JOIN RESPONSE 11 RESPONSE FRAGMENT 16 : uuid : bubble_id 16 : uuid : participant_id /* id of the participant if join was succesful or empty id. */ 16 : uuid : avatar_id /* id of the avatar if it was injected by daemon or empty id. */ 40 : string : bubble_name 51 : string : bubble_asset_cache_url /* Url for accessing binary assets for bubble objects. */ 4 : float : bubble_range 4 : float : bubble_perception_range 4 : time : bubble_realtime PROGRAM FRAGMENT : server_program LEAVE REQUEST 12 LEAVE RESPONSE 13 RESPONSE FRAGMENT INJECT REQUEST 14 OBJECT FRAGMENT INJECT RESPONSE 15 RESPONSE FRAGMENT MODIFY REQUEST 16 OBJECT FRAGMENT MODIFY RESPONSE 17 RESPONSE FRAGMENT EJECT REQUEST 18 16 : uuid : object_id EJECT RESPONSE 19 RESPONSE FRAGMENT INTERACT REQUEST 20 INTERACTION FRAGMENT: request INTERACT RESPONSE 21 RESPONSE FRAGMENT INTERACTION FRAGMENT: response EXAMINE REQUEST 22 16 : uuid : object_id 4 : uint : object_index Either object_id or object_index will be set to default value. (uuid default==empty uuid=="0000-000....") EXAMINE RESPONSE 23 RESPONSE FRAGMENT OBJECT FRAGMENT Participant to Bubble and Bubble to Bubble and CommandsLIST BUBBLES REQUEST 25 1 : byte : list_type /* [0=attached,1=hosted] */ LIST BUBBLES RESPONSE 26 N X BUBBLE FRAGMENT Each fragment is in separate frame. Bubble to Bubble CommandsATTACH REQUEST 30 16 : uuid : target_bubble_id BUBBLE FRAGMENT (source bubble) PROGRAM FRAGMENT (source bubble server) ATTACH RESPONSE 31 RESPONSE FRAGMENT BUBBLE FRAGMENT (target bubble) PROGRAM FRAGMENT (target bubble) DETACH REQUEST 32 DETACH RESPONSE 33 RESPONSE FRAGMENT HANDOVER REQUEST 34 16 : uuid : source_bubble_id 16 : uuid : target_bubble_id OBJECT FRAGMENT HANDOVER RESPONSE 35 RESPONSE FRAGMENT EventsPERCEPTION EVENT 40: an object has been observed for the first time or modified OBJECT FRAGMENT DISAPPEARANCE EVENT 45: Object disappears for another reason than ejection. 4 : uint : object_index MOVEMENT EVENT 41 (not quaranteed) 4 : uint : object_index 12 : vector3f : location 16 : vector4f : orientation ACTION EVENT 60: Object acts in a way which does not affect other objects. 20 : string : action_name 16 : uuid : source_object_id 4 : float : observation_radius 4 : string : extension_dialect 1 : byte : extension_dialect_major_version 1 : byte : extension_dialect_minor_version 4 : uint : extension_length X : data : extension_data HANDOVER EVENT 53: Object was handed over from one bubble to another HANDOVER REQUEST SYNCHRONIZATION BEGIN EVENT 70: Bubble is starting to send full set of perceptions from objects in range. 4 : uint : object_count /* this is approximate perception count to be expected for progress estimates */ SYNCHRONIZATION END EVENT 71: End of synchronization. Event CandidatesCOMPRESSED MOVEMENT EVENT 42 (not quaranteed)
N X {
4 : uint : object_index
6 : vector3f : location
4 : vector3b : orientation
} /* N=1-12 (One message can contain 1-17 movement perceptions)
This event is optimized for social 3d environments with size of ~1000 meters and accuracy of 6 centimeters. Environments with similar accuracy requirements can use this message as well. This message is one third of the size of MOVEMENT EVENT. compressed location = range * location / (bubble observation radius) compressed velocity = range * velocity / (bubble observation radius) compressed orientation = axis angle with unit vector with components scaled to +-max value. Angle is presented in +-180 degress scaled to +-max value. Total size 14 bytes + ~1 byte from all headers per message => total of ~15 bytes per compressed movement message. 1740 Views |
