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

//New Streams can establish an ObjectConnection
message InitializeObjectConnection {
    ///key to indicate how an object's ObjectReference should be restored
    optional uuid object_uuid_evidence=2;
}
//This will be in the argument for the return value of the InitializeObjectConnection function
message ReturnObjectConnection {
    //return value for InitializeObjectConnection message
    optional bytes object_reference = 2;
}
//This message indicates an object has disconnected and should be removed from space. Shutting down the connection can accomplish the same (returns void)
message DisconnectObject {
}

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

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

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

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

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

    //axis of rotation of source object
    optional normal rotational_axis = 6;

    //speed of rotation around axis (may be negative)
    optional float angular_speed = 7;

    //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 = 8;
}
message RegisterProximityQuery {

    //the client chosen id for this query
    required 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 ProximityQueryCallback {

    //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 UnregisterProximityQuery {
    //delete a query by client id
    optional uint32 query_id=2;  
}

A raw translation to protocol buffers is provided as follows:

package Sirikata.Protocol._PBJ_Internal;
message Message {
	optional bytes destination_object = 1 ;
	optional bytes destination_space = 2 ;
	optional bytes source_object = 3 ;
	optional bytes source_space = 4 ;
	optional int64 id = 5 ;
	repeated string message_names = 6;
	repeated bytes message_arguments = 7;
	enum ReturnStatus {
		SUCCESS = 0;
		NETWORK_FAILURE = 1;
		SECURITY_FAILURE = 2;
	}
	optional ReturnStatus return_status = 8 ;
}
message InitializeObjectConnection {
	optional bytes object_uuid_evidence = 2 ;
}
message ReturnObjectConnection {
	optional bytes object_reference = 2 ;
}
message DisconnectObject {
}
message UpdateObjectLocation {
	required fixed64 timestamp = 2;
	repeated double position = 3;
	repeated float orientation = 4;
	repeated float velocity = 5;
	repeated float rotational_axis = 6;
	optional float angular_speed = 7 ;
	enum UpdateFlags {
		FORCE = 1;
	}
	optional uint32 update_flags = 8 ;
}
message RegisterProximityQuery {
	required uint32 query_id = 2;
	optional bool stateless = 3 ;
	repeated float relative_center = 4;
	repeated double absolute_center = 5;
	optional float max_radius = 6 ;
	optional float min_solid_angle = 7 ;
}
message ProximityQueryCallback {
	required uint32 query_id = 2;
	required bytes proximate_object = 3;
	enum ProximityEvent {
		EXITED_PROXIMITY = 0;
		ENTERED_PROXIMITY = 1;
		STATELESS_PROXIMITY = 2;
	}
	required ProximityEvent proximity_event = 4;
}
message UnregisterProximityQuery {
	optional uint32 query_id = 2 ;
}