Q3Map2 Minor Compile Switches: BSP, VIS and Light

This page covers the minor command-line switches documented for all three phases of Q3Map2: BSP geometry compilation, VIS visibility calculations, and Light lighting calculations. Q3Map2 has three major compile phases, invoked with -bsp, -vis, and -light. The minor switches modify the behaviour of the selected phase. Some are intended for everyday compilation, some are specialised quality or performance controls, and others exist mainly for debugging.

It should be noted that Q3Map2 has several forks and game-specific variants, so a switch's exact implementation or availability can differ between versions and results of the same switches can also have variance between those Q3Map2 variants.

Contents

Quick reference: all documented switches
BSP phase - geometry compilation

Custom surface parameters and debugging
Brush classification and map contents
Per-surface geometry limits
Omitting specific geometry or brush types
Surface shading and patch conversion
Compatibility and geometry processing
Entity-only compilation and logging
VIS phase - visibility calculations
Light phase - lighting calculations

Light intensity and radiosity
Lightmap seams and debugging
Directional lighting and ambient occlusion
Compile speed and light calculation methods
Gamma, lightmap size and lightmap allocation
Lightgrid and surface shadowing
Point lights, general intensity and sun lighting
Sampling and shadow-edge quality
Phong shading
Additional lighting output and final diagnostics

Quick reference: all documented switches

The following is a compact index of the switches covered further down the page.

BSP

VIS

Light

BSP phase - geometry compilation

The BSP phase converts the .map file into a compiled .bsp, processing brushes, surfaces, patches and other map data. It also generates supporting files, including portal information and surface data, that later compilation phases can use.

The Wikibooks BSP reference documents 27 minor switches, from -custinfoparms through -verboseentities.

Custom surface parameters and debugging

-custinfoparms

Purpose: Enables custom surface parameters for game mods without requiring Q3Map2 itself to be recompiled.

Custom definitions are stored in custinfoparms.txt in the scripts directory. The file separates two categories:

• Contentflags - flags that determine how a surface or volume interacts with the game, such as contents recognised by a particular engine or mod.
• Surfaceflags - flags that describe surface properties interpreted by the engine or mod.

Each entry maps a parameter name to a hexadecimal bit flag. For example, the documentation illustrates the structure as follows:

// Contentflags
{
    surfaceparmName 0x0000
}

// Surfaceflags
{
    surfaceparmName 0x0000
}

The names and numerical values above are placeholders, not usable universal flag definitions. They must correspond to flags understood by your particular game or modification.

When to use it: When a custom game or mod has surface parameters that Q3Map2 does not recognise by default.

Caution: Defining a parameter in the compiler does not automatically make the game engine implement its behaviour. The engine or mod must understand the corresponding flags.

-debuginset

Purpose: Enables debugging of surface triangle insetting.

The Wikibooks entry does not explain the underlying operation in detail. It is therefore best treated as a specialised diagnostic switch rather than a normal compile optimisation.

When to use it: When investigating compiler behaviour involving triangle insetting, particularly if a specific compiler version or development build is being debugged.

Caution: The available reference does not establish what visual output to expect or which specific geometry defects it diagnoses. Do not assume that enabling it fixes the geometry.

-debugportals

Purpose: Draws portals into the BSP as translucent polygons.

Portals are boundaries used during visibility processing to divide the world into regions or leaves. Visualising them can help reveal how the compiler has partitioned the map.

When to use it:

• Investigating visibility partitioning.
• Inspecting portal placement.
• Diagnosing unexpected splits or visibility behaviour.

Recommended practice: Omit -vis and -light when compiling for this diagnostic output, as the Wikibooks documentation recommends. That helps preserve the usefulness of the portal visualisation.

-debugsurfaces

Purpose: Assigns a different colour to every surface.

This is a visual diagnostic, not a lighting enhancement. It can help distinguish individual compiled surfaces and investigate how geometry has been divided or processed.

When to use it: When checking surface segmentation or investigating unexpected surface boundaries.

Caution: Omit -vis and -light for the clearest debugging result, according to the reference. Do not interpret the artificial colours as the final material appearance.

-fakemap

Purpose: Creates a new .map file containing a blank worldspawn entity and the world brushes from the original map.

This is useful to understand as a map extraction or transformation operation, rather than a conventional visual-quality switch.

Potential uses:

• Isolating world geometry from a larger map.
• Producing a simplified map for inspection or further processing.
• Investigating compiler handling of world brushes separately from the original entity setup.

Caution: The Wikibooks page explicitly notes that the switch is poorly documented there. The exact treatment of entities, brush attributes and special cases should be checked against the particular Q3Map2 build before relying on it in an automated workflow.

-flares

Purpose: Enables support for flares.

Flares are glare-like effects associated with bright light sources. Support depends on the target engine; the Wikibooks page mentions certain Raven titles and ioQuake3 as examples.

When to use it: When building a map for an engine that supports the relevant flare functionality and your map uses flare entities or compatible flare data.

Caution: The switch does not guarantee that a flare will appear in every engine. Compiler support, map entities and engine rendering support must all be compatible.

-flat

Purpose: Forces all texture coordinates for a surface to the texture pixel that best fits the average colour of the assigned texture.

