
ABOUT NEW QBSP, LIGHT, AND VIS
------------------------------

Well, for whatever it's worth, here they are:  My updated versions of
QBSP, Vis, and Light.  I like to do level creation with these tools,
but Carmack's versions (I felt) left a lot to be desired, so I added
useful things where I saw appropriate.	For the most part, the docs
included in "readme.id" are still applicable, but there are some
changes:

	* Each program dumps out a hell of a lot more information.
	  So much, in fact, that it can sometimes be hard to follow
	  as it goes flying by.

	* Output is now logged automatically.  If your map file is
	  myfile.map, the BSP file is myfile.bsp and the log file
	  is myfile.log.

	* Error messages automatically display in bright red so that
	  it's easy to see when you goofed up.

	* "path_corner" classes are now ignored in QBSP when filling
	  the outside.	This used to be an erroneous error of the old
	  QBSP, often generated by having "func_train" objects which
	  move in and out of walls.

	* Each program tries to time-log itself visually with a bar
	  displaying percentage of time to go.	The bar in QBSP only
	  displays how much time is left in the current calculation.

	* Each program tries to show how much memory is being used.
	  This is displayed to the right of the elapsed time.

	* Elapsed time is updated by the internal routines of each
	  program.  If the elapsed time stops counting, that is an
	  indication that the program may have stopped running.

	* Each program automatically displays information about the
	  BSP file on the right side of the screen, so you don't need
	  to run bspinfo to find it out.


INSTALLING
----------

