Protocol

Our wire protocol is written in PBJ[1] which right now compiles directly into protocol buffers but could theoretically target numerous serialization formats.

package Sirikata.Protocol;

/////////////Standard Message Container///////////////

//This is the standard message container. All items sent over the wire should be of type Message
message Message {

    //the destination ObjectReference (space is implicit) if omitted, space is destination
    optional uuid destination_object = 1;

    //optional spaceID of the destination object (in case we have a space routing messages, or it is not otherwise implicit)

    optional uuid destination_space = 2;

    //the source ObjectReference (space is implicit)
    optional uuid source_object = 3;

    //the spaceID origin message (in case we have a space routing messages)
    optional uuid source_space = 4;

    //the message id for the function call request, so out of order messages may be detected and return values may be paired.  
    optional int64 id = 5;

    //the name of the function(s) to call
    repeated string message_names=6;

    //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
    repeated bytes message_arguments=7;

    //the message is a response to a previous message.
    enum ReturnStatus {
      SUCCESS = 0;
      NETWORK_FAILURE = 1;
      SECURITY_FAILURE = 2;
    }
    optional ReturnStatus return_status=8;
}

/////////////Built-in messages///////////////

//This message is from a space to an object updating its position and orientation (returns void)
message ObjLoc {

    //time that the update was sent out
    optional time timestamp = 2;

    //position of source object
    optional vector3d position = 3;

    //orientation of source object
    optional quaternion orientation = 4;

    //velocity of the source object at snapsot
    optional vector3f velocity = 5;

    //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;  
}