leafType(identity: string) → string

The leaf of a component identity: "@builtin::components.SpotLight" is "SpotLight", the vocabulary the kind map and every consumer speak.

declaresKind(component: any) → boolean

Whether a component declares a `kind` field of its own. Asked of the component through its field descriptors, which answer for any component — so the question is settled before the field is read, and a component that declares none is never asked for it.

lightKind(componentType: string, component: any?) → string

The kind a light-role component names — `"point"`, `"spot"`, `"directional"`, `"ambient"`, `"distant"` or `"area"`. A type standing for exactly one kind spells it in its name (`SpotLight` is `"spot"`); a type covering several declares a `kind` field naming which one it is, the way `Light` does, and the field is read only from a component that declares one. So a world's own light component answers here on the same terms the engine's do. `nil` when the component names no kind.

local kind = lighting.lightKind("SpotLight")

lightsDefaultLayer(id: string) → boolean

Whether the entity `id` lights the default render layer — the layer the scene's sun and ambient term belong to, and the one an entity with no render layer of its own lands on. A light confined to other layers reaches the cameras on those layers through its own scoped record and holds neither singleton, so the scans below pass over it. Read guarded: an entity mid-teardown answers nothing, and nothing is on no layer.

lightComponentsOf(e: any) → void

Every light-role component on an entity, each paired with the type that names its kind. An entity may carry several — a spot beside the sun's `Light`, a fill `DirectionalLight` on the same holder — so the question "which light on this entity" is answered by kind rather than by taking whichever one the entity reports first.

lightOfKind(entityId: string, kind: string) → any

The light-role component of `kind` on one entity. An entity may carry several lights — a cone beside the sun's `Light`, a fill on the same holder — so this is how a caller reaches the one it means instead of whichever the entity reports first.

local sun = lighting.lightOfKind(holder, "directional")

lightIsOn(light: any) → boolean

Whether a light component is switched on. A switched-off component's row is out of the renderer, so it holds neither of the scene's singleton field sets whatever kind it names. `enabled` is the engine's own property on every component, so every light answers it.

scanForLightKind(kind: string, exclude: string?, onlyOn: boolean?) → string

scanForHolder(kind: string, exclude: string?) → string

The first entity that can HOLD the scene's `kind` field set: a switched-on light-role component of that kind, other than `exclude`.

resolveSunEntity( ) → string

A singleton field set resolves from the renderer's own answer first: the snapshot names the `Light` entity the frame's sun and the frame's ambient term are each carried by, so the write lands on the light the read reports. The snapshot is a frame behind, so a light spawned THIS frame is not in it yet — the component scan covers that gap, and it is what prices the resolve by the scene rather than by its lights.

resolveAmbientEntity( ) → string

upsertLightEntity(kind: string, resolvedId: string?, label: string, fields: { [string]: any }, spawnDefaults: { [string]: any }) → string

Patch the resolved light in place, or spawn a fresh entity when the scene has none: only the provided fields change, so a partial update never resets authored values. A patched component keeps its identity, its private bake state, and its live row — replacing it would hand the scene a different light that merely looks the same. A fresh spawn starts from `spawnDefaults`; `label` names only the NEW entity, it resolves nothing. `kind` picks WHICH light on the resolved entity is patched: an entity may carry a fill or a cone alongside the one holding a singleton field set, and the patch belongs to the one whose kind the caller named.

resolveSkyEntity( ) → string

The scene's sky entity — the one carrying a sky-role component (ProceduralSky / Skybox). Identity by component, same as the lights.

applySetup(opts: SetupOpts) → SetupResult

Apply a lighting setup in one call. All fields optional — only provided fields change (read-merge-write; unspecified fields keep their authored values). `sun` and `ambient` patch the scene's resolved sun / ambient light components, spawning a carrying entity when the scene has none. `sky` writes the sky entity's ProceduralSky component the same way — any of its fields, plus `enabled = false` to remove the sky component. `clearColor` is `{r, g, b}`. Returns the entity ids each provided section resolved to.

setSun(opts: SunOpts) → string

