Light components — s&box lighting API reference

s&box provides five lighting components that cover the full range of real-time and baked illumination. This page documents the properties of the shared Light base class and each concrete light type, plus the EnvmapProbe component that captures and applies environment reflections.

Light base class

All dynamic light components — DirectionalLight, PointLight, and SpotLight — inherit from the abstract Light class, which provides shared color, shadow, and fog properties.

Color

LightColor

Color

default:"#E9FAFF"

The primary color and intensity of the light. Brightness is driven by the HDR value of this color — values above 1.0 in linear space produce light brighter than white.

Shadows

bool

default:"true"

Enables shadow casting for this light. Disable on lights that are far away or contribute little to scene shading to save shadow-map draw calls.

ShadowBias

float

default:"0.0005"

Depth offset applied when comparing shadow map samples. Increase slightly if you see shadow acne (self-shadowing artifacts). Range 0–1.

ShadowHardness

float

default:"0"

Controls shadow softness. 0 produces hard-edged shadows; 1 produces the softest result. Range 0–1.

Fog

FogMode

Light.FogInfluence

default:"Enabled"

Controls whether this light contributes to volumetric fog.

Value	Behavior
`Disabled`	Light does not scatter in fog.
`Enabled`	Light scatters in fog with shadow casting.
`WithoutShadows`	Light scatters in fog but casts no fog shadows.

FogStrength

float

default:"1.0"

Multiplier on this light’s contribution to volumetric fog scattering. Range 0–1.

DirectionalLight

DirectionalLight simulates a distant light source such as the sun. It illuminates the entire scene uniformly from a single direction determined by the GameObject’s rotation. It uses cascaded shadow maps to provide high-quality shadows across large distances.

var go = new GameObject( "Sun" );
var sun = go.Components.Create<DirectionalLight>();
sun.LightColor = Color.FromHsv( 40, 0.2f, 1.5f ); // warm sunlight
sun.ShadowCascadeCount = 4;

SkyColor

Color

An ambient sky color blended in for legacy compatibility. Use AmbientLight for new projects instead.

ShadowCascadeCount

int

default:"4"

Number of shadow map cascades. More cascades improve shadow resolution at distance, but each additional cascade adds GPU cost. User quality settings can reduce this at runtime.

ShadowCascadeSplitRatio

float

default:"0.91"

Distribution of cascades between the first cascade boundary and the far clip. 0 is uniform; 1 is fully logarithmic. Higher values concentrate more shadow resolution near the camera. Hidden when ShadowCascadeCount is 1.

Four cascades with a high split ratio (0.9–0.95) gives the best balance of near-camera detail and far-field coverage for outdoor scenes.

PointLight

PointLight emits light equally in all directions from a single point. It is the standard choice for light bulbs, torches, explosions, and any omni-directional source.

var go = new GameObject( "Torch" );
var light = go.Components.Create<PointLight>();
light.LightColor = Color.FromHsv( 30, 0.8f, 2.0f );
light.Radius = 300;
light.Attenuation = 1.0f;

Radius

float

default:"400"

Maximum range of the light in world units. Objects beyond this distance receive no light from this source.

Attenuation

float

default:"1.0"

Quadratic falloff coefficient. Higher values make the light fall off faster within the radius, producing a tighter hot spot. 0 gives no quadratic falloff (flat attenuation within radius).

SpotLight

SpotLight emits a cone of light in the direction the GameObject faces — useful for flashlights, stage lighting, and vehicle headlights. The cone is defined by inner and outer angles; the area between the two angles is where the light fades from full intensity to zero.

var go = new GameObject( "Flashlight" );
var spot = go.Components.Create<SpotLight>();
spot.LightColor = Color.White * 3.0f;
spot.Radius = 600;
spot.ConeInner = 20;
spot.ConeOuter = 40;

Radius

float

default:"500"

Maximum range of the spotlight in world units.

ConeInner

float

default:"15"

The half-angle (degrees) of the inner cone where light is at full intensity.

ConeOuter

float

default:"45"

The half-angle (degrees) of the outer cone edge. Light fades to zero between ConeInner and ConeOuter.

Attenuation

float

default:"1.0"

Quadratic falloff coefficient, same as PointLight.Attenuation.

An optional texture projected by the spotlight. Use a black-and-white cookie to shape the beam (for example, a window frame pattern).

AmbientLight

AmbientLight adds a global fill light applied uniformly to all surfaces in the scene. It is the simplest way to prevent areas shadowed by DirectionalLight from going completely black.

var go = new GameObject( "Ambient" );
var ambient = go.Components.Create<AmbientLight>();
ambient.Color = new Color( 0.05f, 0.05f, 0.1f );

Color

default:"Gray"

The ambient light color applied globally outside any light probes. Use low-intensity values — typical ambient colors are below 0.1 in linear space.

AmbientLight replaces the SkyColor property on DirectionalLight from earlier versions of s&box. Prefer AmbientLight for new projects.

EnvmapProbe

EnvmapProbe captures a cubemap of the environment from its location and applies it as specular reflections to nearby surfaces. Probes can be baked offline, rendered once on load, updated in real time, or use a manually provided texture.