In practical terms, this is an unusual rendering-oriented or diagnostic treatment rather than ordinary texture mapping. Instead of retaining the normal variation across the texture, the compiler selects a representative colour.

When to use it: For specialised tests involving surface appearance or simplified colour output.

Caution: It is not a normal production setting for a textured map because it discards the usual texture-coordinate variation.

Brush classification and map contents

-fulldetail

Purpose: Treats all detail brushes as though they were structural brushes.

This switch affects how the compiler handles the distinction between structural and detail geometry. Structural brushes contribute to world partitioning and visibility structure. Detail brushes are generally intended to add geometry without creating the same degree of structural separation.

When to use it: For specialised tests where you want to see how treating detail geometry as structural changes the BSP and portal layout.

Potential consequences:

• Different BSP partitioning.
• More structural separation and potentially more portals.
• Changes to visibility calculations and compile time.

Caution: This is not simply a switch to improve geometric detail. It changes how detail geometry participates in the structural world.

-leaktest

Purpose: Aborts compilation if a leak is encountered.

A leak generally means the enclosed playable world is not properly sealed from the outside void. In a conventional Quake III-style map, this can prevent the compiler from establishing the intended enclosed world and completing the normal visibility workflow.

When to use it: During development, especially when you want a compile to fail immediately if a leak is detected.

Why it helps: It makes leak detection an explicit build requirement instead of allowing the compile workflow to continue as though the map were valid.

Caution: This switch detects a problem; it does not repair the leak. Check the compiler's leak output and follow the leak path to locate the gap in the world geometry.

-meta

Purpose: Enables the meta-surface compilation path used by many advanced Q3Map2 features.

The Wikibooks page describes this as a broadly important switch and recommends using it alongside -v.

Meta surfaces are a representation of compiled geometry that allows the compiler to process and optimise surfaces in ways needed by advanced features. In many Q3Map2 workflows, -meta is part of the standard BSP command.

When to use it: For typical modern Q3Map2 BSP compilation, especially when using advanced surface processing or patch-related features.

Practical advice: Treat it as a standard starting point unless your particular compile workflow or target compiler specifies otherwise.

Caution: It is not a universal quality slider. Its actual effects depend on the Q3Map2 version and the other switches being used.

Per-surface geometry limits

-mi <N>

Purpose: Sets the maximum per-surface index count to N.

An index identifies a vertex used by a surface's triangle data. Index counts and vertex counts are related but are not interchangeable: a surface can reference the same vertex multiple times through different indices.

When to use it: When investigating surface limits, compatibility constraints or compiler behaviour involving unusually large surfaces.

Caution: Raising the limit does not automatically improve performance. The target engine must be able to handle the resulting surface data, and a limit should not be changed without a reason.

-mv <N>

Purpose: Sets the maximum per-surface vertex count to N.

This controls the number of vertices allowed on an individual compiled surface.

When to use it: When working with unusually large or complex surfaces or investigating compiler limits.

Difference from -mi: -mv concerns vertices; -mi concerns indices. A surface's index count can differ significantly from its vertex count because indices describe how vertices are referenced.

Caution: These are low-level surface limits, not substitutes for sensible geometry construction. Exact safe values depend on the compiler and target engine.

Omitting specific geometry or brush types

-nocurves

Purpose: Prevents patch meshes from being compiled into the BSP.

In Quake III mapping, curved surfaces are commonly represented by patch meshes.

When to use it: For specialised tests or workflows that deliberately exclude patch geometry.

Consequences: Curved surfaces may be missing from the compiled map, so this is generally unsuitable for a normal final compile of a map that uses curves.

-nodetail

Purpose: Prevents detail brushes from being compiled into the BSP.

When to use it: When testing or inspecting a map without its detail-brush geometry.

Consequences: Detail geometry may disappear from the compiled map. This is not equivalent to merely changing how detail brushes participate in visibility calculations.

-nofog

Purpose: Prevents fog brushes from being compiled into the BSP.

Fog brushes define regions where the engine can apply fog-related effects.

When to use it: For testing a map without its fog volumes or isolating fog-related issues.

Consequences: The intended fog regions will not be compiled normally. Use this only when that change is deliberate.

-nohint

Purpose: Prevents hint brushes from being compiled into the BSP.

Hint brushes are used to guide the compiler's structural partitioning and portal layout. They are not ordinary visible surfaces intended to decorate a level.

When to use it: To compare a map's structural partitioning with and without hint information.

Consequences: The compiler loses the guidance provided by hint brushes. The resulting portal layout and VIS performance may change.

Caution: Removing hints is not guaranteed to make visibility processing faster. A well-designed hint layout can improve visibility behaviour.

-nosubdivide

Purpose: Prevents visible surfaces from being split; TessSize is ignored.

Surface subdivision can break large surfaces into smaller pieces according to compiler rules and shader settings.

When to use it: For specialised geometry tests or when deliberately investigating the effect of subdivision.

Potential consequences:

• Different surface sizes and counts.
• Changes to the geometry submitted to the renderer.
• Possible compatibility or performance issues if surfaces become too large for the intended engine.

Caution: It is not a general-purpose optimisation. Disabling subdivision can conflict with assumptions made by shaders, surface processing or the target engine.

-notjunc

