MASSIVE-3 User Guide

Chris Greenhalgh, 1st Dec. 2000, rev-4.

Abstract

This document is a short introduction to running MASSIVE-3, in particular using the standard example applications. It does not consider application development.

Contents

  1. Win32 Quick Start
  2. Introduction
  3. An Example Session
  4. Configuration Reference
  5. Application Reference

1. Win32 Quick Start

This section is to get things rolling quickly on some version of Windows (98, NT, 2000).

1.1. Download and unpack

Get a recent tar ball of MASSIVE-3, e.g. mas3rev4b.tar.gz. Move to a suitable directory and uncompress and extract the contents on a suitable drive (winzip should be able to do this, although tar zxf under Cygwin might be safer). This will give you a new directory, e.g. mas3rev4b. For the rest of this section will we identify the full path to this directory as "MASSIVE3ROOT"

1.2. Configure

In the directory %MASSIVE3ROOT%\scripts you should find a script NTenv.bat. Edit this using your favourite editor (such as emacs or wordpad) and set the value of MASSIVE3ROOT correctly for where you have unpacked MASSIVE-3.

1.3. Quick Test

Open the directory %MASSIVE3ROOT%\scripts in Explorer and double click on (run) the script StartMassive3.bat. Two new command windows should open. Wait for a few seconds (until all windows stop printing new messages) and press enter where requested. One more window should open. Again wait for a few seconds (until all windows stop printing new messages) and press enter where requested. One more window should open. A 3D graphical window should then appear as described in section 3.5. Congratulations, you are now using MASSIVE-3. Use the left mouse button in the graphical window to move about; use the right mouse button to try picking up the centre star.

If this doesn't work then double check step 1.2. If this doesn't work, you'll have to work through all the settings, etc. which is best in individual command windows as described in section 3.

If this does work then you have just run:

2. Introduction

MASSIVE-3 is a multi-user collaborative virtual environment system. It allows multiple users to view and become embodied in a 3D audio-graphical virtual world. It supports real-time audio communication between users, and dynamic modification of virtual worlds. MASSIVE-3 is a development of the HIVE project kernel (HIVEK), and this name crops up in some places; it is equivalent for most purposes.

Virtual worlds are constructed from "locales"; each locale is a region of virtual space with its own set of contents and users. A locale might correspond to a room, a building, a region, or a whole virtual world. Locales can be joined together using "boundaries", which create links between locales. Users can typically see through boundaries - to see the locale on the other side - and can also traverse boundaries - to jump to the locale on the other side. Note that these boundaries can have complicated geometric transformations associated with them so that, for example, the inside of a building can be larger than the outside, or a boundary can act like a mirrot. For further information on locales and boundaries see [1, 2].

MASSIVE-3 is primarily structured as a library of C++ classes which provide standard data distribution and other facilities (e.g. rendering). Programmers can use this library to create their own interoperating applications. There are also a number of applications provided with the standard distribution which provide system services or standard application functionality.

The standard applications are listed below.

Core Applications

The core (non-persistent) applications, normally required to view any world are:

Trader
The standard (non-persistent) naming service, required to bootstrap any use of MASSIVE-3.
bodyExampleClient
A simple user client, for accessing MASSIVE-3 worlds.

Example Worlds

The following applications create simple virtual worlds, and can be used as is, or extended by an application programmer:

CveWorld
A MASSIVE-3 application which creates static worlds from MASSIVE-2 world definition files (which typically have the suffix ".cve").
VerySimpleApp
A minimal MASSIVE-3 world-creating application.
SimpleApp
A MASSIVE-3 example world with multiple locales.

Persistent Applications

There is ongoing work on supporting persistent virtual worlds in MASSIVE-3, i.e. virtual worlds which appear to exist all of the time, whether a particular application is running or not. At present these persistent virtual worlds have an alternative infratstructure with variant core applications:

PersistentTrader
A variant trader which supports persistent virtual worlds via the PersistentApp application.
MuseumClient
An extended user client, designed for use with the PersistentTrader, only, which supports additional world editing, including the introduction of new locales and boundaries.
PersistentApp
A program which starts a locale from a serialised file, and maintains an up-to-date disk backup. Normally used with the PersistentTrader.
checkpointer
A simple application which can create a locale file from a running locale, e.g. for subsequent use by PersistentApp.

Temporal Links

