=====
light
=====

.. program:: light

light compiles lightmap data for BSPs



Command-line options
====================

Logging
-------

.. option:: -log [0]
            -nolog [0]

   whether log files are written or not

.. option:: -verbose
            -v

   verbose output

.. option:: -nopercent

   don't output percentage messages

.. option:: -nostat

   don't output statistic messages

.. option:: -noprogress

   don't output progress messages

.. option:: -nocolor

   don't output color codes (for TB, etc)

.. option:: -quiet
            -noverbose

   suppress non-important messages (equivalent to -nopercent -nostat -noprogress)

Performance
-----------

.. option:: -threads n

   number of threads to use, maximum; leave 0 for automatic

.. option:: -lowpriority [0]

   run in a lower priority, to free up headroom for other processes

.. option:: -surflight_subdivide n

   surface light subdivision size

.. option:: -gate n

   cutoff lights at this brightness level

.. option:: -sunsamples n

   set samples for _sunlight2, default 64

.. option:: -extra
            -extra4

   supersampling; 2x2 (extra) or 4x4 (extra4) respectively

.. option:: -fastbounce

   use one bounce point in the middle of each face. for fast compilation.

Game
----

.. option:: -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.

.. option:: -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.

.. option:: -filepriority archive | loose

   which types of archives (folders/loose files or packed archives) are higher priority and chosen first for path searching

.. option:: -path "/path/to/folder" <multiple allowed>

   additional paths or archives to add to the search path, mostly for loose files

.. option:: -q2rtx

   adjust settings to best support Q2RTX

.. option:: -defaultpaths [0]
            -nodefaultpaths [0]

   whether the compiler should attempt to automatically derive game/base paths for games that support it

Output format options
---------------------

.. option:: -onlyents

   only update entities

.. option:: -wrnormals

   output normals, tangents and bitangents in a BSPX lump

.. option:: -arghradcompat

   enable compatibility for Arghrad-specific keys

.. option:: -nolighting

   don't output main world lighting (Q2RTX)

.. option:: -lit

   write .lit file

.. option:: -world_units_per_luxel n

   enables output of DECOUPLED_LM BSPX lump

.. option:: -litonly

   only write .lit file, don't modify BSP

.. option:: -nolights

   ignore light entities (only sunlight/minlight)

.. option:: -facestyles n

   max amount of styles per face; requires BSPX lump if > 4

.. option:: -exportobj

   export an .OBJ for inspection

.. option:: -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.

Debug modes
-----------

.. option:: -surflight_dump

   dump surface lights to a .map file

.. option:: -debugface x y z

.. option:: -debugvert x y z

.. option:: -highlightseams

.. option:: -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)

.. option:: -dirtdebug
            -debugdirt

   only save the AO values to the lightmap

.. option:: -bouncedebug

   only save bounced lighting to the lightmap

.. option:: -bouncelightsdebug

   only save bounced emitters lighting to the lightmap

.. option:: -phongdebug

   only save phong normals to the lightmap

.. option:: -phongdebug_obj

   save map as .obj with phonged normals

.. option:: -debugoccluded

   save light occlusion data to lightmap

.. option:: -debugneighbours

   save neighboring faces data to lightmap (requires -debugface)

.. option:: -debugmottle

   save mottle pattern to lightmap

Postprocessing options
----------------------

.. option:: -soft [n]

   blurs the lightmap. specify n to blur radius in samples, otherwise auto

Experimental options
--------------------

.. option:: -novanilla

   implies -bspxlit; don't write vanilla lighting

.. option:: -radlights "filename.rad"

   loads a <surfacename> <r> <g> <b> <intensity> file

.. option:: -lightmap_scale n

   force change lightmap scale; vanilla engines only allow 16

.. option:: -lit2

   write .lit2 file

.. option:: -bspxlit

   writes rgb data into the bsp itself

.. option:: -lux

   write .lux file

.. option:: -bspxlux

   writes lux data into the bsp itself

.. option:: -bspxonly

   writes both rgb and directions data *only* into the bsp itself

.. option:: -bspx

   writes both rgb and directions data into the bsp itself

.. option:: -lightgrid

   experimental LIGHTGRID bspx lump

.. option:: -lightgrid_dist x y z

   distance between lightgrid sample points, in world units. controls lightgrid size.

.. option:: -lightgrid_format octree

   lightgrid BSPX lump to use

Worldspawn keys
===============

Overridable worldspawn keys
---------------------------

.. worldspawn-key:: "_dist" "n"

.. worldspawn-key:: "_range" "n"

.. worldspawn-key:: "_anglescale" "n"
                    "_anglesense" "n"

.. worldspawn-key:: "_gamma" "n"

.. worldspawn-key:: "_addmin" ""

.. worldspawn-key:: "_minlightMottle" "n"

.. worldspawn-key:: "_light" "n"
                    "_minlight" "n"

.. worldspawn-key:: "_maxlight" "n"

.. worldspawn-key:: "_minlight_color" "x y z"
                    "_mincolor" "x y z"

