Main

MXP Transport Layer Design 0.6 1.0

Tommi S.E. Laukkanen — 2010-04-18T16:07:50Z

This page will contain MXP 0.6 transport layer design.

FrontPage 7.0 (minor-edit)

Tommi S.E. Laukkanen — 2010-04-18T16:06:32Z

== Welcome == All the content is licensed under Apache 2.0 License unless stated differently. We are looking for more contributors with interest in networked virtual environments, network protocols or 3d graphics. We are especially looking for lead 3d artist to create demonstrative content for reference implementations and examples. Our 3d content format of choice is Collada and preferred tool is Blender. Please leave a message to forums or join us at IRC if you are interested to contribute. Our official IRC channel is #mxp at freenode IRC network. You can join the channel with web IRC [[http://www.bubblecloud.org/irc|here]]. Experience the bubble cloud in the demo world which has been distributed to two different continents (requires Windows Vista (XP not working at the moment) and OpenGL 2.0 compliant video card): **1. [[https://www.myopenid.com/|Claim yourself an OpenID in 1 minute process >>]] ** **2. [[http://code.google.com/p/setp/downloads/list|Join demo world by installing the Cloud Deck >>]] ** <> == Introduction == The goal of this open source project is to define minimal and easy to implement open protocol for networked virtual environments (for example virtual worlds, social 3d environments, online games and first person shooters). Metaverse Exchange Protocol (MXP) is a second generation virtual environment protocol specification. MXP has a coherent theoretical model (Bubble Cloud) for networked virtual environments and proposes a working engineering solution. See [Domain Model] for term definitions. NVEs are in this context systems with multiple thin clients and servers simulating single seamless virtual environment. All parties are upkeeping local partial scene graphs which are synchronized using metaverse exchange protocol. MXP concentrates on messages required for the defined 3d simulation model. MXP specification does not contain application specific concepts but acts as a transport layer for specialized interaction and state data encoded as [Metaverse Structured Data] (MSD). In addition to MSD/MXP there are the following protocol candidates for authentication, asset and inventory access. These additional protocols leverage HTTP as a transport layer protocol. HTTP access to internet is available in most networks without explicit firewall configurations. * Asset and inventory access protocol: [[http://opensimulator.org/wiki/AssetServerProposal/ClientDocs|OpenSimulator AssetServerProposal]] * Authentication protocol: [[http://en.wikipedia.org/wiki/Openid|OpenId]] * Authorization protocol: [[http://en.wikipedia.org/wiki/OAuth|OAuth]] === Why Should I Choose MXP? === MXP protocol solves many challenges of distributed virtual environments to offer the following features: * Unlimited continous virtual environments. * Seamless interoperability between different architectures and vendors. * Space defined by bubbles of limited life time. * Load balancing by overlapping bubbles. * 100% availability for space which is covered by at least two bubbles. * Maximum mobile objects per bubble: in the order of thousands. * Maximum object size: bubble observation radius divided by two. * Maximum object observation range: bubble observation radius. * Enables distributed collision detection and physics governed by participants and/or bubbles. * Enables interactions between objects in linked bubbles. * Enables seamless object handovers between bubbles. * Extension mechanism for objects and interactions to allow application specific functionality. * Existing C# reference implementation with demonstrated cloud mode operation (multiple overlapping bubbles). === Background === The ideas and design principles for MXP originate from internet (see [Background Reading]) and two protocols specifications: [[SETP 0.1 DRAFT|SETP]] and [[http://greenphosphor.com:8080/CICP_v1_spec.pdf|CICP]]. SETP stands for Simple Environment Transfer Protocol. CICP stands for Content Injection and Control Protocol. These protocols are previous work of Tommi Laukkanen and Ben Lindquist respectively. CICP has a public domain provisional patent application which will not be completed to actual patent but is used to provide prior art protection for CICP against future patents. The patent application can be viewed here: [[http://www.cybertechnews.org/downloads/CICP_app.pdf]] //I filed this provisional application in the US on March 14th, 2008. I have deliberately allowed it to lapse and have released all interest in CICP to the public domain. - Ben// === Process === The MXP design process is a simple community process driven through MXP wiki and discussion group. The process details and materials can be found at the end of this page under wiki table of contents. === Datagram Specification === [[MXP over UDP Specification Draft 0.4|MXP over UDP is a detailed specification]] describing how MXP is realized over UDP protocol. MXP could be realized using other transport layer protocols. One 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. All application specific information is transmitted as payload over the core UDP messages encoded in MSD format. Another key concept is to multiplex all the data (excluding binary assets) through one UDP port to simplify session handling and network connectivity. === Reference Implementation === A C# reference implementation of MXP can be found at [[http://setp.googlecode.com/]]. The reference implementation covers all message types and implements functional application interfaces. === Demos === ==== Cloud Demo ==== Cloud demo is a demonstration of bubble cloud model. See videos at YouTube: * Cloud Demo Video 1 - [[http://www.youtube.com/watch?v=jwVBvpwW5L8|YouTube]] [[http://setp.googlecode.com/files/cloud-deck-0.2-mxp-0.5-video-1.wmv|WMV (Better Quality)]] Demonstrated features are: * MXP Protocol ** All Specified Message Types * Cloud Model ** Bubble Linking ** Seeing from Bubble to Bubble ** Roaming from Bubble to Bubble ** Server processes in different continents (Europe and North America) * OpenID Authentication * Collada Model Format ** Basic building functionality with Collada Objects * HTTP Asset Loading * Cloud Administration Web Interface The demo consist of Cloud Deck viewer based on Horde3D and Cloud Daemon which is a configurable server program built on top of the CloudService class. Cloud Daemon can run multiple host processes containing multiple bubbles. Bubbles running in different deployments of Cloud Daemon can be linked and users can roam between them. Authentication is fully OpenID based on both Cloud Deck and web interface. All object models are loaded over HTTP in Collada format. Model textures are loaded with HTTP in their native format. Demo requires user to have a **claimed OpenID**. Google OpenID will not work with roaming as google provided OpenID URLs change for each server domain name. Demo also requires at least Windows Vista due to OpenGL + Windows Forms combination in HUD. Windows 7 has not been tested. In this demo best user experience is currently provided by myOpenID: [[https://www.myopenid.com/]] Cloud Deck can be downloaded from: [[http://code.google.com/p/setp/downloads/list|Downloads]] ==== Bubble Bouncer ==== Bubble Bouncer Interactive Demo is a simple demonstration of MXP reference implementation in action. Multiple users can chat and interact with dynamic spheres according to simple physics model. Clients are connected to server using MXP. Sphere objects are simulated by AI participant which is communicating with the server through MXP: * [[http://www.youtube.com/watch?v=SiO7D_HDJR4|Bubble Bouncer Video 1]] * [[http://www.youtube.com/watch?v=8iS34rxsR8M|Bubble Bouncer Video 2]] === Adoption === Applying MXP to traditional virtual world implementation with region concept is straightforward. Region corresponds to bubble and all MXP messages are directly applicable. This is demonstrated by [[http://www.opensimulator.org/|OpenSimulator]] adoption of MXP. The implemented functionality is an MXP module to OpenSimulator server which adds MXP as additional protocol and similar module to [[http://forge.opensimulator.org/gf/project/idealistviewer/|IdealistViewer]]. The work is ongoing but transmit of prims, terrain and avatars is currently operational. === Interoperability === Interoperability between different virtual world implementations can be realised by supporting MXP protocol and a shared MXP extension like Open Metaverse Structured Data. This enables objects to see and traverse between Bubbles from different vendors. Interactions between objects injected by different participant implementations are a question of common interaction extensions or support for other vendors extensions. It is also possible for participants to interact with objects owned by different software implementations in similar manner. If business transactions are required then existing mechanisms like WebServices should be used. MXP is about virtual environment functionality not reinventing remote procedure calls for online business. === Bubble Cloud Model === Networked virtual environments (Cloud) consist of simulations nodes (Bubble). One bubble has cubic or spherical volume. Bubbles in a simulation cloud do not necessarily form a cubic lattice. Bubbles may be sized and placed using various strategies. Bubbles can overlap. Locations in messages are always presented in local simulation coordinates relative to the center of the source bubble or parent object. Each bubble is linked to coexisting and adjacent bubbles to enable object perceptions, interactions and handovers between bubbles. Client (Participant) is connected to a single bubble at a time which is responsible for routing information from adjacent bubbles. Object is simulated by one bubble at a time even if it is located in shared volume. Handover is a process where object is handed over from one bubble to another in analogy with mobile devices and base stations. {{mxp_bubble_model_architecture.png}} // Illustration of MXP bubble model architecture. // == The Big Picture == MXP protocol is responsible for 3d scene synchronization. There are several other functional areas which are needed to build a distributed virtual environment. This chapter describes these other areas and their relation to MXP protocol. === Identity Management === Identity management, authentication and authorization are well established areas. Identities are managed by open identity providers. Participant identity is represented by OpenId URL. Participant may authenticate to identity provider by any means available. Identity provider hands out OAuth tokens to participant. These tokens are then used to to authenticate to bubbles and other services. Bubbles and other services verify the tokens by invoking verification requests to the identity provider. This process can be optimized by using session authentication where client is authenticated only once per session by validating the one time token against identity service provider. After this the session is trusted. To avoid man in the middle attacks both MXP and HTTP connections should be encrypted. See [[http://en.wikipedia.org/wiki/Openid|OpenId]] and [[http://en.wikipedia.org/wiki/OAuth|OAuth]] for detailed description. User groups are well established pattern for managing access rights for large groups of people. Groups can be succesfully applied to distributed systems by identity providers or specialized group identity providers. Group identity providers persist group hierarcies and member lists. Group identities are exposed as security principals through standard identity provider interfaces. Group identity is similar to user identity all though it is not possible to authenticate directly as a group. These group identities can be bound to access lists the same way as user identities. === Inventory Management === Inventories are analogous to remote file systems with metadata support. Users and groups own inventories where data can be stored. Inventory service can be freely acquired from any compliant provider. Inventory service is not bound to the identity provider or home bubble of the owner. Each user and group can have zero to many inventories. See [[http://opensimulator.org/wiki/AssetServerProposal/ClientDocs|OpenSimulator AssetServer Proposal]] for detailed description of a protocol proposal. {{mxp_service_architecture_3.png}} // Illustration of MXP service architecture. // === Asset Management === Asset management, storage and delivery are challenging from ideological, theoretical and engineering view points. MXP is not an asset delivery protocol. In ideological level it is enough to state that any asset can easily be extracted with a specialized client. Because of this there is no feasible technological way to absolutely protect assets from theft in an open system. MXP currently relies on the same model as world wide web does. If a better model is introduced it will be adopted. In practice this means that assets are delivered to all connected participants by the asset cache of a bubble over HTTP. This allows for bubble to track asset integrity and load balance asset delivery. Original assets are stored in an inventory of user or group. When user creates an object he assigns his own inventory or group inventory as the object home inventory. The assigned inventory contains assets of the object. This inventory is then used by bubble to load the assets to local cache for further delivery to clients. In this scheme the asset distribution is load balanced through bubbles and inventory owners can control spread of their objects by limiting the bubbles which may access the inventory in question. Asset ids are all always assigned by inventories according to the proper UUID generation algorithm which will effectively remove threat of id collisions between assets from different inventories. Defining home inventory to object offers both the object metadata persistent storage location and aggregate asset storage location. Multiple objects can share assets but only inside one inventory. Furthermore this information architecture allows for reference counting and carbage collection inside single inventory provider. It can also be argued that object home inventory elegantly solves problem of asset delivery when object is handed over from bubble to bubble. This is especially true for bubbles from different providers which do not share back end services. It is good to consider supporting identification of assets by traditional urls. Some public asset servers could be www servers or svn http servers. All 3d modeling programs are refering to aggregate assets using file paths. It would be easy to upload the model to SVN http server and then using viewer pull out the model and aggregate assets for viewing. This could be alternative asset distribution model. It could work through bubble asset cache or directly from viewer to the http server. See [[http://opensimulator.org/wiki/AssetServerProposal/ClientDocs|OpenSimulator AssetServer Proposal]] for detailed description of a protocol proposal. ** Asset file format candidates ** * Models and animations: [[http://www.khronos.org/collada/|Collada]] * Textures: [[http://www.w3.org/TR/PNG/|Portable Network Graphics (PNG)]] * Music and sounds: [[http://www.xiph.org/ogg/|Ogg]] {{mxp_big_picture.png}} // Illustration of the big picture. // == Team == In alphabetical order: * Ben Lindquist (Arkowitz) / [[http://greenphosphor.com/|Green Phosphor]] - Founder - Specification contributor * Maróy Ákos / [[http://tyrell.hu/|Tyrell Corporation]], [[http://euedge.com/|EU Edge]] - Specification contributor - Java and C++ lead developer * Mike Kalagan (Moyshe BenRabi) - Python developer - C++ developer * Ryan McDougall / [[http://www.adminotech.com/|Admino Technologies]] / [[http://www.realxtend.org/|realXtend]] - Advisor * Tommi Laukkanen - Founder - Coordinator - Specification contributor - C# developer == Project == # [License] - This work is licensed under Apache 2.0 License # [Contributors] - People who have contributed to this specification == Processes == # [Release Process] - Describes how releases are performed. == Design Rationale == # [Immersion] - Illusion of environment and immersive experience == Design == # [Requirements] - List of requirements for the protocol # [Domain Model] - The key concepts and terms # [Use Cases] - The protocol use cases # [Message Sequences] - The logical message sequences # [Performance] - Performance estimations using simple mathematical models # [Comparison] - Comparison matrix between different MXP versions and other protocols. == Specification == # [MXP over UDP Specification Draft 0.5] - Latest stable MXP over UDP specification version. # [MXP 0.6 Scratch Pad] - Scratch pad for sketching 0.6 version of MXP over UDP protocol. # [MXP Messages Draft 0.6] - MXP 0.6 message layer specification. # [MXP UDP Transport Draft 0.6] - MXP 0.6 transport layer specification for UDP protocol. # [MXP Transport Layer Design 0.6] - MXP 0.6 transport layer design. == Implementation == # [Implementation] - The reference implementation sources can be found at [[http://setp.googlecode.com/]] == Installation == # [MX Tank Installation] - Instructions to MXP demo server installation # [MX Deck Installation] - Instructions to MXP demo client installation == Archive == # [MXP over UDP Specification Draft 0.4] # [MXP over UDP Specification Draft 0.3] # [SETPCICP 0.2 DRAFT] # [SETP 0.1 DRAFT] == Related Articles == # [Background Reading] - Links to articles containing relevant background # [Environment Model] - How virtual environment is modeled # [Advanced Grid Configurations] - Advanced space partitioning schemes # [Reference Architecture] - Example of traditional architecture for networked virtual environment

