light_environment Last edited 3 months ago2024-09-15 09:15:23 UTC

light_environment - Point Entity

This entity makes the map's sky (i.e. sky-textured brushes) emit parallel beams of light in the specified direction, just like real world sunlight/moonlight. The only practical way of lighting outdoor maps.

The game also uses the angles and brightness of this entity to override lighting on models if they can trace a line back towards the sky from the reverse direction of this entity's angles. The tutorial on models and lighting has more information on this.

Attributes

• Name (targetname) - Property used to identify entities.
• Pitch, Yaw, Roll (angles) - Sets the pitch (up/down), yaw (left/right) and roll (bank) respectively. This is also the value that the models of entities use to test if their lighting should be overridden by sunlight, so you need to set the Pitch value as well as Yaw.
• Pitch (pitch) - A negative number will give downward pitch (which is normally what you want). Note that using this will result in mismatch in lighting on the world vs on models unless you set the same Pitch value in PYR (angles).
• Brightness (_light) - The first three 3-digit numbers are the colour (RGB) and the fourth is brightness/light intensity (e.g. 248 244 237 350). The brightness of sky lighting is very potent; 2 or 3 is enough to sufficiently light a night map in moonlight.

ZHLT/VHLT-specific keyvalues:

• Ambient Color (_diffuse_light) - Diffused light colour and brightness. This simulates diffuse light usually from blue sky.
• Sun Spread (_spread) - Diffuses the shadow of the sunlight. Values range from 0 to around 10 (0 being sharp shadows).
• Only Dynamic (_fake) - Treat this light_environment as an info_sunlight, causing it to be ignored by HLRAD and only affect dynamic MDL lighting.

Positioning logic

Use the Pitch in Pitch Yaw Roll (angles) (and optionally also Pitch) to shift the sun (or moon) vertically (similar to daytime/hours) and Yaw to shift it horizontally (cardinal direction or obliquity)

Notes

• Don't name light_environment entities if you don't have to toggle the Sun/Moon on/off.
• Sky brushes must have the "SKY" texture on all faces or they won't reliably emit light (depends on version of HLRAD used).
• For world lighting, the key pitch have the same function as the one in angles, although if you add a value (≠0) to pitch it will overwrite the one in angles. Roll has no effect at all.
  • However, be aware that pitch is not used for model lighting, and will cause a mismatch between the two if the two values are not the same.
• For modern compilers you are not advised to use multiple light_environment in a map as they're treated as global. However, you can still use multiple light_environment for multiple colors. If you which to switch to the old behaviour where each light_environment would only light up its own outdoor area (i.e. disable the global feature), use the -noskyfix argument on the RAD compiler.
• This entity doesn't spawn a visible source of light in the sky. Therefore, the sun or moon must be part of the skybox as a picture for visual effects.
• The PYR (angles) and brightness values of this entity is used in game to override lighting on models. If an entity's origin has direct line of sight to the sky (i.e. a "SKY" face) in the reverse direction of this light_environment entity's PYR (angles) value, its lighting will be overridden with values calculated from the brightness of this light_environment entity. Click this link for more information.
  • Note that the game code uses only the PYR (angles) value for this, unlike the RAD compiler which also uses pitch. As a result, there could be a mismatch in sun lighting on the world vs on models. e.g. PYR of (0 0 0) can override model lighting with sunlight when the sky is visible on the Eastern horizon from its location even if pitch is set to, say, -45. The fix is to only use PYR (angles) to set both Pitch and Yaw, and never use pitch.
  • To break line of sight and have entities take lighting from the ground as normal, use a brush textured with black_HIDDEN facing down above the affected area, and SKIP on the other faces.
  • To avoid this effect altogether, use light_spot with "Is Sky" keyvalue set.
• Having multiple light_environment entities confuses the game engine for the above dynamic model lighting. It will only light models with the values of the last light_environment entity. If you need multiple sky light sources/values, use light_spot with "Is Sky" keyvalue for everything, and an info_sunlight for the actual model sky lighting, using an average of all the values.
• The ZHLT/VHLT keyvalues may be missing in your copy of halflife.fgd. To add them, open the file in Notepad (or other suitable text editor). Find the line that starts with @PointClass and contains the text = light_environment, and between the brackets that follow the above line, add the following lines:

_spread(integer) : "Spread Angle" : 0 : "Spread angle for soft shadows."
_diffuse_light(color255) : "Diffuse Light" : "" : "Diffuse light color."
_fake(choices) : "Only Dynamic" : "" =
[
    "" : "No"
    1  : "Yes"
]

Balancing Brightness, Ambient Color, and Sun Spread

Related pages

• Tutorial: Light (older)
• Tutorial: The Complete Guide to Lighting (newer, most exhaustive)
• Tutorial: Environment
• Tutorial: Dark Outdoor Maps
• VERC: Using Skys in Half-Life
• Vlatitude: Advanced Lighting

Example maps

• VERC Archive: lights1.zip