Purpose: Disables T-junction fixing.

A T-junction occurs when one surface's vertex meets the middle of another surface's edge instead of that edge being split at the same point.

When to use it: Primarily for specialised testing of the compiler's T-junction handling.

Consequences: The Wikibooks reference specifically warns that this can cause sparklies and level-of-detail (LOD) cracks. These are visible rendering defects that can occur when adjacent geometry does not line up correctly.

Recommendation: Leave T-junction fixing enabled for normal map production.

-nowater

Purpose: Prevents liquid brushes from being compiled into the BSP.

When to use it: For diagnostic or specialised builds in which liquid brush geometry is intentionally excluded.

Consequences: Water or other liquid brush contents may be absent from the compiled map. This is not a normal way to optimise a production map containing water.

Surface shading and patch conversion

-np <shadeangle> - values from 1 through 179

Purpose: Forces planar shaders to become nonplanar using the specified shade angle.

This switch is related to how surface shading is handled. Planar surfaces normally have a consistent geometric normal across a flat face, whereas nonplanar shading can allow lighting to vary across the surface according to the applicable shading rules.

When to use it: When deliberately testing or changing the shading treatment of surfaces.

Caution: The documented range is 1–179. The switch is not the same as the Light phase's -shade, which enables phong shading. Do not assume that the two switches perform identical operations.

-patchmeta

Purpose: Creates meta surfaces from patch meshes, effectively baking a level of detail into the patches in the BSP.

This is especially useful for workflows that need patch geometry converted into a representation suitable for further processing or model conversion.

When to use it:

• When preparing patch-based geometry for conversion into a model format.
• When deliberately baking patch tessellation into compiled geometry.
• When following workflows that require patch meta surfaces.

Caution: Because the patch representation and its baked tessellation affect the resulting geometry, test the output in the target engine before using the result as a final production asset.

Compatibility and geometry processing

-skyfix

Purpose: Enables a fix for an old texture-clamping compatibility problem involving GL_CLAMP. The Wikibooks page recommends always using it.

The documented historical explanation concerns differences in how graphics drivers handled GL_CLAMP and GL_CLAMP_TO_EDGE, which could cause texture-edge problems in Quake III-era rendering.

When to use it: For traditional Q3Map2 workflows where the target renderer expects this compatibility behaviour.

Caution: The relevance of the fix depends on the renderer and the version of Q3Map2. It should not be confused with a geometry or lighting optimisation.

-snap

Purpose: Enables axial bevel plane snapping to reduce the number of clipped model planes.

This is a specialised geometry-processing operation. The reference recommends caution and does not give a complete technical explanation.

When to use it: When testing a specific brush or model compilation issue where axial bevel plane snapping may be beneficial.

Caution: Since the switch changes geometric processing, compare the resulting BSP and rendered geometry against a normal compile before using it on production assets.

-texrange <N>

Purpose: Limits the per-surface texel count to N.

This is a surface-processing limit related to texture-space size. In Q3Map2 implementations, texture-range constraints can be relevant to subdivision and surface construction.

When to use it: When investigating unusually large texture-space surfaces or working with compiler and engine limits.

Caution: The exact interpretation of the limit should be checked against your Q3Map2 version. It should not be confused with -lightmapsize, which controls the lightmap size rather than the ordinary texture-space limit.

Entity-only compilation and logging

-onlyents

Purpose: Updates only the entities in an already compiled BSP. The Wikibooks reference specifies that it needs a compiled .bsp and a new entity file (.ent).

This can be useful when entity information changes but the world geometry does not need to be rebuilt.

When to use it:

• Updating entity properties.
• Making certain entity-only changes without a full geometry compile.
• Reapplying an external entity file to a previously compiled BSP.

Caution: This is not a replacement for a full BSP compile when brushes, patches, structural geometry or other geometry-affecting data have changed. Make sure the entity file corresponds to the map version you intend to use.

-v

Purpose: Enables verbose output for the BSP phase.

Verbose output provides additional compilation information, making it easier to see what Q3Map2 is doing and diagnose errors.

When to use it: In almost all development and production compile workflows.

Recommendation: Keep it enabled unless you have a specific reason to suppress the extra output.

-verboseentities

Purpose: Prints additional information about compiling entity submodels into the BSP.

This is more specific than general verbose mode. It helps when investigating how entities that contain model or brush geometry are processed.

When to use it: When diagnosing entity submodel compilation, particularly in maps with complex brush entities or model-related workflows.

Caution: It adds diagnostic output; it does not itself correct entity geometry or improve rendering quality.

VIS phase - visibility calculations

The VIS phase calculates which parts of the map can potentially be seen from other parts. It uses the portal information generated during BSP compilation to build visibility data.

This data is commonly described in terms of the Potentially Visible Set (PVS). A good PVS allows the engine to avoid rendering world regions that cannot be seen from the player's current location.

VIS therefore affects rendering efficiency rather than directly changing the map's visible textures or baked lighting. The switches can trade compilation time against visibility accuracy or tightness.

The Wikibooks VIS page documents eight minor switches.

-fast

Purpose: Calculates rough visibility data quickly.

The reference describes this as a quick-and-dirty calculation and cautions that it is not actually useful for proper VIS purposes.

