This is the readme from our most recent licensed developer CD.  
Not all of it is applicable to this source upload, because the map 
editor, source data, and game source code have not been made freely 
available (gotta have some reason to charge lots of $$$ for it...), 
but it is the best documentation I have. 
-- John Carmack Quake Development CD 9/4/96 --
----------------------------------------------

Included is all of the source data and utilities necessary to generate all 
of the data distributed with quake, and the main executable itself.  
You can modify the data in place, or copy the data you wish to modify to 
an addon directory and work from there.

The win-32 tools have not been extensively tested yet, because we still 
do most of our work on unix.


Completely building Quake code and data:
---------------------------------------

This process can take quite some time on a slow machine.  I am omiting 
the steps to rebuild all the maps, otherwise it would take all day 
(literally).

Install VC++ and MASM.  You don't need MASM if you are going to use DJGPP 
to compile the dos version instead of using the windows version.

Copy the contents of the quake development cd to /quake on any drive.  
The directory MUST be called "quake", because that string is searched for 
by the utilities to provide compatability between unix directories mounted 
inside a tree, and windows directories mounted on a drive letter.  You can 
move it off of root, but it will require changes in a few batch files.

Add drive:\quake\bin_nt to your path.

cd \quake\utils
install	  // compiles all of the utilities and copies them to \quake\bin_nt

cd \quake\id1\gfx
foreach %i in (*.ls) do qlumpy %i	// regrab all 2d graphics
// gfx.ls	: graphics that are statically loaded: the small font, 
                  status bar stuff, etc
// cached.ls	: graphics that are dynamically cached: menus, console 
                  background, etc
// the other .ls files are texture paletes for map editing

cd \quake\id1\progs
sprgen sprites.qc	// regrab the sprites used in the 3d world (all 
                        // three of them)

foreach %i in (*.qc) do modelgen %i	// regrab all 3d models
// many of the .qc files do not actually specify a model, but
// running them through modelgen is harmless

qcc			// rebuild progs.dat and files.dat

qfiles -bspmodels	// reads files.dat and runs qbsp and light on all 
                        // external brush models (health boxes, ammo boxes, 
                        // etc)
qfiles -pak 0		// builds \quake\id1\pak0.pak
qfiles -pak 1		// builds \quake\id1\pak1.pak
// note that you should not leave the pak files in your development directory,
// because you won't be able to override any of the contents.  If you are 
// doing your work in an add-on directory, it isn't a problem, and the pak 
// files will load faster than the discrete files.

cd \quake\code
mw		// a batch file that compiles the windows version of quake
q +map newmap	// a batch file that runs "quake -basedir \quake +map newmap"




the bsp tools
-------------

The bsp tools are usually run straight from the map editor, but they 
can also be called from the command line.

cd \quake\id1\maps
qbsp dm1	  // processes dm1.map into dm1.bsp
light dm1	  // generates lightmaps for dm1.bsp.  If you run 
                  // "light -extra dm1", it will make smoother shadow edges 
                  // by oversampling.
vis dm1		  // generates a potentially visible set (PVS) structure for 
                  // dm1.bsp.  This will only work if the map is leak-free.
                  // You can run "vis -fast dm1" to generate a rough PVS 
                  // without spending very much time.
bspinfo newmap	  // dumps the stats on newmap

QuakeEd
-------
You are not expected to be able to figure out how to use QuakeEd from the 
(nonexistant) documentation we have.  You get one full day with one of our 
map designers for tutoring.

If you want to try it out anyway:

cd \quake\id1	// the directory that contains the quake.qe3 project file
qe3		// see quakeed.txt for a box-room walkthrough

QuakeEd is still undergoing development.  The version included in bin_nt is 
a newer version than the source included in utils.  
I don't have the current source here right now.

Expect new versions over the next few weeks.


