light#

light - Caclulate lightmap data for a Quake BSP file

Synopsis#

light [OPTION]… BSPFILE

Description#

light reads a Quake .bsp file and calculates light and shadow information based on the entity definitions contained in the .bsp. The .bsp file is updated with the new light data upon completion, overwriting any existing lighting data.

Options#

Note, any of the Worldspawn Keys listed in the next section can be supplied as command-line options, which will override any setting in worldspawn.

Logging#

-log#: Write log files. Enabled by default.

-nolog#: Don’t write log files.

-verbose#
-v#: Verbose output.

-nopercent#: Don’t output percentage messages.

-nostat#: Don’t output statistic messages.

-noprogress#: Don’t output progress messages.

-nocolor#: Don’t output color codes (for TB, etc).

-quiet#
-noverbose#: Suppress non-important messages (equivalent to -nopercent -nostat -noprogress)

Game#

-gamedir "relative/path" or "C:/absolute/path"#: Override the default mod base directory. if this is not set, or if it is relative, it will be derived from the input file or the basedir if specified.

-basedir "relative/path" or "C:/absolute/path"#: Override the default game base directory. if this is not set, or if it is relative, it will be derived from the input file or the gamedir if specified.

-filepriority archive | loose#: Which types of archives (folders/loose files or packed archives) are higher priority and chosen first for path searching.

-path "/path/to/folder" <multiple allowed>#: Additional paths or archives to add to the search path, mostly for loose files.

-q2rtx#: Adjust settings to best support Q2RTX.

-defaultpaths#: Whether the compiler should attempt to automatically derive game/base paths for games that support it. Enabled by default.

-nodefaultpaths#: Opt out of -defaultpaths.

Performance#

-lowpriority [0]#: Run in a lower priority, to free up headroom for other processes.

-threads n#: Set number of threads explicitly. By default light will attempt to detect the number of CPUs/cores available.

-extra#: Calculate extra samples (2x2) and average the results for smoother shadows.

-extra4#: Calculate even more samples (4x4) and average the results for smoother shadows.

-gate n#: Set a minimum light level, below which can be considered zero brightness. This can dramatically speed up processing when there are large numbers of lights with inverse or inverse square falloff. In most cases, values less than 1.0 will cause no discernible visual differences. Default 0.001.

-sunsamples [n]#: Set the number of samples to use for _sunlight_penumbra and _sunlight2 (sunlight2 may use more or less because of how the suns are set up in a sphere). Default 100.

-surflight_subdivide [n]#: Configure spacing of all surface lights. Default 16 units. Value must be between 1 and 8192. In the future I’d like to make this configurable per-surface-light.

-emissivequality low | high#: For emissive surfaces (both direct light and bounced light), use a single point in the middle of the face (low) or subdivide the face into multiple points, which provides anti-aliased results and more shadows, at the cost of compile time. When using “high”, you can use surflight_subdivide to control the point spacing for better anti-aliasing. Default is low.

Output format options#

-lit#: Force generation of a .lit file, even if your map does not have any coloured lights. By default, light will automatically generate the .lit file when needed.

-world_units_per_luxel n#: Enables output of DECOUPLED_LM BSPX lump.

-onlyents#: Updates the entities lump in the bsp. You should run this after running qbsp with -onlyents, if your map uses any switchable lights. All this does is assign style numbers to each switchable light.

-litonly#: Generate a .lit file that is compatible with the .bsp without modifying the .bsp. This is meant for tweaking lighting or adding colored lights when you can’t modify an existing .bsp (e.g. for multiplayer maps.) Typically you would make a temporary copy of the .bsp, update the lights in the entity lump (e.g. with “qbsp -onlyents”), then re-light it with “light -litonly”. Engines may enforce a restriction that you can’t make areas brighter than they originally were (cheat protection). Also, styled lights (flickering/switchable) can’t be added in new areas or have their styles changed.

-nolighting#: Do all of the stuff required for lighting to work without actually performing any lighting calculations. This is mainly for engines that don’t use the light data, but still need switchable lights, etc.

-nolights#: Ignore light entities (only sunlight/minlight).

-facestyles n#: Max amount of styles per face; requires BSPX lump if > 4.

-exportobj#: Export an .OBJ for inspection.

-lmshift n#: Force a specified lmshift to be applied to the entire map; this is useful if you want to re-light a map with higher quality BSPX lighting without the sources. Will add the LMSHIFT lump to the BSP.

