VRML Interchange Protocol - Specification

1.0 Introduction

The VRML Interchange Protocol is a simple, compact protocol for sending VRML fields over networks to allow multi-user participation in a VRML world. The protocol is currently used by the VNet client-server pair, written in Java and running over a TCP/IP protocol. The protocol was designed to be fast, so that a large number of users could communicate even over modem connections. For this reason, it is binary rather than ASCII.

2.0 Basic Encoding

All basic datatypes used by VIP (integer, boolean, float, double, string) are encoded using the same format as Java's java.io.DataInputStream and DataOutputStream classes. So for instance, 32-bit integers are written as four bytes, MSB first, and character strings are written as two bytes of length followed by a UTF encoding of the string. See http://www.javasoft.com/products/jdk/1.1/docs/api/java.io.DataInputStream.htmlfor more details.

2.1 VRML Field Type Encoding

VIP specifies an encoding for each of the 19 field types in VRML. The first byte is a "tag" byte which indicates which of the 19 types it is. The subsequent bytes represent a VRML field value, encoded as follows (the encoding is variable in length depending on type).

Tag	Type	Encoding	Description
-1	(none)		No data.
0	SFBool	byte	Zero == FALSE, non-zero == TRUE
1	SFColor	float float float	r, g, b
2	SFFloat	float
3	SFImage	int int int [ int int int ... ]	width, height, depth, [ pixels... ]
4	SFInt32	int
5	SFNode	int	Object id of the root node.
6	SFRotation	float float float float	3-vector of axis, angle
7	SFString	utf8
8	SFTime	double	Seconds since the "epoch" (jan 1 1970 GMT)
9	SFVec2f	float float	x, y
10	SFVec3f	float float float	x, y, z
11	MFColor	int [ float float float ... ]	n, followed by n ( r, g, b) 3-tuples
12	MFFloat	int [ float float float ... ]	n, followed by n floats
13	MFInt32	int [ int int int ... ]	n, followed by n ints
14	MFNode	int [ int int int ... ]	n, followed by n object id's
15	MFRotation	int [ float float float float, ... ]	n, followed by n SFRotation 4-tuples
16	MFString	int [ utf8 utf8 utf8 ... ]	n, followed by n utf8-encoded strings
17	MFVec2f	int [ float float, ... ]	n, followed by n (x, y) 2-tuples
18	MFVec3f	int [ float float float, ... ]	n, followed by n (x, y, z) 3-tuples

3.0 Message Format

All messages consist of 3 parts: object, field, and value.

3.1 Object

The object is a 32-bit integer whose value represents the object whose field is to be changed. Object id's are assigned by the VNet server when an object is created and are passed to each client. Thus, all clients refer to objects by the same object id.

3.2 Field

The field is a signed 16-bit integer which represents which field of the target object should be set. Currently, 4 fields are reserved with specific values:

Value	Identifier	Type	Description
0	POSITION	SFVec3f	The position of a user or object in 3D world coordinates. Broadcast by the server to everyone but the sender.
1	ORIENTATION	SFRotation	The orientation of a user or object, expressed as an axis of rotation, and an angle. Broadcast by the server to everyone but the sender.
2	SCALE	SFVec3f	A scaling to be applied to a user or object Broadcast by the server to everyone but the sender.
3	NAME	MFString	The name of an object; used in VNet for 3D nametags.

3.3 Value

The value of the message is a single VRML field value, encoded as shown above.

4.0 Pseudo-fields reserved by VNet

Pseudo-fields are negative field values, used by VNet to send messages which don't conform to fields in actual objects. VNet uses them to send geometry changes, such as "add this object to the scene" or text messages to be displayed in the VNet client window. This keeps implementation of the protocol simple (all messages are in the same format) while allowing for out-of-band messaging.

ID	Name	Type	C->S	S->C	Broadcast	Description
-1	QUIT	(none)	Yes	No	No	User wants to disconnect from the server
-2	MESSAGE	SFString	Yes	Yes	Yes	Display this SFString message in all users' text windows.
-3	ADD_OBJECT	SFString	Yes	Yes	Yes	Add a new object to the scene. The SFString argument is the URL of the object to add.
-4	REMOVE_OBJECT	(none)	Yes	Yes	Yes	Remove an object from the scene. The target is the object id to remove.
-5	PRIVATE_MESSAGE	SFString	Yes	Yes	No	Display a text message in one users' text window. The target is the user id.
-6	CREATE_OBJECT	(none)	Yes	Yes	No	Create a new object id. Unused in VNet 1.0.
-7	USER_INFO	SFString	No	Yes	No	Send the username of a new user (displayed in the user listbox in VNet).

5.0 Sample message exchange

Object	Field	Value	Description
5	0	2.5 0 100.0	Move object 5 to position (2.5, 0, 100.0)
5	-2	"Joe: hi"	(client->server) chat message from object 5 (Joe)
5	-2	"Joe: hi"	(server->client) the same message broadcast by the server
5	-6	(none)	(client->server) Joe wants to create something
15	-6	(none)	(server->client) New object created, id 15
15	-3	"http://www.joe.com/dog.wrl"	(client->server) Add a new object to the scene with given URL
15	-3	"http://www.joe.com/dog.wrl"	(server->client) Add a new object to the scene with given URL
15	3	"Ralph"	(client->server)Change object 15's name to "Ralph"
15	3	"Ralph"	(server->client)Change object 15's name to "Ralph"
5	-1	(none)	user 5 wants to quit

6.0 Future work

While VIP is currently used for sending a hardcoded set of messages, the protocol was designed to be flexible so that in the future, any valid VRML field can be sent. For example, avatars with behaviours could be built using a PROTO:

	PROTO MyAvatar [
		field MFString		gestures [ "smile" "blink" "scream" ]
		eventIn SFBool		smile
		eventIn SFBool		blink
		eventIn SFBool		scream
	] {
	   ...
	}

These behaviors would be enumerated by the client and given unique field identifiers. Buttons would be added to the VNet client window to allow the user to trigger them. When a button was clicked, the client would send a simple SFBool message to the server. The server would forward the messages to the other clients, which would pick the appropriate SFBool behaviour field from the PROTO and trigger it, causing an animation in each client's view. More complex interactions could be built using other VRML data types, such as SFVec3f or MFString. Objects themselves could initiate asynchronous events by listing such fields in a PROTO in a similar way:

	PROTO MyButton [
		field MFString		eventIns [ "clicked" ]
		field MFString		eventOuts [ "clicked" ]
		eventIn SFBool		clicked
		eventOut SFBool		clicked
	] {
	   ...
	}

The eventOut would be automatically given a unique field identifier as above. When a user clicked on the button, it would send the "clicked" message to the server, which would forward it to the other clients, which would display some appropriate animation or whatever.