.\" unoffical man page for q3map2 
.\" patches to: ingar@telenet.be 
.\" 2006-09-18 
.\" release tag 20060918-00
.\" .TH program_name man_section date version title
.TH q3map2 6 "18 september 2006" "q3map2 2.5.16" "Quake 3 III Arena Documentation"
.SH NAME
q3map2 \- a quake 3 BSP compiler
.SH SYNOPSIS
.B q3map2 
\fIcommand\fR [\fIoptions\fR] \fIfile\fR
.SH DESCRIPTION
q3map2 is a BSP compiler for games based on the Quake III Arena engine.
.SH "COMMANDS"
The \fIcommand\fR specifies the operation q3map will perform on the given 
\fIfile\fR. Only one command can be specified.
.IP "\fB-bsp\fR"
Compiles a .map file into a .bsp (binary space partition) file for use with the
Quake III Arena engine. It also writes a .prt (portal information) file and a .srf
(surface) file. This is the default command: if no command is given, \fB-bsp\fR is assumed.
This command requires \fIfile\fR to be a path to an uncompiled .map file.
.IP "\fB-vis\fR"
Creates visibility sets based on the portal file.
This command requires \fIfile\fR to be a path to a .map file, which has been processed
with the \fB-bsp\fR command.
.IP "\fB-light\fR"
Calculates lighting data. 
.\" TODO COMPILE CONDITIONS
This command requires \fIfile\fR to be a path to an uncompiled .map file.
If the \fB-light\fR command is used without additional options, 
less than desirable output will be achieved.

.IP "\fB-convert\fR"
Converts a compiled .bsp to another format.
.\" TODO COMPILE CONDITIONS
This command requires \fIfile\fR to be a path to a compiled .bsp file.

.IP "\fB-export\fR"
Exports internal lightmaps from a compiled .bsp to external .tga images.
This command requires \fIfile\fR to be a path to a compiled .bsp file.

.IP "\fB-import\fR"
Imports external .tga lightmaps back into a compiled .bsp. Imported lightmaps
will only work on the unmodified BSP they were exported from.
This command requires \fIfile\fR to be a path to a compiled .bsp file.

.IP "\fB-info\fR"
Analyzes a compiled bsp and outputs information to the screen or log.
This command requires \fIfile\fR to be a path to a compiled .bsp file.

.IP "\fB-scale\fR \fIfactor\fR"
Scales a compiled .bsp by the prescribed factor. 
For example a \fIfactor\fR of 0.25 will output a new .bsp that is 25% of the original .bsp's size, 
a \fIfactor\fR of 2.0 will output a new .bsp that is twice as large. 
The scaled output is written to the maps subdirectory of the game base directory.
This command requires \fIfile\fR to be a path to a compiled .bsp file.

.SH "OPTIONS"

.SS General options
.P
The following options can be used with any command:

.IP "\fB-connect\fR"
Enables output of q3map2 logging to a remote host.

.IP "\fB-game\fR \fIgame\fB"
Enables support for games other than Quake III Arena. 
\fIgame\fR is one of the following:
quake3, wolf, et, etut, ef, jk2, ja, sof2, tenebrae

.IP "\fB-fs_game\fR \fImodname\fR"
Enables support for game mods other than the basic game defined in your -game
switch. 

.IP "\fB-fs_basepath\fR \fIpath\fR"
Required in order for q3map to use game data of games other than
Quake III Arena. \fIpath\fR specifies the location of the game base directory.

.IP "\fB-v\fR"
Enables verbose mode. This is generally a good idea.

.IP "\fB-rename\fR"
Used to fix an issue with misc_model entities in SOF2. If your misc_models show
up unlit and completely black, use the -rename switch.

.IP "\fB-threads\fR \fInbthreads\fR
.\" TODO VERIFY - wiki says linux version does not autodetect multiple CPU's.
.\" My personal experience tells me otherwise.
Specifies the number of threads to be used during compiling. q3map2
automatically detects the number of CPUs present, and sets the threadcount
accordingly. The \fB-threads\fR switch can be used to override this behavior.

.SS Options for the -bsp command
The following options can be used with the \fB-bsp\fR command:

.IP "\fB-custinfoparms\fR"
.\" VERIFIED by Ingar - only with the -bsp command
Enables custom surfaceparms for game mods without the need to recompile q3map2 itself. 
Custom surfaceparms are stored in custinfoparms.txt, in the scripts subdirectory of the game base directory.

.IP "\fB-debuginset\fR"
.\" TODO It is not clear what this option actually does.
Enables debugging of surface triangle insetting. 

.IP "\fB-debugportals\fR"
Draws the portals into the bsp as translucent polygons. 
Omit \fB-vis\fR and \fB-light\fR for the best \fB-debugportals\fR results.

