Manual
Manual
Lights
Lights shine on what a 3D camera draws. This page covers the three kinds of light, their fields in the Inspector, shadows, the ambient light that keeps a shadow from being black, and lights your game changes as it plays, such as a sun that goes down. For lights in a 2D game, see 2D lights.
Make a light
Entity ▸ Light, or the same menu under the Hierarchy's +, makes one of these:
| Item | What it makes |
|---|---|
| Directional Light | The sun: light shining one way everywhere, made turned down at a slant and casting shadows |
| Point Light | A bulb: light shining every way from where it is, out to its range |
| Spot Light | A torch or a stage light: light in a cone, made pointing down |
The same menu then lists the 2D lights. A scene made from the Basic template, or in the Project panel, has a Directional Light already.
A light is an entity with a Transform. Where a directional light is changes nothing: only the way it is turned does, as it shines along its −Z. A point light shines from where it is, and a spot light from where it is along its −Z.
In the Scene panel, each light shows as an icon in its own color: a sun, a light bulb or a flashlight. Click the icon to pick it. A picked light shows its shape: the sun's disc and its rays, a point light's sphere out to its range, a spot light's cone. A point light's sphere and a spot light's cone have dots on them: drag one to change the light's Range, or a spot light's Outer Angle. Each drag is one Ctrl+Z, and Escape while you drag puts it back.
How strong a light is
A light's strength is in the physical units Bevy uses, and what you see depends on the camera's Exposure too (see Cameras):
| Light | Strength | Starts at |
|---|---|---|
| Directional | Illuminance, in lux: the light falling on each square meter | 10,000, Bevy's daylight |
| Point, spot | Intensity, in lumens: all the light it gives out | 1,000,000 |
As a guide, a sun of 2,000 lux lights a bright day, and 100 lux is moonlight. Every light's Color is a swatch that opens the color picker.
Directional Light
| Field | What it does |
|---|---|
| Color | The light's color. |
| Illuminance | How strong it is, in lux. |
| Shadow Maps Enabled | Whether it casts shadows. Ticked on a directional light the Light menu makes. |
| Contact Shadows Enabled | Whether it casts small contact shadows too, on a camera with Contact Shadows. |
| Affects Lightmapped Mesh Diffuse | Whether it lights a mesh that carries one of Bevy's baked lightmaps. Leave it ticked unless the lightmap already holds this light. |
| Shadow Depth Bias and Shadow Normal Bias | How far its shadows are pushed away from the surfaces that cast them; see Shadows. |
Cascade Shadow Config
A directional light comes with this section, which says how its shadows are spread over distance. Its shadows are drawn into several maps, each covering ground farther from the camera than the one before, so near shadows are sharp and far ones still there.
| Field | What it does |
|---|---|
| Bounds | Where each map ends, in meters from the camera. On a desktop, four maps reach 150 meters. |
| Overlap Proportion | How much each map overlaps the one before, so a shadow does not jump where they meet. |
| Minimum Distance | Where the first map starts, in meters from the camera. |
In a browser, a directional light has one map reaching 64 meters, sharper and much cheaper there; past it nothing casts a shadow.
Point Light
| Field | What it does |
|---|---|
| Color | The light's color. |
| Intensity | How strong it is, in lumens. |
| Range | How far it reaches, in meters: past it, it lights nothing. It starts at 20. |
| Radius | The size of the bulb, in meters, which softens its highlights. 0 is a point. |
| Shadow Maps Enabled | Whether it casts shadows, in every direction. Off to start. |
| Contact Shadows Enabled | Whether it casts small contact shadows too. |
| Affects Lightmapped Mesh Diffuse | Whether it lights a mesh that carries one of Bevy's baked lightmaps. |
| Shadow Depth Bias and Shadow Normal Bias | How far its shadows are pushed away from the surfaces that cast them. |
| Shadow Map Near Z | How near the light its shadows start, in meters. |
Spot Light
A spot light has a point light's fields, and two of its own:
| Field | What it does |
|---|---|
| Outer Angle | How far from the middle of the cone its light reaches, in radians: 0.785, a quarter of pi, is 45 degrees, a cone 90 degrees across. |
| Inner Angle | How far from the middle it is at full strength, in radians; between the two it fades. It starts at 0. |
The Inner Angle must be no wider than the Outer Angle. Dragging the outer angle in the Scene panel brings the inner one in with it where it would be wider, and keeps the cone under 180 degrees across.
Shadows
A light casts shadows when its Shadow Maps Enabled is ticked. A directional light from the Light menu has it ticked; point and spot lights start without, since each light that casts shadows costs time every frame, and a point light's shadows are drawn in six directions.
What casts and receives a shadow is up to each mesh: Cast Shadows and Receive Shadows in its Mesh 3D section.
If a surface shows stripes or specks of shadow where nothing covers it, raise the light's Shadow Depth Bias or Shadow Normal Bias. If shadows look detached from what casts them, lower them. The best values depend on the scene and the scale of what is in it.
Contact Shadows
Add Component ▸ Contact Shadows on a camera has it draw small shadows where things meet, such as a cup on a table, which a shadow map is too coarse to show. A light casts them where its Contact Shadows Enabled is ticked. They are worked out from what the camera sees, so they cost each camera that draws them.
Ambient lighting
Ambient light comes from no direction in particular and lights everything a little, so what no light reaches is not black. Every camera sees by the world's ambient light, white at 80 candela per square meter, unless it carries an ambient light of its own.
Ambient Light
Add Component ▸ Ambient Light on a camera gives it its own:
| Field | What it does |
|---|---|
| Color | The ambient light's color. |
| Brightness | How bright it is, in candela per square meter: about 500 for a day, 50 for a night. It starts at 80. |
| Affects Lightmapped Meshes | Whether it lights meshes that carry a lightmap. |
From code, World.SetAmbientLight gives a camera its own ambient light, and null puts it back to the world's. AmbientLightOf reads it, null where the camera sees by the world's. The world's own ambient light is Bevy's GlobalAmbientLight resource, which your game's Rust can change.
Layers
A light lights every layer, whatever its own layer is and whichever cameras draw what it lights. A camera's Culling Mask decides what is drawn, not what is lit. See Layers.
Lights a game changes as it plays
A day that turns to night changes its sun's color, strength and direction, and the ambient light with it. World.SetLight gives a directional, point or spot light a color, in sRGB, and a strength: lux for a directional light, lumens for the others. LightOf reads them back as a SceneLight, with its Kind. Turning a light is writing its Transform.
Your code reaches a light by its entity. A system that reads Bevy's DirectionalLight finds the sun, and a flow, which runs between frames, changes it:
public sealed class DayPlugin : IPlugin{ private ulong _sun; private ulong _camera;
public void Build(Schedule schedule) { World world = schedule.World; ComponentLayout suns = world.LayoutOf("DirectionalLight"); ComponentLayout cameras = world.LayoutOf("Camera3d");
// Finds the sun and the camera: systems that only read them. schedule.Add("Find the sun", [suns.Read()], context => { foreach (Chunk chunk in context.Chunks) { if (chunk.Entities.Length > 0) _sun = chunk.Entities[0]; } }); schedule.Add("Find the camera", [cameras.Read()], context => { foreach (Chunk chunk in context.Chunks) { if (chunk.Entities.Length > 0) _camera = chunk.Entities[0]; } });
// A day in two minutes: the sun turns, reddens and dims as it sets. schedule.AddFlow("Day", async flow => { float time = 0f; while (true) { await flow.NextFrame(); if (_sun == 0 || _camera == 0) continue;
time += world.Time.DeltaTime / 120f; float angle = time * MathF.Tau; float height = MathF.Sin(angle); // 1 at noon, -1 at midnight float day = Math.Clamp(height * 4f, 0f, 1f);
Quaternion turned = Quaternion.CreateFromYawPitchRoll(0.5f, -angle, 0f); world.WriteTransform(_sun, Transform.Identity with { RotationX = turned.X, RotationY = turned.Y, RotationZ = turned.Z, RotationW = turned.W, });
Vector3 color = Vector3.Lerp(new Vector3(1f, 0.55f, 0.3f), Vector3.One, day); world.SetLight(_sun, color, 2000f * day); world.SetAmbientLight(_camera, new AmbientLighting(new Vector3(0.6f, 0.7f, 1f), 50f + (450f * day))); } }); }}Each of these writes nothing where the light is already as told, so a game can set them every frame. An entity that is no light, or for the ambient light no camera, and a strength below zero are refused with an AbyssException, the light left as it was. The kind of light is its own: SetLight never changes a point light into a spot.
A sky that darkens with the day, and its glow toward the sun, are the camera's: see Sky.
In the Scripting API
- World: SetLight and SetAmbientLight.
- SceneLight and LightKind: a light's kind, color and strength.
- AmbientLighting: the ambient light a camera sees by.
