Lighting internals
Target API: 5 · Target build:
bbb6l5(2026-11-20, production and preprod) · Status: Analyzed (production-bundle JavaScript analysis)blockLightis colored light with three RGB channels. Each light-emitting block defines an emission color[R, G, B](0–15 each) that becomes the light color as-is (regular torch = warm white (14,14,12) / lava = orange (14,8,2) / beacon = cyan (5,14,14) / white torch = (15,15,15), etc.). At the vertex stage it arrives packed as 4 nibbles — r / g / b / sky — in one float attribute. Handling the three channels separately inside the light hook enables colored local lighting — the warm-torch recipe (R9.1) is calibrated against this behavior.
When decoding aPackedLightLevels, the engine floors each channel at 35% of the brightest RGB channel. E.g. a “pure red light” is lifted to (1.00, 0.35, 0) at vertices before interpolation and lift. Torch orange looking “whitish-pink rather than red” in game comes from this — tune warm-torch recipe (R9.1) saturation against this default.
Light composition is not additive. Internally the engine takes the max of block light (after the 35% floor) and sky light built as mix(ambient colour, sky colour, skyLight), then takes max again with held light (after ambient boost). The channel values in this composition are the post-lift values — the engine composes from the same lifted light levels that reach hook inputs (terrainLightLevels after the lift curve), Therefore blockLight and skyLight never cancel each other out — the darker side’s contribution is simply discarded — so weakening sky light barely darkens spots dominated by block light. Design exposure/decay recipes around this structure (the local-light protection in Designing night looks exists to compensate for it).
Handheld light (heldLight) range follows the brightest light-color channel (max 15 blocks) with dist^0.75 preprocessing, the same 35% channel floor, and l.heldLight is the pre-ambient-boost value. The cone falloff, restored from the engine’s light module: the beam’s angular attenuation is 1 − 0.5 × (smoothstep(0.12, 0.65, t) + smoothstep(0.62, 0.95, t)) where t is the normalized angle from the cone axis (0 = center, 1 = edge); the reach is (rangeOverride > 0 ? rangeOverride : brightest channel) × cone falloff with rangeOverride read from the held-light colour’s alpha; inside the reach, an override attenuates by (range − dist) / range while the default subtracts the (preprocessed) distance channel-wise; then comes the 35% floor, division by 15, the lift curve, and finally the ambient boost. Custom items can set spotlightRange and cone angle — a “beam while held” mode whose cone position follows the camera. Packs cannot know beam direction.
Custom blocks may carry skyLightEmission (0–15), which injects into the skyLight channel itself, separately from blockLight BFS. R9.12-style packs judging sun/shadow by skyLight threshold can misjudge in worlds where artificial lights lift skyLight. Distribution packs should judge combined with blockLight to stay robust.