light

Without light, a scene will be black. There are a various ways that a scene can be lit, from simple light sources (pointlights), global illumination (hemilight) to complex light models (pathlight). Finally, photons allow the simulation of light effects such as caustics and diffuse light.

Here are some commonly used values. Check each particular light for specifics on how it is used. Unfortunately, different lights use different ranges, so for pointlight, power ranges from 0 to 500, while for softlight, power ranges from 0 to 10000.

bias: Bias is a value to offset shadow ray calculations. Due to precision errors, points need to be offset by a small value to make sure that any shadow testing don't see the point itself as the shadowcaster, which leads to render artifacts, black spots. The bias parameter can be used to control this value, this should generally be set as low as possible you can get away with, which is different for different platforms.
power: This indicates the strength of the lights.
at: xyz: The point at which the light is placed.
to: xyz: This is a point that the light passes through. It is used to aim the light.
color: rgb: The color of the light, in terms of the red, green and blue components.

light.pointlight

A pointlight emanates from a single point. It creates hard shadows, and is the light most often associated with raytracers.

power: 0.0-??: Strength of the light
cast_shadows: yesno: Determines if the light will generate shadows.
from: xyz: Position of the light
color: rgb: Color given off by the light.

light.sunlight**

Simulate daylight sunlight. This is (apparently) pathtracing limited to a single reflective bounce.

power: 0.0 to 50.0: Strength of the light.
cast_shadows: yesno: Determines if the light will generate shadows.
from: xyz: Position of the light.
color: rgb: Color of the light.

light.softlight**

A softlight is exactly what it sounds like: a simulation of "soft" lighting, with "soft" shadows (instead of shadows with "hard" edges). It uses shadowmaps, so it can approximate soft shadows much faster than real arealights, similar to Lightflow.

power: 0.0 to 10000.0: Strength of the light.
res: 0 to 4096: ??? Resolution
radius: 0 to 100: ???
bias: 0.0 to 5.0: ???
from: xyz: Position of the light.
color: rgb: Color of the light.

light.spotlight

Creates a cone of light.

power: 0.1 to 5000.0: Strength of the light.
size: 1 to 180: The width of the lightcone in degrees (SpotSi) in degrees. Tweaking this is finicky. Go too low or too high, and no light will be produced. Low values (around 10) produce very sharp cones of light. Higher values (80) generate very blotchy results. Values from 30-50 seem to generate the most generic of "spotlight effects".
beam_falloff: 0 to 50: Control the light distribution fallof inside the lightcone. The higher, the less distance the light travels.
halo:: Controls whether volumetric light is rendered for this light or not.
res:: Resolution of the generated shadowmap when halo=on
fog_density:: How thick the fog is when halo=on. Anything over a value of 1 seems to be ignored.
from: xyz: Start position of the light.
to: xyz: Point light passes through.
color: rgb: Color of the light.
fog: rgb: Color of the fog. Does not effect the light reflected off any objects, only the actual fog that is in the spotlight.

light.photonlight**

Photonlight is used to simulate caustic and diffuse light effects, which are caused by light travelling through transparent objects, or bouncing off reflective objects.

For example, if you wish a light to generate diffuse light effects, you will need to create two seperate lights: one for the normal lighting effects, and a photonlight for the caustic or diffuse effect.

power: 0.1 to 1000.0: Strength of the light
photons: ???: Number of photons to shoot into scene. The more photons, the better the information for the photon map will be.
search: 50 to 200
mode: "caustic" or "diffuse": Set light to create caustic or diffuse effects.
fixedradius: ???: ???
from: xyz: Start position of the light.
to: xyz: Point light passes through.
color: rgb: Color of the light.

light.arealight

Unlike a pointlight, an arealight is projected from a quad (plane defined by 4 points). Since light is emitted over an area, it creates soft shadows.

power: 0.1 to 1000.0: Strength of the light.
samples:: This value effects how "grainy" the shadows end up. Low values render faster, but make very noisy shadows. A value of 64 is decent for a test render. 128 seems good for final renders.
psamples: 0 to 1024: This seems to effect the smoothness of transitions from light areas to shadowed areas. Low values tend to produce speckles, high values are much smoother. Like the samples value, 64 is good for test runs and 128 is good for final renders.

light.hemilight

Hemilight is simulated outdoor lighting. It assumes that everything is evenly lit, and only calculates if the point currently being sampled is in shadow or not. It's roughly the same as having an infinite spherical area lightsource (a lit "hemisphere") around your scene.

power: 0.0 to 25.0: Strength of the light.
samples: 0 to 1024: Number of samples to run. Lower values tend to produce images with irritating artifacts, but renders much more quickly. Values of 30 or so are decent for test renders. Anything over 100 seems to have little to no visual impact.

light.pathlight**

Pathtlights are a method of "global illumination". What it allows is more natural shadows, because it better emulates what happens with light in the real world: A ray enters a room, then hits an object. The ray takes into account the properties of what it just hit, and bounces off in another direction appropriatley. It repeats this until it runs out of energy to bounce off anymore objects.

The net effect this has on a scene is a dramatic difference over more standard scenes; shadows are softer. Surfaces tend to take on the color of whatever light is bounced onto them. Surfaces not in direct light tend to recieve light as it gets bounced into dark areas. Basically, the resulting scene will be lit much more realistically. The price is that render times are much slower.

Pathlights are not easy to use. They are dependent on other lights in your scene and seem to require a background to be applied to get any respectable results. The general rules that I have found with pathlights include:

"Standard" lights (such as pointlights, arealights) are not required to get results. A pathlight takes all of it's information from a photonlight and the scene's background. You may, however, want additional lights to fine tune effects in the scene.
No spotlights or pointlights. I don't know why, but I have never recieved satisfactory results in a scene that used either of these. They tend to completely wipe out your scene. Arealights do work however.
Color comes from the background. Set your background to bright red, and any light the pathlight generates will be red.
You need a photonlight, too. The pathlight uses the photon map to produce it's lighting. Scenes that use a pathlight and not a photonlight are generally quite ugly, if you get anything at all.

power: 0.0 to 25.0: Strength of the light.
depth:: Number of "bounces" to allow before stopping lightray. For scenes using a photonlight, this should be set to 1 because the photonlight has already calculated the bounces.
samples:
use_QMC: yes|no: Uses random sampling (monte carlo) instead of quasi-monte carlo. QMC generally renders faster but can put artifacts into the shadows. Monte-carlo has no patterns, but is generally noisier.
cache: on|off: Enables caching of the information the pathlight generates. The short explanation of the effect this has is it speeds up render times. The downside is that each image tends to need different settings (ie, lots of manual tweaking) to get the best performance improvement.
cache_size:: Size of the grid for the cache. Larger values render faster, but give poorer results. 0.02 is a decent default to use for this. Smaller values give better resolution, bigger values render faster.
gradient:: No discernible effect on the resulting image in my tests.
show_samples: gives a visualisation of the Irradiance Cache samples (to test your settings)
search:: the maximum amount of samples to interpolate. Smaller values will give sharper shadows, but will be more blotchy (use values between 30 - 70)
shadow_threshold:: The minimum distance from the sample point an object can be before the caching algorhythm takes more samples. Not sure what the default is, but the general rule is that higher values seem to smooth out transitions from light to shadow. A value of 0.1 for example makes a very "lumpy" effect, 1.0 is decently smooth. Anything much higher tends to put light where it shouldn't be, giving the image a "hazy" feel.
angle_threshold:: The angle between surface normals that determine whether the caching algorhythm considers the surface 'flat', if the surface normal variation is higher than this,the caching algorhythm takes more samples.