q3map2(6)

NAME
q3map2 - a quake 3 BSP compiler

SYNOPSIS
q3map2 command [options] file

DESCRIPTION
q3map2 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 processed 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 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.

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 shadeangle specified. shadeangle can range from 1 to 179.

-onlyents
    Only changes the entities in the compiled .bsp. Needs a compiled .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 predominantly 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 calculating 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 saturated 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 aesthetic that suits your particular map.

-cpma
    Enables full vertex lighting including occlusion on all surfaces, 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 calculated. 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 threshhold 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 compiler. 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.wikibooks.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