.IP "\fB-debugsurfaces\fR"
Colors every surface a different color (very trippy). 
Omit \fB-vis\fR and \fB-light\fR for the best \fB-debugsurfaces\fR results.

.IP "\fB-fakemap\fR"
.\" TODO It is not clear what this option actually does.
Creates a new .map file with a blank worldspawn entity and all the world brushes from your original .map file.

.IP "\fB-flares\fR"
.\" TODO It is not clear how this option actually works
Used to generate coronas on light sources. Quake III Arena does not support flares, other
more modern versions of the engine do.
.br
This option is used in Raven games.

.IP "\fB-flat\fR"
Forces all texture coordinates for a given surface to the pixel that best fits
the average color of the assigned texture.

.IP "\fB-fulldetail\fR"
Will cause all detail brushes to be handled as if they were structural.

.IP "\fB-leaktest\fR"
Will abort the compile if a leak is encountered.

.IP "\fB-meta\fR"
At one time, there was a clear definition as to what, exactly, the \fB-meta\fR switch
did. Now, it has become the magic switch that is required for most of q3map2's
advanced features. Always use the \fB-meta\fR and \fB-v\fR options with the 
\fB-bsp\fR command.

.IP "\fB-mi\fR \fImaxindexcount\fR"
 Sets the maximum per-surface index count to \fImaxindexcount\fR

.IP "\fB-mv\fR \fImaxvertexcount\fR"
Sets the maximum per-surface vertex count to \fImaxvertexcount\fR

.IP "\fB-nocurves\fR"
 Will not compile patch meshes into the .bsp.

.IP "\fB-nodetail\fR"
Will not compile detail brushes into the .bsp.

.IP "\fB-nofog\fR"
Will not compile fog brushes into the .bsp.

.IP "\fB-nohint\fR"
Will not compile hint brushes into the .bsp.

.IP "\fB-nosubdivide\fR"
Visible surfaces will not be split. TessSize is ignored.

.IP "\fB-notjunc\fR"
Will not fix T-Junctions. Using this option can cause sparklies and LOD cracks.

.IP "\fB-nowater\fR"
Will not compile liquid brushes into the .bsp.

.IP "\fB-np\fR \fIshadeangle\fR"
Forces all planar shaders to become nonplanar with the shadeangle specified.
\fIshadeangle\fR can range from 1 to 179.

.IP "\fB-onlyents\fR"
Only changes the entities in the compiled .bsp. 
Needs a compiled .bsp (as well as a .map) to act as a file-filter.

.IP "\fB-patchmeta\fR"
Creates meta surfaces from patch meshes. This "bakes" a set LOD into patches in your .bsp.

.IP "\fB-samplesize\fR \fIsamplesize\fR"
Writes the \fIsamplesize\fR parameter to the .srf surface file. This will affect the \fB-light\fR phase of 
the compile. A lower \fIsamplesize\fR value produces more sharply defined lightmaps. 
.br
The default \fIsamplesize\fR is 16; a samplesize value of 4 produces a very high quality compile,
suitable to call final. A samplesize value of 1 would be total overkill,
resulting in epochal compile times and immensely bloated .bsp filesize.

.IP "\fB-skyfix\fR"
Enables fix for buggy GL_CLAMP behavior. Always use this.
.br
Sidenote: The bug was with nVidia drivers not distinguishing between 
GL_CLAMP and GL_CLAMP_TO_EDGE, and Quake III Arena using the wrong one.
Since Quake III Arena development was done predominantly on nVidia hardware, 
nobody noticed it until too late.

.IP "\fB-snap\fR"
.\" TODO It is not clear what this option actually does.
Enables axial bevel plane snapping to reduce clipped model plane count. Use with care.

.IP "\fB-texrange\fR \fItexelcount\fR"
Limits per-surface texel count to \fItexelcount\fR

.IP "\fB-verboseentities\fR"
Outputs more information about compiling entity sub-models into the .bsp file.

.SS Options for the -vis command

The following options can be used with the \fB-vis\fR command:

.IP "\fB-fast\fR"
Only calculates rough visibility data. Quick and dirty, not actually useful for
VIS purposes.

.IP "\fB-hint\fR"
Will merge the bsp leaves (except for hint portals) before calculating the
visiblity list.

.IP "\fB-merge\fR"
Will merge the bsp leaves before calculating the visibility list.

.IP "\fB-nopassage\fR"
Disables the passage visiblity algorithm. Passage VIS is a bit faster and
tighter than the old algorithm.

.IP "\fB-nosort\fR"
Disables the sorting of portals by complexity. Sorting speeds up visiblity
calculations.

.IP "\fB-passageonly\fR"
Will use the passage visibility algorithm only.

.IP "\fB-nohint\fR"
Omits hint brushes from visibility calculations.

