VRAD
(Redirected from Radiosity)
Jump to navigation
Jump to search
VRAD is the command-line tool for 
Source that takes a compiled BSP map and embeds lighting data into it. VRAD's static and pre-compiled light is bounced around the world with a 
radiosity algorithm.
VRAD will:
- Generate lightmaps
- Generate ambient samples
- Generate per-vertex prop_static lighting
- Generate per-object detail prop lighting
VRAD is generally the slowest of the three compilers due to the many, many calculations it must perform. Lighting optimization can help, as can ensuring your map is free of leaks.
Syntax
For example, a regular compile would look like thus:
This will generate and embed both Standard and High Dynamic Range lighting data, at per-vertex detail for prop_static entities. It also generates shadows based on transparency for prop_static entities that have been flagged as casting texture shadows.
Options
Use these in combination with expert compile mode, a batch file, or a frontend such as 
Compile Pal.
Todo: Fix CLParam template. This template does not work properly with gallery and bug template.
Todo: Add line breaks (<br>) in the larger descriptions where appropriate, to improve legibility.
Effects
- -ldr
- -hdr
- -both
- Whether to compile Standard Dynamic Range lighting (referred to as "Low Dynamic Range lighting" in Source), High Dynamic Range lighting, or both respectively.
Note:Since 
, SDR support was deprecated. Thus making -ldr and -both obsolete in engine branches made on or after . Instead, -hdr is required in order to produce proper lighting for your map.Note:
default to compiling only HDR automatically.
Important:In engine branches prior to (including 
), loading a map compiled with -hdr only when HDR is disabled will result in mat_fullbright 1 being forced on, which applies to all subsequent maps until cheats are enabled. This does not affect maps compiled with -ldr only. As such, final distributables for pre- multiplayer games should be compiled in -both or -ldr to prevent giving fullbright cheats to users with HDR enabled; -hdr can still be useful for faster iteration in development compiles.
- -fast
- Compiles quick low quality lighting. Used for quick previewing.
- Note:-fast will cause random and discolored splotching to appear in darker areas, as well as shadowed edges around Displacements. It is advised to not ship your map using -fast.
Tip:If you have a relatively modern CPU, you can try using other parameters to reduce the standard compile time instead. For example:-fastambient -bounce 1 -noextra -nodetaillight -noskyboxrecurse instead of -fast
- -final
- Increases the quality of light_environment and indirect lighting by spending more time firing rays.
Sets-StaticPropSampleScale to 16.- Sets-aosamples to 32, -extrasky to 16, and -extrapasses to 8.
- -extrasky <integer>
- Trace N times as many rays for indirect light and sky ambient. (-final is equivalent to -extrasky 16; normal is equivalent to -extrasky 1)
- -lights <filename>.rad
- Load a custom RAD file in addition to lights.rad and the map-specific lights file. Include the file extension in the parameter.
- -bounce <integer>
- Set the maximum number of light ray bounces. (default: 100).
- -smooth <integer>
- Set the threshold for automatic phong smoothing of lightmaps between edges, in degrees (default: 45). Use smoothing groups to explicitly define faces as phonged together.
- -luxeldensity <normal>
- Scale down all luxels. Default (and maximum) value is 1.
Warning:Setting too low of a value will cause lighting errors.
- -softsun <float>
- Treat the sun as an area light source of this many degrees. Produces soft shadows. Recommended values are 0-5, default is 0. Identical to the SunSpreadAngle parameter for light_environment, use that instead.
- -StaticPropLighting (in all games since
) - Generate per-vertex lighting on prop_statics. Causes lightingorigin on static props props without $bumpmap or $phong to not affect lighting (only affecting chosen env_cubemap), unless the disablevertexlighting KV is set for the prop. This will increase your map's compile times substantially, based on the amount of props that you have! Disable vertex lighting for props that don't need it to keep compile times down. Static props which are close to bright light_spot entities will still appear as if they were lit per-vertex, due to the lights creating directional elights.
It also generates lightmaps for static props that have generatelightmaps enabled not many games supports this, (only in
). - Warning:In Black Mesa, you should use -StaticPropLighting3 instead.
- Important: Does not work on props with bump maps, except in Counter-Strike: Global Offensive. Note:In , in order to get proper lighting on your static props, you will need to run VRAD with this command.
- -StaticPropPolys (in all games since )
- Use the actual meshes of static props to generate shadows instead of using their collision meshes. This results in far more accurate shadowing.
-StaticPropPolys - Examples Expand
- -textureshadows (in all games since )
- Casts texture shadows from $alphatest and $translucent surfaces of prop_static models that are specified in a RAD file or were compiled with $casttextureshadows. Usually requires -StaticPropPolys to have any effect. A surface will need a low lightmap scale for most texture shadows to be recognizable. Nonetheless, textures such as grate fences, foliage, and barbed wire will still cast noticeably more accurate shadows with this command enabled compared to disabled. Garry's Mod Also casts shadows from model materials with %alphatexture.
-textureshadows - Examples Expand
- Note:(only in ) Also generates lightmap shadows from brushes (but not displacements) using $alphatest.
Bug:Static props with multiple skins will always use the alpha channel(s) from the default skin's texture(s), even though the alternative skins' alpha textures are loaded by VRAD.
This will not work if a translucent texture's $basetexture parameter in the VMT contains the .vtf file extension; file extensions should be omitted from texture paths in VMTs. (tested in:
)
Game/Compiler Specific Parameters
Counter-Strike: Global Offensive
- -aoscale <float> (in all games since )(also in )
- Scales the radius of VRAD's simulated ambient occlusion. 1.0 is default.
- Tip:Valve uses 1.5 for Dust 2.
-aoscale - Examples Expand
- -StaticPropBounce <integer> (only in )(also in )
- Number of static prop light bounces to simulate. The default is 0.
- Tip:Valve uses 3 static prop bounces for Dust 2.
- Note:Any static props that you want light to bounce off of must also have their "Enable Bounced Lighting" keyvalue set.
- -StaticPropLightingFinal (only in )
Merged with -final.
- -StaticPropLightingOld (only in )
- Will use the old lighting algorithm on props, light affects them much more.
- -ambient <color1> (only in
) - Sets the ambient term. Can be used to tweak lightmap color. Appears to just mix the color into all lightmaps.
Also available in Source 2013 if VRAD is compiled in debug mode
- -unlitdetail (only in )
- Disables lighting for detail props.
- -ambientfromleafcenters (only in )
- Samples ambient lighting from the center of the leaf.
- -StaticPropSampleScale <float> (only in )(also in )
- Extra sampling factor for indirect lighting on prop_static.
- slow: 16 (high quality); default: 4 (normal); fast: 0.25 (low quality)
- Note:-final is the equivalent of having -StaticPropSampleScale 16.
- -LeafAmbientSampleReduction <float> (only in )
- Reduction factor for ambient samples. Defaults to 1.0.
Black Mesa
- -StaticPropLighting3 (only in )
- This is a more precise and less buggy version of -StaticPropLighting.
- -choptexlights (only in )
- Enables chopping of texture lights generated from a lights file. Control texture light quality with lightmap density in Hammer. Dramatically increases both texture light quality and compile time.
- -extratransfers (only in )
- Enable overscaling of light transfers.
- -transferscale <float> (only in )
- This is the scale factor of light transfers. Increased values make surfaces transfer extra light (scale of 2-4 suggested). Default 1.0.
- -satthresh <float> (only in )
- This is the threshold that checks how saturated a material color is. Used with -satthreshscale. Default 0.4.
- -satthreshscale <float> (only in )
- The amount to scale light transfers from surfaces that pass the saturation threshold. Default 3.0.
- -ambientocclusion (only in )(also in )
- Enable lightmapped ambient occlusion.
- Tip:Use very low lightmap scale for small stairs or add additional light sources to light them, otherwise stairs will be completely black.
-ambientocclusion Examples Expand
- -experimentalambientocclusion (only in )
- Uses an improved algorithm for ambient occlusion.
- Broken. Don't use.
-experimentalambientocclusion Examples Expand
- -cascadeshadows (only in )
- Indicates that lightmap alpha data is interleved in the lighting lump, required for CSM.
- Must be used with
-StaticPropLighting3to have proper lighting of static props.
-cascadeshadows Examples Expand
- -realskylight (only in )
- Enables VRAD to compute skylight ambient color by using actual values from skybox.
This option was originally designed only for levels in Xen, to make lighting for islands more natural. With earthbound outdoor levels this option makes level lighting weird, especially if level uses a skybox with an open, clear sky.
-realskylight Examples Expand
- -realskylightscale <float> (only in )
- Scale factor of -realskylight intensity. Default: 1.0
- -directsunlightisforadditivemode (only in )
- Toggles direct sunlight for additive mode.
- Bug:This option is not compatible with cascaded shadows. (tested in: )
-directsunlightisforadditivemode Examples Expand
Strata Source
- -aoradius <float> (only in
) - Set the radius of VRAD's simulated ambient occlusion. 36 is default.
- -aosamples <integer> (only in )(also in )
- How many samples to use for VRAD's simulated ambient occlusion.
- -PortalTraversalLighting (only in )
- Enables static lights to go through linked_portal_door, if
Static Portalvalue isYes.
-PortalTraversalLighting Examples Expand
- -PortalTraversalAO (only in )
- Enables static light Ambient Occlusion to go through linked_portal_door, if
Static Portalvalue isYes.
-PortalTraversalAO Examples Expand
Slammin' Source Map Tools
- -softenCosine (only in )(also in )
- Softens coloured lighting so it blends more accurately.
- -worldtextureshadows (only in )
- Allows world polys to cast texture shadows, much like models can.
- Bug:Doesn't work with displacements, and certain file formats might not cast shadows! (tested in: )
-worldtextureshadows Examples Expand
- -translucentshadows (only in )
- Enables -worldtextureshadows on $translucent surfaces. As by default only $alphatest surfaces cast baked shadows.
- Bug:Doesn't work with displacements, and certain file formats might not cast shadows! (tested in: )
-translucentshadows Examples Expand
- -coring (only in )
- Luxels with values dimmer than this are treated as completely black, and don't get supersampled.
Also available in Source 2013 if VRAD is compiled in debug mode
- -reflectivityScale <float> (only in )
- Scale the $reflectivity of all textures. Default 1.0
Mapbase
- -ultrafast (only in )
- Merges '-fast -fastambient -noextra -bounce 1' commands into one, reduces compile time, useful for testing large maps.
- -extrapasses (only in )
- Lets you scale how many extra passes you want your map to go through for supersampling, useful for making the lightmaps more rgb constant.
Half-Life 2 20th
- -HL2LDRAmbientClassic (only in ) 20th
- Use BSP version <20 LDR ambient lighting constant (pre-Lost Coast vmfs)
- -HL2LDRAmbientFix (only in ) 20th
- Use adjusted LDR ambient lighting constant for HDR re-lit maps (Post Xbox 360/Orange Box HL2 VMFs only)
Performance
- -low
- Run as a low-priority process.
- -threads <integer>
- Override the number of CPU threads used. Maximum is 16 threads (32 in , unlimited in
) 
Workaround:With a patched vrad_dll you can use 32 threads. 
fixtoolthreads is a patch for VRAD (and VVIS) that supports unlimited threads and fixes a thread scaling issue.- Note:The above mentioned thread scaling issue has been fixed in ,,,.
- Tip:If you know that the compile time will be very long and would rather do something else while waiting, it may be useful to specify a number of threads 1 or 2 lower than what your CPU has. This allows the computer to allocate some more power to other applications, making it less choppy while lighting is being compiled. Keep in mind that this may slightly extend your compile time.
- -mpi
- Use VMPI to distribute computations.
- -mpi_pw <string>
- Use a password to choose a specific set of VMPI workers.
- -noextra
- Disable supersampling. This will lead to blockier, less accurate lighting.
- -maxchop <integer>
- Coarsest allowed number of luxel widths for a patch, used in face interiors. (Default: 4)
- -LargeDispSampleRadius
- This can be used if there are (dark) splotches of bounced light on terrain. The compile will take longer, but it will gather light across a wider area.
- -compressconstant <integer>
- Compress lightmaps whose color variation is less than this many units. Todo: Find out if this is branch specific, as it doesn't work with TF2.
- -fastambient
- Uses low quality per-leaf ambient sampling to save compute time.
- -noao (only in )
- Disables compiling simulated ambient occlusion for lightmaps.
- -disppatchradius <float>
- Sets the maximum radius allowed for displacement patches. If you get "Patch Sample Radius Clamped", you can try increasing this limit.
Debugging
- -rederrors
- Emit red light when "a luxel has no samples".
- -vproject <directory>
- -game <directory>
- Override the VPROJECT environment variable.
- -insert_search_path <directory>
- Includes an extra base directory for mounting additional content (like Gameinfo.txt entries). Useful if you want to separate some assets from the mod for whatever reason.
- -v
- -verbose
- Turn on verbose output.
- -novconfig
- Don't bring up graphical UI on vproject errors.
- -dump
- Dump patches to debug files.
- -dumpnormals
- Write normals to debug .txt files.
- -debugextra
- Places debugging data in lightmaps to visualize supersampling.
- -dlightmap
- Force direct lighting into different lightmap than radiosity.
- -stoponexit
- Wait for a keypress on exit.
- -nodetaillight
- Don't light detail props.
- -centersamples
- Move sample centers.
- -loghash
- Log the sample hash table to samplehash.txt.
- -onlydetail
- Only light detail props and per-leaf lighting.
- -maxdispsamplesize <integer>
- Set max displacement sample size (default: 512).
- -FullMinidump
- Write large minidumps on crash.
- -OnlyStaticProps
- Only perform direct static prop lighting.
- -StaticPropNormals
- When lighting static props, just show their normal vector.
- -noskyboxrecurse
- Turn off recursion into 3d skybox (skybox shadows on world).
- -nossprops
- Globally disable self-shadowing on static props.
- -dumppropmaps (in all games since )(also in )
- Dump computed static prop lightmaps as TGA files.Tip:This can be used to create lightmaps for dynamic props, using the $lightmap shader parameter.Tip:To pair static props in a map with their dumped lightmaps, use r_staticpropinfo 2 to show static prop IDs on screen.Bug:The resulting TGAs are written with the wrong color space (fixed in ); convert the resulting PPL files instead. This command can be useful for indicating which model and at what location each prop is, which the PPL filenames lack.
Debug Mode Options
If VRAD is compiled in debug mode or the #if ALLOWDEBUGOPTIONS preprocessor is removed, additional options are available.
- -scale <float>
- Scale lighting by this value.
- -ambient <color1>
- Apply a minimum ambient lighting value to the map.
- -scale <float>
- Scale lighting by this value.
- -sky <float>
- -notexscale
- -coring <float>
- Luxels with values dimmer than this are treated as completely black, and don't get supersampled.
Lights files
Main article: RAD file#Source 1
Console output
Todo: Add description about missing outputs output (BuildVisLeafs, other)
Bugs and caveats
Warning:VRAD does not compile shadows based on transparent/translucent brushes or displacements. If you must have shadows made by a brush (such as a fence texture), you can turn the brush into a prop via 
SourceIO, 
Crafty or Propper++ and put it into the RAD file or compile with $casttextureshadows. Alternatively, use an existing fence prop or the "blocklight" tool texture.
Tip:(only in ) You can use -worldtextureshadows to make vrad compile shadows based on brush alpha channels (but not displacements).Warning:VRAD will use 100% of your CPU unless specified otherwise with the -threads # launch option.Bug:In 
and , users seeing crashes when VRAD compiles HDR lighting should read VRAD HDR Crash Fix.Bug:In games before , .mdl files that don't have .dx80.vtx files with them will lead to VRAD skipping lighting for that prop. Copying the .dx90.vtx file and renaming it to a .dx80.vtx will fix the issue.Tip:A windows batch file to do this automatically has been created here, extract the zip contents into your game's models folder and run the included .ps1 file.Note: is exempt from this issue.)Bug:.mdl files that have the IDST1 header will fail to load for VBSP, and will give a error message stating the prop failed to load; this can be fixed by changing the header to IDST0 in a Hex Editor, or by recompiling the prop in a non-L4D branch Studiomdl application such as Source 2013. [todo tested in ?]Bug:Since the release of Source SDK 2013 up until at least October 2017, all known copies of VRAD have a thread sharing bug which causes performance to scale poorly to multiple threads, particularly on outdoor scenes with -final set (despite showing 100% CPU usage). The fix to this bug for Source 2013 is available here and edited DLLs are available here. This issue is fixed in , , , and .
Todo: Is this fixed in ? Also in Source 2007 and earlier, and Alien Swarm SDK, raytrace.cpp isn't present so check if these versions also have the bug or not.
(tested in: ? Also in Source 2007 and earlier, and Alien Swarm SDK, raytrace.cpp isn't present so check if these versions also have the bug or not.
)
Bug:Randomly causes corrupt lightmaps that look like "ink spills" or light splotches. These can be mostly avoided by not using very long or diagonal brushes, as well as not having too low of a light level in your indoor areas.
- [todo tested in ?]Tip:Source Engine BSP Lightmap Editor can be used to manually correct a .bsp lightmap data.
Note:If you are watching the compile dialog and it looks like it has hung at 9... this is usually because VRAD takes longer with each calculation.Clarify: This isn't due to bounce calculations.[1]
Bug:VRAD is unable to calculate texture shadows for textures using DXT3 compression. Use DXT5 instead. (tested in: 
)Note:Super sampling is not implemented on displacements (before ) and lightmapped props. The former is fixed in Slammin' Source Map Tools. See also
- QRAD and HLRAD -
GoldSrc counterparts. - VRAD2 & VRAD3 -
Source 2 counterparts. - Map Compiling Theory
- HDR Lighting Basics
- VRAD HDR Crash Fix
- Static Props show up black
| |||||||||||||||||||||||||||||
