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)