Tune lightmap resolution without bloating a BSP

A lightmap stores baked lighting on a surface. Its samples are often called luxels. A smaller sample size gives the compiler more luxels to describe a narrow shadow, but can add whole lightmap atlas pages to the BSP. In this exercise we compile the same test room three ways and measure the result: a 16-unit baseline, 8-unit detail on two chosen floor plates, and 8-unit sampling everywhere.

1. Know what the number controls

For this Q3Map2 workflow, -samplesize 16 asks for roughly one lightmap sample every 16 map units; -samplesize 8 asks for roughly one every 8 units. Halving the spacing can demand about four times as many luxels on a large two-dimensional surface. Actual BSP growth comes in atlas pages and depends on padding, packing, material groups, compiler limits, and which faces are lightmapped. It is not a fixed 4× multiplier.

The archived Lightmap page describes several defaults and external-map sizes as if they were universal. They vary by game profile, compiler build, and compile flags. State your own -samplesize and measure the output you ship.

2. Compile a baseline and a global high-detail version

Use a Q3-format .map and a Q3Map2 build with the darkplaces game profile. The example used the Q3Map2 2.5.17n build bundled in the supplied QuakeTest workspace. Make two copies of your map, lightmap_16.map and lightmap_8.map, so each output keeps its own BSP. From the compiler directory, run the three stages for each copy:

Add your own -fs_basepath and -fs_basegame when the compiler must locate game textures and shader scripts outside its default paths. In the test, both stages receive the sample size explicitly so a changed default cannot affect the comparison. The -fast VIS and -faster lighting flags keep this small experiment quick; use the quality settings appropriate for a release build.

3. Measure the cost, then target the detail

The test map is a sealed 1024×1024-unit room with 16 separated raised plates, one narrow pillar, one light, and 91 BSP faces. All three variants use the same geometry and FTEQW view. The selective version starts from 16-unit sampling but gives just two shadow-receiving plates an 8-unit material:

Assign tutorial/highres_floor only to the faces that need a crisp contact shadow. The image path above matches the test workspace; replace it with a texture in your own mod. The compiler directive changes the lightmap sampling for faces using this shader. The runtime stages keep the same floor appearance and apply its baked lightmap.

In this map, targeted detail kept the lightmap at two 128×128 RGB pages and increased the BSP by just 72 bytes. Global 8-unit sampling needed two more pages and increased the BSP by 98,304 bytes. These are measured outputs from this build, not guarantees for another map. One 128×128 RGB page occupies 49,152 bytes in the Q3 BSP lightmap lump.

4. Inspect the result in an engine

Load each BSP in DarkPlaces or FTEQW and compare from the same camera position with the same renderer settings. Here are the two global builds from FTEQW. The changes in shadow boundaries are subtle at this camera distance; the measured atlas count is the clearer cost signal.

For a clean comparison, record the exact Q3Map2 build and flags, then inspect the BSP header's lightmap lump or the compiler's “BSP lightmaps” line. A dark line caused by geometry, texture seams, or light placement will not be fixed by adding luxels. Move the light or repair the surface first.

Other controls: entity scale, external maps, deluxemaps

_lightmapscale is an entity-level alternative for a group of brush faces. In toolchains that support it, a func_group with _lightmapscale 0.5 halves the effective sample spacing, while 2 makes it coarser. It multiplies the shader or default sample size, so do not stack it with an 8-unit shader unless you intend still finer sampling. The measured selective build above used q3map_lightmapsamplesize, not this entity key.

-external moves generated lightmap images outside the BSP when supported by the selected game profile. That can reduce the BSP file, but the external files still need to be distributed and loaded. Compare BSP + external image files as one asset budget. Do not use it just to claim a smaller BSP.

-deluxe -deluxemode 0 requests model-space deluxemaps for DarkPlaces-compatible directional lighting. Deluxemaps add light-direction data; they are separate from choosing a finer luxel grid and cost storage and runtime memory. Add them only when your material lighting benefits and your target engine supports the output. Neither external pages nor deluxemaps were enabled in the measured table.

Sources

The exercise was rewritten from the archived Lightmap notes and checked against NetRadiant Q3Map2 command help, the GtkRadiant explanation of _lightmapscale, and the supplied compiler's actual output. The screenshots and measurements come from the local QuakeTest map, not from an existing article image.