> 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-set-up-a-light.md).

# How to set up a light

Use **one directional light** for the sun or moon (rotate it; turn **Cast Shadow** on). Use **point lights** as local fill: colour, intensity, Distance, Decay. Leave **Cast Shadow** **off** on those fills. Ambient (or hemisphere) lifts the whole scene without a shadow map.

A kitbashed level often needs many point lights. That is fine. Each extra light with **Cast Shadow** on adds another shadow pass. Keep maps on the directional light. See [How to use shadow](/the-editor/how-to-use-shadow.md).

Aim a directional light by **rotating** it. Moving it around the map does not change the sun direction. Pair it with Scene Environment: [How to Set Up a Skybox](/the-editor/how-to-set-up-a-skybox.md).

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

{% hint style="info" %}
*NOTE: Point lights illuminate a local area, ambient light affects the whole scene, and directional lights provide a consistent direction suitable for sunlight or moonlight.*
{% endhint %}

If the Outliner shows a parent row named Point Light with a child, select the child that has **Distance**, **Decay**, and **Intensity**. That child is `ENGINE.PointLightNode`.

{% stepper %}
{% step %}

## Add or select the directional light

A new scene already has a Directional Light. To add another, use the Lights tools on the left toolbar.

Rotate it to aim. Set colour and intensity. Turn **Cast Shadow** **on** for this light only (the main silhouette).

Do not add a second directional light to “fill” the dark side. Use ambient or point lights instead. Only one directional light can drive CSM. Details: [How to use shadow](/the-editor/how-to-use-shadow.md).
{% endstep %}

{% step %}

## Add a Point Light for fill

Open the primitives or Lights panel on the left and select Point Light. A new point light appears in the scene.
{% endstep %}

{% step %}

## Move the point light into position

Select the light and use the X, Y, and Z transform controls to place it near the area you want to illuminate. Watch how nearby objects react as the light moves.
{% endstep %}

{% step %}

## Configure the point light

With the Point Light Node selected, use the Inspector.

**Colour** — warm for lamps and fire; cooler for night or tech.

**Intensity** — brightness of this local pool.

**Distance** — how far the light reaches.

**Decay** — how quickly it falls off with range.
{% endstep %}

{% step %}

## Leave Cast Shadow off on fill lights

Keep **Cast Shadow** **off** on point (and spot) fills. The directional light already draws the world silhouette.

Turn **Cast Shadow** on a point light only when you need a local silhouette (a hard lamp shadow on a nearby wall). That costs extra every frame.

Meshes still need their own **Cast Shadow** and **Receive Shadow** for any light that casts. Kit meshes default both **off** after a drag. See [How to use mesh models and ModelMesh nodes](/the-editor/how-to-use-mesh-models-and-modelmesh.md).
{% endstep %}

{% step %}

## Add Ambient Light if the unlit side is too black

Select Ambient Light from the left panel.

**Ambient colour** tints the whole scene. **Ambient intensity** lifts dark areas. Too much flattens contrast.

Hemisphere Light is another fill with no shadows: a sky colour and a ground colour. Leave its position alone.
{% endstep %}

{% step %}

## Place more fills as needed

Duplicate the point-light setup (or add more from the Lights panel) for other local pools. Tune one light at a time. Temporarily disable a light to see what it contributes.

{% hint style="info" %}
*TIP: Avoid raising every light equally. A clear main source, readable fill, and limited local highlights create more depth than uniform brightness.*
{% endhint %}
{% endstep %}

{% step %}

## Test from the gameplay camera

Enter Play mode. Check direction, colour, intensity, Distance, Decay, and that only the sun/moon light is casting the big shadows.
{% endstep %}
{% endstepper %}

## Common mistakes

| What went wrong                                       | What to do                                                                                                                                            |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frame rate drops after adding lamps                   | **Cast Shadow** off on point lights. Keep maps on one directional.                                                                                    |
| Two suns, two shadow directions                       | One directional with **Cast Shadow**. Fills are point or ambient.                                                                                     |
| Moved the directional light and nothing changed       | Rotate it.                                                                                                                                            |
| Point light in the Outliner but Inspector looks empty | Select the **Point Light Node** child.                                                                                                                |
| Kit still unlit under a lamp                          | **Receive Shadow** / **Cast Shadow** on meshes, and Env Map / directional intensity. [How to Set Up a Skybox](/the-editor/how-to-set-up-a-skybox.md). |

{% hint style="info" %}
*TIP: The left panel also has Spot, Hemisphere, and Rect Area lights. Spot is a cone (shadows optional, same cost rule). Rect area is a glowing rectangle with no shadows.*
{% endhint %}

## What You've Done

You have one shadowed directional light, local point fills without extra maps, and optional ambient. Next: [How to use shadow](/the-editor/how-to-use-shadow.md) if silhouettes are missing or too soft, or [How to Set Up a Skybox](/the-editor/how-to-set-up-a-skybox.md) if the backdrop and IBL still fight the sun.


---

# 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-set-up-a-light.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.