Scripting Support (C#)

advanced scripting

Umbra Soft Shadows · Scripting Support (C#)

Namespace: Umbra. The main component is UmbraSoftShadows, a MonoBehaviour attached to the main directional light. Shadow settings are stored in an UmbraProfile (ScriptableObject).

Getting Started

Add using Umbra; at the top of your script. Access the component and its profile:

using Umbra;

UmbraSoftShadows umbra = FindFirstObjectByType<Light>().GetComponent<UmbraSoftShadows>();
umbra.profile.sampleCount = 32;
umbra.profile.lightSize = 10f;

UmbraSoftShadows

Properties

UmbraProfile profile

The currently used Umbra profile with all shadow settings.

ContactShadowsSource contactShadowsSource

Source of contact shadows: DirectionalLight (default) or PointLights.

Transform pointLightsTrigger

Object whose position is used to determine if it is inside point light volumes.

bool debugShadows

Enables debug visualization of the shadow buffer.

Static Members

static UmbraSoftShadows instance

Singleton reference to the active UmbraSoftShadows instance.

static bool installed

True when the render feature is installed and active.

static bool isDeferred

True when the current camera is rendering in deferred mode.

UmbraProfile

Shadow Quality

ShadowSource shadowSource

Which shadow generation system to use: UnityShadows, UmbraShadows (default), or OnlyContactShadows.

int sampleCount

Number of shadow map samples used to resolve shadows (1–64, default 16).

int earlyOutSamples

Number of samples for early exit if the shadow is already fully resolved (1–64, default 32).

float lightSize

Size of the directional light, which influences the penumbra size (0–32, default 6).

bool enableContactHardening

Makes shadows sharper near the occluder (default true).

float contactStrength

Makes shadows sharper and stronger near the occluder (0–1, default 0.5).

float contactStrengthKnee

Modifies the shadow edge appearance (default 0.0001).

float distantSpread

Makes shadows smoother when far from the occluder (1–16, default 1).

int occludersCount

Number of shadow map samples to find occluders for improved penumbra (1–64, default 8).

float occludersSearchRadius

Multiplier for the occluder search radius in texture space (default 8). Higher values create more diffused penumbra.

Blur

int blurIterations

Number of blur passes (0–3). Each pass increases shadow softness.

BlurType blurType

Specifies the blur method: Gaussian15 (default), Gaussian5, or Box.

float blurSpread

Blur kernel radius multiplier (0.5–5, default 1).

float blurEdgeSharpness

Increases contrast on the shadow border (0–1).

float blurEdgeTolerance

Strength of the edge weight when blurring (default 5).

float blurDepthAttenStart

Distance from camera where blur starts to reduce (default 50).

float blurDepthAttenLength

Blur reduction intensity over distance (default 50).

float blurGrazingAttenuation

Blur reduction when viewing shadows from a grazing angle (0–1).

Cascades

bool blendCascades

Enable blending between shadow cascades.

int posterization

Shadow posterization level (1–10, default 1).

float cascade1BlendingStrength

Blending strength for cascade 1 (default 0.1).

float cascade2BlendingStrength

Blending strength for cascade 2 (default 0.1).

float cascade3BlendingStrength

Blending strength for cascade 3 (default 0.1).

float cascade1Scale

Shadow smoothness multiplier for cascade 1 (default 1).

float cascade2Scale

Shadow smoothness multiplier for cascade 2 (default 1).

float cascade3Scale

Shadow smoothness multiplier for cascade 3 (default 1).

float cascade4Scale

Shadow smoothness multiplier for cascade 4 (default 1).

Normals & Performance

NormalSource normalsSource

Method used to obtain surface normals: ReconstructFromDepth (default, fastest), NormalsPass (more accurate), or GBufferNormals (deferred only).

NormalSource effectiveNormalsSource read-only

Gets the effective normals source. Falls back to ReconstructFromDepth when GBufferNormals is selected but camera is not in deferred mode.

LoopStep loopStepOptimization

Reduces the number of samples while keeping shadow size: Default, x2, or x3.

bool frameSkipOptimization

Resolves the shadow map every two frames, reusing the result from the previous frame.

float skipFrameMaxCameraDisplacement

If camera moves more than this distance, the cached shadow map is discarded (default 0.1).

float skipFrameMaxCameraRotation

If camera rotates more than this angle (degrees), the cached shadow map is discarded (default 5).

bool downsample

Resolves screen-space shadows in a half-resolution buffer.

bool forceDepthPrepass

Forces a depth prepass so depth and normals are available even for forward-only materials in deferred mode.

bool preserveEdges

Prevents shadow blurring on geometry edges (default true).

Style

Style style

Stylized look for shadows: Default or Textured.

Texture2D maskTexture

Optional mask texture to create stylized shadows.

float maskScale

Scale of the mask texture (default 1).

Contact Shadows

bool contactShadows

Enables screen-space contact shadows.

float contactShadowsIntensityMultiplier

Intensity multiplier for contact shadows (0–1, default 0.85).

ContactShadowsInjectionPoint contactShadowsInjectionPoint

Injection point: ShadowTexture (default) or AfterOpaque.

ContactShadowsInjectionPoint actualContactShadowsInjectionPoint read-only

Gets the actual injection point, forcing AfterOpaque when shadowSource is OnlyContactShadows.

int contactShadowsSampleCount

Number of contact shadow samples (1–64, default 16).

float contactShadowsStepping

Step size for contact shadow ray marching (default 0.01).

float contactShadowsThicknessNear

Thickness of surfaces at near distance (default 0.5).

float contactShadowsThicknessDistanceMultiplier

Multiplier for thickness over distance.

float contactShadowsJitter

Jitter amount for contact shadow rays (default 0.3).

float contactShadowsDistanceFade

Attenuates shadow intensity with distance to occluder (0–1, default 0.75).

float contactShadowsStartDistance

Minimum distance where contact shadows start.

float contactShadowsStartDistanceFade

Fade distance at the start of contact shadows (default 0.01).

float contactShadowsNormalBias

Offset added to the pixel position to avoid self-occlusion (0.0001–0.25, default 0.1).

float contactShadowsVignetteSize

Attenuates contact shadows at screen edges (0–0.5, default 0.15).

float contactShadowsBias

Bias to avoid self-occlusion (0–1, default 0.001).

float contactShadowsBiasFar

Bias applied at far distances (0–1, default 0.4). Use only if self-shadowing occurs.

float contactShadowsEdgeSoftness

Softens the edges of contact shadows (0.01–0.5, default 0.1).

bool contactShadowsSoftEdges

Enables soft edges for contact shadows. Disable for better performance.

bool contactShadowsPlanarShadows

Makes contact shadows planar by ignoring the Y component of the light direction. Useful for ground shadows.

Overlay Shadows

bool overlayShadows

Adds an extra pass after opaque with custom colored shadows.

float overlayShadowsIntensity

Intensity of the overlay shadow pass (default 0.5).

Color overlayShadowsColor

Color of the overlay shadows (default black).

Transparent Receiver

bool transparentReceiverPlane

Enables a receiver plane to cast shadows from transparent objects.

float receiverPlaneAltitude

World-space altitude of the transparent receiver plane.

Methods

void ApplyPreset(UmbraPreset preset)

Applies a built-in preset: Hard, Soft, Smooth, ExtraSmooth, Blurred, or Fast.

UmbraPointLightContactShadows

Attach this MonoBehaviour to a Point Light to enable contact shadows from that light. Requires a BoxCollider trigger to define the shadow volume.

BoxCollider boxCollider

The box collider defining the shadow volume. Auto-created on enable if not present.

float fadeDistance

Fade distance at the volume boundary (default 1).

static Dictionary<Light, UmbraPointLightContactShadows> umbraPointLights read-only

Dictionary of all registered point lights and their contact shadow components.

float ComputeVolumeFade(Vector3 worldPosition)

Returns a 0–1 fade value based on how close the world position is to the volume boundary.

Code Examples

using Umbra;

// Get Umbra and modify the profile
var umbra = FindFirstObjectByType<Light>().GetComponent<UmbraSoftShadows>();
umbra.profile.sampleCount = 32;
umbra.profile.lightSize = 10f;
umbra.profile.enableContactHardening = true;

// Apply a preset
umbra.profile.ApplyPreset(UmbraPreset.Smooth);

// Enable contact shadows
umbra.profile.contactShadows = true;
umbra.profile.contactShadowsSampleCount = 24;

// Enable overlay shadows with a blue tint
umbra.profile.overlayShadows = true;
umbra.profile.overlayShadowsColor = new Color(0f, 0f, 0.3f);

// Switch to point light contact shadows
umbra.contactShadowsSource = ContactShadowsSource.PointLights;
umbra.pointLightsTrigger = playerTransform;
Was this page helpful?