CaveUT 1.2

Software for Integrated Multi-Screen Displays
Using Unreal Tournament.

CaveUT is a set of modifications, which allows the game Unreal Tournament (UT) to display correctly in CAVE-like displays and panoramic digital theaters. It supports off-axis projection for correct perspective and multiple views from the observer's viewpoint. This page will give a brief introduction, download information, installation instructions, and finally some more detailed explanation. CaveUT is open source and freely available to the public.

New in 1.2: Greatly improved view rotation logic by Willem de Jonge. Detailed instructions on how to make your own PC-based cave. CaveUT for Linux by Joe Manjlovich. How to use the GameBots mod to control CaveUT through a simple TCP/IP connection. Viewpoint offset parameters. Bug fixes and updated insructions.

We developed CaveUT on the BNAVE a PC-based CAVE-like display the Medical Virtual Reality Center, Department of Otolaryngology, University of Pittsburgh. To the left is a pic of a test subject standing in front of two screens of the BNAVE with CTF-LavaGiant (a virtual world that comes prepackaged with UT) displayed in the background. The screens are at an 80.5-degree angle to each other, and we are looking straight into the corner.

The BNAVE consists of three walls arraigned in a "U" around the viewer. A fourth projection surface has been added to the floor, which we have not used, yet. Each wall is a rear-projection screen, upon which The SVGA output of a dedicated PC is rear-projected onto each of the three screens of the BNAVE. All the PCs are connected through a standard LAN, which includes an extra PC. On the extra PC we run a standard networked game with one player. Each screen-PC runs a spectator that is co-located (live-feed) with the player. The modified game code performs the view rotations needed to make the screen views line up. One spectator produces the center view, while the others produce the left and right view. To get the perspective correction right, we subverted the OpenGL code in the open-source portion of UT's C++ code

To make a long story short, CaveUT allows you to have up to 32 "windows" onto a virtual world, all perspective corrected and synchronized for a (theoretical) single observer. With respect to the viewer, the screens can be oriented in almost any way. The simplest example is a two-screen arrangement shown on the right. It showed at CHI 2002 and will show at Ultra Unreal and the HFES 46th meeting. It uses tripod-mounted projectors to project onto screens stretched from a collapsible frame made from PVC pipe. If you would like to build one for yourself, please take a look at my detailed instructions.

The Earth Theater (left) at the Carnegie Museum of Natural History has a CaveUT installation. The theater has a fully digital display composed of five curved front-projected screens spanning 210 degrees horizontal and 30 degrees vertical. Five standard video projectors, each driven by a PC running windows, produce the Unreal Tournament display. As you would expect, each of the five projector PCs is running a spectator, which provides the appropriate view from a single player on a sixth PC. Interestingly, the careful design of the theater makes off-axis projection unnecessary. However, the curved screens require a spherical correction of the image, otherwise we get those wedge-shaped overlaps you can see in the image if you look closely. I am currently soliciting help to add spherical correction to the OpenGL code. On the right is a Schematic of the Earth Theater. The screen is a section of a sphere, 210 degrees horizontal by 30 deg vertical. In the figure, the screen is depicted in a transparent white in front of the seats.

If you are interested in immersive gaming, you should also look at CaveQuake .

Installing CaveUT is not difficult, but using it correctly is. Be prepared to tinker with the view rotations and axis adjustments a LOT before you get it right. You may have to use lots of trigonometry. Also, creating the physical setup with screens and projectors can be a very large undertaking. Read my instructions first.

Contributors

How CaveUT Works

Requirements

Downloads

Installation on a Client Computer

A Playable Interface

Safety and Motion Sickness

Improvements Needed for CaveUT

Starting Up CaveUT

Off-Axis Perspective Correction

Measurements for Configuring CaveUT

Configuring CaveUT for Off-Axis Projection

Bugs

Tips and Tricks

How To Build Your Own PC-Based Cave

Contributors

Jeffrey Jacobson: Perpitrator in chief. OpenGL code. This web site. View rotation math and general design of 1.1. View location offsets. Physical UT_Cave design and instructions.

Willem de Jonge: View rotation math and code for 1.2.

Zimmy Hwang: Game code and general help with CaveUT version 1.1.

Joe Manjlovich: Linux version of 1.1

Many Others: For their technical and moral support.


Epic Games: Wrote this excellent game engine and the open-sourced game code. Under Epic Games' GPL license, Epic Games retains the sole right to make money on UT and anything based on it, including CaveUT. All code added to UT is required to be open-sourced and available for non-commerical purposes.

Dr. Michael Lewis: Extensive personal, academic, and material support. By extension, the creation of CaveUT is partially sponsored by AFOSR contract F49640-01-1-0542 through the Department of Information Sciences at the University of Pittsburgh.

Dr. Mark Redfern: Let Zimmy and I use the BNAVE for development of 1.1 and 1.2. By extension, the creation of CaveUT is partially sponsored by NIH P30 Grant DC05205 through the Department of Otolaryngology, University of Pittsburgh. CaveUT is free and open-source for non-commercial purposes.