A related thread of work concerns making past activity available in the present. This is supported by the following application:

HistoryReplay
A demonstration application which can recreate and replay the activities within a locale that has been logged to a disk file.

Inhabited Television

Continuing from work with MASSIVE-2 (e.g. Out Of This World) MASSIVE-3 is also being used as a prototype platform for inhabited television, in particular camera control and directing, and event management. This effort is supported by the following application:

MgmtServerMain
A MASSIVE-3 application which acts as a TCP server, allowing an external application to access a MASSIVE-3 world via a simple text protocol. Also supports limited rendering of 3D views under the control of the external application.

3. An Example Session

This section describes how to get MASSIVE-3 running in a minimal session.

3.1. Configuration

MASSIVE-3 is configured using a standard set of environment variables, documented below.

On Windows the MASSIVE-3 scripts directory (%MASSIVE3HOME%\scripts) includes 'NTenv.bat' (introduced in section 1.2), which sets up environment variables for running and compiling MASSIVE-3. You should normally take a copy of this and edit it (or edit it in place) to ensure that the first few variables are set to correct directories for your installation (see section 1.2). To run arbitrary MASSIVE-3 commands you should open a new command shell and run this batch file in it; this will set up the environment completely (this is also required to compile MASSIVE-3 applications).

On other platforms, or if you want more customisation, you should normally add these to your environment or collect them together in a scripts that can be easily invoked. The main dependency is on the directory in which MASSIVE-3 is installed. The main environment variables required are as follows:

CRGPATH
A colon (':') separated list of directories, in which applications should look for named files. The main use of this at present is by user clients to locate geometry files. Note that, at present, each application locates and loads geometries independently, so different applications may see different things if CRGPATH is set differently or if different files are available locally to that application.
HIVE_TRADER_PORT
The TCP port which is used to communicate with the Trader (or PersistentTrader). This must be the same on all machines which may interact. Current compiled-in default is 7991. If persistent and non-persistent sessions must co-exist on the same machines, or a conflict in port usage arises, then this may used to over-ride the trader port. The same value must be used for traders, applications and user clients.
TTL
The Time To Live of any multicast packets. Currently, only one of the audio options uses multicast, although optional updates are intended to use multicast. The default value is 1 (local subnet only). Do not increase this unless you know what you are doing!
USER
The user's name - used by the standard user clients. Normally configured by UNIX automatically.
HOME
The directory in which the system will look for user's personal avatar configuration file ("massive3.config"), which is used by the standard user client programs such as bodyExampleClient.
PATH / LD_LIBRARY_PATH
You will also need to configure standard environment variables to allow the system to locate dynamic libraries and executables. For example, on many versions of UNIX PATH is used to locate binaries and LD_LIBRARY_PATH is used to locate dynamic libraries. On Windows PATH is used for both purposes. Binaries and libraries will be located in the subdirectory "<platform>/bin" where <platform> is, for example, "mips-sgi-irix6.3" or "i386-ms-wnt4.0". On UNIX this is the platform name returned by the (GNU) script config.guess. On Windows this is currently hardcoded to "i386-ms-wnt4.0".

See section 4 for additional configuration options.

3.2. The Trader

A trader must be running on every machine involved in a MASSIVE-3 session (whether running an application, a user client or both). For use with persistent worlds this must be the PersistentTrader, however use of this is limited by outstanding security issues.

On Windows a trader can be started using the 'StartTrader.bat' script. Alternatively, once any environment is set in a command shell, the trader can be started by:

> Trader

The trader should respond with diagnostic output including:

...

HIVE trader, listening on port 7991

...

HIVE_MIN_PORT = 0 HIVE_MAX_PORT = 65535
Ready

If the specified port is already in use then the application will abort with a diagnostic message. If the trader is being restarted after being killed then there may be a delay before the port can be reused (typically 2 minutes once all other applications have been killed). On UNIX the commands netstat and fuser can help to determine the status of a port.

In extreme situations HIVE_TRADER_PORT may be set to a different port, but note that the same value must be used for all applications on all interacting machines.

3.3. The Audio Server

To use networked audio each user must run an audio server on their local machine. On Windows this can be started using the 'StartAudioServer.bat' script. Alternatively, once any environment is set in a command shell, the audio server can be started by::

> audio_server

This responds with diagnostic output including:

...

