# 2D Lighting

SimVX provides 2D lighting with point lights, directional lights, and shadow-casting occluders.

## Point Lights

`PointLight2D` emits light radially from its position:

```python
from simvx.core import PointLight2D, Vec2

light = PointLight2D(
    position=Vec2(400, 300),
    colour=(1.0, 0.8, 0.4),
    energy=1.5,
    range=200.0,
    falloff=2.0,        # 1.0=linear, 2.0=quadratic, 0.5=sqrt
)
self.add_child(light)
```

## Directional Lights

`DirectionalLight2D` applies uniform lighting across the entire scene:

```python
from simvx.core import DirectionalLight2D

sun = DirectionalLight2D(
    direction=(0.5, -1.0),   # Normalized automatically
    colour=(1.0, 1.0, 0.9),
    energy=0.8,
)
self.add_child(sun)
```

## Shadow Occluders

`LightOccluder2D` casts shadows from light sources. Define a polygon in local coordinates:

```python
from simvx.core import LightOccluder2D

wall = LightOccluder2D(
    polygon=((0, 0), (100, 0), (100, 20), (0, 20)),
    position=Vec2(200, 400),
)
self.add_child(wall)
```

Enable shadows on the light:

```python
light.shadow_enabled = True
light.shadow_colour = (0, 0, 0, 0.8)  # Semi-transparent shadows
```

## Light Properties

| Property | Default | Description |
|----------|---------|-------------|
| `colour` | `(1, 1, 1)` | RGB, 0.0–1.0 |
| `energy` | `1.0` | Intensity multiplier |
| `range` | `100.0` | Radius in pixels |
| `blend_mode` | `"add"` | `"add"` or `"mix"` |
| `enabled` | `True` | Toggle light on/off |
| `shadow_enabled` | `False` | Enable shadow casting |
| `shadow_colour` | `(0, 0, 0, 1)` | Shadow fill colour (RGBA) |
| `light_cull_mask` | `0xFFFFFFFF` | Bitmask for selective lighting |

## Example

See `packages/graphics/examples/2d_light.py` for a complete demo with multiple coloured lights and occluders.

## API Reference

See {py:mod}`simvx.core.light2d` for the complete 2D lighting API.