Projects - JQMap

Description

JQMap is a progam for exploring textured 3D worlds using the original Quake .bsp file format. The worlds are rendered using a custom software renderer using now well-known 3D visualization algorithms similar to those used by id Software's original Quake engine.

Goals

My goals for this project were fairly simple. I wanted to implement a 3D engine with which I could experiment with various algorithms secondary to a low-level 3D engine, but that required access to the internal workings. The main goal was also to kill free time between Christmas and New Years eve of 1998.

The original goal was to build an engine that could link multiple BSP worlds with portals thereby extending the virtual size of the worlds indefinitely. In addition, I wanted to render still images with a Z-buffer that could then be used as a background for 3d sprite animation. Because of these goals, certain compromises were made in the areas of performance to improve the possibility of better quality output. The choice to use 24-bit color is one example.

At the time, BSP level editors (for Quake, etc.) were numerous and of fairly good quality. Also, I already had experience with loading and displaying Quake BSP files in C. Porting this code to Java and enhancing was the obvious choice.

Back-story

Back in 1997 I used to do a bit of work with 3D graphics as both a hobby and for work. At the time, a programmer by the name of Sean Barret wrote a nifty little Quake level viewer in less than 2000 lines of C called QMAP. This was a neat little program that I looked at to help improve some of my own 3D code. Eventually, I had my own hacked version of a C quake level viewer that had improved support for sky and water textures as well as a span/edge buffer and rudimentary support for creating a W-buffer as the spans were rendered. I also improved the movement routines which were pretty basic in Sean's version and added some simple collision detection. However, all of this was made easier by the benefit of looking at Sean Barret's code.

In December of 1998 I was doing Java contract work for a company that gave it's employees the week off between Christmas and New Years. It was during this week off that I took the opportunity to create the Java Quake level viewer based on my C version that was based on Sean's C version. By the end of that week I had even hacked together basic portal support into the still-shot viewer. Unfortunately, then I went back to work and wasn't motivated to do much more to it.

Screen Shots

Following are some screen-shots of the BSP file that's included with the application. (Click the images for full-size views.)

A screen shot of the window that shows the top-down level schematic. As close to a map as you get. (Click the image for full-size view.)

Technical Information

Under construction.

Future Improvements

One thing that has not been added is a proper span renderer. All polygons are drawn back to front using the painter's algorithm. This is extremely wasteful since it means that alot of division operations are done needlessly since the output pixels are just going to be overwritten by the next poly. Fortunately, poly overlap is minimized by the nature of BSP traversal. Still, if I added a edge/span buffer performance would improve as would integration with portal views... maybe even to the point where portal support could be done in real time.

Other things that might be nice:

• A basic physics engine and some collision detection.
• BSP object support, ie: doors, etc.
• Animated sky
• Z-buffered sprites
• Dynamic lighting
• Realtime portal linking
• Built-in support for multiple resolutions
• And as Sean Barret said in his own docs, "A game"

Download

Note: JQMap requires some form of Java 2 runtime installed. I've personally had problems getting JDK 1.4 to send key events to my windows... so you may want to run it with JDK 1.3. See the Resources section below for a Java download link.

Note on screen resolutions: This code was written to use 24 bit color. This means that there will be definite performance degradation on systems configured with lower screen resolutions. In fact, based on my tests there is occassionally a several second pause as Java figures out optimized translations. Since the code internally uses only 256 colors, I may someday switch to this cheaper format but I wanted to leave my options open for more advanced color management. After all, this was originally developed to do quality still-shots and I wanted to provide depth of field and motion blur which are only reasonably feasible in 24 bit color.

Using JQMap

It's pretty simple really. Once you have the jqmap.jar file, either by downloading it specifically or by extracting it from a downloaded jqmap.zip, simply double click on jqmap.jar. (Alternately, from the command line run: java -jar jqmap.jar)

Controlling the camera is as follows:

Resources

Here is a link to Sun's Java page just in case you don't have a runtime installed and don't know what Java is for some reason.
http://java.sun.com/j2se/?frontpage-javaplatform

When in doubt, check the source. id Software has graciously released the source code to several of their games (including the original Quake) at:
http://www.idsoftware.com/archives/sourcearc.html

Here are some links to various Quake related utilities include WAD file unpackers, level editors, etc.:
http://www.fileplanet.com/index.asp?section=99

Of course, my references list wouldn't be complete without a link to Sean Barret's work:
http://www.geocities.com/SiliconValley/Vista/7788/qmap.htm

This site seems to have many useful links including the link to Sean's page above. I found this while looking for the QMAP pages.
http://www.ziron.com/links/3dtext.htm