Safety and Motion Sickness

It shouldn't surpise anyone if they get motion sickness in a UT cave. If you are particularly sensitive, be preparted to get a headache which could last a while. People who are unsteady on their feet for any reason, should sit while using the UT cave. If you show the UT cave to anyone who has not seen it before, stand near to them at first so you can catch them if they fall. If you are in an institutional setting, you may have to take stronger safety measures, like the safety harness in the BNAVE.


How CaveUT Works

Networked Game of Unreal Tournament

Typically, each player of a networked Unreal Tournament (UT) game has a standard desktop computer, running Windows, Linux or MAC's OS-10. Each one has a complete installation of the game, which we will call a "client." Each client communicates over a LAN or through the internent with the server, a process usually running on one of their desktops along with a client. The server maintains the authoritative copy of the virtual world which all the players share, so they can interact with each other. Each client maintains a complete copy of that world and all the things in it--including the (usually) human figure (avatar) for each player.

Every time a player takes an action, the environment creatures and avatars in their copy of the virtual world respond appropriately. As often a possible, each client tells the server what has changed on its end. The server reconciles the actions of all the players and issues an authoritative update to all clients, so they all change their copies of the world to reflect the new state of things. The process is remarkably seamless, if the network will allow these updates to happen frequently enough. This scheme has a lot of advantages. Not least, it allows for graceful and robust recovery from unexpected network delays. It also uses the minimum bandwidth possible, because the server and clients need only exchange updates, not models or imagery.

How Spectator Mode and Open Source Make CaveUT Possible

While the rendering engine for UT is proprietary, everything else in the game's software is open source. This allows a large community of fans, programmers and even some scientists to make changes and distribute them freely, as with CaveUT. UT and its modifications are available to the public for most non-commercial purposes, while Epic Games retains the sole right to make money off them.

Rather than showing up with an active avatar in the game, a player can show up as a "spectator" instead. Using the "behind view" option, the spectator player can see through the eyes of any of the other players in the game. In the standard UT_Cave setup, there is only one regular player in the game, controlled by whom we will call the "operator", using a desktop which we will call the "console". Each desktop showing a spectator view is connected to a digital projector, which projects the view onto one wall of the UT_Cave. In the two-screen example showed at at CHI 2002 (look right) and with the five-screen Earth Theater all the views are front-projected. In the four-screen BNAVE, the three vertical walls are rear-projected and the one floor screen is front-projected from overhead.

CaveUT is a set of modifications to UT's open-source game code which changes the view rotation and perspective correction of a spectator's view. In the simplest possible example, is the two-walled using the corner of a room as its projection surface. In the UT softare one spectator's view is hacked to look 45-degrees to the right, rather than straight ahead, rather than the straight-ahead view the console shows. That image is projected on the screen on to the right of the optimal viewing point. The other spectator's view is turned 45 degrees to the left and shown on the wall to the viewer's left. The perspective correction is changed on each screen to be correct for the established viewing point. This provides a single, contigous image to the viewer. It is immersive in the sense that the perspective correction is approximately the same as if the virtual world were real the viewer were seeing it from that location.

As the operator navigates through the virtual world, the view on the two screens change in lockstep. Using a typical LAN, properly, the client-server updates can be so quick that there is no latency between the screens and the game provides nearly thirty frames per second. There is no need to explicitly synchronize the screen updates when they update so quickly.

Getting Creative

As you might expect, a CaveUT setup can have many screens. Currently, UT has a limit of 32 players allowed in any one game, so you could make a 31-screen display. The screens can be oriented in almost any arbitrary orientation and distance to the player. The screens don't even have to be connected! For example, you could build an airplane or even mini-submarine cockpit simulator with a separate CaveUT view for each viewport or window. For a driving simulator, you could simulate a rear-view mirror with a very small CaveUT screen.

Consider this: You could have one computer on your network hosting a game and connect more than one CaveUT setup. To do this you would have several operator consoles. One for example, could have four spectators focused on it, to make a display similar to the BNAVE. That would use up five players against the limit of 32--one for the operator and four for the viewers. You could then have three players used for a V-Cave and seven more used for a totally immersive six-walled cave. All three operators would each see the other two as avatars in his or her own CAVE-like display, because they would all be sharing the same virtual world. Remember that there is only one server running. In this scenario, only fifteen "players" are in use, against the limit of 32. So, the server could handle up to 17 more players, where (for example) each one is on a simple deskstop, using the game in the normal fashion. All twenty users would share the single virtual world.


Controlling CaveUT From a TCP Socket

GameBots is also a freeware UT modification intended for scientific research. Once installed, it allows the researcher to open a standard TCP connection to UT server which causes a human figure, a "bot", to appear in the virtual world. This bot can be controlled through commands sent to GameBots over the TCP connection, from some sending program. The sending program can be written in any language capable of opening TCP sockets. You could even use Telnet, though I reccommend it only for debugging purposes.

