Light
A software 2D light-accumulation pass over the framebuffer, run in a render phase after drawing the scene and before Screen.show. Light.ambient multiplies the whole scene toward a tint — the night/cave modulate that darkens everything so lights add mood back on top. Light.point accumulates a radial glow that falls off with distance and clamps per channel, and Light.occlude registers rectangles that block a light's rays to cast hard shadows (cleared each frame with Light.clear_occluders). Lighting is a rendering concern only — it never touches game state or replays — and it is fully deterministic (integer and Q16.16 fixed), so the same scene lights identically every run and in a headless render, keeping screenshots diffable. Colours are 0x00RRGGBB. Beyond the radial core, the pass carries the render-quality tiers: Light.spot cones, a Light.falloff exponent, Light.soft shadows (penumbra), Light.gel colour cookies, normal-mapped surfaces (Light.normal + Light.height) that shade by facing, and a Light.time_of_day day/night ramp — every one deterministic. This is the imperative surface; the engine also consumes Light2D/Occluder components automatically (a Light2D may carry optional direction/spread/falloff/softness/gel fields). Related: Screen, Color, Camera.
Light.ambient(color)Multiply the whole scene by a tint — the night/cave modulate.Light.point(x, y, radius, color, energy)Add a radial glow that falls off with distance.Light.occlude(x, y, width, height)Register a rectangle that blocks light — a hard shadow caster.Light.clear_occluders()Forget every occluder — call once per frame before re-registering.Light.spot(x, y, radius, color, energy, direction, spread)A cone / flashlight light aimed at a direction with a half-angle spread.Light.falloff(exponent)Set the brightness-ramp exponent for later lights (1 linear, 2 quadratic…).Light.soft(radius)Soft shadows — an occluder edge fades through a penumbra of this radius.Light.gel(color)A colour cookie — later lights gel from their centre colour to this rim colour.Light.clear_gel()Clear the gel — later lights are a flat single colour again.Light.normal(x, y, width, height, nx, ny)Stamp a surface normal over a rectangle so lights shade it by facing (N·L).Light.clear_normals()Forget every stamped normal — call once per frame before re-stamping.Light.height(height)Set the virtual height of lights above the surface, for normal-map shading.Light.time_of_day(t)Set the ambient tint from a 0..1 time-of-day — a day/night cycle in one value.