Postprocessing options#

-soft [n]#: Perform post-processing on the lightmap which averages adjacent samples to smooth shadow edges. If n is specified, the algorithm will take ‘n’ samples on each side of the sample point and replace the original value with the average. e.g. a value of 1 results in averaging a 3x3 square centred on the original sample. 2 implies a 5x5 square and so on. If -soft is specified, but n is omitted, a value will be the level of oversampling requested. If no oversampling, then the implied value is 1. -extra implies a value of 2 and -extra4 implies 3. Default 0 (off).

Debug modes#

-dirtdebug#: Implies _dirt “1”, and renders just the dirtmap against a fullbright background, ignoring all lights in the map. Useful for previewing and turning the dirt settings.

-phongdebug#: Write normals to lit file for debugging phong shading.

-bouncedebug#: Write bounced lighting only to the lightmap for debugging / previewing -bounce.

-bouncelightsdebug#: Only save bounced emitters lighting to the lightmap.

-surflight_dump#: Saves the lights generated by surfacelights to a “mapname-surflights.map” file.

-visapprox auto | none | rays | vis#

Change approximate visibility algorithm.

auto: choose default based on format
vis: use BSP vis data (slow but precise).
rays: use sphere culling with fired rays (fast but may miss faces).
none: Disable approximate visibility culling of lights, which has a small chance of introducing artifacts where lights cut off too soon.

-novisapprox#: Alias for -visapprox none

-phongdebug_obj#: Save map as .obj with phonged normals.

-debugoccluded#: Save luxel occlusion data to lightmap.

-debugneighbours#: Save neighboring faces data to lightmap (requires -debugface).

-debugmottle#: Save mottle pattern (used by Q2 minlight, when opted in with _minlight_mottle) to lightmap.

-debugface x y z#

-debugvert x y z#

-highlightseams#

Experimental options#

-addmin#: Changes the behaviour of minlight. Instead of increasing low light levels to the global minimum, add the global minimum light level to all style 0 lightmaps. This may help reducing the sometimes uniform minlight effect.

-lit2#: Force generation of a .lit2 file, even if your map does not have any coloured lights.

-lux#: Generate a .lux file storing average incoming light directions for surfaces. Usable by FTEQW with “r_deluxemapping 1”.

-bspxlux#: Writes lux data into the bsp itself.

-lmscale n#: Equivalent to “_lightmap_scale” worldspawn key.

-bspxlit#: Writes rgb data into the bsp itself.

-bspx#: Writes both rgb and directions data into the bsp itself.

-bspxonly#: Writes both rgb and directions data only into the bsp itself.

-novanilla#: Fallback scaled lighting will be omitted. Standard grey lighting will be omitted if there are coloured lights. Implies -bspxlit. -lit will no longer be implied by the presence of coloured lights.

-wrnormals#: Writes normal data into the bsp itself.

-arghradcompat#: Enable compatibility for Arghrad-specific keys.

-radlights "filename.rad"#: Loads a <surfacename> <r> <g> <b> <intensity> file.

-lightgrid#: Generates a lightgrid and writes it to a bspx lump (LIGHTGRID_OCTREE).

-lightgrid_dist x y z#: Distance between lightgrid sample points, in world units. Controls lightgrid size.

-lightgrid_format octree#: Lightgrid BSPX lump to use. Currently there is only one supported format, octree.

Model Entity Keys#

Worldspawn Keys#

The following keys can be added to the worldspawn entity:

"light" "n"#
"_minlight" "n"#: Set a global minimum light level of “n” across the whole map. This is an easy way to eliminate completely dark areas of the level, however you may lose some contrast as a result, so use with care. Default 0.

Note

In Q2 mode, minlight uses a 0..1 range.

"_minlight_color" "r g b"#
"_mincolor" "r g b"#: Specify red(r), green(g) and blue(b) components for the colour of the minlight. RGB component values are between 0 and 255 (between 0 and 1 is also accepted). Default is white light (“255 255 255”).

"_maxlight" "n"#

"_dist" "n"#: Scales the fade distance of all lights by a factor of n. If n > 1 lights fade more quickly with distance and if n < 1, lights fade more slowly with distance and light reaches further.

"_range" "n"#: Scales the brightness range of all lights without affecting their fade discance. Values of n > 0.5 makes lights brighter and n < 0.5 makes lights less bright. The same effect can be achieved on individual lights by adjusting both the “light” and “wait” attributes.

