Light components

Add dynamic lighting to your scene with PointLight, SpotLight, DirectionalLight, and AmbientLight components. All light types share a common base and can be configured and driven from code.

All light components inherit from the abstract Light base class, which provides color, shadow, and fog properties common to every light type. Add a light component to a GameObject and position it in the scene to illuminate your world.

Light base properties

Every light type exposes the following shared properties.

LightColor · Color · default: "#E9FAFF"

The main color of the light. Drives the tint and intensity of the light’s output.

Shadows · bool · default: "true"

Whether this light casts shadows. Disabling shadows improves performance.

ShadowHardness · float · default: "0.0"

Controls shadow edge softness. 0 gives the softest shadows; 1 gives hard-edged shadows. Range 0–1.

ShadowBias · float · default: "0.0005"

Depth bias applied to shadow maps to reduce self-shadowing artefacts. Range 0–1. This is an advanced property.

FogMode · FogInfluence · default: "Enabled"

Controls how this light interacts with volumetric fog. Options: Disabled, Enabled, WithoutShadows.

FogStrength · float · default: "1.0"

How strongly this light contributes to fog scattering. Range 0–1.

---

Light types

PointLight

Emits light in all directions from a single point in space, like a lightbulb.

Radius · float · default: "400"

Maximum distance in world units that the light reaches. Objects beyond this distance receive no illumination.

Attenuation · float · default: "1.0"

Controls the quadratic falloff of the light with distance. Higher values cause the light to drop off more sharply. Range 0–10.

var point = Components.Get<PointLight>();
point.LightColor = Color.Orange;
point.Radius = 600f;
point.Attenuation = 0.5f;

SpotLight

Emits light in a specific direction inside a cone, like a torch or stage light.

Radius · float · default: "500"

Maximum distance the light reaches along its forward axis.

ConeOuter · float · default: "45"

Outer half-angle of the light cone in degrees. Light falls to zero at this angle. Range 0–90.

ConeInner · float · default: "15"

Inner half-angle of the light cone in degrees. Light is at full brightness inside this angle. Range 0–90.

Attenuation · float · default: "1.0"

Quadratic falloff with distance. Range 0–10.

Cookie · Texture

A texture projected through the cone to create shaped light patterns (gobo effects). Leave null for a plain cone.

Set ConeInner lower than ConeOuter to create a smooth penumbra between the bright centre and the dark edge.

var spot = Components.Get<SpotLight>();
spot.LightColor = Color.White;
spot.Radius = 800f;
spot.ConeOuter = 30f;
spot.ConeInner = 10f;

DirectionalLight

Casts parallel light rays across the entire scene from an infinite distance, like the sun. The rotation of the GameObject determines the light direction.

SkyColor · Color

Ambient sky color contributed by this directional light. Kept for compatibility — prefer an AmbientLight component for ambient illumination.

ShadowCascadeCount · int · default: "4"

Number of shadow map cascades. More cascades improve shadow resolution at a cost to performance. Range 1–4. User quality settings can override this.

ShadowCascadeSplitRatio · float · default: "0.91"

Controls how cascades 2 and above are distributed between the first cascade boundary and the far clip plane. 0 is uniform distribution; 1 is fully logarithmic. Range 0–1.

Rotate the DirectionalLight GameObject to change the sun angle. A pitch of around 45° gives a good default look.

var sun = Components.Get<DirectionalLight>();
sun.LightColor = new Color( 1.0f, 0.95f, 0.8f );
sun.Shadows = true;
sun.ShadowCascadeCount = 3;

AmbientLight

Adds a flat, directionless ambient color to the entire scene. This is a simple alternative to sky-based ambient and does not cast shadows.

Color · Color · default: "Color.Gray"

The ambient light color applied globally to all surfaces outside of light probes.

Only one AmbientLight component is typically needed per scene. If you require directional ambient, use a sky material with a DirectionalLight instead.

var ambient = Components.Get<AmbientLight>();
ambient.Color = new Color( 0.15f, 0.15f, 0.2f ); // cool blue tint

---

Changing color and brightness at runtime

The following example shows how to pulse a point light’s color and simulate a brightness change by scaling LightColor.

using Sandbox;

public sealed class PulsingLight : Component
{
    PointLight _light;

    protected override void OnStart()
    {
        _light = Components.Get<PointLight>();
    }

    protected override void OnUpdate()
    {
        if ( _light is null ) return;

        // Oscillate between dim and bright using a sine wave
        float brightness = 0.5f + 0.5f * MathF.Sin( Time.Now * 2f );

        // Multiply the base color by the brightness factor
        _light.LightColor = Color.Orange * brightness;

        // Also shrink the radius when dim for a more dramatic effect
        _light.Radius = 200f + 200f * brightness;
    }
}

LightColor is a standard Color value. Multiply it by a scalar to vary brightness without introducing a separate intensity property.