Comparison 5.6 (minor-edit)

Tommi S.E. Laukkanen — 2010-02-23T16:25:53Z

== Transport Layer Comparison Matrix == |=Feature|=MXP0.5|=MXP0.6|=[[http://enet.bespin.org/Features.html|ENET]]|=[[http://clb.demon.fi/Kristalli/|Kristalli]]|[[http://wiki.secondlife.com/wiki/Protocol|SLUDP]]|[[http://www.jenkinssoftware.com/|Raknet]]|[[http://www.sirikata.com/wiki/index.php?title=Protocol|TCPSST]]| |Connectivity|+|+|+|+|+|+|+| |Optional guaranteed delivery|+|+|+|+|+|+| | |Message assembly|+|+|+|+| |+|+| |Message fragmentation|+|+|+|+| |+|+| |Multiplexing|+|+| | | | | | |Sequencing| |+|+|+| |+|+| |Channels| |+|+|+| |+|+| |Prioritization| |*| |+| |+| | |Congestion avoidance| |*|+|+| |+|+| |Compression| | | | |+|+| | |Encryption| | | | | |+| | |Separated transport layer| |+|+|+|+|+|+| |Open source license|+|+|+|?|+| |+| |Open specification|+|+| |+|+| |+| |UDP support|+|+|+|+|+|+| | |TCP support| |*| |+| |+|+| |C++ Windows support|+|*|+|+|+|+|+| |C++ Linux support |+|*|+| |+|+|+| |C++ Solaris support |^|*|+| |?|?|+| |C++ Mac support |+|*|+| |+|+|+| |Native C# support |+|*| | |+|^| | |Native Java support |+|*| | |?| | | |Native Python support|^|*| | |?| | | |Binding Python support| | |+| |?|+|+| |Browser JavaScript support| |?| | | | |+| |Mature and widely adopted implementation| | |+| |+|+| | '+' Supported, ' ' Not supported, '^' Developed, '*' Planned == Protocol Innovations == === Kristalli === ==== Three Step Connection Handshake ==== The extra last message explicitly allows the server to properly transition from a pending state into an ok state, without having to wait for a timeout to realize if there was a problem. ==== Message Prioritization ==== Prioritization comes into play when is more data to transfer than the channel bandwidth can handle. High priority messages get transferred first and low priority messages need to wait. The priority value manages the order of messages in a priority queue. The priority is a per-message attribute. If a message depends on another message, there is of course no sense in sending it with a higher priority than the previous one, since it would have to wait for a future message to appear to be processed. ==== Message Dependency Instead of Channels ==== Needs elaboration. === Raknet === ==== Optional Guaranteed Delivery with Both ACK and NAK Schemes ==== Needs elaboration. == Protocol Notes == === SLUDP === ==== Connectivity ==== Partial. No connection establishment - only keepalive and disconnection === Raknet === ==== Open Source License ==== OS-like for indie development, commercial for business use. ==== Open Specification ==== Documented on a high-level, can dig up details from sources. No official detailed spec available, and I doubt the company will welcome free implementations along their commercial one. ==== Native C# Support ==== Apparently being ported to a managed assembly, but not official. == Description of Features == === Connectivity === Protocol forms logical connection between peers. === Optional Guaranteed Delivery === Protocol can mark packets not guaranteed so that if dropped they are not resend. Optional guaranteed delivery is something you can do only with UDP you need to be able to mark some of the messages unreliable so that those packets can be dropped by the network when they in flight. This is important for rapid resolving of congestion in the connection. === Message Assembly === Protocol can assemble multiple messages or message parts to single packet. === Message Fragmentation === Protocol can fragment long messages to suitable parts for transport. === Multiplexing === Protocol splits messages to small frames and multiplexes these to packets for fair delivery. In this approach packets are split to small frames having sizes up to for example one tenth of packet size. Example: With messages: * A - 512 bytes * B - 2048 bytes * C - 2048 bytes If the packet size is 1024 then multiplexing feature would cause packets to be something like this: * Packet 1 - A (F1-256) B (F1-256) C (F1-256) A (F2-256) * Packet 2 - B (F2-256) C (F2-256) B (F3-256) C (F3-256) * Packet 3 - B (F3-256) C (F3-256) === Sequencing === Protocol can retain order of the guaranteed packets. === Channels === Protocol supports N-channel approach where channels have independent sequencing. === Prioritization === Protocol supports packet prioritization where low priority packets may be delayed or dropped. === Congestion Avoidance === Protocol has specified and built in congestion avoidance mechanism. It is not enough to leave it as a burden of the application level to manually limit the bandwidth according to metrics. This would require the library user to always implement their own congestion handling to avoid involuntarily jamming the network. Option for application level flow control is required for graceful congestion handling. === Compression === Protocol supports compression of transmitted data. Any kind of compression scheme is enough. For deeper analysis the protocol data bytes/control bytes ratio should be measured. === Encryption === Protocol supports encryption of the transmitted data. === Separated Transport Layer === The transport layer can be used independently of other related implementation like message serialization layer.

MXP UDP Transport Draft 0.6 10.2 (minor-edit)

Tommi S.E. Laukkanen — 2010-02-10T17:26:24Z

<> == Introduction == UDP transport layer implements the specialized MXP transport layer requirements. This is early draft. Please excuse quality of language at this stage. == Requirements == # Protocol should support **connectivity**. # Protocol should support **[[http://en.wikipedia.org/wiki/Congestion_avoidance|congestion avoidance]]**. # Protocol should support **guaranteed delivery** where delivery and order are guaranteed to be retained over the tranmission link. # Protocol should support **signal delivery** where delivery is not guaranteed and out dated messages are ignored. # Protocol should support **multiple channels**. # Protocol should support **fair bandwidth sharing** between signal and guaranteed data transmission. # Protocol should support **fair bandwidth sharing** between individual channels. # Long message should be **fragmented** to frames and send in intervals to avoid congestion. # One network packet should be able to contain many **message frames**. == Changes == == Next Version Tasks == == Functional Layers == === Channel Layer === Channels are useful concept for enabling multiple ordered streams of messages through the same connection. This enables channels to have independent sequencing mechanisms and bandwidth allocation. ==== Guaranteed Channels ==== Guaranteed channels guarantee message delivery and retain the order of messages. ==== Signal Channels ==== Signal channels offer best effort service and discard messages which have lower order index than previously arrived message. In other words the order of accepted messages is retained. === Assembly Layer === ==== Messages to Packets Assembly ==== Messages are divided to one or more frames and assembled to transport packet data section. This is implemented by having a fragmentation list of maximum N (max_messages_fragmented) messages. These messages are being assembled to packets in the same time. When all message frames have been placed to packets then the message is removed from the list and new message is added to the list from pending message queue. ==== Packets to Messages Assembly ==== Message frames are assembled back to messages by reverse process where unlimited number of incomplete messages form an aggregation list. When a packet is received then the frames from the packet are placed to correct messages. New messages are added to the list on demand. Ready messages are removed from the list and queued for further processing. Messages which have one or more frames timed out are removed from the list. ==== Channel Bandwidth Allocation ==== Per channel bandwidth allocation is realized by choosing messages to be sent according to round robin algorithm from different channels. If a channel already has a message in fragmentation list then the channels is ignored on that round. === Transport Layer === Guaranteed messages have to be delivered without any loss. Fraction of the signal messages may dropped without risking data consistency. Guaranteed and signal data are transported in different packets as guaranteed packets need acknowledgements. On the event of packet drop it would be waste of bandwidth to have signal data in the same packet as guaranteed data as both of them would get resent. ==== Acknowledging ==== Acknowledgements are sent in first outbound packet or if there is no outbound packets then empty transport packet is sent after maximum acknowledgement wait window (max_ack_wait). ==== Retransmit ==== If a guaranteed packet is not acknowledged inside acknowledgement timeout (ack_timeout) then packet is retransmitted. Packet is retransmitted maximum N times (max_packet_retransmit). Packet is retransmitted by inserting it as first in the channel outbound packet queue. This enables the retransmits to honor the per channel bandwidth allocation. ** What happens when maximum number of retransmits has occured. Will the connection break or should exponential back off be applied for some number of times before that? If guaranteed message can not be delivered then connection should disconnect in the end.** ==== Ignoring Duplicates ==== Duplicate packets have to be ignored and number of duplicates counted. Reason for duplicates may be either retransmit, network layer error or attack. ==== Congestion Avoidance ==== On connection initialization the up stream (maximum) bandwidth level defaults to specified default bandwidth level. The remote process transmits input (message) buffer fill percentage in packet header. Local process tunes the outbound bandwidth between predefined transmit levels based on packet loss and remote peer input buffer congestion. Quality is measured within sample time window. If the sample window does not achieve predefined minimum quality level then lower bandwidth level than realized bandwidth is selected. If for N sample windows the quality is level is higher than predefined good quality level and realized bandwidth is 9X% of the current bandwidth level then higher bandwidth level is selected. ==== Guaranteed vs Signal Bandwidth Allocation ==== Guaranteed and signal channels share single connection and bandwidth. These channel types are sent in separate packets and the bandwidth allocation is defined in terms of packet ratio. This is implemented in the send loop by trying to send series of N guaranteed packets and M signal packets. If there is not enough packets to send in either type then the other type fills in the missing slot. The default N/M ratio is defined in this specification. In future this ratio may be application specific or dynamic. ==== Keep Alive ==== If no other packets are send inside half of the activity timeout window (activity_timeout) then keep alive packet is transmitted to avoid activity timeout. === Connectivity Layer === ==== Sockets ==== Each peer (process) has one socket which is used to send and receive all information. Incoming packets are tied to connection based on remote address, port and connection id. ==== Connecting ==== Both peers assign connection up stream id unique inside local process. These stream ids together form connection id. Least significant bits of the connection id are the up stream id defined by the initiating peer. Connection is initiated by connection request packet. Connection request is resent N (connect_retry_count) times if connection response is not received in expected time window (connect_timeout). Connection request packet does not have complete connection id. Connection response is paired to connection by remote address, port and up stream id returned in the least significant bits of the response packet connection id. ==== Disconnecting ==== Disconnect is invoked by sending disconnect packet. Disconnect can also occur due to activity timeout (activity_timeout) or protocol error. == Encoding == === Byte Ordering === http://en.wikipedia.org/wiki/Endianness Little-endian byte ordering is used, except for serializing UUIDs (see below). ** Should we change to big-endian as this is standard inwire format? ** === Signed Fixed Point Representation === Signed values are represented in the Two's complement signed representation. http://en.wikipedia.org/wiki/Two's_complement === Floating Point Encoding === The 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 Encoding === UUIDs are serialized in big-endian byte order, as per section 4.1.2 of the UUID specification. [http://www.ietf.org/rfc/rfc4122.txt] === Types === bitmask: 8 bit bitmask. double: 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 byte: unsigned 8 bit integer uuid: 16 byte Universally Unique Identifier time: 64 bit timestamp with [[http://en.wikipedia.org/wiki/Unix_time|unix time]] encoding. === Packet Structure === UDP 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 - data }}} **PACKET HEADER** {{{ 4 : int : packet_id /* Packet identifier, unique inside connection. */ 4 : int : connection_id /* Connection identifier, unique between two peers. */ 1 : bitmask : flags /* Bitmask containing packet type flags and guaranteed flag. */ /* Type bit being set is that of packet type index. */ /* 7th bit is guaranteed flag. 8th bit not used. */ 1 : byte : input_buffer_fill_percentage 1 : byte : number of acks X : ints : message indexes acked }}} === Packet Types === ** CONNECT 1 ** (not guaranteed) {{{ }}} ** CONNECT_RESPONSE 2 ** (not guaranteed) {{{ }}} ** DISCONNECT 3 ** (not guaranteed) {{{ }}} ** TRANSPORT 4 ** (Empty transport packet is used as keepalive packet and to transmit acks if no payload data needs to be transmitted.) (both guaranteed and not guaranteed) {{{ X : bytes : data }}} === Message Frame Structure === Each frame length is maximum of 268 bytes total. **MESSAGE FRAME** {{{ frame header (14 bytes) - frame data (maximum 255 bytes) }}} **FRAME HEADER** {{{ 4 : int : channel_index /* Channel identifier. */ 4 : int : message_index /* Rotating message index unique inside channel. */ 2 : short : frame_count /* Number of frames in this message. */ 2 : short : frame_index /* Index of the frame. */ 1 : byte : message_type /* Type of the message. */ 1 : byte : frame_data_size /* Number of byte in the frame data section. */ }}} 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.

MXP 0.6 Scratch Pad 5.2 (minor-edit)

Tommi S.E. Laukkanen — 2010-02-08T14:55:18Z

== Changes to Terminology == # Evaluate using primary bubble to denote the bubble where object was injected in contrast to secondary bubble where object is replicated. -> ACCEPTED == Theoretical Development == # Evaluate whether channel prioritization should be supported by giving channels priorities and choosing messages to be send based on that priority. # Evaluate whether three phase handshake should be used to allow server to verify that the response packet it sent was transported correctly back to client instead of going immediately and possibly falsely to connected state after sending connection response. # Evaluate whether bubble should have veto on movement. In other words should all movement be done with request / response. In the same manner as inject. -> Should the movement done by injecting location / orientation fragment of an object? (Tommi) -> We should make it easy to embed a physics engine or other "vetoing" engine into the hub; as far as the protocol is concerned, this should be optional and veto only in effect if initial creation of bubble asked for it (ark) -> agreed. the 'veto' could be a sanity check on the clients calculation of movement. it might be too much to as of the server in terms of CPU resources to do all the phyisics calculation for all clients. after all, all the clients form a wonderful distributed computing grid, let them do a calculation :). (akos) -> another consideration could be some movements / events triggered by the server, instead of the client. this could include physics calculations, special events, or interaction events between clients (e.g. collisions, kills, etc.) (akos) -> Does this mean that we should add no response required field to inject request or requests in general or that we should create move request and response pair which allows for this? Inject request might be more generic. -> Request/response is handled by inject messages by injecting only necessary segment. Optimized situation is supported by allowing participant to send the optimized movement event to server instead of inject. -> ACCEPTED # Consider global identification schemes. Global uuid register, best effort uuid generation with collision possibility and urls as ids. This has to be considered for participants, objects and assets. The url should resolve to xml document containing things like owner, inventory url etc. -> Apply XRI: http://en.wikipedia.org/wiki/Extensible_Resource_Identifier (Tommi) -> No comments so far. Do you agree that XRI is the way to go? -> ACCEPTED # Consider methods for space governance in distributed bubble cloud. Access limits to given space including movement and injection. Ability to inject or move to space normal object, exclusively space reserving object, persistent object, immobile non physics respecting object? Limits to allowed object dimensions? Does this require changes to protocol or can it be handled through extension fragments and contracts between linked bubbles? -> Move this to be handled in later version? (Tommi) -> the concept of persistent objects goes against the grain, imho; every object must have a participant owner; persistence should be accomplished by a daemon participant, not the hub (ark) -> how does this topic relate to scenery? (in my definition, scenery is a range of static objects that are 'agreed to' and shared by all participants, most usually installed locally for each of them) (akos) -> MOVED (To architecture level discussion) # overlapping clouds & level of detail: consider very large bubble spaces, where the number of participants is too large to send all updates to each participant with high frequency. currently the concept is that each participant is connected to only one bubble at any one time, and that the bubble is responsible for sending relevant updates to each client. relevancy includes proximity to other objects, so most probably, updates related to close objects will be more frequent, while updates to far objects will be sparse. similarly, different levels of detail related to 3D representation will be sent for object of different distance - a less detailed 3D model for far objects, a more detailed one for close objects. at the end, from the bubble implementation perspective, this all comes down to slicing up the space into grids, and sending updates for participants within each grid with the highest frequncy, neighburing grids with a bit lower frequency, and all other grids with the least frequency. while this can be implemented within a bubble - why not take the approach to treat each such grid as a different bubble, and the participant can just subscribe to the ones relevant to him? this would move the taks of maintaining grid relevancy for each client from the server, to each client - thus distributing the load. (akos) -> I am not sure I fully grasp how you would extend the current bubble cloud model unless you mean just allowing participants to connect to several bubbles. This would actually raise the server load as each server would have order of magnitude more connections. With current architecture servers connect each other and distribute information via single server to server connection and client has only one server connection. It is not forbidden in the current design that participant would connect several bubbles as well. It just requires more from the client implementation. -> MOVED (To architecture level discussion) == Changes to Protocol == # Evaluate adding ordered delivery functionality to guaranteed message channel. Can this be added on top of the existing layer with minimal changes in implementation? -> After some reflection I am starting to think it would be good idea to make the entire guaranteed channel ordered to allow for rapid injection of interdependent object structures as kripken has requested. (Tommi) -> Guaranteed seems to be relatively trivial. Ideally we could support several guaranteed channels which would all have ordered delivery feature. Guaranteed channels stalls until messages can be delivered in correct order. If we know that the message message delivery has to be guaranteed then it is highly likely that the order matters as well. Can anyone think any exceptions for this? -> ACCEPTED # Evaluate adding time stamps to unguaranteed signal type messages to allow for time stamp based invalidation of late arriving signal messages. -> I would say we should go with time stamp here and leave the details to the engine applying the signal. We would not want the message order changes between messages of different objects to translate to packet loss as would happen if we would use ordered channel. (Tommi) -> Could we use channel concept here as well instead of time stamp. Define large enough channel space (int) so that each object may have unique unguaranteed transport channel. For example negative integers are guaranteed per object channels, zero is transport layer channel. Some of the positive channels can be reserved to certain guaranteed MXP message types and rest can be user assigned? (Tommi) -> Seems possible to get the ordered functionality this way just by adding a "channel" field; we should have both the timestamp and the channel field I think; I also think we should have an IRC to talk specifically about channels and what new functionality the hub may need if any as opposed to client handling (ark) -> don't we already have a timestamp for each packet (first send time)? would the channel concept be a subscription based approach - each client can subscribe to each channel as he sees it necessary? (akos) -> Not all transport layers necessarily have timestamp. -> Unguaranteed channels where we have use case for both ordered and not ordered delivery. Some of the transport layer messages like ACK's and Keepalives do not require ordered delivery. On the other hand all the unguaranteed mxp core messages (only movement currently) seem to be of the type signal. They transmit a continuous signal where order matters but late arriving messages can be discarded. This might suggest we divide unguaranteed channels to one control channel and N signal channels where each object has dedicated signal channel. The dedicated channel can be used for things like movement signal and animation signal. If we do this do we need separate guaranteed flag anymore or could this be deduced from the channel number. For example positive channels are guaranteed ordered channels and negative channels are signal channels. Zero channel would be the control channel. Signal type messages will also contain time stamp. -> ACCEPTED # Evaluate whether message frame header sizes should be optimized by sending most of the information with first frame only. Rest of the frames could contain just message id and frame index. -> this would mean that the 10-byte frame header would decrease to 6 bytes, I'm not sure saving on these 4 bytes make it worthwhile (akos) -> REJECTED # Should we consider to define a TCP-based procol on the side, that can be used easily for less performance demanding applications, like integration into web sites using JavaScript? I'm thinking of a JSON-based serialization interface on top of a RESTful API, with basically the same message structures. simple clients could send in infrequent state updates easily, and one could easily create mash-ups, like Google Maps integration, etc. also, see EEML & patchube for real-world usage concepts on Augmented Reality: http://www.eeml.org/ , http://www.pachube.com/ -> ACCEPTED # Separate packet layer from payload frame encoding. This requires acks to be incorporated to packet header and control messages be changed to specialized packets. -> ACCEPTED == Changes to Encoding == # Evaluate need for standard binary format to present time stamp. -> Do we need this and does such standard exist? (Tommi) -> Our timstamps need not represent "the time"; I believe all they need to do is represent a point in the future, based on the hub's time; I had originally planned for the hub to keep track of the offset between it's time and each client's, and just translate timestamps (ark) -> AFAIK the 'standard' time format is the UNIX time: http://en.wikipedia.org/wiki/Unix_time , which is the same we have now, expect for the epoch being January 1st 1970. I would vote for sending 'the time', as opposed to sending some arbitrary offset to the servers time (re ark), to make conversions easier, and also to make transfers between hubs easier. (akos) -> ACCEPTED (unix time, unless you have objections ark) == Changes to Packet Structure == # Evaluate whether time stamps are needed on packet level. -> I am not sure just being able to measure message Jitter is worth it. (Tommi) -> both jitter and packet relevancy (e.g. packets from too long ago just shouldn't matter) (akos) -> There will be other transport layers in addition to UDP which will not have packets. -> Hence we should not rely on packet time stamps on message relevancy. (Tommi) -> ACCEPTED (If use case for packet level time stamp does not appear.) # Find better name for session_id field. For example stream_id could be better as sequence_id is different for upstream and downstream packets. -> Stream id is probably good. (Tommi) -> in 0.5, we don't actually have a sequence_id field (akos) -> corrected to session_id (Tommi) -> ACCEPTED # Create session id as aggregate of up and downstream ids. -> ACCEPTED == Changes to Message Schematics == # Evaluate whether application extensions could be divided to several segments which could be cached on bubble for full synchronization requests. This would allow efficient partial updates to objects using segments. -> Multiple extension fragments per message and optional extension fragments. Core fragments could also be equal to the extension fragments in implementation level. For example inject message might only inject certain application extension and leave location/orientation fragment out. (Tommi) -> This could be a very important feature; some objects may have huge number of attributes and would impact performance otherwise (ark) -> I'm not sure I understand which extension fragments are we talking about here - sorry for my lack of understanding (akos) -> ACCEPTED (implement if possible) == Changes to Message Serialization == # Evaluate whether messages containing N-fragments should declare the amount of fragments in some kind of header fragment. -> I'm all in for this one, would make implementations easier & nicer (akos) -> NOT APPLICABLE (if we use google protocol buffers we do not need to worry about this) # Evaluate whether string field sizes should be changed from fixed to variable from 0 to defined maximum width. The actual field size in bytes would be defined by leading byte (string) or integer (text). This would decrease the serialized message sizes but make parsing more complicated as frame content would not be predefined anymore. Packet content would also be harder to read by humans as location of fields would not be fixed any more. This might also prove more challenging for any hardware optimization of hubs (pretty theoretical at this point). Both of these can be work around by placing string fields to end of message. This would in practice enforce message content agnostic multiplexing and demultiplexing of message data to/from packet frames via specialized streams. Performance penalty of byte array copies from frames to stream buffer could be avoided by implementing input stream which would allow reading of bytes directly from separate byte arrays of packets. This would keep the packets reserved until all the frames have been read from the packet. -> for possibly long strings / text this would make sense. for example, some URL fields too short lengths now for some real-world applications. from an implementation perspective, I'm don't see this as a problem (akos) -> NOT APPLICABLE (if we use google protocol buffers we do not need to worry about this) # Evaluate possibility of specifying message structure definition language which would allow for code generation of message valuable objects. The same system could be used to define extension fragment serialization. -> Message structure definition language for messages, core fragments and extension fragments. Automatic generation of message code based on the message structure definitions. This would be a big leap in flexibility and would accelerate protocol content development. If we can keep the serialization cpu efficiency we have now then this would be great improvement. (Tommi) -> Structure definition language sounds good provided it is not a pain to parse. Regarding variable length strings, if message structure definition language takes care of this then great; if not then I wonder why a really long string needs to be transmitted via the protocol; any really long content should be downloaded by the clients via http from the content definition layer (ark) -> one could consider the protobuf library to be used for this purpose: http://code.google.com/p/protobuf/ but of course there are others. ark: long strings might be needed to be sent within the protocol, for example URLs might be long (definately longer that the current 50 characters in the spec) (akos) -> ACCEPTED (google protocol buffers (GBF) unless show stoppers appear in further evaluation and implementation) == Changes to Messages Fields == # Evaluate whether object should contain avatar flag to mark it as avatar object. As an optimization perception messages would be sent of objects which are inside perception range of avatar objects. -> I think this would be good to have. One participant could have multiple objects flagged like this to indicate that they are used for active participation to world by the participant. Could the name be different from avatar? For example is_active_object? (Tommi) -> If there is any attempt to make avatars special it will violate the very foundation of the protocol's architecture, imho. I think we need to consider another layer at this point - a layer of attributes which direct aspects of how things should be simulated within the client. I think it is important we get familiar with this next layer up, so that we add things to it that otherwise we would have been trying to cram into the base protocol. (ark) -> ark: can you elaborate on the 'next layer'? -> ACCEPTED (Observer flag to mark the perceptions should be relayed to the participant of the object. # Evaluate whether ObjectFragment should contain InventoryUrl as it is suggested that each object should have home inventory defined where object assets can be loaded from and where object is persisted. -> I think this is needed. (Tommi) -> I though every object already had to have a URL? (ark) -> I think its a good idea (akos) -> ACCEPTED (Apply XRI, i.e. put this url to xml document at the XRI location) # Evaluate whether object should contain persistent flag for deducing if bubble should host the object persistently. In other words whether object should disappear automatically when participant disconnects. -> I think this is needed. (Tommi) -> I do not think a bubble should ever host an object, or persist anything; there should be a daemon participant for this. The persistence flag is then an attribute within the next layer up, not within MXP. (ark) -> interesting consideration - should bubbles 'host' anything, or should they really just reflect whatever is injected into them? I think it makes sense to be able to create a server / deaemon that has an MXP interface already, instead of having to run two daemons: one that hosts the objects, the other just being an MXP bubble (akos) -> ACCEPTED # Evaluate whether object perception range should in included to object fragment. -> I think this is needed. (Tommi) -> Agreed; thought it was already there. (ark) -> ACCEPTED # Change action observation radius to perception range. -> I think this would be more in line with our chosen terminology. -> ACCEPTED # Change action source object id to object index. -> This would require index mapping when action propagates to next bubble. Probably best to use id here. But change field name from source object id to object id. (Tommi) -> ACCEPTED (source object id to object id) # Evaluate whether disappearance event should use objectid instead of object index. In some situations delayed disappearance might not have objectindex available. -> Object id would be symmetrical too. This a good change. (Tommi) -> ACCEPTED # Evaluate removing owner id from bubble. No real use case. Owners may or may not want to mark their ownership and plain id is not anyway enough for this without global guid register. If this is needed one possibility would be to have openid identity url. Might be better to have separate method for accessing bubble metadata from bubble http service. -> Probably clear away fields which are not really needed. -> I think since bubbles are dynamic and much about them is determined at creation time by owner, it will be important for something somewhere to keep track of who owns the bubbles; perhaps this is a bubble directory service, however, and not the hub. (ark) -> REJECTED # Evaluate whether TypeId is required in object and who upkeeps the register. -> Should we change it to Type XRI url? (Tommi) -> otherwise, how do we know what type of object are we getting info on? IMHO we need some kind of type identification (akos) -> ACCEPTED (TypeName will be removed and TypeId stays as XRI URI.) # Evaluate if extension fragment type should have longer field than 4 characters. -> If we change to more dynamic extension fragment via message definition language we probably need this for core fragments as well. Then we might want to minimize the fragment type field size. (Tommi) -> REJECTED (if we use google protocol buffers we do not need to worry about this) # Evaluate whether authentication related fields need to be changed to support openid and openauth. -> Should this be moved to later release? -> should this not be handled by the bubble implementation instead, rather than forcing it to handle openid, leave it open? (akos) -> We probably need some support in MXP messages. For example possibility to carry generic one time token in the mxp connection open request. This token can then be used to connect initial open id authentication carried out via web browser to the mxp connection. -> Should we change the password/passphrase to token or secret. -> Keep the password for basic authentication and add authentication url to join response for advanced http based authentication schemes. -> ACCEPTED # Evaluate whether bubble real_time field is needed. -> Remove bubble real time and add time field to packet header containing latest sent/resent time. -> ACCEPTED # Can we correct the spelling mistake of quaranteed to guaranteed? (akos) -> ACCEPTED == Additions and Removals of Messages == # Evaluate whether there should be a simplified version of modification request which sends only the application specific extension instead of combination of object fragment and application specific extension. This would lower the overhead when only application specific values are being changed. -> I think this is needed. (Tommi) -> Yes I agree (ark) -> ACCEPTED # Evaluate whether separate inject and modify messages are needed as they seem to be handled identically on implementation. -> Can these two be combined so that modification message is removed and injection message can carry one to many object fragments of which one is the core mxp object fragment and rest are application extension fragments. (Tommi) -> Similar change is needed to perception event message. (Perception event can occur because of inject, interact and some internal event in the object.) -> Seems fragments handle the difference so separate messages are not needed. (ark) -> ACCEPTED #Evaluate need for another message request/response pair for measuring delay and clock differences between connected parties. -> Can this wait until someone is working on the distributed physics? (Tommi) -> I think we should go ahead and put it in if needed so when they do work on it we don't have to revise protocol. (ark) -> ACCEPTED (needs specification) # Evaluate whether collision event should be added. Collision event would contain both colliding object Ids. Collision is detected by primary bubbles of both objects. Owning participant is applying the collision to the object trajectory. If objects are in separate bubbles then collision events are sent twice. Only first one is responded to. There has to be cool down time window before reacting to new collision event. -> I think this is immediately useful for basic demonstrations. (Tommi) -> This could be generic interaction event. (Tommi) -> I think this should be the generic interaction event. (ark) -> interaction event would be fine. but are collisions always initiated by the bubble? how about very fine-grained 'touch' events, where the geometry of the participants is far from trivial? (akos) -> ACCEPTED (create interaction request/response) #Evaluate whether challenge request and response should be kept in message list. When they are needed they can be added later back. -> Remove (Tommi) -> ACCEPTED == Implementation Considerations == Here are couple of implementation alternatives to our current approach. Should we try to specify and implement everything in MXP project or should try to rely on external dependencies in some layers? Are natively library dependencies ok? Do we require same level of specification as in MXP ? # Evaluate using Google protocol buffers for serialization. -> Are language implementations compatible? (Tommi) -> Is efficiency of google protocol buffers good enough? Create serialization with GBF of movement message and compare to size of current MXP serialization. (Tommi) -> We could consider using GBF for MXP specific messages and keep transport layer specific ones fixed as they are. This would keep the transport layer independent of of GBF. GBF would in turn be MXP serialization layer. (Tommi) -> is GBF the same as protocol buffers? :) otherwise, yes, protobuf is quite efficient (akos) -> ACCEPTED (if no show stoppers appear) # Evalute using ENET as transport layer to lower to amount of work for each language implementation. The transport layer is probably most challenging to get working properly especially in the area of interoperation if all features like throttling are considered. -> Can each object be assigned separate enet channel for unquaranteed signals like movement? ENET can have maximum 255 channels. This would enforce ordered dependency for unguaranteed packages. ENET drops out of order (late) arriving unguaranteed packet inside a channel. That is problematic if all movement messages use same channel: Movement messages for different objects arrive in wrong order and late arriving would be dropped. This should only happen if movement messages for same object arrive in wrong order. (Tommi) -> ENET is native library. How challenging is it to provide prebuild binaries for different platforms and how would they be packaged? (Tommi) -> Wrappers or native ports do not seem to exist. Can we get the wrappers or ports done as part of MXP project? (Tommi) -> ENET seems to miss specification. Can that be seen as weakness in MXP if adopt ENET as our transport layer? (Tommi) -> My feeling is currently that ENET might require too many compromises. All though it would provide robust alternative in short term I am confident that we can create equal quality in our own transport layer with tailored features. (Tommi) -> enet is promissing, and has proven itself already. but the drawback is that it's native (C-only), whereas we need Java, .NET, C++, Python, etc. binding as well. Also, enet seems to lack a specification (as Tommi has pointed out), so it's probably difficult to write compatible alternative implementations. (akos) -> REJECTED # If we continue working on our own transport layer, is it worth separating it and making it independent of MXP messages? We could also concentrate on modular design to be able to switch to another transport layer. -> would make sense (akos) -> ACCEPTED

Release Process 1.7 (minor-edit)

Tommi S.E. Laukkanen — 2010-02-07T16:03:46Z

== Naming convention == MXP release naming convention is as follows: mxp---- Examples of the naming convetion: # mxp-java-0.5-0.1-src - for MXP Java implementation supporting MXP protocol 0.5, release version 0.1, source release # mxp-cxx-0.5-0.1-linux_x86_64 - for MXP C++ implementation support MXP protocol 0.5, release version 0.1, Linux x86_64 == Steps == # Determine the release version number. # Branch the exact release version to SVN. # Until no blocker issues, repeat: ## Build release candidate. ## Package the release candidate. ## Publish release candidate. ## Test the release candidate. # Tag the release in SVN from the branch. # Declare the latest release candidate as release. # Tag the release to SVN. # Rename packages from release candidate to release. # Publish packages. # Create brief news item to selected feeds about the release. # Syndicate news to freshmeat.net - where else? == Publish == # Publish to: http://code.google.com/p/setp/downloads/list # Summary Convention ## MXP protocol 0.5 - C# implementation 0.1 - sources - release candidate ## MXP protocol 0.5 - C# implementation 0.1 - mono build - release candidate # Tags: Type (Source/Library), Language, OpSys, Featured == Packages == # Separate package for each language and platform combination. # Package content: ## Readme file ## Source release ## Binary release ## Generated documentation ### Manually written content to wiki ### Javadoc / doxygen-style API docs

MXP Messages Draft 0.6 1.1 (minor-edit)

Tommi S.E. Laukkanen — 2009-12-20T17:28:32Z

Google protocol buffers .proto syntax for defining the MXP message structure: {{{ package MXP; message MVector3f { required float X=1; required float Y=2; required float Z=3; } message MQuaternion4f { required float X=1; required float Y=2; required float Z=3; required float W=4; } message MColor4f { required float R=1; required float G=2; required float B=3; required float A=4; } message ResponseSection { required uint32 MessageId=1; required uint32 FailureCode=2; } message ProgramRegion { required string ProgramName=1; required uint32 ProgramMajorVersion=2; required uint32 ProgramMinorVersion=3; required uint32 ProgramBuildNumber=4; required uint32 ProgramRevision=5; required uint32 ProtocolSpecificationMajorVersion=6; required uint32 ProtocolSpecificationMinorVersion=7; required uint32 ProtocolBuildNumber=8; required uint32 ProtocolRevision=9; } message IdentitySection { required string ObjectId=1; required string TypeId=2; required string ParentId=3; required string OwnerId=6; required string ObjectName=7; required bool Persistent=8; required bool Observer=9; } message OrientationSection { required MVector3f Location=1; required MQuaternion4f Orientation=1; } message MotionSection { required MVector3f Velocity=2; required MQuaternion4f AngularVelocity=2; } message ForceSection { required MVector3f Acceleration=1; required MQuaternion4f AngularAcceleration=2; } message BodySection { required float BoundingRadius=1; required float Mass=2; } message ObjectSection { optional uint32 ObjectIndex=1; optional IdentitySection Identity=2; optional OrientationSection Orientation=3; optional MotionSection Motion=4; optional ForceSection Force=5; optional BodySection Body=6; extensions 100 to 1000; } message InteractionSection { required string InteractionName=1; required string SourceParticipantId=2; required string SourceObjectId=3; required string TargetParticipantId=4; required string TargetObjectId=5; extensions 100 to 1000; } message BubbleSection { required string BubbleId=1; required string BubbleName=2; required string BubbleAssetUrl=3; required string OwnerId=4; required string BubbleAddress=5; required uint32 BubblePort=6; required MVector3f BubbleCenter=7; required float BubbleRange=8; required float BubblePerceptionRange=9; } message JoinRequest { required uint32 MessageId=1; optional string BubbleId=2; optional string BubbleName=3; optional string LocationName=4; required string ParticipantId=5; optional string ParticipantSecret=6; required string AvatarId=7; required ProgramRegion ClientProgram=8; } message JoinResponse { required uint32 MessageId=1; required string BubbleId=2; required string ParticipantId=3; required string AvatarId=4; required string BubbleName=5; required string BubbleAssetUrl=6; required float BubbleRange=7; required float BubblePerceptionRange=8; } message LeaveRequest { required uint32 MessageId=1; } message LeaveResponse { required uint32 MessageId=1; required ResponseSection Response=2; } message InjectRequest { required uint32 MessageId=1; optional ObjectSection Object=2; } message InjectResponse { required uint32 MessageId=1; required ResponseSection Response=2; } message EjectRequest { required uint32 MessageId=1; required string ObjectId=2; } message EjectResponse { required uint32 MessageId=1; required ResponseSection Response=2; } message InteractRequest { required uint32 MessageId=1; required InteractionSection Interaction=2; } message InteractResponse { required uint32 MessageId=1; required ResponseSection Response=2; required InteractionSection Interaction=3; } message AttachRequest { required uint32 MessageId=1; required string TargetBubbleId=2; required BubbleSection SourceBubble=3; required ProgramRegion SourceProgram=4; } message AttachResponse { required uint32 MessageId=1; required ResponseSection Response=2; required BubbleSection TargetBubble=3; required ProgramRegion TargetProgram=4; } message DetachRequest { required uint32 MessageId=1; } message DetachResponse { required uint32 MessageId=1; required ResponseSection Response=2; } message HandoverRequest { required uint32 MessageId=1; required string SourceBubbleId=2; required string TargetBubbleId=3; required ObjectSection Object=4; } message HandoverResponse { required uint32 MessageId=1; required ResponseSection Response=2; } enum ListType { Hosted = 0; Linked = 1; Connected = 2; } message ListBubblesRequest { required uint32 MessageId=1; required ListType listType=2; } message ListBubblesResponse { required uint32 MessageId=1; required ResponseSection Response=2; repeated BubbleSection Bubble=3; } message PerceptionEvent { required uint32 MessageId=1; required ObjectSection Object=2; } message DisappearanceEvent { required uint32 MessageId=1; required uint32 ObjectIndex=2; } message MovementEvent { required uint32 MessageId=1; required uint32 ObjectIndex=2; required MVector3f Location=3; required MQuaternion4f Orientation=4; } message MovementEvent2 { required uint32 ObjectIndex=2; required float LocationX=3; required float LocationY=4; required float LocationZ=5; required float OrientationX=6; required float OrientationY=7; required float OrientationZ=8; required float OrientationW=9; } message ActionEvent { required uint32 MessageId=1; required string ActionName=2; required string ObjectId=3; required float EffectRadius=4; extensions 100 to 1000; } message InteractionEvent { required uint32 MessageId=1; required string InteractionName=2; required string SourceObjectId=3; required string TargetObjectId=4; required float EffectRadius=5; extensions 100 to 1000; } message HandoverEvent { required uint32 MessageId=1; required string SourceBubbleId=2; required string TargetBubbleId=3; required ObjectSection Object=4; } message SynchronizationBeginEvent { required uint32 MessageId=1; required uint32 ObjectCount=2; } message SynchronizationEndEvent { required uint32 MessageId=1; } }}}

Requirements 1.5 (minor-edit)

Tommi S.E. Laukkanen — 2009-12-09T05:03:16Z

== General Requirements== # Define **minimal** and **easy to implement** protocol for networked virtual environments. # The protocol grammar and core messages should be presentable **in one page**. # Protocol should be refined from **existing** research, implementations and standards. # Protocol network layer should be implementable inside **hours** rather than days. # Protocol should not limit positioning of simulation nodes relative to each other. # Simulation node volumes can be assumed to be cubes or spheres. # Protocol should support object hierarchies. # Protocol should support versioning of the protocol. Minor version differences mean additional messages which are not mandatory and do not break compatibility. # Vocabulary should not include application specific terms but rather express the defined environment model. # Protocol should enable seamless environment where objects can move and percept without disjointedness. # Protocol should not limit the size of the environment. (No global coordinates and no centralized services which can become bottlenecks. ) # Protocol should focus on transmitting commands and state information and delegate media presentation and transport to the existing standards like Collada and HTTP. # Protocol should be able to transmit object internal state as payload but need not define the data structures. For example XML-schema for object internal state is out of scope for this protocol. Such XML-definitions are considered to be part of a higher level standard covering things like accessing media assets and simulation interoperability. This protocol focuses on issues which are fundamental for distributed 3d simulation. # Protocol should support **dead reckoning** (movement prediction). == UDP Transport Layer Requirements == # Protocol should support **connectivity**. # Protocol should support **[[http://en.wikipedia.org/wiki/Congestion_avoidance|congestion avoidance]]**. # Protocol should support **guaranteed delivery**. # Protocol should support **signal delivery** where packets are not acked and out dated packets are ignored. # Protocol should support multiple signal and guaranteed **channels**. # Protocol should support **bandwidth reservation** for guaranteed channels. # One network packet should be able to contain many **payload frames**. # Long message should be **fragmented** and send in intervals to avoid congesting the channel. # Protocol should support **encryption** for security reasons. # Protocol should support **compression** to achieve optimal performance.

Contributors 1.2 (minor-edit)

Tommi S.E. Laukkanen — 2009-12-06T15:31:52Z

In alphabetical order: * Ben Lindquist * John Hurliman * Jon Watte * Ryan McDougall * Tommi Laukkanen * Stefan Andersson - Deck implementation * Richard Anaya II - Initial python implementation

MXP over UDP Specification Draft 0.5 2.9

Tommi S.E. Laukkanen — 2009-11-12T16:38:55Z

<> == Introduction == One 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. {{FrontPage/mxp_udp.png}} == Changes == # Session Handling ## Incoming and outgoing packets have separate session ids for each connection. Session id is defined for each connection by sender. First response packet (ack) is paired to outgoing session by sent packet id replied in the ack. # PACKET_HEADER ## time field size fixed to 64 bits. # BUBBLE_FRAGMENT ## realtime field size fixed to 64 bits. ## Renamed bubble_server_address => bubble_address ## Renamed bubble_server_port => bubble_port # PROGRAM_FRAMET ## program_name length from 40 to 25 # JOIN_REQUEST ## Realtime field size fixed to 64 bits. ## participant_name => participant_identifier ## participant_passphrase => participant_secret ## Added avatar_id field which is the main avatar injected by client ## Changed location name size to 28 bytes. ## identity_provider_url length to 50 # JOIN_RESPONSE ## Realtime field size fixed to 64 bits. ## asset_cache_provider_url to 50 # LIST_BUBBLE_REQUEST ## changed list_type enumeration values to 0=hosted,1=linked and 2=connected == Next Version Tasks == # Evaluate whether there should be a simplified version of modification request which sends only the application specific extension instead of combination of object fragment and application specific extension. This would lower the overhead when only application specific values are being changed. # Evaluate whether application extensions could be divided to several segments which could be cached on bubble for full synchronization requests. This would allow efficient partial updates to objects using segments. # Evaluate whether ObjectFragment should contain InventoryUrl as it is suggested that each object should have home inventory defined where object assets can be loaded from and where object is persisted. # Evaluate whether object should contain persistent for deducing if bubble should host the object persistently. In other words whether object should disappear automatically when participant disconnects. # Evaluate whether object should contain avatar flag to mark it as avatar object. As an optimization perception messages would be sent of objects which are inside perception range of avatar objects. # Evaluate whether separate inject and modify messages are needed as they seem to be handled identically on implementation. # Evaluate whether object perception range should in included to object fragment. # Evaluate whether collision event should be added. Collision event would contain both colliding object Ids. Collision is detected by primary bubbles of both objects. Owning participant is applying the collision to the object trajectory. If objects are in separate bubbles then collision events are sent twice. Only first one is responded to. There has to be cool down time window before reacting to new collision event. # Change action observation radius to perception range. # Change action source object id to object id. # Evaluate if action object id should be changed to object index. # Evaluate using primary bubble to denote the bubble where object was injected in contrast to secondary bubble where object is replicated. # Evaluate whether bubble should have veto on movement. In other words should all movement be done with request / response. # Evaluate whether disappearance event should use objectid instead of object index. In some situations delayed disappearance might not have objectindex available. # Consider global identification schemes. Global uuid register, best effort uuid generation with collision possibility and urls as ids. This has to be considered for participants, objects and assets. # Consider methods for space governance in distributed bubble cloud. Access limits to given space including movement and injection. Ability to inject or move to space normal object, exclusively space reserving object, persistent object, immobile non physics respecting object? Limits to allowed object dimensions? Does this require changes to protocol or can it be handled through extension fragments and contracts between linked bubbles? # Evaluate removing owner id from bubble. No real use case. Owners may or may not want to mark their ownership and plain id is not anyway enough for this without global guid register. If this is needed one possibility would be to have openid identity url. Might be better to have separate method for accessing bubble metadata from bubble http service. # Evaluate whether TypeId is required in object and who upkeeps the register. # Evaluate if extension fragment type should have longer field than 4 characters. # Evaluate whether messages containing N-fragments should declare the amount of fragments in some kind of header fragment. # Find standard binary format to present time stamp. # Find better name for sequence_id field. For example stream_id could be better as sequence_id is different for upstream and downstream packets. # Evaluate whether third channel is needed which would provide guaranteed ordered message delivery. Could this be implemented on message queue level without touching the packet transport layer? # Evaluate whether dynamic fragment sections should have leading byte containing number of fragments. This would make some parsing strategies easier. # Evaluate whether time stamps are needed on packet level. # Evaluate whether string field sizes should be changed from fixed to variable from 0 to defined maximum width. The actual field size in bytes would be defined by leading byte (string) or integer (text). This would decrease the serialized message sizes but make parsing more complicated as frame content would not be predefined anymore. This would in practice lead to message content agnostic multiplexing and demultiplexing of message data to packet frames via specialized stream. Performance penalty of byte array copies could be avoided by implementing input stream which would allow reading of bytes from separate byte arrays of packets. This would keep the packets reserved until all the frames have been read from the packet. # Evaluate possibility of specifying message structure definition language which would allow for code generation of message valuable objects. The same system could be used to define extension fragment serialization. == Encoding == === Byte ordering === http://en.wikipedia.org/wiki/Endianness Little-endian byte ordering is used, except for serializing UUIDs (see below) === Signed fixed point representation === Signed values are represented in the Two's complement signed representation. http://en.wikipedia.org/wiki/Two's_complement === Floating Point Encoding === The 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 Encoding === UUIDs are serialized in big-endian byte order, as per section 4.1.2 of the UUID specification. [http://www.ietf.org/rfc/rfc4122.txt] === Types === double: 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 (see below for details) byte: unsigned 8 bit integer uuid: 16 byte Universally Unique Identifier time: 64 bit timestamp. // How to encode? // * Proposal: milliseconds since 1.1.2000 00:00 UTC 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. ==== String representation ==== Strings are represented in UTF-8 encoding, and with zero-termination. Usually strings are represented in fixed with spaces. If a string fits into the allocated space, the remaining free space is padded out with zero characters as necessary. If the UTF-8 representation of the string would be longer than the available space, it is truncated so that the last complete UTF-8 sequence and the zero-termination still fit into the space available. == URL Format == Bubbles can be referenced with the following URI type: {{{mxp://

://}}} {{{mxp://

://}}} or with default values: {{{mxp://

/}}} {{{mxp://

:/}}} {{{mxp://

:/}}} == Sockets and Connectivity == === Socket Handling === Each peer has one socket which is used to send and receive all information. Incoming packets are tied to connection based on remote address, port and incoming session id. Peers are divided to clients, servers and hubs. Clients and servers handle participant to bubble communication. Hubs are responsible for bubble to bubble communication. === Connection === Connection is initiated by join request or attach request. First response packet (ack) is paired to outgoing session by sent packet id replied in the ack. New connection request is always responded first by ack. Incoming and outgoing packets have separate session ids for each connection. Session id is defined for each connection by sender. Session id is unique for senders address and port combination. === Disconnection === Disconnect can occur due to leave or detach request which has been successfully responded with response. Disconnect can also occur due to timeout or protocol error. == Data Structures == === Packet Structure (maximum 1452 bytes) === UDP 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 (18 bytes) - message frames (mxa 1434 bytes) }}} **PACKET HEADER** {{{ 4 : uint : session_id /* Upstream session id. */ 4 : uint : packet id /* Id of the packet. */ 8 : 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 Structure (maximum 265 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 255 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 frame. */ 1 : byte : frame_data_size (0-255) }}} === Reusable Fragments === **RESPONSE FRAGMENT** {{{ 4 : uint : request_message_id 1 : byte : failure_code // 0 == success }}} **PROGRAM FRAGMENT** {{{ 25 : 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 /* Bubble object index.. */ 16 : uuid : type_id /* Type id of the object. */ 16 : uuid : parent_object_id /* Identifier of the parent object. */ 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. */ 16 : uuid : owner_id /* Participant who owns the bubble. */ 40 : string : bubble_address 4 : uint : bubble_port 12 : vector3f : bubble_center /* Defined in receiver coordinate space. */ 4 : float : bubble_range 4 : float : bubble_perception_range 8 : time : bubble_realtime }}} == Control Messages == **ACKNOWLEDGE 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 */ }}} == Challenge Messages == Challenge request and response can be used to validate type and version of peer implementation. **CHALLENGE REQUEST 4** {{{ 64 : data : challenge_request_data }}} **CHALLENGE RESPONSE 5** {{{ 64 : data : challenge_response_data }}} == Command Messages == === Participant to Bubble Commands === **JOIN REQUEST 10** {{{ 16 : uuid : bubble_id /* bubble id or empty id */ 16 : uuid : avatar_id /* id of the avatar. */ 40 : string : bubble_name /* bubble name or empty string */ 28 : string : location_name /* landing location or empty string */ 32 : string : participant_identifier /* participant identifier */ 32 : string : participant_secret /* passphrase or authentication token */ 8 : time : participant_realtime /* real time of participant */ 50 : 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 or empty id. */ 16 : uuid : avatar_id /* id of the avatar or empty id. */ 40 : string : bubble_name 50 : string : bubble_asset_cache_url /* Url for accessing binary assets. */ 4 : float : bubble_range 4 : float : bubble_perception_range 4 : time : bubble_realtime /* real time of bubble at connect time. */ 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 }}} === Bubble to Bubble Commands === ** ATTACH 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 }}} === Common Commands === **LIST BUBBLES REQUEST 25** {{{ 1 : byte : list_type /* [0=hosted,1=linked,2=connected] */ }}} **LIST BUBBLES RESPONSE 26** {{{ N X { BUBBLE FRAGMENT 60 : padding : 60 padding bytes (zero values) to fill the frame. } }}} // Each fragment is in separate frame with 60 bytes padding added. // == Event Messages == === Common Events === **PERCEPTION 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 /* Approximate perception count. */ }}} ** SYNCHRONIZATION END EVENT 71**: End of synchronization. {{{ }}} === Event Candidates === ** COMPRESSED 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.

Domain Model 1.4 (minor-edit)

Tommi S.E. Laukkanen — 2009-06-20T07:01:20Z

== Abstract Entities == === Spacetime === The overall goal of our protocol is to enable multiple participants to experience shared spacetime. Mathematically spacetime is a four-dimensional continuum. We constrain this continuum so that the time dimension only moves forward and both time and space are divided to discrete steps. === Participant === Participants are entities which are able to perceive aspects of the simulation and/or have an effect on aspects of the simulation. Participant types are: humans, daemon processes, artificial intelligence scripts and applications. === Object === An object is an atomic unit from the protocol perspective. Effect of an object on spacetime may be comprised of multiple types and occurrences of content but is treated such that either the entire object exists within a given spacetime or none of it exists. If a spacetime bubble is assumed to have a boundary and some object overlaps that boundary then the object can still be expressed in terms of the coordinate system of that spacetime bubble and as such it is considered to exist fully within that spacetime. Every object affecting a given spacetime belongs to a participant connected to that spacetime. If a program issues an injection command thus placing an object into spacetime then that program is a participant in that spacetime. If the program is a human interface then the human using the human interface is considered a participant. === Avatar === Avatar is an object which is used to represent the identity of its owning participant. === Content === Content is anything which can be perceived in the spacetime. Content only exists as a part of an object. Map can consists of one or more objects. All participation in a shared spacetime involves content. This includes images or textures, three-dimensional shapes, audio, fog, and light; it also includes changes occurring to any of these. Content may be injected into a spacetime, updated within a spacetime, ejected from a spacetime, or perceived within a spacetime. Injection, update, or ejection of content is performed via the protocol, by use of a command; perception of content is indicated via the protocol by receipt of an event. Injection, update, and ejection of content all result in perception events. === State === Object external states are visible and can be observed in the 3d environment where as internal state is not visible. === Visibility === Visibility is an attribute which reflects whether object or state can be observed through the spacetime. If bottle is transparent then filled/empty state is external and visible as it can be observed with the mechanisms of the spacetime. If the state has to be inquired in an interaction it is not visible. === Perception Volume === Objects have perception bounds which reflect the volume of interest. However they are defined geometrically, the perception bounds indicate a region of space within a spacetime. If this region of space is affected by other objects, via injection, update, or ejection commands, events representing those effects will be sent to the participant responsible for the object. Objects may be defined with an zero perception range, indicating that no events should be received. Upon issuing an injection command for an object, a participant will receive events which correspond to all objects which were already affecting the spacetime within the awareness bounds of the new object. === Perception === An event where object perception another object inside its awareness bounds. === Injection === Process where participant adds an object it owns to a spacetime bubble. === Ejection === Process where participant removes an object it owns from a space time bubble. === Appearance === When object becomes visible it appears. === Disappearance === When object becomes invisible from the world it disappears. === Interaction === Interaction is atomic event where one object changes the state of another object. Without interactions it could be argued that all objects have their private spacetime. === Handover=== Process where objects migrate from one bubble to another. Handover can be seamless if bubbles overlap. == Architecture Entities == === Bubble (Simulation / Sim) === A spherical or cubic volume defining spherical spacetime. Bubbles may overlap. === Bubble Cloud (Cluster / Grid) === A group of linked bubbles simulating distributed spacetime located in the same or separate bubble servers. === Bubble Server (World Server / Simulation Server) === A bubble server is a program which handles command and event processing for a spacetime. The bubble server is responsible for determining which events go to which participants, based on the awareness bounds and update coordinates of the objects the participants place into the spacetime. The bubble server may be essentially a messaging hub that is spatially aware only in terms of rough bounds and is not expected to perform physics simulation or collision detection. Bubble server will also contain object daemon (artificial active participant) injecting long lived persistent objects. Other daemon could be a physics daemon. === User Interface (Viewer/Browser/Client) === A human interface is a piece of software which uses the protocol and a user interface to enable a human to participate in a shared spacetime. === Subscription === Participants may inject objects which have a subscription capability. This means that other participants may receive updates involving that object directly from the owning participant. This can be useful to avoid network bottlenecking of a server; it is also useful when object updates take the form of a stream such as video or audio. The world server need not understand or process a particular video stream if the participant generating it streams it directly to all the other participants. //It has been suggested by Jon that subscription mechanisms and peer to peer streams could be defined in a separate protocol. - Tommi // //I agree with this as well. All the SETP/CICPv2 protocol needs to do is allow an object to publicize the fact that it has a subscription capability and where to get it. --ark // === Collision Detection === There should be a capability for a server module or special participant to handle collision detection for objects and trigger events based on that; it should also be possible for participants to handle their own collision detection. // It has been suggested by Jon that owning participant should always handle collision detection of an object. Another view point is that the bubble provides fundamental laws like collision detection. If several bubbles (sims from different providers) overlap then the bubble which is the primary bubble for an object (first point of injection) executes collision detection for that object. - Tommi // // Reply: Collision detection is part of simulation of an object. Whether an object is squishy or hard, collides as a convex hull, sphere, mesh, or something else is part of the definition of the object. What the object does when colliding is part of the simulation (for example, does it bounce, or stick, or explode, or turn on a light, or ...). If you want to support simulating an object on a host other than the host that initially injected the object, then you'd have to also support injection and transfer of behavior, which is a Hard Problem and hasn't actually ever been solved well. Thus, an object is owned by its injector, its simulation is handled by its injector, and the lifetime of the object is constrained by the lifetime of the injector(!) // // If two injectors want to negotiate transfer of ownership separately from the protocol, and remove/re-inject the object (or perhaps more elegantly, allow transfer of ownership), then that's fine, but not necessarily part of this particular protocol. // // I figure that since the bubble server has to be able to figure out the overlapping of awareness bounds and physical bounds of objects in order to do its job, why not enable it to also serve the participants with a basic collision (overlap of physical bounds and physical bounds) detection service. Objects have to somehow define their rough physical bounds to the bubble server anyway for awareness detection... the key is to keep it rough and simple. I am willing to ditch the idea of participants delegating collision detection for their objects to other participants; too complicated. Must eject and re-inject instead. --ark // === Interaction Options for an Object === Every object may have interaction options which the owning participant has defined for it. Another participant may choose to activate on of these interaction options, which results in an event being sent to the owning participant; the owning participant is then expected to do something and update the object to reflect what is has done. A human interface should allow a human to indicate a desire to interact with an object, and then display to the human the list of interaction options for that object. The human should then be able to select one, thereby triggering that event to the object's owner.

Implementation 1.2 (minor-edit)

Tommi S.E. Laukkanen — 2009-06-14T18:59:12Z

This page will contain implementation principles and links to the existing implementations. == C# Reference Implementation == Source code is available at: [[http://setp.googlecode.com/]] {{mxp_class_diagram.png}} //MXP API Class Diagram// === Planned Features === * Autologin === Features === C# reference implementation acts as proof of concept. Reference implementation consists of: * MXP - Network layer implementation. * MXPTests - Network layer tests. * MXTank (Server) - Is running 24/7 at tank1.setp.info. ** WindowsService Container - Can be executed as windows service. ** ASP.NET Web Container - Can be executed as ASP.NET web site. ** Demonstrates: *** Client connectivity. *** 100 moving objects injected and ejected every 10 seconds by automatic test participant. * MXDeck (Client) - Can be download from [[http://wiki.setp.info/files|files]] page. ** XNA Game - Is built upon XNA framework which is Microsoft C# game technology. ** Demonstrates: *** Connecting to server. *** Interpolating and rendering smooth movement of server side objects. *** Rendering of character animation with XNA framework. (No protocol support yet). === Current Performance Results === * 100 moving objects with movement event every 400 ms: ** Smooth movement observed ** Bandwidth usage: 95kbps (bits per second)

Metaverse Structured Data 1.2 (minor-edit)

Tommi S.E. Laukkanen — 2009-06-14T13:22:04Z

Metaverse Structured Data (MSD) is encoding scheme which uses [[http://code.google.com/apis/protocolbuffers/docs/overview.html|Google Protocol Buffers]] implementation for encoding and decoding state and interaction payloads transmitted over MXP. Google Protocol Buffers .proto-files are IDL-files which are used by protogen application to create Encoding/Decoding classes. John Hurliman contributed the idea of using Google Protocol Buffers instead of XML based approach. === Application Specific MSD Schemas === * Open Metaverse - Open Metaverse schema is iterative process to define working schema for OpenSimulator and compliant systems. The schema can be viewed from [[http://code.google.com/p/setp/source/browse/trunk/csharp/ReferenceImplementation/MXP/ExtensionFragments/MXP.Extentions.OpenMetaverseFragments.proto|source repository]]. === Common Data Types === {{{ // Metaverse Structured Data Types message MsdVector3f { required float X=1; required float Y=2; required float Z=3; } message MsdQuaternion4f { required float X=1; required float Y=2; required float Z=3; required float W=4; } message MsdColor4f { required float R=1; required float G=2; required float B=3; required float A=4; } }}} === MSD fragment types === * Object state data * Object action data * Object interaction request data * Object interaction response data === Examples === This is an example of extending PerceptionEvent to carry terrain object data in compressed bitmap format: {{{ // Terrain object extension for simple heightmap based terrains. // Heightmap layer is scaled to fit the object are in X,Z-plane. // Layer values are adressed in the array as follows: // float floatValue=heightMap[x+y*width] // Float array presenting height map is first encoded to short array as follows: // short shortValue=(short)((floatValue-offset)*Scale) // This is further compressed with deflate algorithm. message OmBitmapTerrainExt { required uint32 Width=1; required uint32 Height=2; required float Offset=3; required float Scale=4; required bytes HeightMap=5; } }}}

Reference Architecture 1.0

Tommi S.E. Laukkanen — 2009-06-14T12:44:58Z

**This architecture is not MXP reference architecture but example of traditional networked virtual environment architecture.** Architecture consists of N thin clients and N servers. Original source for this page: [[http://questforvr.blogspot.com/2007/04/blog-post.html]] Essentially client consists of user interface framework (3D rendering engine, 3D sound engine, windows, panels, and widgets), virtual reality model (scene graph and media caches), session management (state machine and session data pool), command interface (commanding avatar), state synchronizer (synchronizing server virtual reality model) and network engine. One of the key design challenges for client is that the user should experience smoothly evolving and plausible virtual reality despite of network and server lag. Even writing stand alone 3D games with smooth game play is not easy. Consequently clients are often written with C++ (no garbage collection lag) and have only one executing thread (no unpredictable short thread stalls). Exceptions to this rule are long lasting and unpredictable operations like hard drive access and network transmission which should be executed in a dedicated thread. Another good design principle for real time applications is “keep it simple (s)” and if possible reserve required data structures at initialization phase (no memory leaks at runtime). If one considers client purely as a user interface it is possible to concentrate on rendering engine, UI-framework and network engine without creating overtly complex system. {{VirtualRealityArchitecture.jpg|Reference Architecture}} Virtual reality server has quite a few roles to fulfill: physics engine, rule engine, artificial intelligence, virtual reality object model, model persistency, simulation control, server management and network connectivity. Network connectivity can be further divided to network engine, command processor, state synchronizer, session management, media sharing and IAM (identity and access management). Many of these roles are clearly separated and it is tempting to divide them to several separate server applications. However complexity tends to cause problems. Heterogeneous distribution is harder to administrate and is more prone to failures than homogenous server cluster with load balancing. One good way to do heterogeneous distribution is to divide real time and non real time functionality to separate servers. Another way is to distinguish between high trust and medium trust services thus separating key services to trusted parties and leaving the bulk computing load to less secure servers. These rules suggest a threefold server division: virtual reality server (bulk computing), identity server(s) (high trust and virtual reality integration services) and file server(s). Virtual reality server is a near real time simulation application running the virtual environment simulation. The core components are virtual reality object model (simulation state), physics engine (provides elementary physics), rule engine (scripted object interaction and object internal functionality), artificial intelligence (scripted AI-functionality) and simulation control (coordinates simulation execution and rule execution stack). Virtual reality server could be implemented with C++ (high performance) or .NET/Java (higher level language providing cleaner code base). The most common way of load balancing between virtual reality servers is spatial division (each server simulates separate volume). Identity servers are important building block for global virtual reality where avatars and other objects can traverse between servers. They can be compared to DNS network in architectural sense. Identity servers govern both user and machine identities. They may also govern object identities which are in transit from server to server. Identity information in this context consists of identification, authentication, role, category, statistics and location information. Identity servers need not be virtual reality specific solutions but existing identity governing standards and systems can be utilized. File servers are version aware file repositories providing all shared files for the virtual reality system: client binaries, server binaries and media files. Existing versioned file sharing frameworks can be utilized without additional requirements. System components like clients and servers should be relatively easy to develop and integrate. Such global open virtual reality network requires that all system components converse with each other utilizing well defined protocols.

Advanced Grid Configurations 1.0

Tommi S.E. Laukkanen — 2009-06-14T12:44:27Z

This page contains discussion about advanced grid configurations. In other words how simulation nodes can be located in virtual space to produce optimal performance from both network and cpu consumption perspectives. Another important characteristics is the relative maximum size of objects compared to the simulation node sizes. The following examples demonstrate how these characteristics vary depending on the chosen configuration. In practice these configurations may vary in different virtual locations of the grid depending on the requirements and importance of the volume in question. If you know other good configurations or existing articles please refer them here or extend this article. Critique is very much welcome as well. We will use the following values in the performance requirement calculations: * Observation Frame Size: 64 bytes * Observation Frequency: 1/s * Bandwidth Available for Each Simulation Node: 100 Mbits/s * Bandwidth Available for Each Simulation Client: 250 kbits/s * Bandwidth Reserved for Node to Node Communication: 25 Mbits/s * Node Observation Distance to Outside Node Volume: Node Width / 2 * Maximum Object Size: Node Observation Distance / 2 = Node Width / 4 * Maximum Clients per Node: 300 (See: [[Performance]]) * Maximum Observer Objects per Client: 400 (See: [[Performance]]) == Simple Cubic Lattice == Simplest grid configuration is simple cubic lattice as illustrated in the following picture in 2D: {{setp_grid_configuration_simple_cubic.png}} Simple cubic configuration does not provide redundancy or local load balancing. Local load balancing means that the same space is simulated by several simulations which exchange state information. One object is simulated by one simulation and one client is connected to one simulation at a time. All the servers need to simulate each object with simple 3d physics model to predict movement but the internal state is simulated only by one simulation. Different simulations may be run by different service providers and they may have different implementations. Local load balancing offers networking benefits as clients can be directed to different simulations. For example client could choose to join the simulation with lowest ping or one with well compliant implementation. The same configuration illustrated in 3D: {{setp_grid_configuration_simple_cubic_3d.png}} === Bandwidth Considerations for Simple Cubic Lattice === * Number of Total Observing Nodes: 26 * Number of Effective Observing Nodes (per object): 7 * Effective Node to Node Observation Bandwidth per Object: 448 bytes / s * Maximum Number of Objects per Node: 25 Mbits/s / 448 bytes / s = 3550 * Maximum Number of Objects per Cube Volume: 5580 * Maximum Number of Clients per Cube Volume: 300 == Dual Cubic Lattice == Dual cubic lattice consists of two intersecting simple cubic lattices as illustrated in the following 2D picture: {{setp_grid_configuration_dual_cubic.png}} Dual cubic configuration offers spatial load balancing, local load balancing and redundancy. In redundant grid one simulation node may shutdown and the grid remains accessible in that location. Whether the objects in the simulation which was shutdown still exist after the event depends on succesful migration of the objects to the other simulation nodes governing that volume. Dual cubic lattice also minimizes the amount of offline volume down to 1/8th of node volume when two overlapping nodes shutdown simultaneously. === Bandwidth Considerations for Dual Cubic Lattice === * Number of Total Observing Nodes: 26 + 8 = 35 * Number of Effective Observing Nodes (per object): 11 * Effective Node to Node Observation Bandwidth per Object: 704 bytes / s * Maximum Number of Objects per Node: 3550 * Maximum Number of Objects per Cube Volume: 2*3550 = 7100 * Maximum Number of Clients per Cube Volume: 2*300 = 600

Environment Model 1.0

Tommi S.E. Laukkanen — 2009-06-14T12:43:52Z

Environment model is that of present day social 3d environments, online games and first person shooters: # Environment is divided into simulation nodes which are simulated by separate servers (load balancing). # Map. Slowly changing part of the environment. 3d engine handles this part as a static "level" map. Each simulation provides its own map. Maps need to be compatible at connection points to other simulations. Each map could be defined as a Collada model. # Dynamic objects. Dynamic objects are all the objects in the environment which can move or interact. Dynamic objects are presented by Collada models and can have animation state. All state changes inside one dynamic object is presented as animation to the user. As a thumb of rule all objects are directly connected to root coordinate space from the protocol perspective. Simulation may internally use nested coordinate spaces in other words transformation hierarcies for simulating attachments and forces between objects. When the object movement is presented in observation messages all the values are given in root coordinate space. Migrations may need to support nesting to inform target simulation about relations between objects that are migrating between simulations. # Avatar is the dynamic object representing users chosen virtual identity in the environment. {{setp_observation_flow_illustration.png}}

Background Reading 1.0

Tommi S.E. Laukkanen — 2009-06-14T12:43:14Z

== Articles about Network Protocols and Implementations == [[http://www.gamasutra.com/view/feature/3094/1500_archers_on_a_288_network_.php| Network Programming in Age of Empires and Beyond at Gamasutra]] [[http://www.gamasutra.com/view/feature/3374/the_internet_sucks_or_what_i_.php?page=1| The Internet Sucks Or, What I Learned Coding X-Wing vs. TIE Fighter at Gamasutra]] [[http://www.gamasutra.com/features/19970919/aronson_01.htm|Dead Reckoning at Gamasutra]] [[http://gafferongames.wordpress.com/networking-for-game-programmers/|Networking for Game Programmers at Gaffer on Games]] [[http://www.gamedev.net/community/forums/showfaq.asp?forum_id=15|GameDev.net FAQ Multiplayer and Network Programming]] == Media Standards == [[http://www.collada.org/mediawiki/index.php/Main_Page|COLLADA is an open digital-asset exchange schema for the interactive 3D industry.]] == Networking Libraries == [[http://www.opentnl.org/|OpenTNL - The Torque Network Library]] [[http://www.zoidcom.com/|The Zoidcom network library is a high-level, UDP based networking library]] == Open Source Virtual Reality Implementations == [[http://opensimulator.org/wiki/Main_Page|Open Simulator]] [[http://www.realxtend.com/|realXtend]] == Protocol Definition Efforts == [[http://www.gamers.org/dEngine/quake/QDP/qnp.html|Quake I Network Protocol]] [[http://www.csse.monash.edu.au/~timf/bottim/q2net/q2network-0.03-1.html|Quake II Network Protocol]] [[http://www.tilion.org.uk/Games/Quake_3/Network_Protocol|Quake III Network Protocol]] [[http://web.nps.navy.mil/~brutzman/vrtp/|Virtual Reality Transfer Protocol by Naval Postgraduate School]] [[http://en.wikipedia.org/wiki/Distributed_Interactive_Simulation|Distributed Interactive Simulation (DIS) at Wikipedia]] [[http://www.web3d.org/x3d/specifications/ISO-IEC-FDIS-19775-1.2-X3D-AbstractSpecification/|X3D DIS Component by Web 3D Consortium]] [[http://wiki.secondlife.com/wiki/Protocol|Second Life Protocol at Second Life Wiki]] [[http://wiki.secondlife.com/w/index.php?title=Category:Messages|Second Life Messages at Second Life Wiki]] [[http://wiki.secondlife.com/wiki/Open_Grid_Protocol|Open Grid Protocol at Second Life Wiki]] [[http://www.interopworld.com/vwsis|Virtual World System Interoperability Standard]]

SETP 0.1 DRAFT 1.0

Tommi S.E. Laukkanen — 2009-06-14T12:42:36Z

== Protocol Specification == Low level transport protocol is UDP. Each UDP packet may contain one or more frames. Most messages will have length of just one frame. === UDP Packet Structure === UDP Packet length is maximum of 1500 bytes which consists of header bytes and as many frames as fit in the remaining bytes. udp header (18 bytes) - message frames * 4 - session id: Session id assigned by answering party (UINT) * 4 - packet id: Packet id(UINT) * 8 - first send time: Time the packet was sent for the first time. (TIMESTAMP) * 1 - quaranteed: Whether this is guaranteed and ACK is expected. (UBYTE) * 1 - resend count: Count of resends. (UBYTE) === Frame Structure (maximum 256 bytes) === frame header (10 bytes) - frame data (maximum 246 bytes) frame header: * 1 - type: Type index from message type table. (UBYTE) * 4 - message id: Message id assigned by the sender. Overflows periodically. (UINT) * 2 - frame count: Number of frames in this message. (USHORT) * 2 - frame index: Index of the message part for long messages spanning over multiple packets. (USHORT) * 1 - frame data size (0-246) 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. == Transport Control Messages == === Disconnect Notification === quaranteed: 1 data: - === Keepalive === guaranteed: 1 data: - === Acknowledgement === guaranteed: 0 data: * 4- acknowledged upd packet id (Repeated 1-64 times) (ULONG(s)) === Throttling Notification === guaranteed: 1 data: * 4 - bytes per second. Number of bytes per second sender is ready to receive. (UINT) == Implementation Validation Messages == === Challenge Request === guaranteed: 1 data: * 64 - Challenge request bytes. (DATA) === Challenge Response === guaranteed: 1 data: * 64 - Challenge response bytes. (DATA) == Client to Server Connecting Messages == === Connect Request === guaranteed: 1 session id: - (no session id in connect. Session id is returned in first frame from server which is always ACK.) data: * 60 - client program name (STRING) * 1 - client program major version (UBYTE) * 1 - client program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 32 - user identifier (uuid or user name) (UUID/STRING) * 32 - user passphrase (authentication session uuid or password) (UUID/STRING) Server responds with disconnect if credentials are incorrect or suitable encoding is not found and with connect response if credentials were correct. Simple implementations may create accounts on the fly. Advanced servers may offer web interface for account management. === Connect Success Response === guaranteed: 1 data: * 32 - server name (STRING) * 28 - server program name (STRING) * 1 - server program major version (UBYTE) * 1 - server program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 64 - grid url (STRING) * 64 - media repository url (STRING) * 16 - media packet id (UUID) * 1 - media packet major version (UBYTE) * 1 - media packet minor version (UBYTE) === Connect Failure Response === guaranteed: 1 data: * 32 - server short description (STRING) * 28 - server program name (STRING) * 1 - server program major version (UBYTE) * 1 - server program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 1 - failure code (0 - authentication failed, 1 - not authorized, 2 - unsupported client implementation or version, 3 - unsupported protocol version) (UBYTE) == Client to Server Query Messages == === List Simulations Request === guaranteed: 1 data: - === List Simulations Response === guaranteed: 1 data: Entries repeat as many times as there are simulations. * 16 - simulation identifier: Simulation identifier. (UUID) * 16 - map identifier: Map identifier if map exists. (UUID) * 32 - simulation short description. (STRING) This message may be split to multiple frames. === List Avatars Request === guaranteed: 1 data: * 16 - simulation identifier: Simulation identifier. (UUID) === List Avatars Response === guaranteed: 1 data: Entries repeat as many times as there are avatars. * 16 - avatar identifier: Avatar identifier. (UUID) * 16 - avatar model identifier. (UUID) * 32 - avatar short description. This message may be split to multiple frames. == Client to Simulation Joining Messages == === Join Simulation Request === guaranteed: 1 data: * 16 - simulation identifier: Simulation identifier. (UUID) * 16 - avatar identifier: Avatar identifier. (UUID) === Join Simulation Response === guaranteed: 1 data: * 1 - success: Success of the join. (1 or 0) (UBYTE) === Leave Simulation Notification === guaranteed: 1 data: - This notification can be sent by either party to nofity other about client detaching from the simulation. The operation will always work. == Simulation to Simulation Linking Messages == === Simulation Link Request Message === guaranteed: 1 session id: - (no session id in connect. Session id is returned in first frame from server which is always ACK.) data: * 64 - grid url (STRING) * 16 - simulation id (UUID) * 60 - calling server program name (STRING) * 1 - calling server program major version (UBYTE) * 1 - calling server program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 16 - target simulation identifier: Simulation identifier. (UUID) * 12 - relative location of simulation cube center (vector3(FLOAT)) * 4 - simulation cube width (FLOAT) * 4 - observation cube width (FLOAT) * 4 - approximate simulation cycle length (microseconds) (UINT) Two different grids can also link. In this case linking volume should be limited to be between two simulations and grid portal volume should be clearly marked in the virtual environment. === Simulation Link Success Response Message === guaranteed: 1 data: * 64 - grid url (STRING) * 44 - answering server program name (STRING) * 1 - answering server program major version(UBYTE) * 1 - server program minor version(UBYTE) * 1 - protocol major version(UBYTE) * 1 - protocol minor version(UBYTE) * 4 - simulation cube width (FLOAT) * 4 - observation cube width (FLOAT) * 4 - approximate simulation cycle length (microseconds) (UINT) * 4 - Number of linked simulations <-- Frame Changes --> The following fields area repeated for each existing linked simulation N times. * 16 - simulation id (UUID) * 88 - Address * 4 - Port * 12 - relative location of simulation cube center (vector3(FLOAT)) * 4 - simulation cube width (FLOAT) * 4 - observation cube width (FLOAT) === Simulation Link Failure Response Message === data: * 64 - grid url (STRING) * 28 - answering server program name (STRING) * 1 - answering server program major version(UBYTE) * 1 - server program minor version(UBYTE) * 1 - protocol major version(UBYTE) * 1 - protocol minor version(UBYTE) * 1 - error code (0 - unauthorized, 1 - unsupported server implementation or version, 2 - unsupported protocol version) (UBYTE) == Simulation Messages == === Object Examine by ID === guaranteed: 1 * 16 - object identifier (UUID) Response will consists of object observation and if required movement and animation observations. === Object Examine by Index === guaranteed: 1 * 4 - object index (Zero based index to table of objects known to server.) Response will consists of object observation and if requid animation observations. === Object Observation === guaranteed: 1 * 16 - object identifier (UUID) * 16 - type identifier (UUID) * 16 - model identifier (UUID) * 16 - simulation identifier (UUID) * 4 - object index (Zero based index to table of objects known to server.) * 4 - bounding sphere radius (FLOAT) * 4 - mass (FLOAT) * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT) * 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT) * 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 4 - object internal data length (UINT) * X - object internal data (As long as needed may cause message to be splitted to several frames) (DATA) === Velocity Observation === guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data: * 4 - object index * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT) * 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) === Acceleration Observation === guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data: * 4 - object index * 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT) * 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) Send when acceleration changes and at ~10 seconds intervals. === Animation Observation === guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data: * 4 - object index * 2 - number of animations executing. The following are repeated X times. * 4 - animation identifier * 4 - animation length (milliseconds) (UINT) * 4 - animation phase (milliseconds) (UINT) * 1 - animation state (0=halted, 1=run once, 2 repeat) * 3 - padding === Disappearence Observation === guaranteed: 1 * 4 - object index === Collision Notification === guaranteed: 1 * 4 - source object index * 4 - target object index Collision notification is sent when two dynamic objects collide and they are simulated by different simulations. When either simulation detects collision it calculates collision response to the object it owns and sends collision notification to the other simulation. When simulation receives a collision notification it calculates the collision response to the object it owns unless it has already detected the collision. === Action Request === guaranteed: 1 * 18 - action name (STRING) * 1 - target type : (0: self, 1: object, 2: location, 3: direction, 4 volume) (UBYTE) * 1 - is data public: (1 or 0) (UBYTE) * 4 - source object index * 4 - target object index * 4 - volume sphere radius (FLOAT) * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 4 - action request data length (UINT) * X - action request data (As long as needed. May cause message to be splitted to several frames.) (DATA) === Action Response === guaranteed: 1 * 1 - success (1 or 0) (UBYTE) * 4 - action response data length (UINT) * X - action response data (DATA) === Action Observation === guaranteed: 1 * 18 - action name (STRING) * 1 - target type : (0: self, 1: object, 2: location, 3: direction, 4 volume) (UBYTE) * 1 - is data public: (1 or 0) (UBYTE) * 4 - source object index * 4 - target object index * 4 - volume sphere radius (FLOAT) * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 4 - action request data length (UINT) * X - action request data (No data if data is private.) (DATA) * 4 - action response data length (UINT) * X - action response data (DATA) === Migration Request === guaranteed: 1 * 16 - object identifier (UUID) * 12 - source location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - target location (vector3) (FLOAT,FLOAT,FLOAT) * 8 - object internal data length (ULONG) * 16 - source simulation identifier (UUID) * 16 - target simulation identifier (UUID) * 4 - object internal data length * X - object internal data (As long as needed. May cause message to be splitted to several frames.) Migration is moving from one simulation node to another simulation node. === Migration Response=== guaranteed: 1 * 1 - success (1 or 0) === Migration Observation === guaranteed: 1 * 16 - object identifier (UUID) * 12 - source location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - target location (vector3) (FLOAT,FLOAT,FLOAT) * 16 - source simulation identifier (UUID) * 16 - target simulation identifier (UUID)

SETPCICP 0.2 DRAFT 1.0

Tommi S.E. Laukkanen — 2009-06-14T12:42:02Z

== SETP/CICPv2 Draft 0.2 == Low level transport protocol is UDP. Each UDP packet may contain one or more frames. Most messages will have length of just one frame. === Statistics === Protocol has currently total of 38 messages defined: * 3 client to server connection messages * 3 simulation to simulation connection messages * 4 connection control messages * 2 implementation validation messages * 4 client to server query messages (avatars and simulations) * 3 client to simulation joining messages * 20 simulation messages (queries, perceptions, interactions, handovers and injections) === UDP Packet Data Structure === UDP 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 header (18 bytes) - message frames * 4 - session id: Session id assigned by answering party (UINT) * 4 - packet id: Packet id(UINT) * 8 - first send time: Time the packet was sent for the first time. (TIMESTAMP) * 1 - quaranteed: Whether this is guaranteed and ACK is expected. (UBYTE) * 1 - resend count: Count of resends. (UBYTE) === Frame Structure (maximum 256 bytes) === frame header (10 bytes) - frame data (maximum 246 bytes) frame header: * 1 - type: Type index from message type table. (UBYTE) * 4 - message id: Message id assigned by the sender. Overflows periodically. (UINT) * 2 - frame count: Number of frames in this message. (USHORT) * 2 - frame index: Index of the message part for long messages spanning over multiple packets. (USHORT) * 1 - frame data size (0-246) 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. == Connection Control Messages == === Disconnect Notification === quaranteed: 1 data: - === Keepalive === guaranteed: 1 data: - === Acknowledgement === guaranteed: 0 data: * 4- acknowledged upd packet id (Repeated 1-64 times) (ULONG(s)) === Throttling Notification === guaranteed: 1 data: * 4 - bytes per second. Number of bytes per second sender is ready to receive. (UINT) == Implementation Validation Messages == === Challenge Request === guaranteed: 1 data: * 64 - Challenge request bytes. (DATA) === Challenge Response === guaranteed: 1 data: * 64 - Challenge response bytes. (DATA) == Client to Server Connecting Messages == === Connect Request === guaranteed: 1 session id: - (no session id in connect. Session id is returned in first frame from server which is always ACK.) data: * 60 - client program name (STRING) * 1 - client program major version (UBYTE) * 1 - client program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 32 - user identifier (uuid or user name) (UUID/STRING) * 32 - user passphrase (authentication session uuid or password) (UUID/STRING) Server responds with disconnect if credentials are incorrect or suitable encoding is not found and with connect response if credentials were correct. Simple implementations may create accounts on the fly. Advanced servers may offer web interface for account management. === Connect Success Response === guaranteed: 1 data: * 32 - server name (STRING) * 28 - server program name (STRING) * 1 - server program major version (UBYTE) * 1 - server program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 64 - bubble cloud url (STRING) * 64 - media repository url (STRING) * 16 - media packet id (UUID) * 1 - media packet major version (UBYTE) * 1 - media packet minor version (UBYTE) === Connect Failure Response === guaranteed: 1 data: * 32 - server short description (STRING) * 28 - server program name (STRING) * 1 - server program major version (UBYTE) * 1 - server program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 1 - failure code (0 - authentication failed, 1 - not authorized, 2 - unsupported client implementation or version, 3 - unsupported protocol version) (UBYTE) == Client to Server Query Messages == === List Bubbles Request === guaranteed: 1 data: - === List Bubbles Response === guaranteed: 1 data: Entries repeat as many times as there are bubbles. * 16 - bubble identifier (UUID) * 48 - simulation short description. (STRING) This message may be split to multiple frames. === List Avatars Request === guaranteed: 1 data: * 16 - simulation identifier: Bubble identifier. (UUID) === List Avatars Response === guaranteed: 1 data: Entries repeat as many times as there are avatars. * 16 - avatar identifier: Avatar identifier. (UUID) * 16 - avatar model identifier. (UUID) * 32 - avatar short description. This message may be split to multiple frames. == Client to Simulation Joining Messages == === Join Bubble Request === guaranteed: 1 data: * 16 - bubble identifier (UUID) * 16 - avatar identifier (UUID) === Join Bubble Response === guaranteed: 1 data: * 1 - success: Success of the join. (1 or 0) (UBYTE) === Leave Bubble Notification === guaranteed: 1 data: - This notification can be sent by either party to nofity other about client detaching from the simulation. The operation will always work. == Simulation to Simulation Connection Messages == === Bubble Link Request Message === guaranteed: 1 session id: - (no session id in connect. Session id is returned in first frame from server which is always ACK.) data: * 60 - calling server program name (STRING) * 1 - calling server program major version (UBYTE) * 1 - calling server program minor version (UBYTE) * 1 - protocol major version (UBYTE) * 1 - protocol minor version (UBYTE) * 64 - calling cloud url (STRING) * 16 - calling bubble id (UUID) * 16 - target bubble identifier (UUID) * 12 - relative location of calling bubble center (answering bubble coordinate space)(vector3(FLOAT)) * 4 - bubble range (FLOAT) * 4 - bubble perception range (FLOAT) * 4 - simulation cycle length (microseconds) (UINT) Two different cloudscan also link. In this case linking volume should be limited to be between two bubbles and cloud portal volume should be clearly marked in the virtual environment. === Bubble Link Success Response Message === guaranteed: 1 data: * 64 - cloud url (STRING) * 44 - answering server program name (STRING) * 1 - answering server program major version(UBYTE) * 1 - server program minor version(UBYTE) * 1 - protocol major version(UBYTE) * 1 - protocol minor version(UBYTE) * 4 - bubble range (FLOAT) * 4 - bubble perception range (FLOAT) * 4 - simulation cycle length (microseconds) (UINT) * 4 - Number of linked bubbles <-- Frame Changes --> The following fields area repeated for each existing linked simulation N times. * 16 - bubble id (UUID) * 88 - Address * 4 - Port * 12 - relative location of bubble center (vector3(FLOAT)) * 4 - bubble range (FLOAT) * 4 - bubble perception range (FLOAT) === Bubble Link Failure Response Message === data: * 64 - cloud url (STRING) * 28 - answering server program name (STRING) * 1 - answering server program major version(UBYTE) * 1 - server program minor version(UBYTE) * 1 - protocol major version(UBYTE) * 1 - protocol minor version(UBYTE) * 1 - error code (0 - unauthorized, 1 - unsupported server implementation or version, 2 - unsupported protocol version) (UBYTE) == Simulation Messages == === Object Examine by ID === guaranteed: 1 * 16 - object identifier (UUID) Response will consists of object observation and if required movement and animation observations. === Object Examine by Index === guaranteed: 1 * 4 - object index (Zero based index to table of objects known to server.) Response will consists of object observation and if requid animation observations. === Object Perception === guaranteed: 1 * 16 - object identifier (UUID) * 16 - type identifier (UUID) * 16 - model identifier (UUID) * 16 - simulation identifier (UUID) * 4 - object index (Zero based index to table of objects known to server.) * 4 - bounding sphere radius (FLOAT) * 4 - mass (FLOAT) * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT) * 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT) * 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 4 - object internal data length (UINT) * X - object internal data (As long as needed may cause message to be splitted to several frames) (DATA) === Movement Perception === guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data: * 4 - object index * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT) * 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) === Advanced Movement Perception === guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data: * 4 - object index * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT) * 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT) * 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) Send when acceleration changes and at ~10 seconds intervals. === Animation Perception === guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data: * 4 - object index * 2 - number of animations executing. The following are repeated X times. * 4 - animation identifier * 4 - animation length (milliseconds) (UINT) * 4 - animation phase (milliseconds) (UINT) * 1 - animation state (0=halted, 1=run once, 2 repeat) * 3 - padding === Disappearence Perception === guaranteed: 1 * 4 - object index === Collision Perception === guaranteed: 1 * 4 - source object index * 4 - target object index Collision notification is sent when two dynamic objects collide and they are simulated by different simulations. When either simulation detects collision it calculates collision response to the object it owns and sends collision notification to the other simulation. When simulation receives a collision notification it calculates the collision response to the object it owns unless it has already detected the collision. === Interaction Request === guaranteed: 1 * 18 - action name (STRING) * 1 - target type : (0: self, 1: object, 2: location, 3: direction, 4 volume) (UBYTE) * 1 - is data public: (1 or 0) (UBYTE) * 4 - source object index * 4 - target object index * 4 - volume sphere radius (FLOAT) * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 4 - action request data length (UINT) * X - action request data (As long as needed. May cause message to be splitted to several frames.) (DATA) === Interaction Response === guaranteed: 1 * 4 - message id * 1 - success (1 or 0) * 124 - failure message (STRING) * 4 - action response data length (UINT) * X - action response data (DATA) === Interaction Perception === guaranteed: 1 * 18 - action name (STRING) * 1 - target type : (0: self, 1: object, 2: location, 3: direction, 4 volume) (UBYTE) * 1 - is data public: (1 or 0) (UBYTE) * 4 - source object index * 4 - target object index * 4 - volume sphere radius (FLOAT) * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 4 - action request data length (UINT) * X - action request data (No data if data is private.) (DATA) * 4 - action response data length (UINT) * X - action response data (DATA) === Handover Request === guaranteed: 1 * 16 - object identifier (UUID) * 12 - source location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - target location (vector3) (FLOAT,FLOAT,FLOAT) * 8 - object internal data length (ULONG) * 16 - source simulation identifier (UUID) * 16 - target simulation identifier (UUID) * 4 - object internal data length * X - object internal data (As long as needed. May cause message to be splitted to several frames.) Handover is a process where object is handed over from one bubble to another bubble. === Handover Response=== guaranteed: 1 * 4 - message id * 1 - success (1 or 0) * 124 - failure message (STRING) === Handover Perception === guaranteed: 1 * 16 - object identifier (UUID) * 12 - source location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - target location (vector3) (FLOAT,FLOAT,FLOAT) * 16 - source simulation identifier (UUID) * 16 - target simulation identifier (UUID) === Injection Request === guaranteed: 1 * 16 - object identifier (UUID) * 16 - type identifier (UUID) * 16 - model identifier (UUID) * 16 - simulation identifier (UUID) * 4 - object index (Zero based index to table of objects known to server.) * 4 - bounding sphere radius (FLOAT) * 4 - mass (FLOAT) * 12 - location (vector3) (FLOAT,FLOAT,FLOAT) * 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT) * 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT) * 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT) * 4 - object internal data length (UINT) * X - object internal data (As long as needed may cause message to be splitted to several frames) (DATA) Injection is a process where participant injects an object to a bubble. Injected object is governed by the participant and all interaction requests should be forwarded to it. === Injection Response=== guaranteed: 1 * 4 - message id * 1 - success (1 or 0) * 124 - failure message (STRING) === Ejection Request=== guaranteed: 1 * 16 - object identifier (UUID) Ejection is a process where participant ejects object it owns from the world. === Ejection Response=== guaranteed: 1 * 4 - message id * 1 - success (1 or 0) * 124 - failure message (STRING)