"_sunlight" "n"#
"_sun_light" "n"#: Set the brightness of the sunlight coming from an unseen sun in the sky. Sky brushes (or more accurately bsp leafs with sky contents) will emit sunlight at an angle specified by the “_sun_mangle” key. Default 0.

"_anglescale" "n"#
"_anglesense" "n"#: Set the scaling of sunlight brightness due to the angle of incidence with a surface (more detailed explanation in the “_anglescale” light entity key below).

"_sunlight_mangle" "yaw pitch roll"#
"_sun_mangle" "yaw pitch roll"#
"_sun_angle" "yaw pitch roll"#: Specifies the direction of sunlight using yaw, pitch and roll in degrees. Yaw specifies the angle around the Z-axis from 0 to 359 degrees and pitch specifies the angle from 90 (shining straight up) to -90 (shining straight down from above). Roll has no effect, so use any value (e.g. 0). Default is straight down (“0 -90 0”).

"_sun2" "n"#

"_sun2_color" "x y z"#

"_sun2_mangle" "x y z"#

"_sunlight_penumbra" "n"#: Specifies the penumbra width, in degrees, of sunlight. Useful values are 3-4 for a gentle soft edge, or 10-20+ for more diffuse sunlight. Default is 0.

"_sunlight_color" "r g b"#
"_sun_color" "r g b"#: Specify red(r), green(g) and blue(b) components for the colour of the sunlight. RGB component values are between 0 and 255 (between 0 and 1 is also accepted). Default is white light (“255 255 255”).

"_sunlight2" "n"#: Set the brightness of a dome of lights arranged around the upper hemisphere. (i.e. ambient light, coming from above the horizon). Default 0.

"_sunlight_color2" "r g b"#
"_sunlight2_color" "r g b"#: Specifies the colour of _sunlight2, same format as “_sunlight_color”. Default is white light (“255 255 255”).

"_sunlight3" "n"#: Same as “_sunlight2”, but for the bottom hemisphere (i.e. ambient light, coming from below the horizon). Combine “_sunlight2” and “_sunlight3” to have light coming equally from all directions, e.g. for levels floating in the clouds. Default 0.

"_sunlight_color3" "r g b"#
"_sunlight3_color" "r g b"#: Specifies the colour of “_sunlight3”. Default is white light (“255 255 255”).

"_dirt" "n"#
"_dirty" "n"#: 1 enables dirtmapping (ambient occlusion) on all lights, borrowed from q3map2. This adds shadows to corners and crevices. You can override the global setting for specific lights with the “_dirt” light entity key or “_sunlight_dirt”, “_sunlight2_dirt”, and “_minlight_dirt” worldspawn keys. Default is no dirtmapping (-1).

"_sunlight_dirt" "n"#: 1 enables dirtmapping (ambient occlusion) on sunlight, -1 to disable (making it illuminate the dirtmapping shadows). Default is to use the value of “_dirt”.

"_sunlight2_dirt" "n"#: 1 enables dirtmapping (ambient occlusion) on sunlight2/3, -1 to disable. Default is to use the value of “_dirt”.

"_minlight_dirt" "n"#: 1 enables dirtmapping (ambient occlusion) on minlight, -1 to disable. Default is to use the value of “_dirt”.

"_dirtmode" "n"#: Choose between ordered (0, default) and randomized (1) dirtmapping.

"_dirtdepth" "n"#: Maximum depth of occlusion checking for dirtmapping, default 128.

"_dirtscale" "n"#: Scale factor used in dirt calculations, default 1. Lower values (e.g. 0.5) make the dirt fainter, 2.0 would create much darker shadows.

"_dirtgain" "n"#: Exponent used in dirt calculation, default 1. Lower values (e.g. 0.5) make the shadows darker and stretch further away from corners.

"_dirtangle" "n"#: Cone angle in degrees for occlusion testing, default 88. Allowed range 1-90. Lower values can avoid unwanted dirt on arches, pipe interiors, etc.

"_gamma" "n"#: Adjust brightness of final lightmap. Default 1, >1 is brighter, <1 is darker.

"_lightmap_scale" "n"#: Forces all surfaces+submodels to use this specific lightmap scale. Removes “LMSHIFT” field.

"_bounce" "n"#: Non-zero enables bounce lighting, disabled by default. The value is the maximum number of bounces to perform.