Spectator mode in UT can "watch" a bot created by GameBots. Therefore, you can install GameBots on your UT server along with CaveUT, and effectively control the display over the TCP connection just by moving the bot! You can also create more bots which can look like anything and can be controlled over their own TCP connections. This allows you to write your own software to present a wide range of visual experiences and interactive designs.

For example, I recentely used UT/GameBots/CaveUT and LabView to instrument an experiment in the BNAVE, with help from Dr. Patrick Sparto and Leigh Mahoney. Lab View is a software package used by many experimental scientists to perform data acquisition and instrument control for lab experiments. It can be used to control actuators, read sensors, and execute programs written in it's built-in scripting language. At the appropriate times during the experiment, the experimenter I ran a Lab View script which would send commands to the operator PC's UT installation. The diagram one the right summarizes the setup.


Requirements

Operating System

CaveUT's modified OpenGL code works in MS Windows and now Linux. To my knowledge, Epic Games has not released its OpenGL driver code for the MAC, and unless they do, there cannot be a MAC version of CaveUT. All the instructions assume the user is using some version of MS Windows. Click here for the additional instructions for the Linux version. Be aware that only CaveUT_1.1 has been translated to Linux. The 1.2 changes should be easy to add....

Hardware

Basically, anything that can run Unreal Tournament to your satisfaction. Even an ancient PC, like a P2-MMX 300mhz will do fine, just so long as you have a good OGL capable graphics card. I recommend Nvidia's GeForce-4, but there are other good brands.

Unreal Tournament

You will have to buy a $15 copy of the game for each PC in your display's mini-network. You must also download and install the Unreal Tournament patch, version 436. You must not use an earlier or later patch, because that's the last version for which Epic games released their OpenGL driver code. CaveUT uses modified modules from that release.


Downloads

Currently, download is offered via http only. If you have any problems, let me know ASAP at goshen@sis.pitt.edu. In your web browser click on:

CaveUT_1.2.zip
and save it to any handy directory. You can unpack it using WinZip or something comparable. (Someday, I might make this into a UMOD, but not until CaveUT is considerably more mature.) Next, download the UT 436 patch:
UTPatch436.exe
That's all you need for the Windows version of CaveUT. Alternatively, you can click here for the
Linux version of CaveUT 1.1.

If you are interested in playing with the code, you will need the 432 code headers:

ut432pubscr.zip
I compiled them and the C++ CaveUT hacks using MSVC C++ 6.0 successfully. If you really want to change the code, you need to make certain changes to your default project setting. I'll post the needed changes, here, if anyone seriously wants them.

Finally, you can still get CaveUT_1.1.zip for Windows, here. It requires the UT 432 patch.


Installation on a Client Computer

These instructions refer to what you must do for each PC that produces the digital image for one screen of your multi-screen display

1   Install Unreal Tournament

Just follow the instructions that came with it.

2   Install Version 436 Patch

Download it to any convenient directory and execute it. It should find your Unreal Tournament Installation and do what has to be done.

3   Set Video Options

From the main control panel, go to Options->Preferences and select the "Video Options" tab. Select OpenGL for your video driver. With Version 436, UT will usually crash when you change video driver, but when you start it up again, it's all right. Yeah, it's stupid, but the game is otherwise quite stable. Really.

4   Optional: Backup certain files

Installing CaveUT will change these files in your ./UnrealTournament/system/ directory: User.ini, OpenGLDrv.ini, OpenGLDrv.dll, Engine.u. It's a good idea to make copies of them before you get started. If CaveUT somehow trashes your UT installation, you can always repair it by bringing these files back.

5   Move CaveUT.zip

Put this file in your ./UnrealTournament/ directory.

6   Unzip CaveUT.zip

Be sure to have the "Use folder names" option on, so it will put the files in the correct subdirectories. Unzipping will place these files in your /UnrealTournament/ directory:

Readme.txt

Right now, it's a pointer to this web page, plus change history notes. Eventually, it will have full instructions for CaveUT.

BNAVE-Actual-Cave.ini

The CaveUT configuration file for the BNAVE. Put here as an example.

CaveCalc Source

The source for CaveCalc.exe. I compiled using MSVC 6.0.

OpenGL.cpp

The modified source code for the UT OpenGL code. You won't need this unless you want to make changes to CaveUT's OpenGL code. To recompile CaveUT using MSVC++, copy pubscr436.zip into your UnrealTournament directory and unzip it. Be sure to look at its README file. Then, copy the modified OpenGL.cpp file into /UnrealTournament/OpenGL/Src, and recompile to create a new OpenGLDrv.dll. All the interesting stuff happens at the OpenGL call to glFrustum. If you really are serious about modifying this code, let me know and I'll post more detailed instructions.

Then, these files will go into your /UnrealTournament/system/ directory:

Cave.ini

