Protocol
Jump to navigation
Jump to search
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; }