"_bouncescale" "n"#: Scales brightness of bounce lighting, default 1.

"_bouncecolorscale" "n"#: Weight for bounce lighting to use texture colors from the map: 0=ignore map textures (default), 1=multiply bounce light color by texture color.

"_bouncelightsubdivision" "n"#

"_surflightscale" "n"#: Scales the surface light emission from Q2 surface lights (excluding sky faces) by this amount.

"_surflightskyscale" "n"#: Scales the surface light emission from Q2 sky faces by this amount.

"_surflightsubdivision" "n"#
"_choplight" "n"#

"_bouncestyled" "n"#: 1 allows styled lights to bounce (e.g. flickering or switchable lights). Default is 1.

"_spotlightautofalloff" "n"#: When set to 1, spotlight falloff is calculated from the distance to the targeted info_null. Ignored when “_falloff” is not 0. Default 0.

"_surflight_radiosity" "n"#: Whether to use Q1-style surface subdivision (0) or Q2-style surface radiosity.

"_sky_surface" "x y z"#
"_sun_surface" "x y z"#

"_compilerstyle_start" "n"#

"_compilerstyle_max" "n"#

"_surflight_minlight_scale" "n"#

Scale factor for automatic minlight on an emissive face, derived from the light color being emitted.

This is intended to prevent, e.g., a light fixture texture which is configured as a surface light, from being completely black.

Default 1.0, can set to 0.0 to disable minlight.

Model Entity Keys#

The following keys can be used on any entity with a brush model.

If used on func_detail* or func_group, a full qbsp pass need to be run.

"_minlight" "n"#: Set the minimum light level for any surface of the brush model. Default 0.

Note

Q2 uses a 0..1 scale for this key

"_minlight_mottle" "n"#
"_minlightMottle" "n"#: Whether minlight should have a mottled pattern. Defaults to 0.

"_minlight_exclude" "texname"#
"_minlight_exclude2" "texname"#
"_minlight_exclude3" "texname"#: Faces with the given texture are excluded from receiving minlight on this brush model.

"_minlight_color" "r g b"#
"_mincolor" "r g b"#: Specify red(r), green(g) and blue(b) components for the colour of the minlight. RGB component values are between 0 and 255 (between 0 and 1 is also accepted). Default is white light (“255 255 255”).

"_shadow" "n"#: If n is 1, this model will cast shadows on other models and itself (i.e. “_shadow” implies “_shadowself”). Note that this doesn’t magically give Quake dynamic lighting powers, so the shadows will not move if the model moves. Set to -1 on func_detail/func_group to prevent them from casting shadows. Default 0.

"_shadowself" "n"#
"_selfshadow" "n"#: If n is 1, this model will cast shadows on itself if one part of the model blocks the light from another model surface. This can be a better compromise for moving models than full shadowing. Default 0.

"_shadowworldonly" "n"#: If n is 1, this model will cast shadows on the world only (not other bmodels).

"_switchableshadow" "n"#

If n is 1, this model casts a shadow that can be switched on/off using QuakeC. To make this work, a lightstyle is automatically assigned and stored in a key called “switchshadstyle”, which the QuakeC will need to read and call the “lightstyle()” builtin with “a” or “m” to switch the shadow on or off. Entities sharing the same targetname, and with “_switchableshadow” set to 1, will share the same lightstyle.

These models are only able to block style 0 light (i.e., non-flickering or switchable lights). Flickering or switchable lights will shine through the switchable shadow casters, regardless of whether the shadow is off or on.

"_dirt" "n"#: For brush models, -1 prevents dirtmapping on the brush model. Useful if the bmodel touches or sticks into the world, and you want to prevent those areas from turning black. Default 0.

"_phong" "n"#: 1 enables phong shading on this model with a default _phong_angle of 89 (softens columns etc).

"_phong_angle" "n"#: Enables phong shading on faces of this model with a custom angle. Adjacent faces with normals this many degrees apart (or less) will be smoothed. Consider setting “_anglescale” to “1” on lights or worldspawn to make the effect of phong shading more visible. Use the “-phongdebug” command-line flag to save the interpolated normals to the lightmap for previewing (use “r_lightmap 1” or “gl_lightmaps 1” in your engine to preview.)

