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


Manual Reference Pages  -  Q3MAP2 (6)

NAME

q3map2 - a quake 3 BSP compiler

CONTENTS

Synopsis
Description
     General options
     Options for the -bsp command
     Options for the -vis command
     Options for the -light command
     Options for the -convert command
Examples
History
Author
Copyright
See Also

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

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


q3map2 2.5.16 Q3MAP2 (6) 18 september 2006

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