Q3Map2 Handbook: Beta Edition
[ Home ] [ disclaimer ] [ bsp ] [ vis ] [ ss_flare ] [ basecompile ] [ foghull_guide ] [ Q3Map2 handbook: alpha edition ]

Q3MAP

it is understood that all switches are proceeded by the - character.

usage: q3map [-<general option>] [-<switch> [-<switch> ...]] <path/to/maps/mapname>

if it's a link to another page, it's probably finished.

if you see information on this page, it's not done yet. the information you see is generally accurate, and fairly comprehensive, but some options remain untested and the information unrefined.

Switches

general options

connect (hostname/ip)
Will output logging to a remote host. {courtesy of jer}

paths to games

1. -game
2. -fs_game
3. -fs_basepath

threads (n)
The number of threads that Q3Map will use to compile the map.
In Windows, the qthreads code, what Q3Map uses, will detect the number of CPU's present, and set the threadcount accordingly. This can be overridden, by setting -threads.
Linux users will still need to set this though, in order to enable SMP.
For the fastest compile times, -threads should be set to however many CPU's you have. (no that doesn't mean on a shelf in your closet)

v
Outputs verbose information about the status of your compile.

main

• -bsp
• -vis
• -light
• -export
• -import
• -info
• q3map_keywords
• surfaceparms
• spawnflags

lightmaps (i/o/ext)

-import
(Usage: q3map -import [-v] )

-export
(Usage: q3map -export [-v] )

light
usage: q3map -light [- [- ...]]

-approx (%d)
Approximates lightmaps within a byte tolerance of %d. approx forces simple surfaces without much shadow detail to be vertex lit, thus saving lightmaps. The range is from 0-255, 0 being default (no approximation). try -approx 50.

area (scale)
This scales the intensity of area lights. (Area (shader) light scaled by %f to %f)

border
Creates a debugging border around the lightmap, and helps you to correlate areas of your map to areas in the lightmap when you export the lightmap or use external lightmaps.

bounce (n)
((n) = number of radiosity passes) This enables radiosity calculation. It will re-diffuse the light emitted onto a surface (n) times. In addition, it will write out the bsp after every pass, so it can be cancelled without loss. The tint of light that's reflected is the lightmap/vertex * texture color, and subsampled to certain granularity across every lit surface. Use q3map_lightimage in a shader to override the reflected color.

bouncegrid
This enables radiosity affecting the lightgrid. The lightgrid is used for the lighting of game models and game entities, such as player models, ammo boxes, powerups and so forth. This also affects vertex lighting. (explanation courtesy of jer and shadowspawn)

cheap
This stops Q3Map from 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
This is the same as cheap, but it is used only in lightgrid calculations.

debug
Enables lightmap debugging.

debugsurfaces
This colors lightmaps by surfacenum % 6, and will color every surface with a different color.

debugunused
(Unused luxel debugging) This colors unused lightmap pixels (luxels) hot pink.