"_phong_angle_concave" "n"#: Optional key for setting a different angle threshold for concave joints. A pair of faces will either use “_phong_angle” or “_phong_angle_concave” as the smoothing threshold, depending on whether the joint between the faces is concave or not. “_phong_angle(_concave)” is the maximum angle (in degrees) between the face normals that will still cause the pair of faces to be smoothed. The minimum setting for “_phong_angle_concave” is 1, this should make all concave joints non-smoothed (unless they’re less than 1 degree apart, almost a flat plane.) If it’s 0 or unset, the same value as “_phong_angle” is used.

"_phong_group" "n"#

Integer specifying a “smoothing group ID” for phong shading. Default 0, faces with a _phong_group will only smooth with faces with a matching _phong_group.

Equivalent to the Q2 .map format’s “value” field.

"_lightignore" "n"#: 1 makes a model receive minlight only, ignoring all lights / sunlight. Could be useful on rotators / trains.

See also

Lighting Channels for a more powerful version of this

"_light_twosided" "n"#

Set to 1 to enable receiving light from either side.

Default is 0 execept on liquids (Q1 *, Q2 contents LAVA/SLIME/WATER), where it defaults to 1.

"_light_alpha" "n"#: Float, range 0-1. Allows customizing the opacity of this face when it’s acting as “stained glass”.

Todo

Document default, and which conditions cause a face to be “stained glass”

"_litwater" "n"#
"_splitturb" "n"#: Overrides the worldspawn/command line option qbsp -litwater for these specific brushes.

"_surflight_rescale" "n"#

Integer, 0 or 1.

If 1, rescales any surface light emitted by these brushes to emit 50% light at 90 degrees from the surface normal. Otherwise, use a more natural angle falloff of 0% at 90 degrees.

Default is 0 on sky faces, otherwise 1.

"_surflight_color" "r g b"#

Customize the emissive color of a surface light.

Default is to use the average texture color.

"_surflight_style" "n"#: Override the surface light lightstyle number for light emitted from these brushes.

"_surflight_targetname" "name"#: Override the surface light targetname for light emitted from these brushes.

"_surflight_minlight_scale" "n"#: Overrides the worldspawn setting _surflight_minlight_scale

"_bounce" "n"#: Set to -1 to prevent this model from bouncing light (i.e. prevents its brushes from emitting bounced light they receive from elsewhere.) Only has an effect if “_bounce” is enabled in worldspawn.

"_autominlight" "n"#

“Autominlight” is a feature for automatically choosing a suitable minlight color for a bmodel entity (e.g. a func_door), by averaging incoming light at the center of the bmodel bounding box.

Default behaviour is to apply autominlight on occluded luxels only (e.g., for a door that opens vertically upwards, it would apply to the bottom face of the door, which is initially pressed against the ground).

A value of “-1” disables the feature (occluded luxels will be solid black), and “1” enables it as a minlight color even on non-occluded luxels.

"_autominlight_target" "name"#: For autominlight, instead of using the center of the model bounds as the sample point, searches for an entity with its “targetname” key set to “name”, and use that entity’s origin (typically you’d use an “info_null” for this).

"_world_units_per_luxel" "n"#: When -world_units_per_luxel is in use, customizes the lightmap scale on this entity.

"_surflight_group" "n"#

Integer. Default 0.

Can be set to a nonzero value to make these brushes emit as surface lights only from a light template with a matching _surflight_group value.

"_lightcolorscale" "n"#

Saturation control as a postprocessing step on these specific faces’ lightmaps.

Default 1.0, 0.0 is fully desaturated to greyscale.

Light Entity Keys#

Light entity keys can be used in any entity with a classname starting with the first five letters “light”. E.g. “light”, “light_globe”, “light_flame_small_yellow”, etc.

Point Lights#

"light" "n"#: Set the light intensity. Negative values are also allowed and will cause the entity to subtract light cast by other entities. Default 300.

"wait" "n"#: Scale the fade distance of the light by “n”. Values of n > 1 make the light fade more quickly with distance, and values < 1 make the light fade more slowly (and thus reach further). Default 1.

"delay" "n"#

Select an attenuation formaula for the light:

0 => Linear attenuation (default)
1 => 1/x attenuation
2 => 1/(x^2) attenuation
3 => No attenuation (same brightness at any distance)
4 => "local minlight" - No attenuation and like minlight,
      it won't raise the lighting above it's light value.
      Unlike minlight, it will only affect surfaces within
      line of sight of the entity.