fixed_gain = 1 (FIXED_GAIN, int)
limit_gain = 2 (LIMIT_GAIN, int)

...

audio_server running on control port 1523...

...

3.4. An Application

Once the trader is running an application can be started. For example, VerySimpleApp creates a virtual world with just a grid and a few stars in it. Again, on Windows, the script StartVerySimpleApp.bat does this (as well as setting up the shell environment).

> VerySimpleApp

This responds with diagnostic output including:

...

HIVE_MIN_PORT = 0 HIVE_MAX_PORT = 65535
HIVE_MC_ADDR_BASE = 239.0.0.0 HIVE_MC_ADDR_MASK = 0.255.255.255
NOTE: ttl (TTL_ENV) = 1
Note: logging disabled: APPLOGFILE not set
Created Environment ID[128.243.22.200, 0]
Created environment "SimpleAppEnvironment": [128.243.22.200, 0]
Ready

The trader will also print additional diagnostic information, including a warning that a connection has closed; this is normal and correct operation.

Note that the application has registered itself with the local machine's trader under the name "SimpleAppEnvironment" (a compiled-in default).

Alternatively, the application CveWorld can be used to create a world from a MASSIVE-2 world definition file (see section 4 for details).

3.5. A User Client

It is now possible to enter and view the virtual world. For example, using the basic bodyExampleClient. On Windows this can be started with the script StartClientSample.bat. Otherwise use the command:

> bodyExampleClient SimpleAppEnvironment

This responds with (lots of) diagnostic output including:

...

Join environment SimpleAppEnvironment
Note: read config file t:\massive3\dev-cmg\etc\massive3.config: ok (22 lines)HIVE_MIN_PORT = 0 HIVE_MAX_PORT = 65535
Note: logging disabled: APPLOGFILE not set

...

HIVE_MC_ADDR_BASE = 239.0.0.0 HIVE_MC_ADDR_MASK = 0.255.255.255
NOTE: ttl (TTL_ENV) = 1
Created Environment ID[128.243.22.200, 1]

...

Agent::joinEnvironment: request [EnvNameToEnvID/SimpleAppEnvironment]
Agent::joinEnvironment: request [EnvIDToAgentID/[128.243.22.35,0]]
Agent::joinEnvironment: replicate [128.243.22.35, 0] from master [128.243.22.35,
 3322, 0]
NOTE: ttl (TTL_ENV) = 1
Agent::joinEnvironment: joined environment [128.243.22.35, 0]Note: logging disabled: APPLOGFILE not set

...

NOTE: Applying first renderer policy to audio
Connected to 128.243.22.35 on port 1523
NOTE: audio_server reset on first audio session

...

BodyExample::createBody in environment 128.243.22.35/SimpleAppEnvironment (0x01953920)

...

Ready

...

Environment::notificationP: completed spool of 128.243.22.35/SimpleAppEnvironment

...

Note that this will connect (if it exists) to the world on the local machine registered with the trader as "SimpleAppEnvironment". To connect to a world on another machine use a name of the form "<dotted-ip-address>/<world-name>".

If the specified world does not exist then you will just see an empty void world, and the command shell will print an additional error message such as:

If you ran VerySimpleApp successfully you will see something like this:

The icons around the edge of the graphical view are exclusive to this user (i.e. not visible or accessible to other users in the virtual world). Anti-clockwise from the top left there is:

Most interaction is via the mouse:

Note that some objects may be locked, i.e. you cannot pick them up. Others may have more sophisticated constraints which mean that dragging them has an effect, but you can't move them arbitrarily (e.g. constrained motion, or interaction with an application).

Standard keyboard controls are:

So walk about and do stuff. Audio should work at least within a single locale.

4. Configuration Reference

The following environment variables support configuration of the MASSIVE-3 library or specific applications.