var go = new GameObject( "Reflection Probe" );
var probe = go.Components.Create<EnvmapProbe>();
probe.Mode = EnvmapProbe.EnvmapProbeMode.Realtime;
probe.Resolution = EnvmapProbe.CubemapResolution.Medium;
probe.Bounds = BBox.FromPositionAndSize( 0, 512 );

Mode

EnvmapProbe.EnvmapProbeMode

default:"Baked"

Controls how the probe’s cubemap texture is sourced.

Mode	Behavior
`Baked`	Uses the `BakedTexture` property set during scene baking.
`Realtime`	Renders the cubemap dynamically according to `UpdateStrategy`.
`CustomTexture`	Uses the texture assigned to the `Texture` property.

Texture

The custom cubemap texture used when Mode is CustomTexture.

BakedTexture

Texture

The pre-baked cubemap texture used when Mode is Baked. Set automatically during baking.

Volume and blending

Projection

ProjectionMode

Whether the cubemap is projected using Box or Sphere projection. Box projection corrects parallax inside enclosed rooms; sphere is appropriate for open areas.

Bounds

BBox

default:"(±512, ±512, ±512)"

The world-space bounding volume within which this probe influences surfaces.

Feathering

float

default:"8.0"

Distance over which the probe’s influence blends in or out at the edges of Bounds. Positive values create a soft falloff; negative values create a hard edge.

TintColor

Color

default:"White"

A multiplicative tint applied to the captured cubemap. Use to warm or cool reflections without re-capturing.

Priority

int

default:"0"

When multiple probes overlap, the one with the highest priority wins.

Rendering (Realtime / Baked)

Resolution

EnvmapProbe.CubemapResolution

default:"Small (128×128)"

Resolution of the captured cubemap. Higher resolutions show more detail but use more GPU memory and baking time.

Value	Resolution
`Small`	128 × 128
`Medium`	256 × 256
`Large`	512 × 512
`Huge`	1024 × 1024

ZNear

float

default:"16"

Near clip distance for the probe’s capture camera.

ZFar

float

default:"4096"

Far clip distance for the probe’s capture camera.

Realtime update strategy

UpdateStrategy

EnvmapProbe.CubemapDynamicUpdate

default:"OnEnabled"

Controls how often the realtime cubemap is re-rendered.

Value	When it updates
`OnEnabled`	Once when the component is enabled (or on demand via `MultiBounce`).
`EveryFrame`	Every frame. Expensive — avoid unless necessary.
`FrameInterval`	Every `FrameInterval` frames.
`TimeInterval`	Every `DelayBetweenUpdates` seconds.

MaxDistance

float

default:"512"

Only updates dynamically when the camera is within this distance of the probe.

FrameInterval

int

default:"5"

Number of frames between updates when UpdateStrategy is FrameInterval. Range 0–16.

DelayBetweenUpdates

float

default:"0.1"

Seconds between updates when UpdateStrategy is TimeInterval. Range 0–10.

MultiBounce

bool

default:"false"

When true and UpdateStrategy is OnEnabled, the probe renders 4 bounces on startup to converge inter-reflection. Adds cost on load.

Dirty

bool

Setting this to true forces the probe to re-render on the next frame, regardless of update strategy.

Lighting tips

Shadow quality vs performance

Keep ShadowCascadeCount at 2 for indoor scenes. Use 4 only for large outdoor environments where far-field shadows are visible.

PointLight vs SpotLight

Prefer SpotLight wherever a surface or direction is obvious — it costs less per shadow draw call and avoids wasted light on areas you cannot see.

EnvmapProbe placement

Place one probe per distinct enclosed area. Enable Projection = Box for rooms and corridors so reflections are parallax-corrected.

Ambient fill

Set AmbientLight.Color to a low-saturation complement of your DirectionalLight color (e.g., a cool blue ambient for a warm orange sun) for natural-looking shadowed areas.

Rendering guide

Overview of the rendering pipeline and post-processing.

CameraComponent

Camera settings, post-process anchors, and HUD rendering.

Shaders guide

Writing shaders that react to scene lights and environment maps.

Scene & GameObjects

How components attach to GameObjects.

Scene & Objects

Built-in Components

Systems

Light components — s&box lighting API reference

Light base class

Color

Shadows

Fog

DirectionalLight

PointLight

SpotLight

AmbientLight

EnvmapProbe

Mode

Volume and blending

Rendering (Realtime / Baked)

Realtime update strategy

Lighting tips

Shadow quality vs performance

PointLight vs SpotLight

EnvmapProbe placement

Ambient fill

Rendering guide

CameraComponent

Shaders guide

Scene & GameObjects

Build docs developers (and LLMs) love

Scene & Objects

Built-in Components

Systems

Documentation Index

​Light base class

​Color

​Shadows

​Fog

​DirectionalLight

​PointLight

​SpotLight

​AmbientLight

​EnvmapProbe

​Mode

​Volume and blending

​Rendering (Realtime / Baked)

​Realtime update strategy

​Lighting tips

Shadow quality vs performance

PointLight vs SpotLight

EnvmapProbe placement

Ambient fill

​Related pages

Rendering guide

CameraComponent

Shaders guide

Scene & GameObjects

Build docs developers (and LLMs) love

Light base class

Color

Shadows

Fog

DirectionalLight

PointLight

SpotLight

AmbientLight

EnvmapProbe

Mode

Volume and blending

Rendering (Realtime / Baked)

Realtime update strategy

Lighting tips

Related pages