Difference between revisions of "Protocol"

From Sirikata Wiki
Jump to navigation Jump to search
Line 1: Line 1:
−
Our wire protocol is written in PBJ[http://github.com/danielrh/pbj] which right now compiles directly into protocol buffers but could theoretically target numerous serialization formats.
+
== High Level Interaction Overview ==
 +
In this document we use the word Client interchangably with the phrase
 +
"Object Host" when referring to a 3rd party connecting to a space server
 +
to become part of that space. Traditionally Clients host a single
 +
object: the camera, which maintains a perspective query of the
 +
surrounding environment, but this is left up to the client
 +
implementation and the policies in the space: you may find clients
 +
hosting avatars, bots, or other objects in a given world.
  
−
package Sirikata.Protocol;
+
Object hosts simulate individual objects and facilitate these objects to
−
   
+
each connect to one or more spaces.  Once an object connects to a space,
−
/////////////Standard Message Container///////////////
+
it may communicate with that space to setup standing queries for nearby
−
+
or important objects, advertise its position or send messages to
−
//This is the standard message container. All items sent over the wire should be of type Message
+
objects for which it knows the identifier.
−
message Message {
+
 
−
+
A typical client behavior involves the following steps
−
    //the destination ObjectReference (space is implicit) if omitted, space is destination
+
* Connect camera object to space server
−
    optional uuid destination_object = 1;
+
* Upon connection, register for a new object Id with desired position
−
+
* Setup a proximity query for nearby objects that occupy N pixel area on its screen
−
    //optional spaceID of the destination object (in case we have a space routing messages, or it is not otherwise implicit)
+
 
−
+
At this point the camera object will be ready to receive standing query
−
    optional uuid destination_space = 2;
+
results of nearby objects.  As these come in, the client will likely
−
+
wish to act upon them.
−
    //the source ObjectReference (space is implicit)
+
 
−
    optional uuid source_object = 3;
+
As a proximity request is returned the client is likely to perform the
−
+
following steps
−
    //the spaceID origin message (in case we have a space routing messages)
+
* Examine the proximity response and understand any bundled data (which may include current location, mesh data, type, etc)
−
    optional uuid source_space = 4;
+
* Construct a message asking that object for remaining data including
−
+
** Mesh URI
−
    //the message id for the function call request, so out of order messages may be detected and return values may be paired.  
+
** Position
−
    optional int64 id = 5;
+
** Light information
−
   
+
** ...
−
    //the name of the function(s) to call
+
Once the Data is retrieved, the object may be displayed on the client.
−
    repeated string message_names=6;
+
In the future the client may setup an individual subscription for
−
+
location updates and other properties of interest with the relevant
−
    //message to be decoded by the function(s). Length must match the number of strings unless return_status set and function's length is 0
+
subscription service. The subscription service is optional and the
−
    repeated bytes message_arguments=7;
+
client must not rely on such a service being present. In the absence of
−
+
such a service, asking the location service for location updates at a
−
    //the message is a response to a previous message.
+
rate proportional to the distance^2 of the object is sufficient.
−
    enum ReturnStatus {
+
 
−
      SUCCESS = 0;
+
Clients may wish to interact with objects in the scene (asking them to
−
      NETWORK_FAILURE = 1;
+
move, changing their properties, etc). This is accomplished through
−
      SECURITY_FAILURE = 2;
+
sending a message to that object on a number of ports. The standard
−
    }
+
message goes to the object on port 0 and invokes a scripting language
−
    optional ReturnStatus return_status=8;
+
function on that object by that name with the provided binary string
−
}
+
argument.
−
+
 
−
/////////////Built-in messages///////////////
+
== Low Level Network Protocols ==
−
+
Sirikata is planned to support 2 low level protocols
−
//This message is from a space to an object updating its position and orientation (returns void)
+
* TCP under TCPSST
−
message ObjLoc {
+
* UDP under ENET
−
+
All components of the system should be able to speak both protocols so the best may be selected for the given circumstance.
−
    //time that the update was sent out
+
 
−
    optional time timestamp = 2;
+
===TCPSST===
−
+
TCPSST is an effort to build a structured streams-like abstraction ontop of TCP by using a handful of individual TCP streams over which to multiplex a number of independent SubStreams. Clients may choose to connect to servers with one or more TCP streams using a handshake that pairs them up appropriately. The default is 3 TCP streams per TCPSST connection. This setup prevents head of line blocking and allows unordered messages to be sent on the least congested stream.
−
    //position of source object
+
 
−
    optional vector3d position = 3;
+
====Handshake====
−
+
every stream begins with the 6 characters SSTTCP then 2 characters delineating in human readable how many streams will be associated with this connection (up to 99) and then a UUID for this connection.
−
    //orientation of source object
+
This data will be used by the server to pair up the connections and treat them as a single overarching TCPSST stream.
−
    optional quaternion orientation = 4;
+
The server then sends back a similar handshake header with its own unique UUID to acknowledge the connection pairing.
−
+
 
−
    //velocity of the source object at snapsot
+
====Framing====
−
    optional vector3f velocity = 5;
+
After the handshake is complete, data may be sent across the bidirectional sockets as long as each packet of data is preceeded by a packet size (including all following data including the substream identifier) and a substream identifier
−
 
−
    //axis of rotation of source object
 
−
    optional normal rotational_axis = 7;
 
−
 
−
    //speed of rotation around axis (may be negative)
 
−
    optional float angular_speed = 8;
 
−
 
−
    //Force update send out even if last update is within range (often useful for final resting pos)
 
−
    flags8 UpdateFlags{
 
−
            FORCE=1;
 
−
    }
 
−
    //options for this update, right now only force is the option
 
−
    optional UpdateFlags update_flags = 6;
 
−
}
 
−
 
−
//New Streams can establish an ObjectConnection
 
−
  message NewObj {
 
−
    ///key to indicate how an object's ObjectReference should be restored
 
−
    optional uuid object_uuid_evidence=2;
 
−
    ///The object host may request a position for a newly created object
 
−
    optional ObjLoc requested_object_loc=3;
 
−
    ///the bounding sphere for the mesh, so that proximity detection can begin right away
 
−
    optional boundingsphere3f bounding_sphere=4;
 
−
}
 
−
 
−
 
−
//This will be in the argument for the return value of the NewObj function
 
−
message RetObj {
 
−
    //return value for NewObj message
 
−
    optional uuid object_reference = 2;
 
−
    //the definitive location of the object
 
−
    optional ObjLoc location=3;
 
−
    ///the defininitive bounding sphere for the mesh: may be smaller than the requested bounding sphere due to policy
 
−
    optional boundingsphere3f bounding_sphere=4;
 
−
}
 
−
 
−
//This message indicates an object has disconnected and should be removed from space. Shutting down the connection can accomplish the same (returns void)
 
−
message DelObj {
 
−
}
 
−
 
−
message NewProxQuery {
 
−
 
−
    //the client chosen id for this query
 
−
    optional uint32 query_id=2;
 
−
 
−
    //If present and set to true, the query is fired once, the relevant items are returned and the query is forgotten
 
−
    optional bool stateless=3;
 
−
 
−
    //the relative offset from the source object
 
−
    optional vector3f relative_center=4;
 
−
 
−
    //an absolute query center...this ignores the source object
 
−
    optional vector3d absolute_center=5;
 
−
 
−
    //query returns all objects within this many meters
 
−
    optional float max_radius=6;
 
−
 
−
    //query returns all objects that occupy at least this many steradians
 
−
    optional angle min_solid_angle=7;
 
−
}
 
−
message ProxCall {
 
−
 
−
    //the id of the query
 
−
    required uint32 query_id=2;
 
−
 
−
    //the object falling within (or falling out) of range
 
−
    required uuid proximate_object=3;
 
−
 
−
    //the type of proximity callback we are getting
 
−
    enum ProximityEvent {
 
−
        EXITED_PROXIMITY=0;
 
−
        ENTERED_PROXIMITY=1;
 
−
        STATELESS_PROXIMITY=2;
 
−
    }
 
−
    required ProximityEvent proximity_event=4;
 
−
}
 
−
 
−
// used to unregister a proximity query.
 
−
// May be sent back as a return value if space does not support standing queries
 
−
message DelProxQuery {
 
−
    //delete a query by client id
 
−
    optional uint32 query_id=2; 
 
−
}
 

Revision as of 05:49, 27 August 2009

High Level Interaction Overview

In this document we use the word Client interchangably with the phrase "Object Host" when referring to a 3rd party connecting to a space server to become part of that space. Traditionally Clients host a single object: the camera, which maintains a perspective query of the surrounding environment, but this is left up to the client implementation and the policies in the space: you may find clients hosting avatars, bots, or other objects in a given world.

Object hosts simulate individual objects and facilitate these objects to each connect to one or more spaces. Once an object connects to a space, it may communicate with that space to setup standing queries for nearby or important objects, advertise its position or send messages to objects for which it knows the identifier.

A typical client behavior involves the following steps

  • Connect camera object to space server
  • Upon connection, register for a new object Id with desired position
  • Setup a proximity query for nearby objects that occupy N pixel area on its screen

At this point the camera object will be ready to receive standing query results of nearby objects. As these come in, the client will likely wish to act upon them.

As a proximity request is returned the client is likely to perform the following steps

  • Examine the proximity response and understand any bundled data (which may include current location, mesh data, type, etc)
  • Construct a message asking that object for remaining data including
    • Mesh URI
    • Position
    • Light information
    • ...

Once the Data is retrieved, the object may be displayed on the client. In the future the client may setup an individual subscription for location updates and other properties of interest with the relevant subscription service. The subscription service is optional and the client must not rely on such a service being present. In the absence of such a service, asking the location service for location updates at a rate proportional to the distance^2 of the object is sufficient.

Clients may wish to interact with objects in the scene (asking them to move, changing their properties, etc). This is accomplished through sending a message to that object on a number of ports. The standard message goes to the object on port 0 and invokes a scripting language function on that object by that name with the provided binary string argument.

Low Level Network Protocols

Sirikata is planned to support 2 low level protocols

  • TCP under TCPSST
  • UDP under ENET

All components of the system should be able to speak both protocols so the best may be selected for the given circumstance.

TCPSST

TCPSST is an effort to build a structured streams-like abstraction ontop of TCP by using a handful of individual TCP streams over which to multiplex a number of independent SubStreams. Clients may choose to connect to servers with one or more TCP streams using a handshake that pairs them up appropriately. The default is 3 TCP streams per TCPSST connection. This setup prevents head of line blocking and allows unordered messages to be sent on the least congested stream.

Handshake

every stream begins with the 6 characters SSTTCP then 2 characters delineating in human readable how many streams will be associated with this connection (up to 99) and then a UUID for this connection. This data will be used by the server to pair up the connections and treat them as a single overarching TCPSST stream. The server then sends back a similar handshake header with its own unique UUID to acknowledge the connection pairing.

Framing

After the handshake is complete, data may be sent across the bidirectional sockets as long as each packet of data is preceeded by a packet size (including all following data including the substream identifier) and a substream identifier

Retrieved from "http://www.sirikata.com/wiki/index.php?title=Protocol&oldid=448"