APPLOGFILE
Set a filename to which APPLOG reporting should be directed. The special value "stderr" indicates the standard error stream of the process, while "stdout" indicates the standard output stream of the process. If unset, no logging is performed.
APPLOGOPTS
A colon (':') separated list of APPLOG item prefixes to be logged to the file specified by APPLOGFILE. See the core library file logging.h for details of APPLOG.
CRGPATH
Path used to locate named files, e.g. geometries.
See section 2.1.
HISTORY_DIR
Specifies a (writable) directory in which environment (locale) history logs should be recorded. This will generate one file for each environment which the application joins. This file will record the initial state of the environment, and all events which occur in it. These logs can be replayed by the application HistoryReplay.
HIVE_MIN_PORT
Minimum port number to be used for dynamically bound UDP ports. Defaults to 0. May be used when configuring port use in relation to firewalls.
HIVE_MAX_PORT
Maximum port number to be used for dynamically bound UDP ports. Defaults to 0. May be used when configuring port use in relation to firewalls.
HIVE_MC_ADDR_BASE
Minimum class D IP address to use when allocating (random) multicast groups. Default 239.0.0.0.
HIVE_MC_ADDR_MASK
Bit mask in dotted decimal notation to determine the range of class D IP address used for allocated multicast groups. Default 0.255.255.255.
HIVE_TRADER_PORT
TCP port used to contact host trader processes.
See section 2.1
HOME
The directory in which the system will look for user's personal avatar configuration file ("massive3.config"), which is used by the standard user client programs such as bodyExampleClient.
IGNORE_SIGINT
Causes Agent (mainloop) to NOT register a handler for the INT signal. Can be useful in testing. Default is to register a signal handler to do a controlled application exit on INT.
LOCALHOST
Specify the local IP address to be used for binding sockets. Overrides the default use of gethostname/gethostbyname. May be useful/required on multi-homed machines to force use of a particular IP address to guide return routing.
MOVE_RATE_S
For user clients only; specify, in seconds, the minimum interval between position update messages. I.e. controls movement update rate limiting. Default 0.5 (seconds).
TTL
Multicast packet TTL used for all multicast communication.
See section 2.1
REGIONAL_SERVER
For use with regional audio mixing; overrides local (multicast) discovery of regional server.
TEST_CONSTRAINT
For BodyExample, only. Testing use - specify a constraint to be applied to the user's movement.
USER
Used by user clients - user's name.
See section 2.1

5. Application Reference

In alphabetic order - see index for structured list.

bodyExampleClient

Usage:
bodyExampleClient <world-name>
bodyExampleClient <world-ip-address>/<world-name>
<world-ip-address> is IP address of machine running world in dotted decimal notation.
<world-name> is name under which starting locale is registered with its local trader.
Purpose:
A simple user client, for accessing MASSIVE-3 worlds. Described in section 2.4.
Source directory:
stdapps
Bugs/issues:
If a "massive3.config" file is not found using the environment variable HOME then the program will look for one using CRGPATH.
If a geometry named in a world cannot be found locally using CRGPATH then the client will just print an error message and will not display anything for that geometry.
If a geometry is changed on disk while the program is running then it will not be reloaded by any client that has already loaded it (but clients started subsequently would see the changed geometry).
On some platforms, some version of the client hang with a blank graphical window if a geometry cannot be found. This is believed to be fixed in the latest version.

checkpointer

Usage:
checkpointer <world-name>
checkpointer <world-ip-address>/<world-name>
See bodyExampleClient usage.
Purpose:
A simple application which can create a locale file from a running locale, e.g. for subsequent use by PersistentApp. Joins the named locale and creates a serialised copy of the environment in the file "<world-ip-address>.<world-name>.env". Note that this application does not work correctly with the current version of serialised environment transfer - it will give an empty locale.
Source directory:
stdapps
Bugs/issues:
Note that this application does not work correctly with the current version of serialised environment transfer - it will give an empty locale.
Log files are specific to particular versions of the core library.
May well be out of date.

CveWorld

Usage:
CveWorld <world-name> <cve-file>
<world-name> is the name with which the new locale will be registered with the local trader.
<cve-file> is a MASSIVE-2 world file, typically with a ".cve" suffix.
Purpose:
A MASSIVE-3 application which creates static worlds from MASSIVE-2 world definition files (which typically have the suffix ".cve"). Note that each user client will need to have its CRGPATH environment variable correctly set to locate all named geometries.
Source directory:
stdapps
Bugs/issues:
Currently, each client locates and loads geometry files locally and independently.
Some functions of MASSIVE-2 are not supported. Regions are also not supported.

HistoryReplay