5 => 1/(x^2) attenuation, but slightly more attenuated and
      without the extra bright effect that "delay 2" has
      near the source.

"_falloff" "n"#

Sets the distance at which the light drops to 0, in map units.

In this mode, “wait” is ignored and “light” only controls the brightness at the center of the light, and no longer affects the falloff distance.

Only supported on linear attenuation (delay 0) lights currently.

"_color" "r g b"#: Specify red(r), green(g) and blue(b) components for the colour of the light. RGB component values are between 0 and 255 (between 0 and 1 is also accepted). Default is white light (“255 255 255”).

"targetname" "name"#: Turns the light into a switchable light, toggled by another entity targeting it’s name.

"style" "n"#: Set the animated light style. Default 0.

"_anglescale" "n"#
"_anglesense" "n"#: Sets a scaling factor for how much influence the angle of incidence of light on a surface has on the brightness of the surface. n must be between 0.0 and 1.0. Smaller values mean less attenuation, with zero meaning that angle of incidence has no effect at all on the brightness. Default 0.5.

"_dirtscale" "n"#
"_dirtgain" "n"#: Override the global “_dirtscale” or “_dirtgain” settings to change how this light is affected by dirtmapping (ambient occlusion). See descriptions of these keys in the worldspawn section.

"_dirt" "n"#: Overrides the worldspawn setting of “_dirt” for this particular light. -1 to disable dirtmapping (ambient occlusion) for this light, making it illuminate the dirtmapping shadows. 1 to enable ambient occlusion for this light. Default is to defer to the worldspawn setting.

"_deviance" "n"#: Split up the light into a sphere of randomly positioned lights within radius “n” (in world units). Useful to give shadows a wider penumbra. “_samples” specifies the number of lights in the sphere. The “light” value is automatically scaled down for most lighting formulas (except linear and non-additive minlight) to attempt to keep the brightness equal. Default is 0, do not split up lights.

"_samples" "n"#: Number of lights to use for “_deviance”. Default 16 (only used if “_deviance” is set).

"_bouncescale" "n"#: Scales the amount of light that is contributed by bounces. Default is 1.0, 0.0 disables bounce lighting for this light.

"_nostaticlight" "n"#: Set to 1 to make the light compiler ignore this entity (prevents it from casting any light). e.g. could be useful with rtlights.

Spotlights#

Supports all keys from Point Lights in addition to the following:

"target" "name"#: Turns the light into a spotlight, with the direction of light being towards another entity with it’s “targetname” key set to “name”.

"mangle" "yaw pitch roll"#: Turns the light into a spotlight and specifies the direction of light using yaw, pitch and roll in degrees. Yaw specifies the angle around the Z-axis from 0 to 359 degrees and pitch specifies the angle from 90 (straight up) to -90 (straight down). Roll has no effect, so use any value (e.g. 0). Often easier than the “target” method.

"angle" "n"#: Specifies the angle in degrees for a spotlight cone. Default 40.

"_softangle" "n"#: Specifies the angle in degrees for an inner spotlight cone (must be less than the “angle” cone. Creates a softer transition between the full brightness of the inner cone to the edge of the outer cone. Default 0 (disabled).

Surface Lights#

"_surface" "texturename"#

Makes surfaces with the given texture name emit light, by using this light as a template which is copied across those surfaces. Lights are spaced about 128 units (though possibly closer due to bsp splitting) apart and positioned 2 units above the surfaces.

To restrict this surface light config to a subset of brushes with the “texturename” texture applied, see the _surflight_group key.

"_surface_offset" "n"#: Controls the offset lights are placed above surfaces for _surface. Default 2.

"_surface_spotlight" "n"#: For a surface light template (i.e. a light with _surface set), setting this to “1” makes each instance into a spotlight, with the direction of light pointing along the surface normal. In other words, it automatically sets “mangle” on each of the generated lights.

"_surface_radiosity" "n"#

Whether to use Q1-style surface subdivision (0) or Q2-style surface radiosity (1) on this light specifically.

Use in conjunction with _surface.

The default can be changed for all surface lights in a map with worldspawn key _surflight_radiosity.

"_surflight_group" "n"#

Integer, default 0.

For use with _surface lights.

Can be set to a nonzero value to restrict this surface light template to only emit from brushes with a matching _surflight_group value.

Projected Texture Lights#

"_project_texture" "texture"#: Specifies that a light should project this texture. The texture must be used in the map somewhere.