.IP "\fB-saveprt\fR"
Disables the automatic deletion of the .prt portal file after VIS finishes.

.SS Options for the -light command

The following options can be used with the \fB-light\fR command:

.IP "\fB-areascale\fRi \fIscale\fR"
Scales up area (shader) lights by the prescribed factor. 
A \fIscale\fR factor of 0.25 will result in area lights that are only 25% 
as bright as those in a .bsp compiled with a \fIscale\fR factor of 1.0.

.IP "\fB-approx\fR \fItolerance\fR"
Approximates lightmaps within \fItolerance\fR bytes. 
\fB-approx\fR forces simple surfaces without much shadow detail to be vertex lit, 
thus saving lightmaps. \fItolerance\fR ranges from 0 to 255. 
The default is 0: no approximation.

.IP "\fB-border\fR"
Creates a debugging border around each lightmap.

.IP "\fB-bounce\fR \fIbounces\fR"
Calculating radiosity light through \fIbounces\fR bounces.

.IP "\fB-bouncegrid\fR"
Allows bounced light to affect the lightgrid.

.IP "\fB-bouncescale\fR \fIscale\fR"
Scales up radiosity lights by the prescribed \fIscale\fR factor.

.IP "\fB-cheap\fR"
Stop calculating light on a sample after it exceeds (255, 255, 255). 
This may produce odd artifacts on maps with lots of saturated colored lighting. 
Also, do not use cheap with radiosity if you want to preserve all the emitted light.

.IP "\fB-cheapgrid\fR"
Stop calculating light on a sample after it exceeds (255, 255, 255), 
but only for the lightgrid.

.IP "\fB-compensate\fR \fIvalue\fR"
Scales back lightmap values to adjust for overbrighting when -gamma is used. 
For Quake III Arena, a good compensate \fIvalue\fR is 4, 
though some experimentation may be needed to find an aesthetic that suits your particular map.

.IP "\fB-cpma\fR"
Enables full vertex lighting including occlusion on all surfaces, including lightmapped. 
Causes incorrect handling of \fB-approx\fR in Quake III Arena even with special shaders.

.IP "\fB-dark\fR"
Enables darkening of lightmaps at brush/lightmap seams. Very subtle.

.IP "\fB-debug\fR"
Enables lightmap debugging.

.IP "\fB-debugaxis\fR"
Colors lightmaps based on their projection axis.

.IP "\fB-debugcluster\fR"
Colors lightmaps based on the PVS-cluster the luxel falls into.

.IP "\fB-debugorigin\fR"
Colors lightmaps based on the luxel origin relative to the raw lightmap's bounding box.

.IP "\fB-debugunused\fR"
Colors unused luxels hot pink.

.IP "\fB-dirty\fR"
Enables ambient occlusion or dirtmapping. Less-visible areas such as cracks and crevices will become darker.
This simulates a dirty, grimy effect.

.IP "\fB-dirtdepth\fR \fIdepth\fR"
Use with -dirty. Sets maximum \fIdepth\fR of occlusion checking in game units. 
The default \fIdepth\fR is 128.

.IP "\fB-dirtmode\fR \fImode\fR"
Use with -dirty. Controls the mode in which the dirtmap is calculated.
Possible values for \fImode\fR are: 
.RS
.IP "0"
Uniform mode, generates a smooth looking dirtmap (default).
.IP "1"
Noisy mode, generates a noisy dirtmap.
.RE

.IP "\fB-dirtscale\fR \fIscale\fR"
Use with -dirty. Scales up the "darkness" of the dirtmapping effect by the prescribed factor.

.IP "\fB-dump\fR"
Dumps radiosity lights into numbered prefabs.

.IP "\fB-fast\fR"
Enables light envelopes for area (shader) lights. This includes radiosity lights. 
Results in a much quicker \fB-light\fR compiles, but darkens all enveloped light sources considerably.
Using \fB-fast\fR is generally a good idea, since omiting this option results 
in a huge increase in compile time.

.IP "\fB-fastbounce\fR"
Enables \fB-fast\fR style calculations, but only for radiosity lights.

.IP "\fB-faster\fR"
The \fB-faster\fR option enables test mode 
light calculations. Very fast, but produces poor results. 
Use this option if you want a quick a test compile.

.IP "\fB-fastgrid\fR"
Enables \fB-fast\fR style calculations, but only for the lightgrid.

.IP "\fB-filter\fR"
Applies a gaussian blur to lightmaps, smoothing out shadows.
Sounds good in theory, but -filter doesn't play nice 
with a lot of the more interesting effects... don't use it. 
Use \fB-samples\fR instead.