The main source code:
--------------------
You can use the djgpp compiler (http://www.delorie.com) to rebuild quake 
for dos.  We used a cross-compiler built for our Digital Unix alpha system 
that works very rapidly, but the dos hosted compiler is quite slow.

Our reccomended procedure is to forget about dos and just work with the 
windows version for code changes.  

Currently at id we compile for three different platforms: NEXTSTEP, dos, 
and windows.  The code also compiles for linux, but that is not part of 
our regular process.  The C code is totally portable, but the assembly code 
was writen for GAS, which was unfreindly for windows development.  Michael 
wrote a GAS to MASM translator to allow the assembly code to compile under 
windows.  We still consider the GAS code (.s) to be the master, and derive 
the masm (.asm) code from it inside the makefile.  If you are never going 
to touch the assembly code (we don't reccoment you do), or you are willing 
to take full responsibility for it, you can throw out the .s files and just 
use the .asm.

The direct-sound driver is not very good right now.  You may want to run 
with "-nosound".


The utilities source:
--------------------

Each utility has a seperate directory of code with a VC++ project file.  
They all share several code files in the "common" directory.  The NT versions
of these utilities have not been very extensively tested, as we still use 
DEC Unix for most of our work (soon to change).  The two source files you 
are most likely to change are: common/lbmlib.c to load a more common graphics
format, like pcx, and common/trilib.c to load a 3D format other than Alias 
object seperated triangles.


qe3 : The map editor.  Designed for use on open GL accelerated systems such 
as intergraph or glint-TX based systems, but it will still run on the basic 
NT software version.  REQUIRES A 3-BUTTON MOUSE!

qbsp / light / vis : these utilities are called directly from the map 
                     editor to process .map files into .bsp files.  They 
                     can be executed by hand if desired.

bspinfo : a command line utility that will dump the count and size 
          statistics on a .bsp file.

qlumpy : the 2-D graphics grabber.  Grabs graphics off of .lbm pictures.  
         Used for grabbing the 2d graphics used by quake (status bar stuff, 
         fonts, etc), and also used for grabbing the textures to be viewed 
         in qe3 and extracted by qbsp.  Qlumpy script files have the default 
         extension ".ls" (LumpyScript).

qcc : the Quake-C compiler.  Reads "progs.src", then compiles all of the 
      files listed there.  Generates "progs.dat" for use by quake at runtime,
      "progdefs.h" for use at compile time, and "files.dat" to be used as 
      input for qfiles.exe.

qfiles : Builds pak files based on the contents of "files.dat" writen out 
         by qcc.  It can also regenerate all of the .bsp models used in a 
         project, which is required if any changes to the file format have 
         been made.

sprgen : the sprite model grabber.  Grabs 2d graphics and creates a .spr file.

modelgen : the 3-D model grabber.  Combines skin graphics with 3d frames 
           to produce a .mdl file.  The commands are parsed out of .qc files
           that can also be read by qcc, so a single source can both generate
           and use the data.

texmake : creates 2d wireframe outlines of a 3d model that can be drawn on 
to give a texture to a model.  This is only done once per model, or when the 
base frame changes.
Example:
cd \quake\id1\models\torch
texmake base		// reads base.tri and creates the graphic base.lbm
copy base.lbm skin.lbm	// never work on the base skin, it might get 
                        // overwritten
cd \quake\id1\progs
modelgen torch.qc	// creates torch.mdl out of files in 
                        // \quake\id1\models\torch



Continuing development work at id:
------------------------------
winquake : work is still being done on the direct-X drivers for quake.

qe3 : the NT editor does not yet have full functionality for texture 
      positioning and entity connecting.

qrad : a radiosity replacement for light.exe.  Instead of placing light 
       entities, certain textures automatically become light emiters.  The 
       light bounces off of surfaces, so a single light panel can light all 
       sides of a room.

qcsg / qbsp / qwrite : qbsp.exe is being broken up into multiple programs 
                       to reduce memory usage and provide a better means 
                       for experimentation.  It should get faster, as well.

visx : a faster replacement for vis.