surfaceLight

Rectangular area lights — a screen, window or strip that emits from its whole surface.

local surfaceLight = require("@builtin::systems.areaLights.surfaceLight")

surfaceLight.set("tv", {
    position = { 0, 2, 0 },
    right = { 1, 0, 0 }, up = { 0, 1, 0 },
    width = 2, height = 1.2,
    range = 12, color = { 0.6, 0.8, 1 }, intensity = 5,
})
surfaceLight.remove("tv")
surfaceLight.configure({ specular = 0.5 })
surfaceLight.count()
surfaceLight.active()
surfaceLight.clear()

Lights are keyed by a caller-chosen string. Re-submitting the same key moves that light rather than adding another, which is what lets a component push its rectangle every frame as its entity moves.

right and up are the rectangle's own axes; their cross product is the direction it emits, so a surface behind the emitter receives nothing.

diffuse and specular scale the two terms separately: the wash across a surface, and the reflected shape of the emitter.

For a light that should follow an entity's face, author the SurfaceLight component instead. This module is for code placing emitters directly.

The full description is in the package readme: guides { path = "systems/areaLights" }.