.IP "\fB-gamma\fR \fIvalue\fR"
Use a prescribed gamma correction factor. The default \fIvalue\fR is 1.0. 
Good values are in the 1.4-2.2 range, but this may depend on the map and the
game you are compiling it for. 
.br
Games that use r_overBrightBits and r_mapOverBrightBits (Quake III Arena, most notably) 
will need those cvars disabled unless \fB-compensate\fR is used accordingly. 

.IP "\fB-lightmapsize\fR \fIsize\fR"
.\" TODO needs more information
Limits the lightmap size.

.IP "\fB-lomem\fR"
Decreases memory usage at the cost of increased compile time.
If you are getting safe_malloc errors, or just running out of memory, try this option.

.IP "\fB-nocollapse\fR"
Disables collapsing of identical lightmaps. 
.\" TODO needs more information
This switch is required for Q3Map2 lightstyles.

.IP "\fB-nogrid\fR"
Disables calculation of the lightgrid.

.IP "\fB-normalmap\fR"
Colors lightmaps based on the facings of their vertex normals.

.IP "\fB-nosurf\fR"
Disables the surface tracing of detail brushes and patch meshes for shadow casting.

.IP "\fB-notrace\fR"
No light tracing is performed. As a result, no shadows will be cast.

.IP "\fB-novertex\fR"
Disables the calculation of vertex lighting.

.IP "\fB-patchshadows\fR"
Enables the casting of shadows by patch meshes.

.IP "\fB-pointscale\fR \fIfactor\fR"
Scales up point (entity) lights by the prescribed \fIfactor\fR.
Default is 1.0.

.IP "\fB-samples\fR \fIvalue\fR"
Enables intelligent antialiasing of shadow edges in lightmaps. 
A \fIvalue\fR of 2 both looks good and compiles quickly, 
while a \fIvalue\fR of 3 looks great but compiles somewhat more slowly.

.IP "\fB-scale\fR \fIfactor\fR"
Scales up all light sources by the prescribed \fIfactor\fR. Default is 1.0.

.IP "\fB-shade\fR"
Enables phong shading.

.IP "\fB-sky\fR \fIfactor\fR"
Scales up all sun/sky light sources by the prescribed \fIfactor\fR. Default is 1.0.
.\" TODO needs more info
.\"In this new era of -gamma -compensate, -sky 3 can allow "old style" sky shaders to be used without manually rewriting them.

.IP "\fB-sunonly\fR"
Computes sun/sky light only, no other light sources.

.IP "\fB-super\fR \fIvalue\fR"
Enables arbitrarily ordered grid supersampling of lightmaps.

.IP "\fB-thresh\fR \fIthreshhold\fR
Sets the recursive triangle subdivision threshhold. 
The \fIthreshhold\fR range is 0.0 to 1.0.

.SS Options for the -convert command
This command is used to convert an existing .bsp file to a different format.
By default, q3map2 converts a compiled .bsp file into an .ase model.
Other formats are available via the \fB-format\fR option.
.P
This command can by used to decompile a .bsp file back into a .map file.
Most entities are lost, as is all texture alignment information. 
The converted output is written to the maps subdirectory of the game base directory.
.P
It can also be used to convert a .bsp file from one game to an other
(the other game is specified with the \fB-game\fR option). This feature is experimental.
.P
The following options can be used with the \fB-convert\fR command:
.IP "\fB-format\fR \fIformat\fR"
Specify the output format for the \fB-convert\fR command. 
\fIformat\fR is one of the following:
ase, map, quake3, wolf, et, etut, ef, jk2, sof2, tenebrae

.SH EXAMPLES

.IP "BSP phase:"
q3map2 -bsp -v -meta mymap.map

.IP "VIS and LIGHT phases with test settings:"
q3map2 -vis -v -saveprt -fast mymap.map
.br
q3map2 -light -v -faster mymap.map
	
.IP "VIS and LIGHT phases with final settings:"
q3map2 -vis -v -saveprt mymap.map
.br
q3map2 -light -fast -super 2 -bounce 6 mymap.map
	
.IP "Convert a Wolfenstein: Enemy Territory .bsp file to a .map file:"
q3map2 -game et -convert -format map etmap.bsp

.SH HISTORY
Q3Map2 started out as a bugfix for Q3Map, the original Quake 3 map compiler.
Q3Map was written by Id Software Inc.

.SH AUTHOR
The bicycle-riding, aids-fighting, wonder-coding superhero ydnar is the man
behind q3map2. He is on the government's list of the 50 best people in the USA.

.P
The text for this manpage was edited and converted by Ingar (ingar@telenet.be)
from the text available at http://en.wikibooks.org/wiki/Q3Map2.

.SH COPYRIGHT
This text is available under the terms of the GNU Free Documentation License.
The full text of this license can be found at http://www.gnu.org/licenses/fdl.txt

.SH SEE ALSO

.PI "\fBThe q3map2 wikibook\fR"
http://en.wikibooks.org/wiki/Q3Map2