Todo

This is a qbsp limitation which could be fixed

"_project_mangle" "yaw pitch roll"#: Specifies the yaw/pitch/roll angles for a texture projection (overriding mangle).

"_project_fov" "n"#: Specifies the fov angle for a texture projection. Default 90.

Sun Light#

Also called directional light. Emitted from sky faces.

"_sun" "n"#: Set to 1 to make this entity a sun, as an alternative to using the sunlight worldspawn keys.

"target" "t"#: If the light targets an info_null entity, the direction towards that entity sets sun direction. The light itself is disabled, so it can be placed anywhere in the map.

"mangle" "yaw pitch roll"#

Alternate way of specifying sunlight direction.

Equivalent to worldspawn key _sunlight_mangle.

"light" "n"#: Equivalent to worldspawn key _sunlight.

"_color" "r g b"#: Equivalent to worldspawn key _sunlight_color.

"deviance" "n"#: Equivalent to worldspawn key _sunlight_penumbra.

"_dirt" "n"#: Equivalent to worldspawn key _sunlight_dirt.

"_anglescale" "n"#: Equivalent to worldspawn key _anglescale.

"style" "n"#: Flicker style for styled sunlight.

"targetname" "name"#: Targetname for switchable sunlight.

"_suntexture" "texname"#: This sunlight is only emitted from faces with this texture name. Default is to be emitted from all sky textures.

Sky Light#

Hemisphere shaped light emitted from sky faces.

"_sunlight2" "n"#: Set to 1 to make this entity control the upper dome lighting emitted from sky faces, as an alternative to the worldspawn key _sunlight2. The light entity itself is disabled, so it can be placed anywhere in the map.

"_sunlight3" "n"#: Same as _sunlight2, but makes this sky light come from the lower hemisphere.

"light" "n"#: Sets the dome light brightness. Equivalent to worldspawn key _sunlight2.

"_color" "r g b"#: Sets the dome light color. Equivalent to worldspawn key _sunlight2_color.

"_dirt" "n"#: Equivalent to worldspawn key _sunlight2_dirt.

"_anglescale" "n"#: Equivalent to worldspawn key _anglescale.

"style" "n"#: Flicker style for styled sky light.

"targetname" "name"#: Targetname for switchable skylight.

"_suntexture" "texname"#: This sky light is only emitted from faces with this texture name. Default is to be emitted from all sky textures.

Lighting Channels#

Lighting channels allow custom lighting setups where certain light entities only affect certain bmodels. Useful for lighting rotators, doors, etc.

Note

Currently, bounced light, surface lights, and sunlight are always on channel 1.

Light Keys#

"_light_channel_mask" "n"#

Mask of lighting channels that the light casts on.

In order for this light to cast light on a bmodel, there needs to be a least 1 bit in common between _light_channel_mask and the receiving bmodel’s _object_channel_mask (i.e. the bitwise AND must be nonzero).

Default 1.

"_shadow_channel_mask" "n"#

This is the mask of lighting channels that will block this entity’s light rays. If the the bitwise AND of this and another bmodel’s _object_channel_mask is nonzero, the light ray is stopped.

This is an advanced option, for making bmodels only cast shadows for specific lights (but not others).

Defaults to _light_channel_mask

Model Keys#

"_object_channel_mask" "n"#

Mask of lighting channels that this bmodel receives light on, blocks light on, and tests for AO on.

Default 1.

Note

Changing this from 1 will disable bouncing light off of this bmodel.

Note

Changing this from 1 implicitly enables _shadow.

Note

Changing to 2, for example, will cause the bmodel to initially be solid black. You’ll need to add minlight or lights with _light_channel_mask 2.

Other Information#

The \b escape sequence toggles red text on/off, you can use this in any strings in the map file. e.g. "message" "Here is \bsome red text\b..."

Author#

Eric Wasylishen
Kevin Shanahan (aka Tyrann) - http://disenchant.net
David Walton (aka spike)
Based on source provided by id Software

Reporting Bugs#

Please post bug reports at https://github.com/ericwa/ericw-tools/issues.

Improvements to the documentation are welcome and encouraged.

Copyright#

Copyright (C) 2017 Eric Wasylishen
Copyright (C) 2013 Kevin Shanahan
Copyright (C) 1997 id Software
License GPLv2+: GNU GPL version 2 or later
<http://gnu.org/licenses/gpl2.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.