GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
q3map2(6) Quake 3 III Arena Documentation q3map2(6)

q3map2 - a quake 3 BSP compiler

q3map2 command [options] file

q3map2 is a BSP compiler for games based on the Quake III Arena engine.

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.

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.

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.

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.

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.

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

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 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.

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

http://en.wikibooks.org/wiki/Q3Map2
18 september 2006 q3map2 2.5.16

Search for    or go to Top of page |  Section 6 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.