MXP over UDP Specification Draft 0.3 1.0

Tommi S.E. Laukkanen — 2009-06-14T12:41:33Z

One 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://

://}}} {{mxp_udp.png}} === Byte ordering === http://en.wikipedia.org/wiki/Endianness Little-endian byte ordering is used. === Floating Point Encoding === The 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 Encoding === [http://www.ietf.org/rfc/rfc4122.txt] === Types === double: 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? // * Proposal: microseconds since 1.1.2000 00:00 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 Data === UDP 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 Messages == **ACKNOWLEDGE 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 Messages == **CHALLENGE REQUEST 4** {{{ 64 : data : challenge_request_data }}} **CHALLENGE RESPONSE 5** {{{ 64 : data : challenge_response_data }}} == Reusable Fragments == **RESPONSE 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 }}} **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 : state_payload_dialect 4 : uint : state_payload_length X : data : state_payload }}} **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 : interaction_payload_dialect 4 : uint : interaction_payload_length X : data : interaction_payload_data }}} **BUBBLE FRAGMENT** {{{ 16 : uuid : bubble_id 40 : string : bubble_name 55 : string : cloud_url /* Cloud web site url identifying the cloud in question. */ 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 }}} // Frame data length == 195 // == Commands == === Participant to Bubble Commands === **JOIN REQUEST 10** {{{ 16 : uuid : bubble_id 32 : string : location /* this could be parsed by human interface from uri */ 95 : string : identity_provider_url /* for example OpenId provider url */ 32 : string : participant_name 32 : string : participant_passphrase 4 : time : participant_realtime PROGRAM FRAGMENT : client_program }}} **JOIN RESPONSE 11** {{{ RESPONSE FRAGMENT 40 : string : bubble_name 55 : string : cloud_url /* Cloud web site url identifying the cloud in question. */ 16 : uuid : participant_id /* id of the participant if join was succesful or empty id. */ 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 Commands === **LIST 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 Commands === ** ATTACH 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 }}} == Events == **PERCEPTION 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 : action_request_payload_dialect 4 : uint : action_request_payload_length X : data : action_request_payload_data }}} **HANDOVER EVENT 53**: Object was handed over from one bubble to another {{{ HANDOVER REQUEST }}} === Event Candidates === ** COMPRESSED 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. === Obsolete Events === **INJECTION 50**: An object has been injected. {{{ OBJECT FRAGMENT }}} **EJECTION 51**: An object has been ejected. Contains the same eject. {{{ EJECT REQUEST }}} **INTERACTION 52**: Participant and object or two objects have interacted. Sent only if interaction is public. {{{ INTERACTION REQUEST AND INTERACTION RESPONSE }}}