> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/the-editor/how-to-use-shadow.md).

# How to use shadow

Configure a directional light, scene objects, and receiving surfaces so shadows appear correctly, then refine their quality and softness.

A shadow is a depth map from the light's point of view. The GPU draws casters into that map, then tests receivers against it. That is extra work every frame. Use it for the main sun or moon silhouette, not on every fill light.

{% embed url="<https://youtu.be/DbcaQhZhzeQ?si=r8KHQ7K5VLgxOEPl>" %}

{% hint style="info" %}
*NOTE: A visible shadow requires three settings: **Cast Shadow** on the light, **Cast Shadow** on the object, and **Receive Shadow** on the surface beneath it. Those are the Inspector names (`castShadow` / `receiveShadow`). There is no `Shadow Enabled` toggle.*
{% endhint %}

## Which lights can cast

| Light             | Class                         | Shadows                                                                     |
| ----------------- | ----------------------------- | --------------------------------------------------------------------------- |
| Directional Light | `ENGINE.DirectionalLightNode` | Yes — main outdoor / sun shadows. Optional **CSM** for long view distances. |
| Spot Light        | `ENGINE.SpotLightNode`        | Yes — a cone. Extra GPU cost per light that has **Cast Shadow** on.         |
| Point Light       | `ENGINE.PointLightNode`       | Yes — all directions. Extra GPU cost per light that has **Cast Shadow** on. |
| Ambient Light     | `ENGINE.AmbientLightNode`     | No. Shadow setup is a no-op.                                                |
| Hemisphere Light  | `ENGINE.HemisphereLightNode`  | No. Shadow setup is a no-op.                                                |
| Rect Area Light   | `ENGINE.RectAreaLightNode`    | No. Shadow setup is a no-op.                                                |

Keep **Cast Shadow** on one directional for the world silhouette. Turn it off on decorative point lights. Ambient and hemisphere fill the scene without maps. Adding lights: [How to set up a light](/the-editor/how-to-set-up-a-light.md). Measuring cost: [Performance & optimization](/the-editor/performance-and-optimization.md).

## Why a shadow is missing or cuts off

The directional light uses an orthographic shadow camera. Casters **outside** that box never appear in the map, so they throw no silhouette even when **Cast Shadow** is on.

Default box on `DirectionalLightNode` (when CSM is off): `shadowCameraLeft` / `Right` / `Top` / `Bottom` at **±50**, `shadowNear` **0.1**, `shadowFar` **100**. Widen the box or `shadowFar` if the play space is larger than that. A box that is much larger than the scene wastes resolution (blocky edges).

Also check:

* The light's **Cast Shadow** is on.
* The mesh's **Cast Shadow** (caster) and **Receive Shadow** (ground) are on.
* The mesh is drawn: **visible** on, **hiddenInGame** off for Play, not **editorOnly** if you expect it in Play.
* **CSM** (`useCsmShadows`): for large view distances. **Only one directional light can drive CSM at a time.** `csmMaxFar` should stay **smaller** than `shadowFar`. More `csmCascadeCount` costs more GPU. Leave CSM off for small, fixed scenes.

## Performance

`shadowMapSize` is the map resolution (default **2048**, square). Higher is sharper and heavier. Lower is cheaper and blockier. `shadowRadius` is the PCF kernel radius (edge softness). It does not make shadows longer.

Each extra light with **Cast Shadow** on adds another map pass. CSM splits that work into cascades (`csmCascadeCount`, default **4**).

Turn **Cast Shadow** off on small props, particles, and anything the player will not miss. A floor needs **Receive Shadow**; a sky mesh does not.

{% stepper %}
{% step %}

## Select the directional light

In the Outliner, select the directional light. Its settings appear in the Inspector.
{% endstep %}

{% step %}

## Enable shadows on the light

In the directional light properties, scroll to Cast Shadow and enable it. The light can now generate shadows, but they will not appear until the relevant scene objects are configured.
{% endstep %}

