This document describes version 0.4 of the CVE Network Protocol. The document historically served as a design document and was not strictly followed. The implementation has not implemented some of the message types proposed here, and various additions to the implementation are not described here or are inadequately described. This situation is under repair.
At present:
\command arguments* \nMost commands are short, but some commands are quite long, including tasks such as sending messages with many text lines in them. Newlines are "escaped" (replaced by a substitute string) in such messages. TCP does not guarantee delivery of an entire command in a single packet. The client and server must remember incoming unfinished commands in a buffer until the packet containing their newline is received. Multiple commands are generally batched into a single packet in order to reduce OS overhead.
Some of these items are really local client commands, not network protocol commands. For each command we need to ask: does it need to go the server? and then: which client(s) should the server forward it on to? and then: does it require a reply, and if so, from whom? Lastly: for each command, does it require that the server remember the state change and store it in a database?
Every command can be abbreviated by a unique prefix. Common commands can be abbreviated with nonunique prefixes. Each client avatar has a current default command which executes for lines not beginning with \.
| Example | Description |
|---|---|
| \login [-cvecypher] userid passwd [npc] | log in; server replies "Valid" |
| \version | identify CVE protocol; server replies Valid Version #.# |
| \logout | log out |
| Example | Description |
|---|---|
| \say hello | chats to the current room |
| \tell joe hello | chats to a specific person |
Maybe Not Yet Implemented:
| Example | Description |
|---|---|
| \tell groupname hello | chats to a specific group |
| \tell sessionname hello | chats to a specific session |
| \group hello | chats to the current group |
| \sig hello | chats to the current special interest group |
| \course hello | chats to the current course |
| \emote | a supposedly non-verbal |
| Example | Description |
|---|---|
| \newuser id password firstname lastname email affiliation | register a new user; server replies Valid |
| Example | Description |
|---|---|
| \invite | invite (currently selected person) to join group |
| \disband | disband current group |
| \groups | list my groups |
| \lsgroups | list all groups |
| \makesig unicon [closed] | Create a special interest group. The default is an open sig. An optional parameter would create a closed/moderated sig. Closed is the default for all types of groups other than sigs. |
| \makecourse cs371 | create a course |
| \sig=unicon | sets the current/default special interest group you are sending to |
| \unicon | sends a message to any sig by name |
| \join unicon | join (subscribe to listen) a sig |
| \course cs371 | sets the current course you are sending to |
| \ignore joe | discard all messages from user joe |
| Example | Description |
|---|---|
| \createsession sessionname sessionid | server assigns id to created (temporary) group |
| \destroysession sessionname | destroy a (temporary) group |
| \subsession sessiontype sessionname | create a subgroup |
| \invite sessionname username(s) | client invites user(s) to join group |
| \invite sessiontype sessionname | server forwards invitation to user(s) to join group |
| \join sessionname | accept membership |
| \decline sessionname | decline membership |
| \leave sessionname | exit membership |
| \dismiss sessionname username | kick someone out |
| \listsessions | client requests |
| \listsessions ssnname, ssntype, ssnname, ssntype, ... | server responds |
| \listmembers sessionname | |
| \requestcontrol sessionname | |
| \releasecontrol sessionname | |
| \givecontrol sessionname username |
| Example | Description |
|---|---|
| \goto 0,0,3.5 | move to (x,y,z) |
| \goto sh371 | move (teleport) to sh371 |
| \goto spock | move (teleport) to user spock |
| \look | get a 2D detailed look at nearest 2D object |
| \look board | get a 2D detailed look at the nearest whiteboard |
| \look screen | get a 2D detailed look at the nearest PC screen |
| \look up | go back to 3D view |
| \look 0,0,3.5 | (turn and) look at (x,y,z) |
| \pen red | set the current pen to red |
| \whiteboard sh118b-a | set/lock the current whiteboard to sh118b-a |
| \draw 50,50 | set (x,y) on the nearest board to current pen color |
| \drawline 50,50,55,30 | draw line from (x,y)-(x2,y2) on the nearest board to current pen color |
| \fillrectangle 50,50,10,10 fill rectangle from (x,y) with (width,height) on the nearest board to current pen color | |
| \erase | erase the nearest board |
| \door | toggle nearest door more open or closed |
| \hand | toggle (raise/lower) hand |
| \follow | follow the currently targeted user |
| \voice [on off] | enable disable realtime microphone |
| \sound [on off] | enable disable realtime speaker |
| \video [on off] | enable disable realtime videocamera feed |
| Example | Description |
|---|---|
| \putfile dat/avatars/curtis.avt 206 | dat/avatars/curtis.avt is the file to upload, and it is 206 bytes. Immediately after the newline (after the 6) the actual contents of the file (ASCII or binary; use writes()/reads() for no newline-handling) would be sent. |
| \getfile dat/avatars/curtis.avt | this asks the server to execute a \putfile |
| Example | Description |
|---|---|
| \quit! | exits immediately |
| \exit | exits with a grace period |
| \afk | marks you as away from keyboard |
| \who | show who is on the system |
| \loc | shows your current location |
| \log [on off] | turns on/off your private recorder |
| \cmd say | sets the default command to \say |
| Example | Description |
|---|---|
| \give joe pen | give joe permission to draw on the board |
| \give joe voice | give joe permission to speak |
| \give joe legs | give joe permission to move |
| \take joe ... | remove students' specific permissions |
| \stop joe | remove all of joe's permissions, he is paralyzed |
| Example | Description |
|---|---|
| \enroll joe cs371 | adds joe to a class |
| \kill joe | dumps joe out of the application |
| \lock joe | prevents joe from logging in any more |
| Editing Message | Description |
|---|---|
| \make class name params | create a new virtual object |
| \move name params | alter coordinates of virtual object |
| \edit name param=val ... | alter attributes of virtual object |
| \texture dat/uidaho/jeb121/sign.gif ... | upload a texture |
Examples:
\make Room bedroom5 13.2 0 11 5 3.3 4.4 ( name x y x w h l texture (defaults) ) \edit bedroom5 floor=floor.gif
For each command, there is the command name and syntax on the left side of a header line. The right side of the header line will contain the word client, server, or both to indicate whether the command is sent by clients (to server), by server (to clients) or both. The body of the command entry gives the semantics of the command, and indicates if it is issued asynchronously at any time, or only occurs in a specific command context, i.e. in response to another command. By default you can imagine a static virtual world in which the server is a stateless forwarder of chat messages. In that situation, it would make sense for the default source to be both and the default context to be asynchronous, i.e. it can be sent at any time.
list users / userlist()
add a user / useradd()
remove a user / userrem()
change a user / userchange()
quit and kill / shutdown()
Send client a list of all users / all_users()
Instantiate an avatar of someone who has logged in.
sends a fetchip message to client; compare with getip
sends a \say message to client telling me userid's (external) IP# (defaults to my own), for peer-to-peer purposes
send user a response, allowing them to measure latency of their connection
subscribe to a loghandler / logHandler.subscribe()
Move an avatar to [position] / moveAvatar()
Set the door openness to [setting]. Transmit to clients as a \doorMotion.
Ask a question (this is vague). / query()
Send a chat to all users. Could reduce scope to "nearby within earshot" users.
send client a list of logged in users / who_is_up()
Send the user a webpage? / Url_Send()
Add a new news feed. Feed label/name is contents, which if longer than 30 characters may be truncated. Who_is_allowed (to post) can be ALL, or a specific user.
Remove a news feed.
This NewsFeed command is supposed to put a persistent message on someone's "wall", even when they are not logged in. Such messages are stored on the server in userID/wall.log
Create a (new/additional) room in the world. Tell other clients about it.
Save a room. This writes (on the server) a roomdat/roomname.dat file that contains @ for newline, # for tab, and ~ for spaces. It also writes (if FLAG is 1) a new include line in roomdat/roomlist.dat, and maybe adds that file to the ServerUpdate.tim file so clients will download it.
Check server for updates. Checks ServerUpdate.tim, containing a list of file[\t]time strings. For every file missing or outdated, send a \createDatFile [contents] message. Contents is filename[\t] followed by the file contents, with $ for newline. Appears not to work for binary files. After the last file, send a \createDatFile BREAK command.
Remove the named wall post. objType is Group or Project
Add a (persistent) wall post. objType is either Group or Project. The post is written to objName/Wall/userID~priority[postID].log and added to the members' communication logs. The format of a wall post is
User: userID Date/Time: date and time ================================================== contentswhere
contents uses $$ to encode newlines.
Reply to an existing post. Replies are appended to objName/Wall/postName on the server.
insert an opening into the world.
Create a (temporary) group. There are various possible applications, such as to incorporate mini-games, as special collaborative sessions.