Usage:
HistoryReplay <world-name> <history-log-file>
<world-name> is the name with which the new locale will be registered with the local trader.
<history-log-file> is the name of a locale log, e.g. recording via setting the HISTORY_DIR environment variable.
Purpose:
A demonstration application which can recreate and replay the activities within a locale that has been logged to a disk file. An empty locale is created which holds simple VCR-style controls (restart, backwards, forwards, slow forwards, stop). Pressing play will replay the events which occurred in the log file.
Source directory:
stdapps
Bugs/issues:
This functionality should be repackaged as a generic temporal link facility in the not too distant future. Log files are specific to particular versions of the core library.

MgmtServerMain

Usage:
MgmtServerMain <tcp-port>
<tcp-port> is the port on which the application will wait for controlling TCP connections.
Purpose:
A MASSIVE-3 application which acts as a TCP server, allowing an external application to access a MASSIVE-3 world via a simple text protocol. Also supports limited rendering of 3D views under the control of the external application. The ASCII protocol is documented elsewhere.
Source directory:
mgmtapi
Bugs/issues:
Several features currently unimplemented.
Supports only one control connection at a time.
Visual views are not correctly deleted when a control connection terminates.

MuseumClient

Usage:
MuseumClient <world-name>
MuseumClient <world-ip-address>/<world-name>
<world-ip-address> is IP address of machine running world in dotted decimal notation.
<world-name> is name under which starting locale is registered with its local trader.
Purpose:
An extended user client based on bodyExampleClient (described in section 2.). Designed for use with the PersistentTrader, only, which supports additional world editing, including the introduction of new locales and boundaries.
Source directory:
stdapps
Bugs/issues:
See bodyExampleClient.

PersistentApp

Usage:
PersistentApp <locale-name>
<locale-name> is the name of a locale, and also the name of a local file which contains the current state of that locale.
Purpose:
A program which starts a locale from a serialised file. If the file does not exist initially then a new empty locale is created of that name. Periodically the disk file is updated to reflect the current state of the locale (default once per minute). If the locale is inactive (has no users present) for a signficiant length of time (default two minutes) then the application will quit after lodging a reactivation request with the local trader (which must be a PersistentTrader for this to work). This will cause the PersistentTrader to restart the PersistentApp if the locale is subsequently requested.
Source directory:
stdapps
Bugs/issues:
Log files are specific to particular versions of the core library.
Reactivation will only work with a local PersistentTrader (which may have security implications).

PersistentTrader

Usage:
PersistentTrader
PersistentTrader <trader-log>
<trader-log> is a filename in which to record/re-read trader offers.
Purpose:
A variant trader which supports persistent virtual worlds. First, the trader can maintain a log of offers, so that it can recover after crashes or restarts of the trader itself (although all current clients will fail). Second, the PersistentTrader can be set to fork a new application when a given locale is requested. Typically this would start a PersistentApp, to re-create the requested locale.
Source directory:
stdapps
Bugs/issues:
The PersistentTrader can current be requested to execute any command line when a particular locale is looked up; any process can make this request. This command line is executed as the user ID as which the PersistentTrader is running. This is very bad. Soon the trader should be fixed to only start a restricted range of applications.

SimpleApp

Usage:
SimpleApp
Purpose:
A MASSIVE-3 example world with multiple locales. Creates a world with lots of locales (parts of a football stadium).
Source directory:
stdapps
Bugs/issues:
Always registers the locale as "LocaleAppEnvironment".
Each user client's CRGPATH must include the etc/ subdirectory in order to obtain the necessary geometries.
You may not have the correct graphics files to see anything!

Trader

Usage:
Trader
Purpose:
The standard (non-persistent) naming service, required to bootstrap any use of MASSIVE-3. See section 2.1.
Source directory:
stdapps
Bugs/issues:

VerySimpleApp

Usage:
VerySimpleApp
Purpose:
A minimal MASSIVE-3 world-creating application.
Source directory:
stdapps
Bugs/issues:
Always registers the locale as "SimpleAppEnvironment".
Each user client's CRGPATH must include the etc/ subdirectory in order to obtain the necessary geometries.

References

[1] "HIVE Kernel Locale facilities - overview", Jim Purbrick, Jan. 1999. http://www.crg.cs.nott.ac.uk/research/systems/MASSIVE-3/docs/locale-overview.pdf

[2] "HIVE Kernel Locale facilities - details", Jim Purbrick, Jan. 1999. http://www.crg.cs.nott.ac.uk/research/systems/MASSIVE-3/docs/locale-implementation.pdf