When to use it: For temporary development builds when you need a rough visibility calculation quickly.

Advantages:

• Reduces the time spent calculating visibility.
• Useful for quick testing during active map development.

Disadvantages:

• Produces less precise visibility information.
• May result in less efficient in-game rendering because more areas can be treated as potentially visible.

Recommendation: Use it for temporary testing, not as the default for a final release build. Check the behaviour of the particular compiler version before relying on its output.

-hint

Purpose: Merges BSP leaves before calculating visibility, except for hint portals.

This is a visibility optimisation that retains the distinction introduced by hint portals while merging other leaves.

A leaf is a region of space in the BSP tree. Portals separate adjacent leaves and help the visibility algorithm reason about what can be seen through the world.

When to use it: When you want a faster VIS calculation that respects the hint portal structure.

Potential benefits:

• Reduces the complexity of the visibility calculation.
• Retains hint portals as important boundaries in the visibility process.
• Can be useful when the map's hint layout has been deliberately designed to guide visibility.

Caution: Merging leaves changes the representation used by VIS. The result depends on the map's structural geometry and hint placement.

-merge

Purpose: Merges BSP leaves before calculating the visibility list.

This is similar in purpose to -hint, but the documented distinction is that -merge merges the leaves generally rather than explicitly preserving hint portals as exceptions.

When to use it: When you want to speed up VIS calculations by reducing the complexity of the leaf structure.

Potential benefits:

• Less work for the visibility algorithm.
• Faster compilation on suitable maps.

Potential drawbacks:

• The merged visibility representation may be less tight.
• A less precise PVS can result in more geometry being rendered in-game.

Choosing between -hint and -merge: If hint portals are an important part of your visibility strategy, test -hint first. If you want a more general leaf-merging strategy, compare it with -merge.

Neither should be assumed to improve the final map's rendering performance without testing.

-nopassage

Purpose: Disables the passage visibility algorithm.

The Wikibooks reference describes passage VIS as somewhat faster and tighter than the older algorithm.

Passage visibility is an alternative method for determining whether one region may be visible from another.

When to use it: When testing the older PortalFlow-style visibility calculation or comparing the output of different VIS algorithms.

Advantages:

• Provides an alternative to passage-based visibility processing.
• Can be useful for diagnosing differences between visibility algorithms.

Disadvantages:

• May take longer than passage VIS.
• May produce a less efficient PVS, depending on the map and compiler implementation.

Recommendation: For a normal compile, do not disable passage VIS without a specific reason. Compare compile times and in-game performance if you are investigating a visibility problem.

-nosort

Purpose: Disables sorting portals by complexity before visibility calculation.

Portals vary in complexity. Sorting them can allow the compiler to process more useful or simpler visibility cases first, improving the overall calculation time.

When to use it: For testing or debugging VIS performance, particularly if you want to compare the effect of portal sorting.

Effect on compilation: The reference explicitly notes that sorting speeds up visibility calculations. Disabling sorting will therefore often make the compile slower.

Recommendation: Leave sorting enabled for normal work. -nosort is primarily useful as an experimental control rather than an optimisation.

-passageOnly

Purpose: Uses only the passage visibility algorithm.

This is the opposite of using -nopassage in terms of algorithm selection: rather than disabling passage VIS, it explicitly requests passage-only processing.

When to use it:

• Comparing passage visibility with other VIS approaches.
• Investigating the effect of the passage algorithm on compilation time.
• Testing how a specific map behaves under a different visibility strategy.

Caution: The switch should not automatically be interpreted as a guarantee of faster or better results. Its behaviour depends on the compiler version and map complexity.

-saveprt

Purpose: Prevents Q3Map2 from automatically deleting the .prt portal file when VIS finishes.

The .prt file contains portal information used by the visibility stage.

When to use it:

• Inspecting portal structure after a compile.
• Keeping intermediate files for debugging.
• Investigating leaks, portal layout or visibility problems.
• Running experiments with different VIS switches without needing to regenerate the portal file immediately.

Why it is useful: It preserves an intermediate compilation artefact that is normally disposable after visibility processing.

Caution: The portal file must correspond to the relevant BSP and map geometry. If the geometry changes, an old .prt file should not be treated as valid for the new map.

-v

Purpose: Enables verbose output during VIS compilation.

Verbose output is useful for tracking the progress of visibility calculations and diagnosing problems with a long-running compile.

When to use it: Almost always during development and production compilation.

Recommendation: Keep -v enabled. It is especially useful when comparing different VIS settings, since compile times and the compiler's reported progress can help reveal whether a change is beneficial.

Light phase - lighting calculations

The Light phase calculates the map's lighting data. Depending on the target engine and compile settings, this can include lightmaps, vertex lighting, lightgrid information, shadows, radiosity and ambient occlusion.

Lighting switches are particularly important because they influence both visual quality and compile time. Some are designed for final-quality lighting, while others reduce computation for rapid testing.

The Wikibooks Light reference documents 47 minor switches.

Light intensity and radiosity

-areascale <N.N>

Purpose: Scales area lights defined through shaders by the specified factor.

-light -areascale 0.25

This makes area lights 25% as bright as they would be at a scale of 1.0, according to the reference.

