Lights

Lights illuminate the scene. Plinken supports four types: directional, point, spot, and area.

Creating Lights

local light = scene:create_light("Key", "directional")
-- kind: "directional" | "point" | "spot" | "area"

Shared Properties

All light types share these properties:

Property	Type	Access	Default	Description
name	string	r/w	—	Light name
color	color	r/w	{1,1,1}	RGB color
intensity	number	r/w	—	Brightness (lux for directional, candela for point/spot)
enabled	bool	r/w	true	Toggle on/off
position	vec3	r/w	—	World position (or attach to node)
direction	vec3	r/w	—	Light direction (normalized)

Directional Lights

Simulates distant light like the sun. Direction matters, position does not.

local sun = scene:create_light("Sun", "directional")
sun.color = { r = 1, g = 0.95, b = 0.9 }
sun.intensity = 8.0    -- lux
sun.direction = { x = -0.5, y = -1, z = -0.3 }

Point Lights

Emits light equally in all directions from a position.

local bulb = scene:create_light("Bulb", "point")
bulb.position = { x = 3, y = 2, z = 2 }
bulb.intensity = 2000   -- candela
bulb.range = 10.0       -- meters (nil = infinite falloff)

Spot Lights

A cone of light defined by inner and outer angles.

local spot = scene:create_light("Spot", "spot")
spot.position   = { x = 0, y = 4, z = 0 }
spot.direction  = { x = 0, y = -1, z = 0 }
spot.intensity  = 5000
spot.range      = 15.0
spot.inner_cone = 0.2    -- radians (full-intensity core)
spot.outer_cone = 0.4    -- radians (falloff edge)

Area Lights

Soft light emitted from a surface. Shape can be rectangular or disc.

local panel = scene:create_light("Panel", "area")
panel.width  = 1.0
panel.height = 0.5
panel.shape  = "rect"    -- "rect" | "disc"
panel.intensity = 3000

Area lights are currently stubbed — values are stored but not rendered yet.

Per-Light Shadows

Each light can independently cast shadows:

light.cast_shadow       = true     -- default: false
light.shadow_resolution = 2048     -- shadow map size, default: 1024
light.shadow_bias       = 0.005    -- depth bias to reduce shadow acne

See also Shadows for global shadow settings and cascades.

Querying Lights

local lights = scene:get_lights()   -- array of all lights

Destroying Lights

light:destroy()

Example: Three-Point Lighting

-- Key light (main illumination)
local key = scene:create_light("Key", "directional")
key.intensity = 8.0
key.direction = { x = -0.5, y = -1, z = -0.3 }
key.cast_shadow = true

-- Fill light (soften shadows)
local fill = scene:create_light("Fill", "point")
fill.position = { x = 3, y = 2, z = 2 }
fill.color = { r = 0.6, g = 0.7, b = 1.0 }
fill.intensity = 2000
fill.range = 10.0

-- Rim light (edge highlight)
local rim = scene:create_light("Rim", "spot")
rim.position = { x = -2, y = 3, z = -3 }
rim.direction = { x = 0.3, y = -0.5, z = 0.8 }
rim.intensity = 4000
rim.inner_cone = 0.15
rim.outer_cone = 0.35