Chapter 3. Using VOS to Explore and Build Virtual Worlds
While the object system described in the preceding chapters is general purpose, it was concieved with a specific use in mind: as the infrastructure on which to build multiuser 3D virtual environments. This chapter explains how to use VOS to explore and build such environments. First, we need some object types that represent objects in 3D worlds: this collection of MetaObjects is called A3DL (Abstract 3D Layer). Then, a client program is needed to find those objects, render them graphically, and provide controls for interacting with them and with other users in the world: this program is called Ter'Angreal (and its helper, Metatronic). Finally, we need some tools for creating 3D geometry and publishing it as A3DL objects.
The following sections describe the client program, Ter'Angreal, and some world building tools: the VOS World Server, the Blender export script, the A3DL converter for converting 3D Studio Max ASE files, and the swiss army knife shell tool, Mesh.
3.1. Ter'Angreal
Ter'Angreal [1] (which also was referred to as S3/VR in the past) is the VOS virtual reality application. It uses the cross-platform 3D engine Crystal Space to render graphics. In addition, it uses a program called Metatronic to provide a standard 2D GUI display. This section explains how to install and use Ter'Angreal.
3.1.1. Compiling Ter'Angreal
Ter'Angreal is available in both source code and binary forms. If you wish to download precompiled binaries, see Appendix A. For instructions on how to compile Ter'Angreal (and the rest of VOS), see Chapter 4. This section contains some information specific to compiling Ter'Angreal from source code.
Ter'Angreal uses the Crystal Space 3D engine. If you are building Ter'Angreal from source, you must download and install Crystal Space separately. You should download the most recent version of Crystal Space (as of this writing, 0.97 from CVS). Crystal Space can be found at http://crystal.sourceforge.net.
Unpack Crystal Space and follow the directions supplied to compile or install it. If you are compiling Crystal Space yourself, you may want to enable some of the plugins which are disabled by default [2] You may install it globally on your system after compiling if you wish, but this is not required.
Set the CRYSTAL environment variable to point to the CS directory. If you are using the bash shell, do this:
$
export CRYSTAL=/your/path/to/CS
(You can add that line to your .bashrc file to
execute automatically in the future if you wish.)
If you are using the csh or tcsh
shells, do this:
%
setenv CRYSTAL /your/path/to/CS
(You can add that line to your .cshrc file to
execute automatically in the future if if you wish)
If you are using Windows NT, 2000 or XP, set the variable in the
System control panel.
Now you can configure and build the VOS corelibs, metaobjects and 3D packages. The 3D configure script should now detect cs-config and build Ter'Angreal. (If you have already configured and built the 3D stuff, you will need to configure and rebuild). See Chapter 4 for more information about building and installing VOS
3.1.2. Connecting to a 3D Server
When you first run Ter'Angreal, you will be presented with a listing any 3D worlds that Ter'Angreal has discovered on the local network, servers that have been registered in the interreality.org service directory, and with any other service directories you have added to Ter'Angreal's configuration file. To connect to a world server, select one of the items on the list and click on . Alternately you may type in a different world URL in the supplied text entry and click on . You may also change the name you will use in that world.
Ter'Angreal will then connect to that work, search for 3D objects, and begin downloading. When it is finished, a message is written to the output box at the top of the screen. At this time Ter'Angreal will also try to find a running Metatronic GUI display. If one is not found after a period of time, Ter'Angreal will try to run Metatronic based on the settings in its helpers.cfg config file. Once it has made contact with Metatronic, a small GUI window should appear.
To find servers on the local network, Ter'Angreal queries the service list daemon, servicelistd. This is included in the VOS Apps package. Ter'Angreal also uses the servicelistd to search for a running Metatronic GUI display. If you experience problems finding servers or running Metatronic, you can run these programs manually.
3.1.3. Controls
Once you have successfully connected to and downloaded the world, you will be placed at its starting viewpoint. From there, you may move around with the mouse and keyboard. These are the default button/key actions; they can be changed in the keys.cfg configuration file.
- Mouse1 (left mouse button) or Up arrow
Pushing and holding this button will make your avatar move forward.
- Left arrow
Turn avatar left
- Right arrow
Turn avatar right
- PgUp
Turn avatar up
- PgDn
Turn avatar down
- Mouse2 (right mouse button) or Control+Mouse1
Holding down this button enables "mouse look" mode. When "mouse look" is on, moving the mouse will turn your avatar. You can also toggle "mouse look" on and off with the Tab key.
- Mouse3 (middle mouse button) or Alt+Mouse1
Clicking this button will select a 3D object, popping up a window offering ways to interact with the object (Note: some features are still incomplete). After selecting an object, dragging with this button will allow you to move the selected object around.
- Shift+Mouse3 (middle mouse button) or Alt+Shift+Mouse1
If you drag with the middle mouse button while holding down shift, you can rotate the selected object.
- Ctrl+Z
"Push" selected item forward
- Ctrl+Shift+Z
"Pull" selected item backward
- Esc
Deselect object(s)
- Shift+Left arrow
Move left
- Shift+Right arrow
Move right
- Shift+Up arrow
Move up
- Shift+Down arrow
Move down
- Home
Straighten
- Ctrl+Q
Quit
- Show Avatar List
F1
- Show Viewpoint List
F2
- Next Viewpoint
CTRL+]
- Prev Viewpoint
CTRL+[
- Toggle object tags
F5
- Toggle object types
F6
- Toggle system-info display
F7
- Toggle selected-object box
F8
3.1.4. Configuration
The configuration files for Ter'Angreal are: terangreal.cfg, keys.cfg, commands.cfg, and helpers.cfg. Ter'Angreal searches for each configuration file in the following directories, in the following order, if they exist. The first file found is used. (You can also add an additional directory with the --add-config-dir command-line parameter to terangreal.
On Windows NT, 2000 and XP:
\Documents and Settings\ USER\Application Data\TerAngreal
\Program Files\TerAngreal
On Windows 95, ME and 98:
\Windows\Profiles\USER \Application Data\TerAngreal
\Program Files\TerAngreal
On Mac OSX:
HOME/Library/Application Support/TerAngreal. This directory will be created if it does not exist. Cache files are kept here as well.
/Library/Application Support/TerAngreal
The TerAngreal application's internal resources.
On Other Unix Platforms:
The current directory
a .terangreal directory in your home directory This directory will be created if it does not exist. Ter'Angreal also keeps it's cache files here.
Install Prefix/etc/terangreal/
/etc/terangreal/
In terangreal.cfg, you can set many options, such as your avatar, default starting world, GUI options, tracking device paramters, as well as options for the CrystalSpace 3D engine (color parameters, screen size, OS parameters, etc.). keys.cfg and commands.cfg are used to define the key and text commands. helpers.cfg is used to determine which external programs to run to follow hypercards to non-3D-world objects (e.g. random data files, web pages, etc.), and where to find metatronic if it needs to be run at startup.
3.1.5. Text messages and commands
Text typed into the bar at the bottom of the screen will be sent to all other users in the world. In the large message window near the top of the screen, you will see messages from the system, and from other users.
You can also use the text input window to give commands to Ter'Angreal. Commands are defined in the commands.cfg configuration file. By default, commands start with the '/' character.
In addition, if you turn on the CommandSocket option in the configuration file, or with a command, TerAngreal will open a TCP/IP socket at port 8003 that can be used to give text commands.
 | Be very careful with this option, as anyone will be able to connect and give commands using this socket, including /system commands that run in your shell! Only use CommandSocket in a highly trusted LAN, preferable isolated from other networks. |
3.1.6. Supported file formats
Ter'Angreal can load several formats for 3D model objects and for texture images, using the CrystalSpace file importers/converters. Supported 3D model formats are: Wavefront/Maya (OBJ), 3D Studio Max (3DS, ASE), Quake (MDL), Quake II (MD2), PovRay (POV) and ".SPR" (CS sprite format). Supported image formats are: JPEG, PNG, GIF, Windows bitmap (BMP), SGI bitmap (SGI), Targa bitmap (TGA) and ".WAL" (I have no idea what this is).
3.1.7. Troubleshooting
- Q: When I start Ter'Angreal, I get an empty window frame, or I get errors about OpenGL. What is going on?
- Q: Why don't 3DS models don't show up?
- Q: Why do I get errors such as "Warning: Crystal Space installation directory not detected." and "WARNING: could not load plugin 'crystalspace.kernel.vfs'" and then "Warning: could not find any valid config file!" when trying to run Ter'Angreal?
- Q: What does the error message "8-bit palette mode no longer works in the software renderer!" mean?
- Q: What about errors about "DirectDraw"?
Q: When I start Ter'Angreal, I get an empty window frame, or I get errors about OpenGL. What is going on?
A: Your graphics hardware may not support OpenGL, or it may be misconfigured. To use the software-only renderer, run terangreal with a command line option "-video=software" or edit your terangreal.cfg file and set System.PlugIns.VideoDriver to "crystalspace.graphics3d.software".
(To explicitly turn OpenGL on, use "-video=opengl" on the command line, or set your VideoDriver to opengl.)
If you have an OpenGL graphics card, make sure you have the latest OpenGL drivers and libraries, downloaded from the manufacturer if possible.
A: If you don't see 3DS models, the 'ie3ds' plugin for CrystalSpace plugin is probably not installed. To build this plugin, first install lib3ds. Then re-run CrystalSpace's configure script, (use the --with-lib3ds option if lib3ds is not in a default path) and run 'make ie3ds', then reinstall. The lib3ds webpage is http://lib3ds.sourceforge.net.
Q: Why do I get errors such as "Warning: Crystal Space installation directory not detected." and "WARNING: could not load plugin 'crystalspace.kernel.vfs'" and then "Warning: could not find any valid config file!" when trying to run Ter'Angreal?
A: Try setting a CRYSTAL environment variable to the location of CrystalSpace. If you use Ter'Angreal often, you might want to set it in your shell init file (e.g. .cshrc or .bashrc). In Windows, you can set environment variables in the System control panel. (The CRYSTAL environment variable should not be needed if CrystalSpace is installed in its standard location, or in the same directory as terangreal.)
A: CrystalSpace's software renderer only supports 16 and 32 bit color mode, not 24 bit. You may need to change your system's display settings to use 32 or 16 bit color mode.
A: You need to install DirectX. You can usually do this via Windows Update