Configuration file for CaveUT. It contains the roll, pitch and yaw parameters, which determine the direction gaze (in the virtual world for this display. Three offset parameters X, Y and Z allow you to offset the view CaveUT renders from the actual location of the single player. It also has dimensions, orientation and distance information for the display, with respect to the real viewer. Detailed instructions on how to fill it out are described in the CaveCalc tutorial below.

CaveCalc.exe

A simple program, which reads Cave.ini and modifies User.ini and OpenGLDrv.ini. You should not edit these files directly, but allow CaveCalc to do it for you. It computes the required off-axis projection parameters and FOV needed to make the display's perspective converge on the viewer's location. This information and the roll, pitch and yaw parameters are written out in a form the modified UT code can read.

OpenGLDrv.dll

The modified version of the code UT uses to talk to OpenGL. So far, it works equally well for Windows NT, 2000 and 98.

OpenGLDrv.ini

Configuration file for graphics drivers, containing extra parameters OpenGLDrv.dll. You may notice that the extra parameters refer to "long side" and "short side" instead of "Y side length" and "X side Length" respectively. This is a holdover (actually a hangover) from a time when I was thinking about the math differently. I will normalize the terms when I get around to it. This should have no effect on anyone who just wants to use CaveUT.

User.ini

General configuration file for game play. When WinZip writes this file into your ./UnrealTournament/system/ directory, it will trash your game preferences, such as controls, handedness, and so on. You can set them back through UT's "Options" control panel. You will find the CaveUT related parameters at the bottom of User.ini: Roll, Pitch and Yaw.

Engine.u

The modified game code for Unreal Tournament, written in "Unreal Script" a Java-like language. It can be opened and modified using the Unreal Editor. It contains the modifications needed to add the roll, pitch and yaw modifications to the viewer's (virtual) viewpoint in the Unreal world. It also turns off the Head's Up Display and the Weapon, all of which are figures drawn in the foreground during normal play.

7   Run Unreal Tournament

Just to test it. The default settings for CaveUT is to make the HUD and the weapon go away, but to have no other effect on the display Make sure UT displays properly. This is a good time to reset your preferences, like handedness and game controls, to what you prefer.

8  Be Sure to Put the Client Into "Spectator" Mode.

In the first screen for UT, the one with all the menus along the top, go to the "Options" menu and select "Player Setup." A dialogue box will pop up. Click the "Play as Spectator" checkbox. Check it and exit. This will enable the CaveUT code.

9   Configure Cave.ini

First, figure out the added Roll, Pitch and Yaw you want for your display.

For example, if you want the display to always show you what is directly to the left of the viewer, then you want a Yaw of -90 degrees. Do this by editing the Yaw value in Cave.ini. Initially, just changing it from zero (the default value) to -90. Run CaveCalc (see instructions, below), which will automatically change the Yaw value in User.ini. The Pitch and Roll parameters work the same way. For Pitch, up is positive and down is negative. For Roll, right is positive and left is negative. Make sure that no other program, like Notepad, has either file open. If so, CaveCalc will not perform the update and (currently) will not warn that it failed.

Alternatively, you could change this by editing your new User.ini file, directly. Just edit the "yaw" value, one of the new parameters at the bottom. However, you must multiply the -90 by 179, then you add the result to the yaw value already there. (The default value of "Yaw" is zero.) To look to the right, multiply 90 by 179 and add that to the original Yaw.

Creating side views like this, without altering the perspective correction, is useful for testing and adequate for some kinds of displays. For example, the Earth Theater does not use off-axis projection, at all, because of its particular design. If you do need perspective correction, read the CaveCalc tutorial and the math sections in these instructions, make the appropriate changes to Cave.ini and run CaveCalc.

You also have the option of creating a perminant X, Y and/or Z offset between the single player's location and the viewpoint CaveUT renders. For example, if you change the X_Offset paramter in cave.ini from its default zero to 10, then CaveUT will always show the viewpoint 10 unreal units along the X axis away from the player's viewpoint. Similarly with the Y_Offset and Z_Offset parameters.

This is useful for helping you match up your screens or create interesting effects. You know that gun and hand in front of you? It's actually very very small but very close to your eye. You can make it move radically with very small adjustments to the offsets--small in comparison to the difference it makes to your viewpoint in the virtual world.

(If you are configuring multiple screens, it is easiest to edit just one copy Cave.ini, entering the measurements for each screen under its name. Then, copy it to the /UnrealTournament/system/ directory on each machine. Be sure to put the current screen's name at the top of Cave.ini, so CaveCalc will use the appropriate measurements.)

10  Run CaveCalc.exe

In windows, just double-click the file icon. A window may pop up or it may flash by. In either case, it will update user.ini and OpenGLDrv.ini

11  Setup a Connection Shortcut.

Create a shortcut to UnrealTournament.exe and put it on your desktop, or some folder you plan to have open just before you launch this client's copy of UT. Left-click on the icon, in the menu that pops up click on "properties", and edit the "target" field. The "target" should be:

.../UnrealTournament/system/UnrealTournament.exe
On the end of that string, add a space and the IP address of your server machine. For example:
.../UnrealTournament/system/UnrealTournament.exe 123.456.789.012
With this modification, clicking on the shortcut will start up UnrealTournament, which will immediately try to connect to a multi-player game on your server machine. As you will notice when you play with CaveUT a bit, changing the perspective correction always clips off part of UT's display and stretches what's left across the whole screen. Depending on your modifications, this usually makes UT's main control screen very difficult to use, because the menus are usually off the edge!


Installation on Your Server Machine

1   Install Unreal Tournament.

Install UT on your server machine.

2   Install the Version 436 code patch.

All you have to do is install UT and the Version 436 code patch.

3   Install CaveUT.

Copy CaveUT.zip into your /UnrealTournament/system/ directory, and unzip it. Do not run CaveCalc.

4   Fix your preferences to what you like.

This machine is essentially the control console for your panoramic display. You don't even have to use the OpenGL graphics drivers, but it's probably a good idea. That way, your server's console display will look more like what's on your multi-screen display.

5   Create a shortcut to UnrealTournament.exe.

Just as you did with the client machines, but instead of putting the IP address after "../UnrealTournament.exe", put "-alladmin". This will allow you to issue useful commands from the control panel, as described in the UT documentation.

If your display does not require off-axis projection, you are ready to start, as described in the next section. Otherwise, you will have to fill in the values needed in Cave.ini.


Starting Up CaveUT

After you have configured Cave.ini for each of the projector machines and run CaveCalc, do the following.

On the server machine, start a multi-player game with the level of your choice. Make sure the bots are turned off, at least until you are comfortable with CaveUT.

On each of the projector machines, double-click your desktop icon for UT to start it up.

Press the "fire" button on the keyboard or mouse on each client. That will change the spectator's viewpoint to the one player in the game It should automatically connect to your server machine, as a spectator, seeing through the eyes of the one and only player. All the rotations and perspective corrections should kick in.

The images on your screens will never line up the first time. Use the roll, pitch and yaw parameters in Cave.ini to tweak the views to match them up. Use the X, Y and Z offsets only if you must. Do not tweak the perspective correction just to make your screens line up, unless you really know what you are doing. If the perspective appears to be wrong, it's best to just check or retake your measurements.

With luck, that should be all you have to do. Real life is never so easy. As I find time, I will add troubleshooting notes.


Off-Axis Perspective Correction

The math for CaveUT is remarkably simple, calculating just a few modifiers to Unreal Tournament's display, leaving UT to do all the hard work. The following discussion doesn't show how to do the calculations, but presents the basic concepts, so you can use CaveCalc (a stand-alone program) do the math for you.

In western culture, ever since the renaissance, paintings have use the technique of perspective correction to create an illusion of depth. In its most simple form, the primary lines in the composition all converge to a single point on the canvas, called "the vanishing point". The same effect is widely used in photography, film, and computer imagery. There must be thousands of explanations of this basic principle, which you can find in textbooks for art, computer graphics, human perception, mathematics and more. I found one by Dzorin on line, but you would do better with an art text.

Think of Unreal Tournament displaying on a single screen in the standard way. The vanishing point of the image is co-located with the physical center of the screen, as with most "first-person" video games. A "first-person" view of a virtual world presents the screen as a moveable window onto the world. Ideally the perspective of the presented image is the same as if you are looking through a window onto a real scene. The general situation is illustrated here: In figure one, the viewing frustum is simply a way to describe what the viewer can see through a window. With a painting or photograph or video game, the frustum extends from the eye, though physical space and into virtual space. The illusion of depth is correct, but (usually) only so long as a perpendicular drawn from the plane of the image to the observer's eye is over the vanishing point in the display. For Unreal Tournament, this means that you have to be looking straight at the center of the screen for the depth illusion to be mathematically correct.

In practice, your brain is very agile, and will allow you to comfortably view a movie/photo/painting/video-game from a considerable angle in comfort. However, you can only do this with one display screen at a time, and the whole idea behind CaveUT is to array several screens around the viewer to create an immersive display, like so:

In the figure to the left, the viewing frustum associated with each screen is shown in dashed lines. (The floor is also a screen) Each frustum begins with the viewer's eye, occupies an area in physical space shaped roughly like a pyramid up to the projection screen, then continues through virtual space to an imaginary infinity. The perpendicular line from the viewer's eye to each screen is shown in light gray. Where the perpendicular intersects the plane of the screen is the vanishing point of the image shown on the screen. Is it important to note that all four viewing pieces fit together like overly simple puzzle pieces. This allows the viewer to look in any direction and see all objects in the virtual scene in correct perspective. Properly done, four paintings or photographs could achieve the same effect, but for one static scene, only.

CaveUT's primary ability is to move the vanishing point in UT's display someplace other than the center of the screen. The vanishing point need only stay in the same plane as the display itself. That is how all four screens of the BNAVE can have their view frustums converge on the same point, as shown in figure above, despite their different orientation to the viewer. Theoretically, you could use CaveUT to orient lots of view screens at all sorts of weird angles to the viewer, and each one would show part of consistent view of the virtual world. Personally, I have never tried anything stranger than the BNAVE and the Earth Theater.

Definition of Terms:

Display
The computer monitor or the image on your wall or screen produced by your digital projector.

X Side
One side of your display area. By (my) convention the shorter side, which on a typical computer monitor the display height.

Y Side
The other side of your display area. I assign this term to the width of the display on a typical computer monitor. The aspect ratio of the X side to the Yside is usually 3/4.

X Side Displacement

The distance from the physical center of the display to the new vanishing point along the display's X-axis.

Y Side Displacement

The distance from the physical center of the display to the new vanishing point along axis of the display's y-axis.

Vanishing Point Displacement (VPD)

The X and the Y displacements, together.


Measurements for Configuring CaveUT

To use CaveUT, you will need to come up with two sets of specifications for EACH view screen. The term "view screen", as it is used here, refers to the portion of the physical display, which is actually showing pixels generated by the PC's video card. Almost always, there is some extra physical screen or monitor material around the edges of computer-generated display, which we are not concerned with here.

First, you will need to rotate the display for each view screen (except possibly a single front screen) so it will show the correct part of the virtual scene. With the BNAVE, for example, the front screen does not need to be rotated left of right (yaw) because by default it shows a right view. The right screen's display needs to be rotated to the right by 80.5 degrees, so it will show things to the right of the viewer, as shown in the figure to the right. Similarly, the left screen needs a -80.5 degree rotation (yaw) and the floor screen needs a 90-degree rotation (pitch).

Second, you need to figure out where this view screen's new vanishing point has to be for its corresponding view frustum to line up with the screen's four corners and the viewer's "eye" location. To do this, draw a perpendicular line from that point to the plane of the view screen. (For now, let's assume that this point is on the view screen itself--CaveUT can support more dramatic adjustments, which are not needed for the BNAVE.) Measure the X and Y displacements and the location of the original vanishing point, to the new one, the where the perpendicular intersects the plan of the screen. As with all measurements for CaveUT, you can use any unit(s) of measurement you want, as long as you are consistent. CaveUT uses only ratios of distances, so your measurements can all be in inches, meters, light-years or furlongs, as long as they are all in the same unit of measurement.

Do this for all your screens. Follow the instructions for "configure Cave.ini".


Configuring CaveCalc for Off-Axis Projection

CaveCalc is an intermediate program, which pre-digests your settings in Cave.ini and writes them into Cave.ini and OpenGLDrv.ini. I don't want to make it too fancy, because it will eventually be replaced by (new) code within UT itself when I, or someone, adds in real-time head tracking. I could move the code for CaveCalc into UT, now, and maybe I should. It's just that I don't like making any more changes than I have to the Core UT code, especially when they are throwaway changes. Besides, keeping the CaveCalc code separate allows people to experiment with it safely. The equations in there are bound to need some refinement.

To function properly, CaveCalc needs to be in the same directory as Cave.ini (input) and User.ini (input and output) and OpenGLDrv.ini (output). That's why you should normally run it in your /UnrealTournament/system/ directory, but you can test it out in separate directory. It reads from Cave.ini, it modifies User.ini, and it completely overwrites OpenGLDrv.ini. You can run it by double-clicking its icon, run it from the "run" command above the "start" menu or from DOS prompt. It will pop up a DOS window with some debugging output, just to let you know it's working properly. At this point, the User.ini file and the OpenGLDrv.ini files should have been changed, appropriately.

Below, are the contents of a sample Cave.ini file:

[BNAVE]
WhichScreen=[BnaveDefaultScreen]

[BnaveRightScreen]
RollInDegrees=-90.0
PitchInDegrees=-2.6
YawInDegrees=80.5
bb CaveOffsetX=0.0 CaveOffsetY=0.0 CaveOffsetZ=0.0 YsideLength=94.0
XsideLength=70.5
YsideDisplacement=18.0
XsideDisplacement=11.5
DistanceToScreenPlane=43.7

[BnaveDefaultScreen]
RollInDegrees=0.0
PitchInDegrees=0.0
YawInDegrees=0.0
CaveOffsetX=0.0 CaveOffsetY=0.0 CaveOffsetZ=0.0 YsideLength=1.0
XsideLength=1.0
YsideDisplacement=0.0
XsideDisplacement=0.0
DistanceToScreenPlane=1.0

The first line "[BNAVE]" is just a title, you can write anything into. Useful for saving multiple configurations. Remember that CaveUT, at this time, only supports one optimal viewing location for the user's eye, at any one time. So it might be useful, for example, to have several different Cave.ini files on hand, for different eye heights. Say, one for you, one for your kid, one for you when you are sitting, you standing, and so on.

The next line, "WhichScreen=[BnaveDefaultScreen]", identifies which set of parameters below will use for CaveCalc's calculations. So, with "WhichScreen" set to "BnaveDefaultScreen", CaveCalc will read only the parameters under the "[BnaveDefaultScreen]" title. Each set of parameters has one title (which can be anything) followed by eight parameters, starting with "RollInDegrees" and ending with "DistanceToScreenPlane", all of which I will now explain:

RollInDegrees=real

Rotate the view (of the virtual world) on the display by the specified degrees. Positive numbers rotate the scene clockwise, negative numbers rotate it counter-clockwise. For example,

RollInDegrees=90.0
will turn the scene sideways, as shown in the image on the right. Or, you can rotate the image counter-clockwise with:
RollInDegrees=-90.0
which will also turn the scene sideways, but in the way shown on the left.

PitchInDegrees=real

Works the same way "RollInDegrees" does, except that it rotates the scene up (looking at the sky) or down (looking at your feet). Positive values will rotate the scene upwards, while negative values rotate it downward.

YawInDegrees=real

Works the same way as "RollInDegrees" and "PitchInDegrees", except that it rotates the viewer's scene left or right. Positive numbers cause the scene to rotate to the right, negative numbers cause it rotate to the left.

X_Offset=integer

Offset the rendered view from the location of the single player. The offset is along the X dimension according to player figure's internal coordinate system. So, the CaveUT "eye" would be locked to a certain distance and orientation from the player's viewpoint. The best way to learn what affect this has is to experiment with it.

Y_Offset=integer
Z_Offset=integer
YsideLength=real
XsideLength=real
YsideDisplacement=real
XsideDisplacement=real

DistanceToScreenPlane=real

The length of the perpendicular from the viewer's eye to the new vanishing point on the view screen.

CaveCalc computes the aspect ratio of the display from the X & Y measures. If you want to maintain a certain aspect ratio, you can force it by measuring the length of one side of the display and computing the other. The computed sides should be expressed in many digits to insure accuracy.

So, edit the Cave.ini file to add a full entry for each one of your display's screens. Be sure to keep the "DefaultScreen" settings, because you will need them to set your display back to normal. There is nothing wrong with having extra screen entries. TIP: When you are installing CaveUT on several PCs, create a single Cave.ini file with all the measurements for all the screens. unzip CaveCalc as described above, then copy your modified Cave.ini into each machine's system directories. Be sure to change the second line of Cave.ini on each PC, so the file points to the correct settings for that PCs display. Run CaveCalc on each machine, except for your server machine. Now, you should be ready to start.

To recompile CaveCalc using MSVC 6.0 on a Windows PC, go into the Project-->Settings dialogue box and click on the "Debug" tab. Set the "Executable for Debug Session" to ":\CaveCalc Source\Debug\CaveCalc.exe" And set the working directory to where you want it. The working directory must have "Cave.ini" for input, and "User.ini" and "OpenGLDrv.ini" for output.

A final note: When you use CaveUT to produce an off-axis projection where the new vanishing point is offset in both the X and Y directions, an apparent rotation in the view is introduced. You will see it along the side with the larger displacement. The explanation for this is lengthy, but the fix is simple--just introduce a counter-rotation using the roll, pitch or yaw values in "Cave.ini". For the BNAVE, for example, this extra rotation is about 0.5 degrees.


A Playable Interface

The two walled UT Cave showed at the gamer convention, Ultra Unreal, 19-21 July 2002. This was the first time the CaveUT 1.2 had any serious use and the first time CaveUT had been used by large numbers of gamers. There, I experimented with different control strategies with the help of expert players, like Ian MacKechney

Interestingly, most of the UT players at Ultra Unreal use keyboard and mouse, but that's not such a good option for a UT Cave. You would have to rig a platform to hold them up, and it's physical presence partially separates you from the visual display, degrading the experience.

I used a "MacAlley USB Airstick for the PC", bought in summer 2001. It is essentially a joystick which works normally, but with physical base. Instead, it uses built-in acellerometers to detect tilt, allowing you to simply hold it in mid-air. The control setting for (UT Main Menu)->Perferences->Controls are:


Fire: Joy-5
Alternate Fire: Joy-6
Move Forward Joy-4
Move Backward Joy-1
Strafe Left Joy-3
Strafe Right Joy-2
Jump: Joy-7 or Joy-8
Crouch/Down JoyPovDown
Joystick X-Axis Turn Left/Right
Joystick Y-Axis Look Up/Down

The Gravis Destroyer game pad worked reasonably well, and seemed to be easier to learn. But it lacked the analog control with a joystick, making targeting a little bit more difficult.

Obviously there are many, many other options. One I would like to see is giving the player a trackball to control view rotations, to reduce the load on his/her primary hand.


Tips and Tricks

When you are setting up CaveUT, try turning off spectator mode, turn on the HUD and make sure the crosshairs are visible. The crosshairs mark the vanishing point of the screen image. You can use that for calibrating your off-axis probjections and/or view rotations.

Instead of the crosshairs for targeting, which are turned off in CaveUT, you can simply tape a penny or something onto the screen where the weapons fire is focused. In a typical two-walled UT-Cave, this is about two-thirds of the way up from the bottom along the central seam.


Bugs

Animated 2D images which depict 3D shapes (billboards) don't look right in CaveUT. Examples include the background in CTF-Face or fires and sometimes weapons when they are spinning on the ground, waiting to be picked up. These images and animations are pasted onto 2-D surfaces located IN the 3D virtual world. As a result, the CaveUT hacks cannot change the way the objects in that image look, because they are already renedered. So, if such and image falls across the instersection of two screens, it's two parts will not line up. This is not so much a bug as an inherent limitation with billboards in 3D engines.

There is a long standing bug in UT's spectator mode (v432 & v436) which makes rotations in CaveUT jerkey. To my eye, about 1/3 of a second passes between the time a player starts to rotate and the time the spectator's view begins begins to rotate. Then the spectator's view jumps into the correct position, creating a visual jerk. If you are using any kind of button control for rotation, then it will be all jerks.

Generally, the views in CaveUT will occasionally get out of sync. They line up again, after the player fires his or her weapon. Sometimes the spectator's view will turn nearly sideways when its player first respawns after getting killed. The view realigns after the player starts to move then fires a weapon.

When you enter value (in degrees) for one of the rotation parameters in cave.ini, CaveCalc doesn't actually give you that rotation, you get something slightly less. You can overcome it by just messing with the rotation parameters, which you have to do to line things up anyway.

Always be sure to use 32-bit color depth in UT's video preferences. For some strange reason, it greatly reduces problems with coplanar polygons in some virtual worlds. When you change this parameter, UT will typically crash, but when you start it up again it's fine and the parameter has changed.


Improvements Needed for CaveUT

Care to help? CaveUT is a completely open-source effort, protected under Epic Games' GPL agreement. There is much to do, and I hope that people in the Unreal community are interested in developing CaveUT further. I am not quite ready to setup a Source Forge project...yet. But I am more than willing to post patches and/or additions to CaveUT, and help anyone who wants to work on such.

Make CaveUT into a Mutator

That would greatly ease installation and uninstallation issues. It would also be cleaner, providing a better base for everyone to work

Develop More and Better Control Interface

The solution descibed on this page is a good start, but there can never be enough testing and innovation on controls for CaveUT. Mainly, it would be good to separate firing direction from movement direction. Maybe with a head tracker, movement with a separate device (Handheld thing? Foot controls?) and weapon targeting with a third control. The cave player would have many advantages--and some disadvantages with respect to someone on the standard desktop VR arrangement. Exploring/exploiting these questions would be very useful and a lot of fun.

Empower the Viewer to Look Up and Down

Solved by Willem de Jonge's new view rotation code!   :-)

Put CaveUT Hacks Into a Separate Class

Currently, the changes in OpenGLDrv.cpp and Engine.u are just modifications to existing base code. The needed variables have to ride in on existing *ini files, User.ini and OpenGLDrv.ini. Not very object oriented. It would aid future development for someone to write CaveUT into one or two separate classes, contained in one or two files, reading directly from Cave.ini.

Introduce a Spherical Correction

It's not readily apparent from that lovely shot of the Earth Theater, but CaveUT has a problem with that display, because the screens are curved not flat. Currently, CaveUT works by simply carving out a section of UT's (flat) display. Dan Vogel sent me his latests OpenGL driver code for UT, which I intend to incorporate in my next CaveUT update. It contains code that does something very close to a fisheye distortion, the inverse of which IS the spherical correction needed. Turning that into an actual fishye should not be too difficult, once you understand the math. I may even do this one myself, if I get a minute....

Remote Control

Solved by GameBots!   8-)