Set the scene's sun, the same opts `applySetup`'s `sun` section takes. Read-merge-write: only the fields given change, so `{ intensity = 2 }` keeps the authored direction and colour. The light is resolved by component, and a scene carrying none is given one. castsShadows?: boolean }`.

lighting.setSun({ intensity = 2.4, color = { 1, 0.95, 0.85 } })

setAmbient(opts: AmbientOpts) → string

Set the scene's ambient term, the same opts `applySetup`'s `ambient` section takes. Read-merge-write: only the fields given change, so `{ intensity = 0.5 }` keeps the authored colour. The light is resolved by component, and a scene carrying none is given one.

lighting.setAmbient({ intensity = 0.5 })

lightScans( ) → number

How many times, since the module loaded, a light was reached by walking the scene's entities rather than through the record its own component published. A write that finds its light through the record leaves this count where it was, whatever the scene holds; one that walks the scene raises it by one per walk. Read it either side of a write to know which the write was.

local before = lighting.lightScans(); lighting.setAmbient({ intensity = 0.5 }); assert(lighting.lightScans() == before)

__registerSun(record: Sun?) → void

Publish the scene's sun — called by the `Light` component whenever the directional light it carries wakes, changes, or goes away. Nothing else should call this: the component is the one that knows.

__lightsDefaultLayer(id: string) → boolean

Whether the entity `id` lights the default render layer — the layer the scene's sun and ambient term belong to. A `Light` confined to other layers reaches the cameras on those layers through its scoped record and holds neither singleton, so it asks here before publishing itself as the sun.

__resolveSun(exclude: string?) → void

Find a directional light in the scene and publish it as the sun. Called by a `Light` component that is giving the sun up — despawned, switched off, or no longer directional. A scene may carry several directional lights, so which one holds the sun is a question about the SCENE, not about the light that is leaving: the departing one cannot know who should take it. Only a switched-on light can take it, the renderer holding no row for one that is off. This scans, which is why it runs only on that handoff and never per frame. does so and is therefore skipped.

sun( ) → Sun

The scene's sun: the values its directional `Light` currently carries. A table read when a component holds the sun — safe to call every frame.

local s = lighting.sun(); print(s.intensity, s.direction[2])

directionals( ) →

Every directional light with its render layer scope: one record per light entity, each carrying `entityId`, `layerMask` (the render layer mask of the entity carrying it — cameras whose include mask intersects it are lit by it), `color`, `intensity`, `direction` and `castsShadows`. A light on an entity with no explicit render layer records the default layer.

for _, d in lighting.directionals() do print(d.entityId, d.layerMask) end

ambients( ) →

Every ambient light with its render layer scope, on the same terms as `directionals`: one record per light entity, each carrying `entityId`, `layerMask`, `color` and `intensity`.

for _, a in lighting.ambients() do print(a.entityId, a.layerMask) end

ambient( ) → Ambient

The scene's ambient term: the colour and intensity the frame's ambient light is shaded by, as the renderer resolved it. The term is one field set with one holder, so `entityId` names the ambient `Light` whose values it carries — a scene carrying several ambient lights reads here which of them the frame is shaded by, and the rest are authored and unread until one of them takes the term. ambient lights the scene.

local a = lighting.ambient(); print(a.intensity, a.entityId)

setProbeVolume(key: string, volume: { [string]: any }) → void

Publish (or replace) the irradiance light-probe volume under `key`: `volume` is { boundsMin = {x,y,z}, boundsMax = {x,y,z}, res = {x,y,z}, sh = {...} } where `sh` is the baked SH L2 field as a flat float array (9 vec4 = 36 floats per probe, X-fastest then Y then Z). A scene carries one entry per baked volume (adaptive brick set); every standard-PBR fragment inside a volume's bounds takes its ambient term from the covering field(s) instead of the flat ambient light. `VolumeProbe.bake` publishes each freshly baked field through here automatically.

lightRows( ) → void

Every punctual light in the scene as the renderer resolved it this frame: world-space `position`, `direction`, `color`, `intensity`, `radius`, the spot cone as `coneInnerCos`/`coneOuterCos`, and an area light's rect as `tangentU`/`tangentV` with `halfWidth`/`halfHeight` and `twoSided`. `kind` is "point", "spot", "area", or "distant", and `entityId` names the carrying entity when one exists. Every vector is a `{x, y, z}` array. A "distant" row is parallel light arriving from `direction` everywhere in the world — a second star, a moon, a fill from the far side. Its `direction`, `color` and `intensity` are what the shading reads, and its `radius` is 0: distance does not attenuate parallel light. The scene's sun is a single field rather than a row: read it with `lighting.sun()`. The transform hierarchy is already applied, so anything that has to shade the same lights the renderer does — a GI bake, a lighting inspector — reads world space here instead of re-deriving it from components. `shadowSlot` is where a shadow-casting point light was seated in the point-shadow cube pool, and `-1` when it was not: the pool holds `renderer.pointShadowBudget().slots` lights, and a caster past it renders lit with no shadow. `shadowLayer` and `shadowResolution` say the same for a spot or a rect: the spot-shadow atlas layer its depth map went into and the texel resolution it was given there, with `-1` for a caster the atlas had no tile left for.

removeProbeVolume(key: string) → void

Retract the irradiance light-probe volume published under `key` (volume removed / bake cleared). An empty key clears every published volume; fragments outside every remaining volume fall back to the flat ambient light term.