dump
Dumps radiosity lights into numbered prefabs, for each bounce. (maps/

export
This exports internal lightmaps in the .bsp to .tga images.

extra
Sets -super 2. Use -extra if you're too lazy to type -super 2.

extrawide
Sets -super 2. Sets -filter. Use -extrawide if you're too lazy to type -super 2 -filter.

fast
This enables light envelopes for area lights, and enables light culling. With some maps, using it could speed up light calculations by 50x or more. For maps with large numbers of dim surface lights, it also has the side effect of producing dimmer maps, so you'll need to tweak your lighting. Fast makes for great final compiles though, as long as you light accordingly. To disable light culling, and at the same time disable compile time speed increases, don't put fast in your command line.

fastbounce
This enables fast for radiosity passes only.

fastgrid
This enables fast for lightgrid calculation only.

filter
Gives you a gaussian blur for shadows, and applies a 3x3 box filter (similar to Photoshop's blur) to the lightmap. It breaks down on the edges of a lightmap, because there isn't anything to sample from off the edge. Filter averages a given luxel with 3 of it's neighbors. This is what the old extrawide did, but filter is a bit smarter about it.

nocollapse
Identical lightmap collapsing disabled. Collapse compares raw lightmap a to raw lightmap b. Then if they are exceedingly similar, (off by (0.0025 in 3 * x * y)), they are merged.

nogrid
This disables calculation of the lightgrid for dynamic model lighting.

normalmap
(Stores normal map instead of lightmap). This colors lightmaps by their facings, and is good for debugging phong shading.

nosurf
This disables the surface tracing of detail brushes and patches for shadow calculation.

notrace
no light tracing is performed. As a result, no shadows will be cast.

novertex
This disables calculation of vertex lighting.

patchshadows
This enables the casting of shadows by patches.

point (%f=scale)
This scales the intensity of point lights. (Point (entity) light scaled by %f to %f)

samplesize (n)
This sets the lightmap pixel size to (nxn) units. The default is 16. (16x16). The -samplesize argument allows the mapper to set a map wide samplesize value in the -light phase that overrides the default 16 value. It is overridden by surfaces with explicit lightmap sample sizes. (q3map_lightmapsamplesize)

shade
Phong shading enabled.

shadeangle (%d)
Phong shading enabled with a breaking angle of %d degrees. This also turns on phong shading, and gives you the ability to specify the angle of light determined by (%d).

smooth
temporarily non-functional. This makes for smoother shadows. A smarter version of extra, smooth only subsamples lightmap pixels that are shadowed. It produces results comparable to extra, but in approx. 1/3 the time. It can also be combined with super and filter, for ?16 or ?48-tap sampling.

sunonly
Only computes sunlight, no other light at all.

super (n)
Arbitrarily ordered grid supersampling of lightmaps. This replaces extra & extrawide. This replacement does true n-tap supersampling, rather than the weird filter that extrawide did. note that -super requires an argument >= 2.

supersample
super is the new shorter name for supersample.

thresh (n.n)
Thresh sets the recursive triangle subdivision threshold. The range is from 0.1 - 1.0. Default is 1.0

-trisoup
Converts brush faces to triangle soup (merge?)

These need further work/clarification

-tempname
-area (area light scaling at %f)
-point (point light scaling at %f)
-bounce (Radiosity enabled with %d bounce(s))
-supersample (Supersampling enabled with %d sample(s) per lightmap texel)
-filter (Lightmap filtering enabled)
-shadeangle (Phong shading enabled with a breaking angle of %d degrees)
-thresh (Subdivision threshold set at %.3f)
-approx (Approximating lightmaps within a byte tolerance of %d)
-sunonly (Only computing sunlight)
-nocollapse (Identical lightmap collapsing disabled)
-shade (Phong shading enabled)
-bouncegrid (Grid lighting with radiosity enabled)
-smooth (Smoothing enabled)
-fast (Fast mode enabled)
-fastgrid (Fast grid lighting enabled)
-fastbounce (Fast bounce mode enabled)
-cheap (Cheap mode enabled)
-cheapgrid (Cheap grid mode enabled)
-normalmap (Storing normal map instead of lightmap)
-trisoup (Converting brush faces to triangle soup)
-debug (Lightmap debugging enabled)
-debugsurfaces (Lightmap surface debugging enabled)
-debugunused (Unused luxel debugging enabled)
-export (Exporting lightmaps)
-notrace (no occlusion tracing)
-patchshadows (Patch shadow casting enabled)
-extra (Extra detail tracing)
-extrawide (Extra wide detail tracing)
-samplesize (lightmap sample size is %dx%d units)
-novertex (no vertex lighting = true)
-nogrid (no grid lighting = true)
-border (Adding debug border to lightmaps)
-nosurf (not tracing against surfaces)
-dump (Dumping radiosity lights into numbered prefabs)

Q3Map Keywords

General

q3map_backshader (shadername)
Shadername is the path/shadername of the shader or texture to be used at the back side of the surface.

q3map_backsplash (percentage) (distance)
{pjw} by default, all shaders are assigned backsplash values:
1. 0.05 for the percentage
2. 23 units for the distance.
A surface light is also lit by itself, using back splash point lights with a lower intensity. The percentage parameter specifies the intensity percentage they use from the q3map_surfacelight parameter. The distance parameter controls the distance of these back splash lights from the surface. You can set the percentage to zero, or a negative value, to disable the backsplash lights.

q3map_bounce (n.n)
(1.0 = default) (range of 0-1). Use a number between 0 and 1.0, (or higher), to scale the amount of light reflected in radiosity passes. You can oversaturate it by using a number higher than 1.0, but this can lead to excessive compile times. Using 90 would probably make things positively glacial. 1.0 is just a default, fudged number that looked ok with the maps that were tested. Tweaking it to 1.5 or 2.0 wont hurt anything, per se, but it does give you finer control over how each shader re-emits light.

q3map_cloneshader
This is used in furshading.

q3map_extrashader
This does not exist.

q3map_fadealpha (n)
This does not exist.

q3map_flare (shadername)
Creates a flare using the specified shader at the center of a surface.

q3map_forcemeta
Probably forces the meta process on a per shader basis.

q3map_forcesunlight
By default, no sunlight is cast on vertex-lit .md3 models or vertex-lit terrain. Using this option, sunlight, (aka overbright bits created by the q3map_sun option), will be cast on these surfaces.

q3map_fur
This is used in furshading.

q3map_globaltexture
When this option is set, the texture is not aligned to the world.

q3map_indexed
This instructs Q3Map to look at the ents _indexmap key, for an image to pull index values from, and then to construct a shader name with a root of _shader key.

q3map_invert
This is used in celshading. Probably inverts something.

q3map_lightimage (image)
This specifies the image to be used for the light_color_value of a surface light, instead of the image(s) used by the shader. The color is averaged from the texture. The texture must be the same size as the base image map.

q3map_lightmapsamplesize (n)
Surfaces using a shader with this option will have the pixelsize of the lightmaps set to (nxn). This option can be used to produce high-resolution shadows on certain surfaces. In addition, it can be used to reduce the size of lightmap data, where high-resolution shadows are not required.

q3map_lightmapaxis (L)
Lightmapaxis takes one argument: either x, y or z. The keyword q3map_terrain has an implicit (read default) q3map_lightmapaxis defined as z.

q3map_lightmapsampleoffset (n.n)
Takes a single parameter, defaulting to 1.0, which specifies how many units off a surface should Q3Map2 sample lighting from. Use larger values (2.0-8.0) or so if you're getting ugly splotches on lightmapped terrain.

q3map_lightrgb
normalized rgb values

q3map_lightsubdivide (n)
For the actual lighting of the world, a surface light is subdivided into many smaller point lights. q3map_lightsubdivide controls the distance, in game units, between those point lights. The default value is 120. (thx Gef)

q3map_noclip
You might have noticed that terrain has been made to not clip or t-junction anymore. It was causing too many issues, so a new parameter was added: q3map_noclip. normally, Q3Map clips all faces to the bsp, and then takes the minimum polygon that encompasses all visible fragments. q3map_noclip forces Q3Map to use the original brush faces. (This is implicit for autosprite (2) surfaces) Therefore, if you map tidy, you could theoretically use q3map_noclip on all your shaders. q3map_noclip and q3map_notjunc, when used in combination, will preserve mesh geometry exactly as you make it.

q3map_nofast
When used on surfaces that emit light, this will disable -fast optimizations. This is useful for large areas of dim sky, where you want the dim light to reach all surfaces. This shader keyword prevents fast from affecting dim sky surfaces. It is necessary, if you cant do a workaround with brighter skies or by using a larger q3map_lightsubdivide value. Other methods of surfacelight calculation are currently being investigated. For instance, beam trees.

q3map_nonplanar
This option instructs Q3Map to merge any adjacent triangles into a non-planar triangle soup.

q3map_notjunc
With this option, surfaces modified by a shader are not used for t-junction fixing. q3map_noclip and q3map_notjunc, used in combination, will preserve mesh geometry exactly as you make it.

q3map_novertexshadows
Shaders that are used on misc_models or terrain can now use q3map_novertexshadows to disable shadows being cast on the vertex lit surfaces. Casting shadows at small, misc_model objects often makes sense. However, having shadows on large, vertex lit terrain surfaces often looks bad. Shadows are not cast on forced_vertex_lit surfaces by default. (shaders with pointlight).

q3map_offset (n.n)
This is used in celshading. Probably offsets something.

q3map_patchshadows
When this option is used in conjunction with the original lighting algorithm , (-light), surfaces with textures modified by this option will show shadows that are cast by curve patches. Under normal circumstances, curve patches do not cast shadows.

q3map_replicate
This does not exist.

q3map_shadeangle (x y)
(angle) (degrees) Specifies the breaking angle for phong shading.

q3map_sun (red) (green) (blue) (intensity) (degrees) (elevation)
Color will be normalized, so it doesn't matter what range you use. The intensity falls off with angle but not distance. A value of 100 is a fairly bright sun.
degrees: 0 = east. 90 = north.
elevation: 0 = sunrise/sunset. 90 = noon.

q3map_surfacelight (value)
Sets the amount of light a surface emits (see q3map_backsplash).

q3map_tc_gen
q3map_tcGen ivector ( 256 0 0 ) ( 0 256 0 )
will project the texture every 256 units in x, and every 256 units in y, along the z-axis. Ivector means inverse vector, and this means you won't have to do the divide with a calculator. ivector ( 256 0 0 ) ( 0 256 0 ) == vector ( 1/256 0 0 ) ( 0 1/256 0 ). inverse = 1.0 / n, unless the value is 0. If the value is 0, then the matrix value is set to 0. A bit of dodgy math, but it works.

q3map_terrain
Your terrain shaders (typically textures/common/terrain and terrain2) must have the q3map_terrain keyword. Terrain is handled completely differently from previous versions. Q3Map no longer looks for the word terrain in a shader name to determine whether or not its an indexed shader. It looks for q3map_indexed, or q3map_terrain, which then sets off a bunch of stuff to emulate TA terrain. Terrain is just a subset of indexed shaders, which get their values from the _indexmap image. With a bunch of default stuff shoehorned into it, like: the lightmap axis, texture projection, etc
By default, q3map_terrain sets the following:
q3map_tcGen ivector ( 32 0 0 ) ( 0 32 0 )
q3map_lightmapaxis z
q3map_nonplanar
q3map_shadeangle 180 // maybe 175?
q3map_indexed

q3map_texturesize (x y)
q3map_texturesize is really only useful as a substitute for q3map_tcGen. q3map_texturesize is really for times when you want to have a small lightimage but want the texture to map as if it is bigger.

q3map_tracelight
Surfaces using a shader with this option will always be lit with the original light algorithm. Patches will not cast shadows on this surface, unless the shader option q3map_patchshadows is also used.

q3map_vertexscale (scale)
The light value, at the vertices of a surface using a shader with this option, is multiplied by the scale value. This is a way to lighten, or darken, a vertex_lit surface, in comparison to other lightmap_lit surfaces around it.

q3map_vertexshadows
By default, no shadows are cast on vertex_lit_surfaces (see surfaceparm pointlight). In addition, when running Quake3 Arena in vertex light, no shadows are cast upon any surface at all, since shadows are a part of the lightmap. When using this shader_keyword, shadows will be cast on surfaces that are vertex lit. However, sharp shadow edges wont be seen on the surfaces, since lightvalues are only calculated at the vertices.

surfaceparm pointlight
Surfaces using a shader with this parameter will always be vertex lit. This option can be used to reduce the lightmap data. It is often used on surfaces that don't need shadows.

surfaceparm dust
If a player lands (jumps onto) on a surface that uses a shader with this parameter, a puff of dust will appear at the players feet.
note1: the worldspawn entity of that map must have an enabledust key set to a value of 1.
note2: this surfaceflag has been replaced by surfaceparm woodsteps in RTCW.

These need further work/clarification

q3map_lightmapSize (W H) (powers of 2 (exponents))
substitutes $lightmap with path/to/lightmap.tga. you don't have to do anything, just add q3map_lightmapsize 512 512 or something to your shaders that you want to use larger pages. q3map handles everything else.

q3map_lightmapgamma (n.n)

q3map_nofog
(implemented?)

q3map_lightmapMergable
q3map_lightmapmerge doesn't work yet
it will specify that the shaders using it can merge nonplanars together onto a single lightmap, so you can have a single 512x512 lightmap across a terrain entity
{wf}shadowspawn> so does that mean they wont by default.

q3map_nolightmap

q3map_pointlight

q3map_notjunc
skies should have no-t_junc

q3map_normalimage
(bumpmapping normal map)

qer_editorimage

q3map_lightimage

q3map_surfacelight

q3map_lightsubdivide

q3map_lightmapsamplesize

q3map_lightrgb

polygonoffset
(for no culling)

q3map_terrain
legacy support for terrain/terrain2 shaders. team arena terrain is assumed to be nonplanar, with full normal averaging, passed through the metatriangle surface pipeline, with a lightmap axis on z.

q3map_indexed
for explicit terrain-style indexed mapping.

q3map_noclip
preserve original face winding, don't clip by bsp tree.

q3map_nofast

q3map_bounce

q3map_offset

q3map_invert
inverts a drawsurface's facing

q3map_nonplanar
make it a nonplanar merge candidate for meta surfaces

q3map_shadeAngle

q3map_tcGen