When to use it: When area lights are too bright or when you need to adjust the overall contribution of shader-based light sources without rewriting every individual shader.

Important distinction: This controls area lights, not necessarily all light sources in the map. For point lights and all light sources generally, see -pointscale and -scale.

-bounce <N>

Purpose: Enables radiosity and calculates bounced light through N bounces.

Radiosity approximates indirect illumination. Light emitted by a source illuminates a surface, and that surface can contribute reflected light to other surfaces.

-light -bounce 8

requests up to eight radiosity bounces in the documented workflow.

When to use it: When you want indirect illumination, such as coloured light reflected from a red wall onto a nearby surface.

Advantages:

• More natural indirect lighting.
• Greater colour bleeding between surfaces.
• Better illumination in areas where direct light does not reach.

Disadvantages:

• Longer compile times.
• Potentially more complex interactions between light sources and geometry.
• Diminishing visual returns from additional bounces in some maps.

Recommendation: Start with a small number of bounces, inspect the result, and increase the count only when additional indirect illumination materially improves the scene.

-bouncegrid

Purpose: Allows bounced light to affect the lightgrid.

The lightgrid stores lighting samples used for dynamic entities and models in engines that support the relevant Quake III-style lighting system.

When to use it: When indirect illumination should affect entities and models sampled through the lightgrid, rather than being restricted to the surfaces receiving baked lighting.

Caution: Support and the resulting behaviour depend on the target engine and its lighting implementation.

-bouncescale <N.N>

Purpose: Scales radiosity light by the specified factor.

This is different from changing the number of bounces. -bounce determines how many bounce iterations are calculated, while -bouncescale changes the intensity of the bounced light.

When to use it: When the indirect lighting is too weak or too strong but the number of bounces is already suitable.

Practical advice: Adjust this alongside the direct lighting settings carefully. Excessive bounced light can flatten contrast and wash out areas that should remain darker.

-cheap

Purpose: Stops calculating additional light contributions for a sample once it exceeds the RGB value (255, 255, 255).

This is a performance-oriented lighting option.

When to use it: When testing lighting on maps where samples are unlikely to benefit significantly from further light accumulation.

Caution: The reference warns that it can produce odd artefacts in maps with highly saturated coloured lighting. It also advises against using it with radiosity when you want to preserve all emitted light.

For a final compile with strong coloured illumination or radiosity, compare the output against a compile without -cheap.

-cheapgrid

Purpose: Applies the same general early-stopping principle as -cheap, but only to the lightgrid.

When to use it: When you want to reduce the cost of lightgrid calculations without applying the same restriction to surface lighting.

Difference from -cheap: -cheap affects light-sample calculations generally; -cheapgrid is restricted to the lightgrid.

Caution: Dynamic entities and models may be affected even if the static world lightmaps look acceptable. Inspect both.

-compensate <N.N>

Purpose: Scales lightmap values back to account for overbrightening when -gamma is used.

The Wikibooks reference suggests a value of 4 as a useful starting point for Quake III: Arena, while noting that experimentation may be required.

When to use it: When using gamma adjustment and needing to balance the resulting lightmap brightness with the target game's renderer.

-light -gamma 2 -compensate 4

Important: The appropriate value depends on the engine's overbright settings and the rest of the lighting configuration. It should not be treated as a universally correct value for every game based on the Quake III engine.

-cpma

Purpose: Enables full vertex lighting, including occlusion, on all surfaces, including surfaces that use lightmaps.

The switch is associated with CPMA-style lighting behaviour.

When to use it: When compiling for a compatible game or mod that requires this particular vertex-lighting approach.

Caution: The reference warns that it causes incorrect handling of -approx in Quake III: Arena, even with special shaders. Do not combine these options without checking the behaviour of your target build.

Lightmap seams and debugging

-dark

Purpose: Darkens lightmaps at brush and lightmap seams.

The reference describes this as a subtle effect resembling a rudimentary occlusion pass.

When to use it: When experimenting with additional darkening around joins between surfaces.

Potential benefit: Can emphasise seams and make some surface intersections appear more grounded.

Caution: It is not a substitute for proper ambient occlusion or correct geometry. Excessive or unwanted darkening can make seams look dirty.

-debug

Purpose: Enables lightmap debugging.

This is a general debugging switch, rather than a specific lighting-quality control.

When to use it: When investigating lightmap generation or diagnosing unusual lighting output.

Caution: The reference does not specify a single diagnostic visualisation for every Q3Map2 version. Consult the compiler output and the behaviour of the particular build.

-debugaxis

Purpose: Colours lightmaps according to their projection axis.

This is useful for examining how surfaces are projected into lightmap space.

When to use it:

• Investigating lightmap layout.
• Comparing how differently oriented surfaces are mapped.
• Diagnosing unexpected lightmap projection behaviour.

Caution: The resulting colours are diagnostic. They are not intended to represent the actual lighting in the final map.

-debugcluster

Purpose: Colours lightmaps according to the PVS cluster into which each luxel falls.

A luxel is a lightmap element, analogous to a pixel in a texture but used for baked lighting.

When to use it: When investigating relationships between lightmap samples and visibility clusters.

Potential benefit: Can help reveal how lightmap samples relate to the compiled spatial partitioning.

Caution: This is a specialised diagnostic setting; the colour information is not final lighting.