You should have received the whole package as a single .ZIP file.  If
not, you should download a reliable copy from ftp.cdrom.com.  Unzip the
.ZIP file to some directory (I prefer Q:/PROG/QBSP, but your mileage may
vary) making sure that you allow directories to be created as well
(in PKUNZIP that means using the -d flag).  You should have these files:

	LIGHT.EXE		The new version of Light
	QBSP.EXE		The new version of QBSP
	VIS.EXE 		The new version of Vis
	GO32.EXE		The DJGPP DOS extender
	README.id		id Software's original README
	README.LIN		The Linux README
	README.TXT		This file
	SRC/*			Source code for the three programs

You should be able to use the programs simply by executing them from
their directory.  I recommend, however, that you put them in a directory
accessable from your PATH, since it makes using them easier.  If you
do, you will need to put GO32.EXE into the same directory as the other
three tools since they depend on it.  (I have a C:\UTIL directory which
is in my PATH and contains useful utilities and tools; that is where I
keep these programs.)

The QBSP options for -l, -v, and their variants will not work unless
the three programs (and GO32) are in your PATH.

FOR THOSE WITH DJGPP INSTALLED:  The version of GO32.EXE included in
this package is somewhat old, so it may be incompatible with your
existing version.  However, if you have newer versions of GO32.EXE
and DJGPP, you can use those to run the three programs instead.  The
.EXE files are all made by COFF2EXE; presumably you can use EXE2COFF
to generate COFF files if you need them for some reason.


NEW OPTIONS 
-----------

QBSP has several new options, as does Light.  All three programs have
had the -threads option removed because most people don't own a
multiprocessor system; if you want a multithreaded version, you'd better
use Carmack's.

Equally useful is that all three programs have rebuilt command-line
info which displays the options with a lot of extra useless information.
Just type the program name by itself on the command-line to see the
information.

QBSP's new options are:

	-v	Will run Vis on the file, assuming QBSP runs successfully.
		This is standard, slow, O(n^5) Vis-ing.

	-vf	Will run Vis "-fast" on the file, assuming QBSP runs
		successfully.  This is much faster than Vis usually is,
		but is often less accurate (i.e., produces a much slower
		level).

	-l	Will run Light on the file, assuming QBSP runs successfully.

	-e	The quick way to say "-onlyents" to QBSP.

	-el	Updates only entities and then runs Light.

        -lv     Will run Light and Vis on the file, assuming QBSP runs
		successfully.  If QBSP fails, neither Light nor Vis will run.
		If Light fails, Vis will not be run.

	-lvf	Like "-lv", only uses the "-fast" option with Vis.

Light's new options are:

	-v	Will run Vis on the file, assuming Light runs successfully.

	-vf	Will run Vis "-fast" on the file, assuming Light runs
		successfully.


DISCLAIMER
----------

While these versions may not be useful to everyone, I certainly do find
them useful.  Or, more accurately, I do not put a warranty of any kind
on these programs:  If they fail, or if they eat your hard drive, or do
some other destructive thing, do not come whining to me; it's not my
problem:  You were the one who ran them.  To be blunt:

	<WARRANTY>
        THERE IS NO WARRANTY, EXPRESSED OR IMPLIED, ON THESE
	VERSIONS OF QBSP, LIGHT, OR VIS.
	</WARRANTY>
 
I do not claim to understand what the heck is going on in these programs.
I have a pretty good idea of what's going on, but I fully intend to keep
it to myself, so don't bother e-mailing me about how to use them:  E-mail
about these programs will probably receive a *thunk* into the nearest
/dev/null.  If you want to know what's going on, either pray that Carmack
will answer your e-mail, or better yet, post your stupid questions to
rec.computer.games.quake.editing or the Quake Developer's Mailing List.

If you have brilliant ideas about how these programs could be made better,
you're welcome to send them, but bear in mind that I probably have better
things to do than read funky ideas, so I may *thunk* those as well.  And,
no, I don't plan to speed up Vis, either.  I have a team of mathematicians
working on it, but until they sit down and start coding, Vis will run just
as fast as it always has.


TECHNICAL INFO
--------------

The output stuffs use a general-purpose I/O library I hacked up for the
task.  It is in two halves, the ultra-general-purpose library in curs.c
and curs.h, and the QBSP/Light/Vis -specific part in scrn.c.  I stuck
with Carmack-style formatting as much as I could stomach it, but beware
that I probably reformatted some stuff in places for my personal ease of
use.

The curs.c file is the only part specific to the PC architecture.  Replace
it and this will run on anything, just like before.  I plan to build a
UNIX/ANSI version of this just as soon as I can get around to it.
I don't plan to do a Windows 3.1/95/NT version, *ever*.  If
you want a Windows-capable version, you're more than welcome to do the
nasty work yourself.  You won't find me degenerating to that $#!&.
All of the output should no longer be using printf with the exception
of the initial command-line-usage-output stuff, so if you *really* want
a windowed version, it shouldn't be too hard to write.

I took out -threads because I don't own a multiprocessor system and
multiprocessing code doesn't lend itself too well to this kind of output
anyway.  If you want -threads back, #if 1 the command-line switches and
rebuild the curs.c and scrn.c code as necessary with mutexes around those
functions you think might need to be reentrant.

The Makefile is completely different.  The old one didn't like my system
much, so I rebuilt it.	The bspinfo and entmap programs are not included
in this; if you want those, get Carmack's original qbsp.tar.gz from some
public ftp site.  I don't quite know what they're supposed to do, haven't
asked on the Net, and really don't care: I don't use them, so they're not
here.

All of the source to QBSP, Light, and Vis should be in here, so if you
want to modify anything, go right ahead.

I have included working DOS executables and the version of GO32.EXE that
I am using.  You should be able to get these tools running with that.  I
don't recommend running these programs in Windows 3.1/95/NT; while they'll
probably run, they'll probably run very poorly since they have significantly
less memory to work in than they would on a vanilla-DOS system.


COMMON QUESTIONS
----------------

Q: Where are the rest of the tools?
A: Not ready for release yet.  They are due; just wait a few weeks.

Q: I have a question:  Can I e-mail you?
A: Sure.  Just don't expect a response most of the time.

Q: Where's the Windows version?
A: Don't ask me.  I'm not writing it.

Q: Can I put these programs on a CD and sell them?
A: Whatever rules id put on the original versions apply to these.  If
   you want to know if you can sell it, ask them, since a lot of this
   is still their code.


RELEASE LOG
-----------

November 5, 1996        Initial release of the new tools.


BUGS
----

	* Everything is too slow.  But since my algorithmic skills aren't
	  up to par to rebuild Carmack's code, this fix will have to wait.

	* Output is cryptic.  Beginning users won't understand half that
	  stuff flashing at them.

	* Log files are too cryptic.

	* Multithreading is not supported.

	* The source code is nearly unreadable.

	* QBSP eats too much memory and should probably be split up.

	* The CSG4 stage of QBSP seems to barf on really big levels on
	  small systems.  This may be memory related, though.

        * Doesn't support ANSI or VT100 output, which makes it unusable in
	  UNIX.  This is probably the next fix coming.

	* Needs a friendlier startup interface, possibly with menus to
	  simplify things.  The command-line args are useful but very
	  cryptic.

	* Ought to be able to have configuration files for things like
	  project directory and such.  Ought to support multiple project
	  directories too.

	* It would be nice if these could intelligently decide what to
	  update from .MAP to .BSP.   { editor's note:  This may never
					get done, but it's a fun thought,
					isn't it? }


SPECIAL THANKS
--------------
	John Carmack	  For writing these tools in the first place
	id Software	  For making the coolest games in the Milky Way
	set@netcom.com	  For converting the original versions for use in GCC
	D.J. Delorie	  For making GCC run in MS-DOG
	Michael Abrash	  For leaving Microsoft and joining id
	Senator Exon	  For not noticing Quake yet :)




				--- Sean Werkema
				    stw113@psu.edu
				    November 5, 1996

