Manual

Manual

2D lights

2D lights light what a 2D camera draws: torches that glow round them, spots cut by the level's shadows, and the darkness between. This page covers each kind of 2D light and its fields, the shadows sprites and Tilemaps cast, what a 2D light leaves alone, the 2D Lights switch in the Scene view, and how lit a point is from code.

How 2D lighting works

A 2D camera that sees no 2D light draws everything as its art is drawn. As soon as it sees one, it draws lit:

  • Everything starts in the light of the scene's Global Light 2Ds, added together. With none, it starts in darkness.
  • Each Point Light 2D adds its own light round it, as far as its radius, stopped where a Shadow Caster 2D is in the way.
  • The camera's picture is then multiplied by that light: 1 shows what is drawn as it was drawn, 0 is black, 2 twice as bright.

What a camera sees of the lights follows its Culling Mask: a light on a layer the camera does not draw does not light it (see Layers). A light that is hidden, or has an Intensity of 0, lights nothing. Everything the camera draws is lit, its clear color and a 3D camera's picture under it included, except what carries Unlit 2D. The game's interface is never lit. 2D lights light only 2D cameras; 3D cameras use the 3D lights (see Lights).

On a camera that does not draw in HDR, light brightens what is drawn to twice as bright at most.

Make a 2D light

Entity ▸ Light, and Light in the Hierarchy's + menu, make three 2D lights after the three 3D ones:

ItemWhat it makes
Point Light 2DA Point Light 2D shining all round, white, with a Radius of four units and hard shadows.
Spot Light 2DThe same light as a spot: 90 degrees wide, whole across the middle 60, turned to shine down.
Global Light 2DA Global Light 2D, white, showing what is drawn as it is.

A dark level usually has one Global Light 2D with a low Intensity and a cool Color for the dark, and Point Light 2Ds for the torches and windows.

Point Light 2D

A Point Light 2D shines round its entity, or in a cone about the entity's up (+Y). Turn the entity about Z to aim a spot.

FieldWhat it does
ColorIts color.
IntensityHow bright it is where it reaches whole: 1 shows what is drawn as it was drawn, 2 twice as bright.
RadiusHow far it reaches, in units. Nothing past it is lit by it. 4 to begin with.
Inner RadiusHow far it reaches whole, in units, before it falls off toward its Radius.
FalloffHow it falls off from its Inner Radius to its Radius: 1 evenly, more falls off sooner, less later.
Outer AngleHow wide it shines about its entity's up, in degrees: 360 all round, less for a spot.
Inner AngleHow wide it shines whole inside its Outer Angle, in degrees, fading between the two.
ShadowsNone: it shines through everything. Hard, the default: what a Shadow Caster 2D is on casts sharp shadows. Soft: their edges fade as from a light Size units across, 0.25 to begin with; the wider, the softer.

Soft shadows are worked out from twelve points round the light, each a twelfth of it, so they cost more than hard ones. Use them for a few large lights rather than every torch.

In the Scene view

A Point Light 2D is marked by a lightbulb in the Scene panel. When it is picked, its reach is drawn flat on the world's XY plane: a circle for its Radius, or an arc as wide as its Outer Angle, with its Inner Radius and Inner Angle drawn fainter inside. Drag the dots on them to change the Radius, the Inner Radius and the Outer Angle; the Inner Angle is kept no wider than the Outer Angle.

Global Light 2D

A Global Light 2D is the light everything a lit 2D camera draws starts in, wherever it is. Several add up. It is marked by a globe in the Scene panel.

FieldWhat it does
ColorIts color.
IntensityHow bright everything is before any other light: 1 shows what is drawn as it was drawn, less darkens it.

Shadow Caster 2D

Add Component ▸ Shadow Caster 2D has what its entity draws cast shadows from Point Light 2Ds whose Shadows are Hard or Soft.

FieldWhat it does
ShapeOutline, the default: the outline of what shows of its sprite, its clear pixels left out. Rectangle: its sprite's whole rectangle, for a crate or a block that fills it. A Tilemap casts from its solid tiles either way.

The faces of a caster turned toward a light are lit, and so is the caster itself; its shadow begins where the light leaves it. A light inside a sprite that casts, such as a lantern a character carries, is not shadowed by it.

On a Tilemap, a Shadow Caster 2D casts from the outline of its solid tiles, the same outline Physics 2D meets, each tile counting as its tile shape, so a thin wall casts a thin shadow. Its one-way tiles cast from a line along their tops, and tiles whose collision is None cast nothing. A light inside the solid tiles lights only them. Put the Shadow Caster 2D on the Tilemap of walls and ground, and leave it off the background's.

Lights in pixel art

Where the 2D camera is a Pixel Perfect Camera, light and shadow step from art pixel to art pixel, so each pixel of the art takes one light and a shadow's edge follows the art's grid, at any zoom. The Scene panel's view steps by the first Pixel Perfect Camera of the game's. Everywhere else, light is smooth.

The 2D Lights switch

The lightbulb button in the Scene panel's row, 2D Lights, switches the Scene view's 2D lighting on and off. Off, the Scene view shows the scene as its art is drawn, unlit, so you can work on a dark level in full light. It changes only the Scene view: the Game panel and the built game are always lit. The editor keeps the switch as you left it.

How lit a point is from code

world.Lights2D works out how lit a point of the world is, through the same shadows the lights are drawn with: to hide a character in the dark, or have a guard see only what is lit.

// In a flow, or another place that runs between frames.Vector3 light = flow.World.Lights2D.LightAt(new Vector2(4f, 1.5f));   // linear red, green and bluefloat brightness = flow.World.Lights2D.BrightnessAt(new Vector2(4f, 1.5f));bool hidden = brightness < 0.25f;

LightAt gives what multiplies what is drawn there: 1 as drawn, 0 dark, more than 1 brighter. BrightnessAt weighs those three as the eye does, 0 dark and 1 as drawn. Every Global Light 2D and what of every Point Light 2D reaches the point counts, on every layer, with the lights and casters where they are when asked. A game's Rust system that takes the world calls abyss_ffi::light_at.

A light's fields are changed from code as any engine component's are. This system makes every light with a Flicker component of the game's flicker about its own brightness (see How C# sees a Rust component):

[AbyssComponent]public partial struct Flicker{    public float Brightness;                 // the light's Intensity at rest    [HideInInspector] public float Phase;}
// In a plugin's Build:World world = schedule.World;ComponentLayout light = world.LayoutOf("PointLight2D");ComponentField intensity = light["intensity"];ComponentType<Flicker> flicker = world.Component<Flicker>();
schedule.Add("Flicker", [light.Write(), flicker.Write()], context =>{    foreach (Chunk chunk in context.Chunks)    {        FieldView<float> intensities = chunk.GetFieldView<float>(0, intensity);        Span<Flicker> flickers = chunk.GetSpan<Flicker>(1);        for (int row = 0; row < flickers.Length; row++)        {            flickers[row].Phase += context.DeltaTime * 9f;            intensities[row] = flickers[row].Brightness * (1f + (0.1f * MathF.Sin(flickers[row].Phase)));        }    }});

In the Scripting API