.. worldspawn-key:: "_spotlightautofalloff" ""

.. worldspawn-key:: "_compilerstyle_start" "n"

.. worldspawn-key:: "_compilerstyle_max" "n"

.. worldspawn-key:: "_dirt" ""
                    "_dirty" ""

.. worldspawn-key:: "_dirtmode" "n"

.. worldspawn-key:: "_dirtdepth" "n"

.. worldspawn-key:: "_dirtscale" "n"

.. worldspawn-key:: "_dirtgain" "n"

.. worldspawn-key:: "_dirtangle" "n"

.. worldspawn-key:: "_minlight_dirt" ""

.. worldspawn-key:: "_phong" "[0]"

.. worldspawn-key:: "_phong_angle" "n"

.. worldspawn-key:: "_bounce" ""

.. worldspawn-key:: "_bouncestyled" ""

.. worldspawn-key:: "_bouncescale" "n"

.. worldspawn-key:: "_bouncecolorscale" "n"

.. worldspawn-key:: "_bouncelightsubdivision" "n"

.. worldspawn-key:: "_surflightscale" "n"

.. worldspawn-key:: "_surflightskyscale" "n"

.. worldspawn-key:: "_surflightsubdivision" "n"
                    "_choplight" "n"

.. worldspawn-key:: "_sunlight" "n"
                    "_sun_light" "n"

.. worldspawn-key:: "_sunlight_color" "x y z"
                    "_sun_color" "x y z"

.. worldspawn-key:: "_sun2" "n"

.. worldspawn-key:: "_sun2_color" "x y z"

.. worldspawn-key:: "_sunlight2" "n"

.. worldspawn-key:: "_sunlight2_color" "x y z"
                    "_sunlight_color2" "x y z"

.. worldspawn-key:: "_sunlight3" "n"

.. worldspawn-key:: "_sunlight3_color" "x y z"
                    "_sunlight_color3" "x y z"

.. worldspawn-key:: "_sunlight_dirt" "n"

.. worldspawn-key:: "_sunlight2_dirt" "n"

.. worldspawn-key:: "_sunlight_mangle" "x y z"
                    "_sun_mangle" "x y z"
                    "_sun_angle" "x y z"

.. worldspawn-key:: "_sun2_mangle" "x y z"

.. worldspawn-key:: "_sunlight_penumbra" "n"

.. worldspawn-key:: "_sky_surface" "x y z"
                    "_sun_surface" "x y z"

.. worldspawn-key:: "_surflight_radiosity" "n"

   whether to use Q1-style surface subdivision (0) or Q2-style surface radiosity

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

.. program:: light

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

Performance options:
--------------------

.. option:: -threads n

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

.. option:: -extra

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

.. option:: -extra4

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

.. option:: -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.

.. option:: -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.

.. option:: -surflight_subdivide [n]

   | Configure spacing of all surface lights. Default 128 units. Minimum
     setting: 64 / max 2048. In the future I'd like to make this
     configurable per-surface-light.

Output format options:
----------------------

.. option:: -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.

.. option:: -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.

.. option:: -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.

.. option:: -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.

| 

Postprocessing options:
-----------------------

.. option:: -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:
------------

.. option:: -dirtdebug

   Implies "-dirt", and renders just the dirtmap against a fullbright
   background, ignoring all lights in the map. Useful for previewing and
   turning the dirt settings.

.. option:: -phongdebug

   Write normals to lit file for debugging phong shading.

.. option:: -bouncedebug

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

.. option:: -surflight_dump

   Saves the lights generated by surfacelights to a
   "mapname-surflights.map" file.

.. option:: -novisapprox

   | Disable approximate visibility culling of lights, which has a small
     chance of introducing artifacts where lights cut off too soon.

Experimental options:
---------------------

.. option:: -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.

.. option:: -lit2

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

.. option:: -lux

   Generate a .lux file storing average incoming light directions for
   surfaces. Usable by FTEQW with "r_deluxemapping 1"

.. option:: -lmscale n

   Equivalent to "_lightmap_scale" worldspawn key.

.. option:: -bspxlit

   Writes rgb data into the bsp itself.

.. option:: -bspx

   Writes both rgb and directions data into the bsp itself.

.. option:: -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.

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

Model Entity Keys
=================

Worldspawn Keys
---------------

The following keys can be added to the *worldspawn* entity:

.. worldspawn-key:: "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.

.. worldspawn-key:: "_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").

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_sunlight" "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.

.. worldspawn-key:: "_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).

