2D lighting¶

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

Point lights¶

PointLight2D emits light radially from its position:

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:

from simvx.core import DirectionalLight2D

sun = DirectionalLight2D(
    direction=(0.5, -1.0),   # normalised 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:

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:

light.shadow_enabled = True
light.shadow_colour = (0.0, 0.0, 0.0, 0.75)  # a = shadow strength; rgb = residual tint
light.shadow_softness = 1.5                   # widen the soft (PCF) penumbra

Shadows use a per-light 1D shadow map sampled with PCF, so they are soft (penumbra widens with shadow_softness) and never bleed between lights: each light is occluded only by its own shadow. Point lights cast radial shadows; DirectionalLight2D casts parallel shadows along its direction. The technique is identical on the desktop (Vulkan) and web (WebGPU) backends, and is entirely zero-cost when no light has shadow_enabled.

shadow_colour is (r, g, b, a) where a is the shadow strength (fraction of light removed in full shadow: 1.0 = fully dark, 0.5 = half) and rgb tints the residual light in shadow (default black = plain darkening).

Light properties¶

Property	Default	Description
`colour`	`(1, 1, 1)`	RGB, 0.0 to 1.0
`energy`	`1.0`	Intensity multiplier
`range`	`200.0`	Radius in pixels (sizes the shadow map for directional lights)
`blend_mode`	`"add"`	`"add"` or `"mix"`
`enabled`	`True`	Toggle light on/off
`shadow_enabled`	`False`	Enable shadow casting
`shadow_colour`	`(0, 0, 0, 0.5)`	`a` = shadow strength, `rgb` = residual tint
`shadow_softness`	`1.0`	PCF penumbra width (`0` = hard edge)
`light_cull_mask`	`0xFFFFFFFF`	Bitmask for selective lighting

Example¶

See examples/features/2d/light.py for a complete demo with multiple coloured lights and shadow-casting occluders.

API reference¶

See simvx.core.light2d for the complete 2D lighting API.