general usage notes
the cospace.dat config file
command language
extending cospace
problems and bugs

general usage notes

When the cospace client starts, you'll be prompted for a name/password. Pressing "go" with a valid name/pass will start the session. pressing "save" will store the name/password in the cospace.dat file in the same directory. Password authentication is turned off in this version -- any non-null password will work

The cospace client normally runs as a companion applications alongside a web browser (netscape or IE). The synchronization of client and web browser is controlled by the link/unlink control in the button panel at the lower right of the interface. When linked, the synchronization of cospace and the web browser is bilateral -- navigation with the web browser to a new site will cause the cospace browser to follow to the room corresponding to that site. Likewise navigation with the cospace client to a new room will cause the web browser to follow (if that room is associated with a website). Cospace automatically creates private portals between rooms as one moves from one site to another.

Cospace distinguishes two types of portals, private and shared. Private portals, which have a plain stonelike texture, are visible only to an individual user (so the portals created automatically during navigation will not reveal to other users what site you came from). Shared portals, which have a checkered texture, are visible to everyone within the spaces they connect. Buth types of portals are dynamic and may come and go freely.

The text interface at the bottom of the client window is used for user communication and informational messages. Text typed into the field at the bottom of the cospace client is interpreted as `speech' or commands. The default scope of communication is the current room, so an utterance would be seen by anyone else in that space.

The state of the Cospace world is represented and saved in an object database, so portals, objects, and room state persists from one session to the next (e.g. portals created during a cospace session will be there the next time you connect to cospace).

the cospace.dat config file
there are a few cospace parameters that are stored in a file named cospace.dat, in the same directory as the cospace executable. most parameters can be left alone, but there are a few worth knowing about. Typical cospace.dat file looks like this:

    #cospace properties
    #Tue Dec 07 12:19:14 EST 1999
    host=cospace.research.att.com
    update=prompt
    base=http://cospace.research.att.com/xclient/
    browser=ie
    port=10447
    muport=10446
    name=dogmeat
    pass=foo

command language
the cospace command language is a textual line-oriented interface to the cospace database. MOO users may observe some similarity to the interfaces they're familiar with, though no attempt has been made to emulate that interface (cospace is not a moo).

commands for interacting with the cospace database are of the form "action arg1 arg2....argN". Commands are typed into the text typein field of the cospace client. The syntax to distinguish an action command from an normal line of text is to begin the line with a "/". e.g. "/drop box" or "/look".

Every object has an integer indentifier; direct object references by identifer are specified as "@id", e.g. "@23" refers to the database object whose identifier is 23.

A command string is interpreted as follows:
1. arguments are tokenized, using whitespace as token separators; string arguments that contain whitespace should be surrounded by doublequotes to treated as single tokens
2. an execution context for the command is created; this context includes the actor executing the command and the current location (e.g. room) in which the string is being interpreted
3. an argument resolution pass attempts to resolve names of objects into the actual objects. the default resolution algorithm (subject to change) first replaces matches for the special tokens {me, myself, here} and for direct object references (e.g. @23) ; then tries to find named objects among the objects that the current actor is holding; then it looks among the objects in the current location; then it looks in the user namespace; then it looks in the room namespace. (these last two are very questionable and will probably go away). if no object is found named by this token, then the token is returned as a literal string. name resolution may be overridden by preceding an argument with a singlequote.
4. the code for the action (a generic function) is retrieved and applied to the cooked argument list
5. output and/or errors resulting from execution of the action appears in the text window

Following is a partial list of actions in the current cospace vocabulary. optional arguments are indicated with surrounding brackets.

/say string

  broadcast string to other objects in current location/container

  note that a normal line typed to the cospace client (i.e. not beginning 
  with "/") is implicitly turned into /say "the text that was typed...."

  page user with string, wherever they are --seen only by sender 
   and receiver

  whisper to user with string -- seen only by sender and receiver

  describe self taking some action in 3rd person

  teleport self to home location

  set (self's) home location to place (default current location)

  teleport self to room

  create a private portal from room1 to current room 
   (or to room2 if provided)

  create a shared portal from room1 to current room 
   (or to room2 if provided)

  remove a portal from room1 to current room 
   (or to room2 if provided)

  print location of user

  list contents of container (e.g. room, user)

  look at something's description; default (no args) is current room

  get rid of all of your private portals

;; following actions are called implicitly by the system, generally not used explicitly

/touch thing

  touch an object -- this verb is called when an object is clicked on

  bump an object -- this verb is called when colliding with an object

There are a more actions defined for manipulating the environment that are not listed here. These include actions for creating new objects (e.g. bringing new vrml objects into the environment), moving things around, removing objects, etc. Drop me a note if you'd like the extended list of actions (I'm not discouraging their use, just don't wanted the world to modified anonymously).

extending cospace
There are a couple of ways to extend cospace; integrating custom room desigs into the cospace architecture, and defining new actions that operate on objects in the database. As with the extended actions described above, I don't want these features to be used anonymously, but you're welcome to drop me a note if you'd like additional documentation and examples of extending cospace.

known problems and bugs
an (incomplete) list of bothersome stuff that probably won't get fixed:

the DDE communication between the cospace client and the web browser can be flaky, so synchronization of client and browser sometimes fails.

using the vrml browser viewpoint mechanism will generally confuse both the cospace client and you, so avoid it. if you find yourself lost in space, type "/home" in the text interface to get back to a reasonable place.

portals between rooms can occasionally fail to punch holes in the wall polygons -- if you get stuck for no apparent reason at the entrance to another room, this is probably what happened (won't see the wall in this case because the wall polygon backfaces aren't rendered). to fix this, navigate back to the room you came from and type "/reportal" in the text interface.

when the cospace client is synchronized with the web browser, ad banners and page redirects can confuse the cospace client. workaround is to select "unlink" from the button panel

room architecture is dreadfully monotonous. the functionality for making the spaces more variable exists, but has not been made available in this version...sorry