.. worldspawn-key:: "_sunlight_mangle" "yaw pitch roll"
                    "_sun_mangle" "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").

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_sunlight_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").

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_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").

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_sunlight_color3" "r g b"
                    "_sunlight3_color" "r g b"

   Specifies the colour of "_sunlight3". Default is white light ("255
   255 255").

.. worldspawn-key:: "_dirt" "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).

.. worldspawn-key:: "_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".

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

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

.. worldspawn-key:: "_dirtmode" "n"

   Choose between ordered (0, default) and randomized (1) dirtmapping.

.. worldspawn-key:: "_dirtdepth" "n"

   Maximum depth of occlusion checking for dirtmapping, default 128.

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_gamma" "n"

   Adjust brightness of final lightmap. Default 1, >1 is brighter, <1 is
   darker.

.. worldspawn-key:: "_lightmap_scale" "n"

   Forces all surfaces+submodels to use this specific lightmap scale.
   Removes "LMSHIFT" field.

.. worldspawn-key:: "_bounce" "n"

   1 enables bounce lighting, disabled by default.

.. worldspawn-key:: "_bouncescale" "n"

   Scales brightness of bounce lighting, default 1.

.. worldspawn-key:: "_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.

.. worldspawn-key:: "_bouncestyled" "n"

   1 makes styled lights bounce (e.g. flickering or switchable lights),
   default is 0, they do not bounce.

.. worldspawn-key:: "_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.

Model Entity Keys
-----------------

The following keys can be used on any entity with a brush model.
"_minlight", "_mincolor", "_dirt", "_phong", "_phong_angle",
"_phong_angle_concave", "_shadow", "_bounce" are supported on
func_detail/func_group as well, if qbsp from these tools is used.

.. bmodel-key:: "_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

.. bmodel-key:: "_minlight_mottle" "n"
                "_minlightMottle" "n"

   Whether minlight should have a mottled pattern. Defaults
   to 1 in Q2 mode and 0 otherwise.

.. bmodel-key:: "_minlight_exclude" "texname"

   Faces with the given texture are excluded from receiving minlight on
   this brush model.

.. bmodel-key:: "_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").

.. bmodel-key:: "_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.

.. bmodel-key:: "_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.

.. bmodel-key:: "_shadowworldonly" "n"

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

.. bmodel-key:: "_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.

.. bmodel-key:: "_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.

.. bmodel-key:: "_phong" "n"

   1 enables phong shading on this model with a default \_phong_angle of
   89 (softens columns etc).

.. bmodel-key:: "_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.)

.. bmodel-key:: "_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.

.. bmodel-key:: "_lightignore" "n"

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

   .. seealso:: `Lighting Channels`_ for a more powerful version of this

.. bmodel-key:: "_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.

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.

.. light-key:: "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.

.. light-key:: "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.

.. light-key:: "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.

.. light-key:: "_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.

.. light-key:: "_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").

.. light-key:: "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".

.. light-key:: "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.

.. light-key:: "angle" "n"

   Specifies the angle in degrees for a spotlight cone. Default 40.

.. light-key:: "_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).

.. light-key:: "targetname" "name"

   Turns the light into a switchable light, toggled by another entity
   targeting it's name.

.. light-key:: "style" "n"

   Set the animated light style. Default 0.

.. light-key:: "_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.

.. light-key:: "_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.

.. light-key:: "_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.

.. light-key:: "_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.

.. light-key:: "_samples" "n"

   Number of lights to use for "_deviance". Default 16 (only used if
   "_deviance" is set).

.. light-key:: "_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.

.. light-key:: "_surface_offset" "n"

   Controls the offset lights are placed above surfaces for "_surface".
   Default 2.

.. light-key:: "_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.

.. light-key:: "_project_texture" "texture"

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

.. light-key:: "_project_mangle" "yaw pitch roll"

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

.. light-key:: "_project_fov" "n"

   Specifies the fov angle for a texture projection. Default 90.

.. light-key:: "_bouncescale" "n"

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

.. light-key:: "_sun" "n"

   Set to 1 to make this entity a sun, as an alternative to using the
   sunlight worldspawn keys. 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.

   The following light properties correspond to these sunlight settings:

   ::

      light       => _sunlight
      mangle      => _sunlight_mangle
      deviance    => _sunlight_penumbra
      _color      => _sunlight_color
      _dirt       => _sunlight_dirt
      _anglescale => _anglescale
      style       => flicker style for styled sunlight
      targetname  => targetname for switchable sunlight
      _suntexture => this sunlight is only emitted from faces with this texture name

.. light-key:: "_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.

   The following light properties correspond to these sunlight settings:

   ::

      light       => _sunlight2
      _color      => _sunlight2_color
      _dirt       => _sunlight2_dirt
      _anglescale => _anglescale
      style       => flicker style for styled dome light
      targetname  => targetname for switchable sunlight
      _suntexture => this sunlight is only emitted from faces with this texture name

.. light-key:: "_sunlight3" "n"

   Same as "_sunlight2", but for the lower hemisphere.

.. light-key:: "_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.

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-key:: "_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-key:`_light_channel_mask` and the receiving bmodel's :bmodel-key:`_object_channel_mask` (i.e. the bitwise AND must be nonzero).

   Default 1.

.. light-key:: "_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 :bmodel-key:`_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-key:`_light_channel_mask`

Model Keys
----------

.. bmodel-key:: "_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 :bmodel-key:`_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-key:`_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.