Real Time Head Tracking

Mainly, this would require moving the code in CaveCalc into CaveUT, proper. Making a head-tracker (if you have one into an input peripheral for unreal should not be a problem. The tricky part is getting the CaveUT code in Engine.u (JavaScript) communicating in real time with the C++ code in OpenGLDrv.cc. The best solution would be to simply define some variable visible to both. Would that have to be declared in the API for UT's rendering engine? Alternatively, you might be able to create a native-code module, a separate DLL, which connects to the Unreal Script code and is linked to the OpenGLDrv.dll at the same time. If this communication problem could be solved, the next step is easy: just fold the code in CaveCalc into GameCode.

Stereographic Display

One of the ways we percieve depth in the real world is through the fact that each eye sees the world from a slightly different angle. Out to a distance of about eight feet, your brain is able to calculate the distance from your eyes to any object using this disparity. Stereographic displays effectively project both the right and left eye views onto some virtual scene. Special glasses separate the images for you so that each eye sees the scene meant for it.

The hard part is that the computer software must generate two views, in concert, for the projector to display. Once that is done, you can have stereopsis (stereographic viewing) in Stupid-Mode, where it only looks right as long as you hold your head level or look up and down on the center screen's central axis only. Once Stupid-Mode stereo works, the next step is to combine that with head tracking so the disparity between the left and right eye views will follow your eyes (your nose, really) whichever way you turn your head.



That's all for now. If you have comments about CaveUT in general or this website in particular, please contact Jeffrey Jacobson.