{% step %}

## Set the floor to receive shadows

Select the floor or ground asset, then enable **Receive Shadow** in the Inspector.
{% endstep %}

{% step %}

## Set scene objects to cast shadows

Select each object that should block the light, then enable Cast Shadow. The shadow should now appear on the floor or another receiving surface.
{% endstep %}

{% step %}

## Configure objects that receive shadows

Enable Receive Shadow on any object that should display a shadow from another object. For example, stacked boxes may need both Cast Shadow and Receive Shadow enabled.

{% hint style="info" %}
*TIP: Use Cast Shadow without Receive Shadow when an object should create a shadow but remain unaffected by shadows from other objects.*
{% endhint %}
{% endstep %}

{% step %}

## Adjust the shadow quality

Select the directional light and change one Inspector value at a time. The engine copies these onto the Three.js shadow: `mapSize`, `bias`, `normalBias`, `near` / `far` on the shadow camera, and `radius`. The renderer uses **PCF** (`THREE.PCFShadowMap`) on both WebGL and WebGPU, which is why radius has an effect.

**`shadowMapSize`**

Width and height of the depth map, in pixels (same value on both axes). Default **2048**. Changing it disposes the old map so the new size applies. Larger = sharper silhouettes, more memory and GPU. Smaller = cheaper, blockier.

**`shadowBias`**

Depth offset for the comparison. The engine describes it as a conservative **negative** bias. A live directional in-project used **-0.0005**. Too close to zero (or the wrong sign for your setup) shows shadow acne: speckles and flicker on the lit surface. A larger magnitude pulls the silhouette off the mesh (a gap). With **CSM** on, each farther cascade uses `shadowBias * (cascade index + 1)` so distant cascades get more bias automatically.

**`shadowNormalBias`**

Offset along the surface normal. Use it for self-shadowing on slopes. It is copied to each CSM cascade as-is. It does not lengthen the shadow.

**`shadowNear` / `shadowFar`**

Near and far planes of **each** shadow camera. Defaults **0.1** and **100**. Geometry closer than near or farther than far is not in that map. For CSM, these apply per cascade; keep `shadowFar` **larger** than `csmMaxFar`. The directional node also places its light target at `shadowFar * 0.5` along the light direction so the shadow camera overshoots the aim point.

**`shadowRadius`**

PCF sample radius (`shadow.radius`). Default **3**. Higher = softer, wider edges. Lower = harder edges. This is not shadow length and not bloom.

**`shadowCameraLeft` / `Right` / `Top` / `Bottom`**

Ortho box for **standard** directional shadows only (CSM off). Defaults **±50**. Ignored as the coverage box when `useCsmShadows` is on — CSM fits cascades from the play camera instead (`csmMaxFar`, `csmLightMargin`, `csmMode`: `practical` / `uniform` / `logarithmic`, `csmFade` to blend cascade joins).
{% endstep %}

{% step %}

## Change the shadow direction

Rotate the directional light to change where the light comes from. A lower light angle produces longer-looking shadows, while a more overhead angle produces shorter-looking shadows.
{% endstep %}

{% step %}

## Disable unwanted shadows

Disable the setting that controls the shadow you want to remove.

* **To remove every shadow from the directional light,** disable Cast Shadow on the light.
* **To remove one object's shadow,** disable Cast Shadow on that object.
* **To stop a surface from displaying shadows,** disable Receive Shadow on that surface.
  {% endstep %}

{% step %}

## Reset and test the result

Use the reset arrow beside an adjusted value to restore its default. Enter Play mode and check shadow detail, softness, distance, artifacts, and performance from the gameplay camera.
{% endstep %}
{% endstepper %}

## What You've Done

The directional light and scene objects now work together to cast and receive shadows. You can refine the result per object or from the light without affecting unrelated scene elements. If silhouettes vanish at the edge of the level, widen the shadow camera or `shadowFar` before raising `shadowMapSize`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/the-editor/how-to-use-shadow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.