q3map2(6) Quake 3 III Arena Documentation q3map2(6)NAMEq3map2 - a quake 3 BSP compiler
SYNOPSISq3map2 command [options] file
DESCRIPTIONq3map2 is a BSP compiler for games based on the Quake III Arena engine.
COMMANDS
The command specifies the operation q3map will perform on the given
file. Only one command can be specified.
-bsp 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, -bsp is assumed. This
command requires file to be a path to an uncompiled .map file.
-vis Creates visibility sets based on the portal file. This command
requires file to be a path to a .map file, which has been pro‐
cessed with the -bsp command.
-light Calculates lighting data. This command requires file to be a
path to an uncompiled .map file. If the -light command is used
without additional options, less than desirable output will be
achieved.
-convert
Converts a compiled .bsp to another format. This command
requires file to be a path to a compiled .bsp file.
-export
Exports internal lightmaps from a compiled .bsp to external .tga
images. This command requires file to be a path to a compiled
.bsp file.
-import
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 file to be a path to
a compiled .bsp file.
-info Analyzes a compiled bsp and outputs information to the screen or
log. This command requires file to be a path to a compiled .bsp
file.
-scale factor
Scales a compiled .bsp by the prescribed factor. For example a
factor of 0.25 will output a new .bsp that is 25% of the origi‐
nal .bsp's size, a factor of 2.0 will output a new .bsp that is
twice as large. The scaled output is written to the maps subdi‐
rectory of the game base directory. This command requires file
to be a path to a compiled .bsp file.
OPTIONS
General options
The following options can be used with any command:
-connect
Enables output of q3map2 logging to a remote host.
-game game
Enables support for games other than Quake III Arena. game is
one of the following: quake3, wolf, et, etut, ef, jk2, ja, sof2,
tenebrae
-fs_game modname
Enables support for game mods other than the basic game defined
in your -game switch.
-fs_basepath path
Required in order for q3map to use game data of games other than
Quake III Arena. path specifies the location of the game base
directory.
-v Enables verbose mode. This is generally a good idea.
-rename
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.
-threads nbthreads
Specifies the number of threads to be used during compiling.
q3map2 automatically detects the number of CPUs present, and
sets the threadcount accordingly. The -threads switch can be
used to override this behavior.
Options for the -bsp command
The following options can be used with the -bsp command:
-custinfoparms
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.
-debuginset
Enables debugging of surface triangle insetting.
-debugportals
Draws the portals into the bsp as translucent polygons. Omit
-vis and -light for the best -debugportals results.
-debugsurfaces
Colors every surface a different color (very trippy). Omit -vis
and -light for the best -debugsurfaces results.
-fakemap
Creates a new .map file with a blank worldspawn entity and all
the world brushes from your original .map file.
-flares
Used to generate coronas on light sources. Quake III Arena does
not support flares, other more modern versions of the engine do.
This option is used in Raven games.
-flat Forces all texture coordinates for a given surface to the pixel
that best fits the average color of the assigned texture.
-fulldetail
Will cause all detail brushes to be handled as if they were
structural.
-leaktest
Will abort the compile if a leak is encountered.
-meta At one time, there was a clear definition as to what, exactly,
the -meta switch did. Now, it has become the magic switch that
is required for most of q3map2's advanced features. Always use
the -meta and -v options with the -bsp command.
-mi maxindexcount
Sets the maximum per-surface index count to maxindexcount
-mv maxvertexcount
Sets the maximum per-surface vertex count to maxvertexcount
-nocurves
Will not compile patch meshes into the .bsp.
-nodetail
Will not compile detail brushes into the .bsp.
-nofog Will not compile fog brushes into the .bsp.
-nohint
Will not compile hint brushes into the .bsp.
-nosubdivide
Visible surfaces will not be split. TessSize is ignored.
-notjunc
Will not fix T-Junctions. Using this option can cause sparklies
and LOD cracks.
-nowater
Will not compile liquid brushes into the .bsp.
-np shadeangle
Forces all planar shaders to become nonplanar with the shadean‐
gle specified. shadeangle can range from 1 to 179.
-onlyents
Only changes the entities in the compiled .bsp. Needs a com‐
piled .bsp (as well as a .map) to act as a file-filter.
-patchmeta
Creates meta surfaces from patch meshes. This "bakes" a set LOD
into patches in your .bsp.
-samplesize samplesize
Writes the samplesize parameter to the .srf surface file. This
will affect the -light phase of the compile. A lower samplesize
value produces more sharply defined lightmaps.
The default samplesize 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.
-skyfix
Enables fix for buggy GL_CLAMP behavior. Always use this.
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 pre‐
dominantly on nVidia hardware, nobody noticed it until too late.
-snap Enables axial bevel plane snapping to reduce clipped model plane
count. Use with care.
-texrange texelcount
Limits per-surface texel count to texelcount
-verboseentities
Outputs more information about compiling entity sub-models into
the .bsp file.
Options for the -vis command
The following options can be used with the -vis command:
-fast Only calculates rough visibility data. Quick and dirty, not
actually useful for VIS purposes.
-hint Will merge the bsp leaves (except for hint portals) before cal‐
culating the visiblity list.
-merge Will merge the bsp leaves before calculating the visibility
list.
-nopassage
Disables the passage visiblity algorithm. Passage VIS is a bit
faster and tighter than the old algorithm.
-nosort
Disables the sorting of portals by complexity. Sorting speeds up
visiblity calculations.
-passageonly
Will use the passage visibility algorithm only.
-nohint
Omits hint brushes from visibility calculations.
-saveprt
Disables the automatic deletion of the .prt portal file after
VIS finishes.
Options for the -light command
The following options can be used with the -light command:
-areascalei scale
Scales up area (shader) lights by the prescribed factor. A
scale factor of 0.25 will result in area lights that are only
25% as bright as those in a .bsp compiled with a scale factor of
1.0.
-approx tolerance
Approximates lightmaps within tolerance bytes. -approx forces
simple surfaces without much shadow detail to be vertex lit,
thus saving lightmaps. tolerance ranges from 0 to 255. The
default is 0: no approximation.
-border
Creates a debugging border around each lightmap.
-bounce bounces
Calculating radiosity light through bounces bounces.
-bouncegrid
Allows bounced light to affect the lightgrid.
-bouncescale scale
Scales up radiosity lights by the prescribed scale factor.
-cheap Stop calculating light on a sample after it exceeds (255, 255,
255). This may produce odd artifacts on maps with lots of satu‐
rated colored lighting. Also, do not use cheap with radiosity
if you want to preserve all the emitted light.
-cheapgrid
Stop calculating light on a sample after it exceeds (255, 255,
255), but only for the lightgrid.
-compensate value
Scales back lightmap values to adjust for overbrighting when
-gamma is used. For Quake III Arena, a good compensate value is
4, though some experimentation may be needed to find an aes‐
thetic that suits your particular map.
-cpma Enables full vertex lighting including occlusion on all sur‐
faces, including lightmapped. Causes incorrect handling of
-approx in Quake III Arena even with special shaders.
-dark Enables darkening of lightmaps at brush/lightmap seams. Very
subtle.
-debug Enables lightmap debugging.
-debugaxis
Colors lightmaps based on their projection axis.
-debugcluster
Colors lightmaps based on the PVS-cluster the luxel falls into.
-debugorigin
Colors lightmaps based on the luxel origin relative to the raw
lightmap's bounding box.
-debugunused
Colors unused luxels hot pink.
-dirty Enables ambient occlusion or dirtmapping. Less-visible areas
such as cracks and crevices will become darker. This simulates
a dirty, grimy effect.
-dirtdepth depth
Use with -dirty. Sets maximum depth of occlusion checking in
game units. The default depth is 128.
-dirtmode mode
Use with -dirty. Controls the mode in which the dirtmap is cal‐
culated. Possible values for mode are:
0 Uniform mode, generates a smooth looking dirtmap
(default).
1 Noisy mode, generates a noisy dirtmap.
-dirtscale scale
Use with -dirty. Scales up the "darkness" of the dirtmapping
effect by the prescribed factor.
-dump Dumps radiosity lights into numbered prefabs.
-fast Enables light envelopes for area (shader) lights. This includes
radiosity lights. Results in a much quicker -light compiles,
but darkens all enveloped light sources considerably. Using
-fast is generally a good idea, since omiting this option
results in a huge increase in compile time.
-fastbounce
Enables -fast style calculations, but only for radiosity lights.
-faster
The -faster option enables test mode light calculations. Very
fast, but produces poor results. Use this option if you want a
quick a test compile.
-fastgrid
Enables -fast style calculations, but only for the lightgrid.
-filter
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 -samples
instead.
-gamma value
Use a prescribed gamma correction factor. The default value 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.
Games that use r_overBrightBits and r_mapOverBrightBits (Quake
III Arena, most notably) will need those cvars disabled unless
-compensate is used accordingly.
-lightmapsize size
Limits the lightmap size.
-lomem 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.
-nocollapse
Disables collapsing of identical lightmaps. This switch is
required for Q3Map2 lightstyles.
-nogrid
Disables calculation of the lightgrid.
-normalmap
Colors lightmaps based on the facings of their vertex normals.
-nosurf
Disables the surface tracing of detail brushes and patch meshes
for shadow casting.
-notrace
No light tracing is performed. As a result, no shadows will be
cast.
-novertex
Disables the calculation of vertex lighting.
-patchshadows
Enables the casting of shadows by patch meshes.
-pointscale factor
Scales up point (entity) lights by the prescribed factor.
Default is 1.0.
-samples value
Enables intelligent antialiasing of shadow edges in lightmaps.
A value of 2 both looks good and compiles quickly, while a value
of 3 looks great but compiles somewhat more slowly.
-scale factor
Scales up all light sources by the prescribed factor. Default is
1.0.
-shade Enables phong shading.
-sky factor
Scales up all sun/sky light sources by the prescribed factor.
Default is 1.0.
-sunonly
Computes sun/sky light only, no other light sources.
-super value
Enables arbitrarily ordered grid supersampling of lightmaps.
-thresh threshhold
Sets the recursive triangle subdivision threshhold. The thresh‐
hold range is 0.0 to 1.0.
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 -format option.
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.
It can also be used to convert a .bsp file from one game to an other
(the other game is specified with the -game option). This feature is
experimental.
The following options can be used with the -convert command:
-format format
Specify the output format for the -convert command. format is
one of the following: ase, map, quake3, wolf, et, etut, ef, jk2,
sof2, tenebrae
EXAMPLES
BSP phase:
q3map2-bsp -v -meta mymap.map
VIS and LIGHT phases with test settings:
q3map2-vis -v -saveprt -fast mymap.map
q3map2-light -v -faster mymap.map
VIS and LIGHT phases with final settings:
q3map2-vis -v -saveprt mymap.map
q3map2-light -fast -super 2 -bounce 6 mymap.map
Convert a Wolfenstein: Enemy Territory .bsp file to a .map file:
q3map2-game et -convert -format map etmap.bsp
HISTORY
Q3Map2 started out as a bugfix for Q3Map, the original Quake 3 map com‐
piler. Q3Map was written by Id Software Inc.
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.
The text for this manpage was edited and converted by Ingar
(ingar@telenet.be) from the text available at http://en.wiki‐
books.org/wiki/Q3Map2.
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
SEE ALSO
http://en.wikibooks.org/wiki/Q3Map2
q3map2 2.5.16 18 september 2006 q3map2(6)