-debugorigin

Purpose: Colours lightmaps based on the origin of each luxel relative to the raw lightmap's bounding box.

When to use it: When diagnosing lightmap generation, placement or coordinate-related issues.

What it helps with: It provides a visual indication of where samples lie in relation to the raw lightmap's bounds.

Caution: It is not an ordinary lightmap quality option and should be used for diagnosis rather than final output.

-debugunused

Purpose: Colours unused luxels hot pink.

When to use it: When inspecting lightmap packing and identifying unused portions of the lightmap data.

Why it matters: Unused lightmap elements can be relevant when investigating packing efficiency or unexpected lightmap allocation.

Caution: Hot pink is a diagnostic indicator, not a lighting colour to be preserved in the final compile.

-border

Purpose: Creates a debugging border around every lightmap.

When to use it: When inspecting lightmap boundaries and packing.

Potential benefit: Makes the division between lightmaps easier to identify during inspection.

Caution: It is a debugging aid, not a way to improve the resolution or quality of baked lighting.

-normalmap

Purpose: Colours lightmaps according to the directions faced by their vertex normals.

This is a diagnostic view of surface orientation.

When to use it: When investigating shading problems, surface normals or unexpected lighting transitions.

Caution: Do not confuse this switch with generating a conventional tangent-space normal map texture. The documented function is to colour lightmaps based on vertex-normal orientation.

Directional lighting and ambient occlusion

-deluxe

Purpose: Generates deluxemaps for directional light attenuation.

A deluxemap stores directional information alongside lighting data, allowing a compatible renderer to account for the direction from which light reaches a surface.

When to use it: When targeting an engine that supports deluxemaps. The Wikibooks reference names DarkPlaces, QFusion and XreaL as examples.

Caution: Generating the data does not make an unsupported engine use it. Confirm compatibility with the target engine and its renderer.

-dirty

Purpose: Enables ambient occlusion, also called dirtmapping.

Ambient occlusion approximates the reduction of ambient illumination in places where geometry blocks or restricts the surrounding environment's contribution to a surface.

It tends to darken:

• Corners and recesses.
• Narrow cracks.
• Areas where walls meet floors.
• Tight spaces around intersecting geometry.

When to use it: When you want more depth and contact shading than direct light and radiosity alone provide.

Potential benefit: Helps give a scene a more grounded appearance by distinguishing open surfaces from enclosed corners.

Caution: Excessive dirtmapping can make a map look artificially dirty or overly dark. It should complement the lighting rather than replace proper light placement.

-dirtdepth <N>

Purpose: Sets the maximum depth of the occlusion check used with -dirty.

The Wikibooks reference gives a default of 128 game units.

When to use it: When adjusting how far the ambient-occlusion calculation considers surrounding geometry.

General interpretation:

• A smaller depth restricts the calculation to nearer geometry.
• A larger depth allows more distant surrounding geometry to contribute to the occlusion calculation.

The visual effect depends on the map's geometry and the implementation.

Caution: This option is meaningful in conjunction with -dirty; it is not a general-purpose shadow-distance setting for all light sources.

-dirtmode <N>

Purpose: Selects the mode used to calculate dirtmapping. It is intended for use with -dirty.

The reference identifies mode 0 as the default.

When to use it: When choosing between smoother ambient occlusion and a more irregular effect.

Caution: The noisy mode is not inherently more realistic. Compare the result in context, particularly around floors, walls and small decorative geometry.

-dirtscale <N.N>

Purpose: Scales the darkness of the dirtmapping effect.

This option is used with -dirty.

When to use it: When the occlusion pattern is useful but its strength needs adjustment.

Practical advice: Start with conservative values. Strong ambient occlusion can obscure detail and compete with the actual light sources.

-dump

Purpose: Dumps radiosity lights into numbered prefabs.

When to use it: When investigating the results of a radiosity calculation or examining the light sources generated by the radiosity process.

Potential benefit: Provides a way to inspect the generated lighting elements separately.

Caution: The reference does not document the complete prefab naming or export workflow. Check the output of your particular Q3Map2 build before using the result in an automated process.

Compile speed and light calculation methods

-fast

Purpose: Enables light envelopes for area lights, including radiosity lights.

The reference explains that this can make lighting compiles much faster, but it darkens enveloped light sources considerably. Increasing shader surfacelight values may compensate for the change.

When to use it: For practical production lighting where compile time matters but you still want useful lighting quality.

Important: In Q3Map2, -fast is not necessarily a crude preview mode. The Wikibooks reference explicitly states that it can be suitable for final compiles.

Caution: Re-tune the area-light intensity after enabling it. A faster calculation may change the brightness of your area lights, so identical lighting settings do not necessarily produce identical output.

-fastbounce

Purpose: Applies fast-style calculations only to radiosity lights.

When to use it: When you want to accelerate the bounced-light portion of a compile while leaving other lighting calculations on their usual settings.

Difference from -fast: -fast affects area-light calculations more broadly, including radiosity lights; -fastbounce is specifically limited to the radiosity-light calculation path.

Caution: Compare the indirect lighting against a full-quality radiosity compile, especially where bounced colour is an important part of the scene.

-faster

Purpose: Enables the faster, lower-quality light calculation mode.

