q3map2 - a quake 3 BSP compiler
q3map2 is a BSP compiler for games based on the Quake III Arena engine.
specifies the operation q3map will perform on the given
. Only one command can be specified.
- 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.
- Creates visibility sets based on the portal file. This command requires
file to be a path to a .map file, which has been processed with the
- 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.
- Converts a compiled .bsp to another format. This command requires
file to be a path to a compiled .bsp file.
- Exports internal lightmaps from a compiled .bsp to external .tga images.
This command requires file to be a path to a compiled .bsp file.
- 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.
- 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 original
.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 subdirectory of the
game base directory. This command requires file to be a path to a
compiled .bsp file.
The following options can be used with any command:
- 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
- -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.
- Enables verbose mode. This is generally a good idea.
- 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
The following options can be used with the -bsp
- 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.
- Enables debugging of surface triangle insetting.
- Draws the portals into the bsp as translucent polygons. Omit -vis
and -light for the best -debugportals results.
- Colors every surface a different color (very trippy). Omit -vis and
-light for the best -debugsurfaces results.
- Creates a new .map file with a blank worldspawn entity and all the world
brushes from your original .map file.
- 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.
- Forces all texture coordinates for a given surface to the pixel that best
fits the average color of the assigned texture.
- Will cause all detail brushes to be handled as if they were structural.
- Will abort the compile if a leak is encountered.
- 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
Will not compile patch meshes into the .bsp.
- Will not compile detail brushes into the .bsp.
- Will not compile fog brushes into the .bsp.
- Will not compile hint brushes into the .bsp.
- Visible surfaces will not be split. TessSize is ignored.
- Will not fix T-Junctions. Using this option can cause sparklies and LOD
- Will not compile liquid brushes into the .bsp.
- -np shadeangle
- Forces all planar shaders to become nonplanar with the shadeangle
specified. shadeangle can range from 1 to 179.
- Only changes the entities in the compiled .bsp. Needs a compiled .bsp (as
well as a .map) to act as a file-filter.
- 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.
- 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 predominantly on nVidia
hardware, nobody noticed it until too late.
- Enables axial bevel plane snapping to reduce clipped model plane count.
Use with care.
- -texrange texelcount
- Limits per-surface texel count to texelcount
- Outputs more information about compiling entity sub-models into the .bsp
The following options can be used with the -vis
- Only calculates rough visibility data. Quick and dirty, not actually
useful for VIS purposes.
- Will merge the bsp leaves (except for hint portals) before calculating the
- Will merge the bsp leaves before calculating the visibility list.
- Disables the passage visiblity algorithm. Passage VIS is a bit faster and
tighter than the old algorithm.
- Disables the sorting of portals by complexity. Sorting speeds up visiblity
- Will use the passage visibility algorithm only.
- Omits hint brushes from visibility calculations.
- Disables the automatic deletion of the .prt portal file after VIS
The following options can be used with the -light
- -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:
- Creates a debugging border around each lightmap.
- -bounce bounces
- Calculating radiosity light through bounces bounces.
- Allows bounced light to affect the lightgrid.
- -bouncescale scale
- Scales up radiosity lights by the prescribed scale factor.
- 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
- 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 aesthetic that suits your
- Enables full vertex lighting including occlusion on all surfaces,
including lightmapped. Causes incorrect handling of -approx in
Quake III Arena even with special shaders.
- Enables darkening of lightmaps at brush/lightmap seams. Very subtle.
- Enables lightmap debugging.
- Colors lightmaps based on their projection axis.
- Colors lightmaps based on the PVS-cluster the luxel falls into.
- Colors lightmaps based on the luxel origin relative to the raw lightmap's
- Colors unused luxels hot pink.
- Enables ambient occlusion or dirtmapping. Less-visible areas such as
cracks and crevices will become darker. This simulates a dirty, grimy
- -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 calculated.
Possible values for mode are:
- Uniform mode, generates a smooth looking dirtmap (default).
- Noisy mode, generates a noisy dirtmap.
- -dirtscale scale
- Use with -dirty. Scales up the "darkness" of the dirtmapping
effect by the prescribed factor.
- Dumps radiosity lights into numbered prefabs.
- 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
- Enables -fast style calculations, but only for radiosity lights.
- The -faster option enables test mode light calculations. Very fast,
but produces poor results. Use this option if you want a quick a test
- Enables -fast style calculations, but only for the lightgrid.
- 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
- -lightmapsize size
- Limits the lightmap size.
- 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
- Disables collapsing of identical lightmaps. This switch is required for
- Disables calculation of the lightgrid.
- Colors lightmaps based on the facings of their vertex normals.
- Disables the surface tracing of detail brushes and patch meshes for shadow
- No light tracing is performed. As a result, no shadows will be cast.
- Disables the calculation of vertex lighting.
- Enables the casting of shadows by patch meshes.
- -pointscale factor
- Scales up point (entity) lights by the prescribed factor. Default
- -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
- Enables phong shading.
- -sky factor
- Scales up all sun/sky light sources by the prescribed factor.
Default is 1.0.
- 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 threshhold
range is 0.0 to 1.0.
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
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
- -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,
- 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
Q3Map2 started out as a bugfix for Q3Map, the original Quake 3 map compiler.
Q3Map was written by Id Software Inc.
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
The text for this manpage was edited and converted by Ingar (firstname.lastname@example.org)
from the text available at http://en.wikibooks.org/wiki/Q3Map2.
This text is available under the terms of the GNU Free Documentation License.
The full text of this license can be found at