The reference characterises it as a debug or testing mode that produces poor results quickly. It recommends -fast for normal or final compiles.

When to use it: When you need a very quick preview and do not care about final lighting quality.

Avoid it for: Final map releases, quality comparisons or evaluating subtle lighting effects.

-fastgrid

Purpose: Enables fast-style calculations only for the lightgrid.

When to use it: When the lightgrid is taking a significant amount of compile time and you want to speed up that part of the process.

Difference from -fastbounce: -fastgrid targets the lightgrid, whereas -fastbounce targets radiosity-light calculations.

Caution: Check dynamic entities and models in-game, because changes to the lightgrid may not be apparent when inspecting only the static world.

-filter

Purpose: Applies a Gaussian blur to lightmaps, smoothing shadow transitions.

When to use it: For controlled experiments involving blurred lightmaps.

Caution: The Wikibooks reference warns that it can interact poorly with other lighting effects and recommends -samples instead. For most normal workflows, test multisampling first if your goal is smoother shadow edges.

-lomem

Purpose: Trades longer compile time for lower memory usage.

The reference recommends trying it when Q3Map2 encounters safe_malloc errors or runs out of RAM.

When to use it: On maps that consume substantial memory during lighting or on systems with limited available RAM.

Trade-off: A compile may take longer, but it may be able to finish with less memory pressure.

Caution: It does not necessarily reduce the final BSP's file size or improve the game's runtime memory usage. Its documented purpose is to reduce the memory required during compilation.

Gamma, lightmap size and lightmap allocation

-gamma <N.N>

Purpose: Adjusts the lightmap colour ramp to provide a more realistic transition between light and dark.

The reference suggests values in the region of 1.4–2.2 as a starting range.

When to use it: When tuning the relationship between dark areas and illuminated areas in the baked lighting.

Important interaction: Quake III: Arena and other games with overbright rendering settings may require those settings to be disabled or appropriately balanced with -compensate.

Caution: Gamma adjustment is not a substitute for fixing poor light placement. It changes the tonal response of the baked lightmaps rather than physically correcting the lighting setup.

-lightmapsize <N>

Purpose: Limits the lightmap size. The documented default is 128.

When to use it: When managing lightmap dimensions and compatibility with the target renderer.

General trade-off: Smaller lightmaps may reduce the amount of lightmap data required per allocation but can constrain how much detail fits in each lightmap. The actual effect depends on surface layout, packing and compiler behaviour.

Caution: Do not confuse this with -samplesize. -lightmapsize sets a lightmap dimension limit; -samplesize controls the sampling density used when generating lightmaps.

-approx <N>

Purpose: Approximates lightmaps within a specified byte tolerance. The documented range is 0–255, with 0 as the default, meaning no approximation.

The reference explains that simple surfaces with little shadow detail can be made vertex-lit instead of requiring lightmaps, saving lightmap resources.

When to use it: When reducing lightmap usage on surfaces that do not need detailed baked shadows.

General trade-off:

• Higher tolerance allows more approximation.
• Lower tolerance preserves more of the original lightmap detail.
• 0 disables this approximation behaviour.

Caution: Vertex lighting and lightmapping can produce different visual results. Check surfaces with fine shadows, sharp light transitions or small geometric features carefully.

-nocollapse

Purpose: Disables the collapsing of identical lightmaps.

When to use it: When working with Q3Map2 lightstyles, for which the reference says this switch is required.

Lightmap collapsing normally allows identical lightmaps to be shared or consolidated rather than retaining duplicate data.

Trade-off: Disabling the optimisation can increase lightmap storage requirements.

Caution: This is a specialised functional switch, not a general-purpose quality improvement. Use it when the lighting workflow requires distinct lightmaps to remain separate.

Lightgrid and surface shadowing

-nogrid

Purpose: Disables calculation of the lightgrid.

When to use it: When a particular workflow deliberately does not need lightgrid data, or when isolating lightmap-related compile behaviour.

Potential benefit: Reduces work associated with generating the lightgrid.

Caution: In an engine that uses the lightgrid to light dynamic entities or models, disabling it may result in missing or incorrect lighting for those objects. It should not be used indiscriminately in a playable map.

-nosurf

Purpose: Disables surface tracing of detail brushes and patch meshes for shadow casting.

When to use it: When testing the contribution of detail brushes and patch meshes to shadows, or when you need to isolate shadow-tracing behaviour.

Consequences: Shadows that depend on the excluded surface tracing may be missing or differ from the normal compile.

Caution: This is not equivalent to -notrace, which disables light tracing more generally. -nosurf specifically targets surface tracing for detail brushes and patch meshes.

-notrace

Purpose: Disables light tracing. The reference states that, as a result, no shadows will be cast.

When to use it: For specialised previews where shadow computation is unnecessary, or for investigating whether an issue originates in shadow tracing.

Consequences: The resulting lighting will lack the shadows normally produced by light tracing.

Recommendation: Do not use it for a final compile where normal shadowing is required.

-novertex

Purpose: Disables calculation of vertex lighting.

When to use it: When the workflow deliberately excludes vertex-lighting data or when testing a lighting issue involving the vertex-lighting path.

Caution: This may affect dynamic models or other objects that depend on vertex lighting. It does not simply disable all lighting in the map.

-patchshadows

Purpose: Enables patch meshes to cast shadows.

Patch meshes are commonly used for curved architectural surfaces, pipes, arches and similar geometry.

When to use it: When patches should contribute to the map's shadowing, particularly in areas where curved geometry needs to cast a visible shadow.

Caution: Patch-shadow support can increase the work required during lighting compilation. Inspect the result to ensure the shadows match your intended geometry and lighting.

Point lights, general intensity and sun lighting

-pointscale <N.N>

Purpose: Scales point (entity) lights by the specified factor.

When to use it: When you need to adjust the intensity of point lights globally without modifying each light entity individually.

Difference from other intensity switches:

• -pointscale adjusts point lights.
• -areascale adjusts area lights.
• -sky adjusts sun and sky lights.
• -scale adjusts all light sources generally.

Caution: Global scaling can alter the balance between different types of lighting. Recheck rooms and areas that were tuned around particular point-light intensities.

-scale <N.N>

Purpose: Scales up all light sources by the specified factor.

When to use it: When the overall lighting intensity needs to be adjusted without changing every individual light.

-light -scale 1.5

This requests a global intensity scale of 1.5, subject to the particular compiler's implementation.

Caution: Scaling everything can also change the balance between direct and indirect illumination. It should not be used as a substitute for correcting individual lighting problems.

-sky <N.N>

Purpose: Scales sun and sky light sources by the specified factor.

When to use it: When tuning the brightness of outdoor illumination or the contribution of sky shaders that emit light.

-light -sky 3

The reference notes that a sky scale of 3 can help older-style sky shaders work in conjunction with newer gamma and compensation settings.

Caution: This affects sky or sun illumination, not all the other lights in the scene. The result depends on the target game's sky shader and light settings.

-sunonly

Purpose: Calculates sun and sky lighting only, excluding other light sources.

When to use it:

• Previewing outdoor lighting.
• Testing the direction and strength of sunlight.
• Isolating sky-lighting problems.
• Comparing the effect of natural illumination before adding interior or artificial lights.

Caution: The output is not a normal full-lighting compile if the map relies on point lights, area lights or other sources.

Sampling and shadow-edge quality

-samples <N>

Purpose: Enables intelligent antialiasing of shadow edges in lightmaps.

The reference suggests:

• 2 as a good balance of visual quality and compile speed.
• 3 for improved results at the cost of a slower compile.

When to use it: When you want smoother shadow edges and fewer jagged transitions.

Practical advice: Start with -samples 2, then compare with -samples 3 if shadow quality needs improvement.

Caution: Increasing the sample count can increase compile time. The benefit depends on the map's geometry and shadow complexity.

-samplesize <N>

Purpose: Controls the lightmap sampling size through the .srf surface file.

Important build requirement: The .srf file is generated during BSP compilation. Therefore, the reference says -samplesize must be supplied to both the BSP and Light phases for the setting to take effect.

q3map2 -bsp -meta -samplesize 8 mapname.map
q3map2 -light -samplesize 8 mapname.map

Caution: A smaller samplesize value is not automatically better. Excessively fine lightmap sampling can increase file size, compilation time and the risk of visual artefacts.

-super <N>

Purpose: Enables arbitrarily ordered grid supersampling of lightmaps.

The reference warns that it is much slower than -samples.

When to use it: For specialised high-quality sampling experiments where ordinary antialiasing is insufficient.

Caution: Because the method is computationally expensive, test it on a small map or limited workflow before committing to a full compile.

-thresh <N.N>

Purpose: Sets the recursive triangle subdivision threshold. The documented range is 0.0–1.0.

The compiler recursively subdivides triangles when determining luxel normals for phong shading and bumpmapping. The reference explains that the threshold is related to the product of the threshold value and the samplesize. Lower thresholds result in smaller triangles and more samples per luxel, improving normal accuracy and potentially producing smoother shading.

When to use it: When you need more accurate phong shading or bumpmapping and are willing to accept the additional calculation.

General trade-off:

• Lower values produce finer subdivision and potentially smoother shading.
• Higher values allow larger triangles and reduce subdivision work.

Caution: The ideal value depends on geometry, samplesize and the target implementation. Do not lower it indiscriminately without comparing the resulting lighting.

Phong shading

-shade

Purpose: Enables phong shading.

Phong shading smooths the lighting across adjoining surfaces by using interpolated surface normals rather than treating every face as having a completely independent flat shading normal.

When to use it: When smooth transitions between adjacent surfaces are desirable, particularly for curved or rounded geometry.

Potential benefit: Helps curved surfaces and suitably constructed brushwork appear smoother under lighting.

Caution: Phong shading affects the shading treatment, not the underlying collision geometry. It can also produce unexpected results on surfaces that are intended to have crisp edges.

For more accurate phong shading, consider how -thresh and -samplesize interact with the geometry.

Additional lighting output and final diagnostics

-v

Purpose: Enables verbose output for the Light phase.

When to use it: Almost always. Verbose output makes it easier to monitor a long lighting compile and investigate errors or unexpected behaviour.

Recommendation: Keep it enabled while developing the map, particularly when experimenting with radiosity, ambient occlusion or lightmap sampling.