Skip to Content

Lighting

Target API: 5 · Target build: bbb6l5 (2026-11-20, production and preprod) · Status: Analyzed (restored verbatim from the live header)

v5 published the lighting API. What the engine did internally (building litColour) is now callable from packs. This page covers the lighting inputs, functions, and processing order as a system.

The full pipeline

The complete color chain, as the default light-stage implementation (bloxdDefaultLight) shows it:

surface.colour │ mix with overlayColour (mix(colour, overlay.rgb, overlay.a)) ▼ overlaid │ multiply by bloxdShading(light) — material & angle response ▼ shaded │ mix with enchantColour (mix(shaded, enchant.rgb, enchant.a)) ▼ enchanted │ multiply by bloxdWorldLight(light) — world light (brightest of block/sky/held) ▼ lit = bloxdLitColour(surface, light) ← the color "before emission and fog" │ + surface.emission ← emission added after lighting ▼ │ bloxdApplyFog(colour, light) ← mix(colour, fogColour, fogAlpha) ▼ BloxdLight.colour (final color)

bloxdLitColour() order (header summary: “mixed with overlayColour, then bloxdShading, then mixed with enchantColour, then bloxdWorldLight”):

  1. apply overlayColour
  2. shade with bloxdShading()
  3. apply enchantColour
  4. apply world light with bloxdWorldLight()

Emission and fog order: emission is added after lighting and before fog, and fog sinks emission too (bloxdDefaultLight = bloxdApplyFog(lit + emission, light)).

Functions

bloxdLit() — the gate

fn bloxdLit() -> bool

Whether block & sky lighting is on. Guarantees when off:

FieldValue when off
blockLight / heldLight0
skyLight1
ambientLightColour / skyLightColour1 (white)

v4’s #ifdef BLOXD_LIGHTING is gone. Replace with if (!bloxdLit()) { return bloxdDefaultLight(...); }.

bloxdShading() — material & angle response

fn bloxdShading(light: BloxdLightIn) -> vec3f { let diffuse = light.directional * light.diffuse; return saturate(diffuse + light.emissive + light.ambient); }
  • multiplies directional (summed Lambert) by diffuse (material RGB response), adds emissive (material glow) and ambient (RGB ambient), clamps to 0–1
  • the new v5 inputs diffuse / emissive let you swap just the Lambert term while keeping the engine’s material response

bloxdWorldLight() — the world’s light

fn bloxdWorldLight(light: BloxdLightIn) -> vec3f { let ambientLight = light.ambientLightColour; let blockLight = ambientLight + light.blockLight * (1.0 - ambientLight); let skyLight = mix(ambientLight, light.skyLightColour, light.skyLight); let heldLight = ambientLight + light.heldLight * (1.0 - ambientLight); return max(max(blockLight, skyLight), heldLight); }
  • shapes each of the three channels (block / sky / held) with ambientLightColour as the floor, then takes the brightest
  • skyLight interpolates from ambientLightColour toward skyLightColour by the sky-light amount

bloxdLitColour() — the engine recipe

fn bloxdLitColour(surface: BloxdSurface, light: BloxdLightIn) -> vec3f { let overlay = surface.overlayColour; let overlaid = mix(surface.colour, overlay.rgb, overlay.a); let shaded = bloxdShading(light) * overlaid; let enchant = surface.enchantColour; let enchanted = mix(shaded, enchant.rgb, enchant.a); return max(enchanted * bloxdWorldLight(light), vec3f(0.0)); }

bloxdApplyFog() — fog

fn bloxdApplyFog(colour: vec3f, light: BloxdLightIn) -> vec3f { return mix(colour, light.fogColour, light.fogAlpha); }
  • fogAlpha: 0 = no fog, 1 = only fogColour (inverted from v4’s fogVisibility)
  • fogColour is the game’s fog RGB; vec3f(0.0) when the game has no fog

bloxdDefaultLight() — the whole default

fn bloxdDefaultLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { let lit = bloxdLitColour(surface, light); return BloxdLight(bloxdApplyFog(lit + surface.emission, light)); }

Input fields (BloxdLightIn)

FieldTypeMeaningNote
litColourvec3flit & enchanted RGB (before emission and fog)a result value, not a source
directionalf32summed Lambert from directional lights0 when no directional lights
diffusevec3fmaterial RGB response to directional lightlets bloxdShading() rebuild the material response
emissivevec3fmaterial RGB glow (added to directional)
ambientvec3fRGB ambient (added to directional)
blockLightvec3fRGB block light0 when !bloxdLit()
skyLightf32sky light1 when !bloxdLit()
ambientLightColourvec3fminimum RGB light (floor)1 when !bloxdLit()
skyLightColourvec3fRGB color of skyLight1 when !bloxdLit()
heldLightvec3fRGB held light0 when !bloxdLit() or nothing held
fogColourvec3fgame fog RGB0 with no fog
fogAlphaf320 = no fog, 1 = only fogColourinverted from v4 fogVisibility

Light-level physics (background, skippable)

  • blockLight / skyLight / heldLight arrive mapped to 0–1: the 0–15 levels through an ease-out curve (e.g. 6 → 0.45, 12 → 0.92). All exclude ambientLightColour
  • Lift curve: skyLight is really “can this position see the sky” — voxel occlusion data, i.e. a shadow map. Threshold-based sun/shade separation may need the inverse transform (see the realism guide)
  • Fog internals: in linear mode fogAlpha = 1 - (fogEnd - dist) / (fogEnd - fogStart) (clamped 0..1), computed per vertex in view space. The current build is linear-only (details in Engine Internals: Fog Internals)

Recipes

Custom shading + the engine’s world light

What v4 authors approximated by scaling litColour can now be written exactly:

fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { let nDotL = light.directional; // already summed Lambert let wrapped = nDotL * 0.5 + 0.5; let shaded = saturate(wrapped * light.diffuse + light.emissive + light.ambient); let colour = max(shaded * bloxdWorldLight(light), vec3f(0.0)); return BloxdLight(bloxdApplyFog(colour + surface.emission, light)); }

Keep the engine’s world light, boost emission only

fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { let lit = bloxdLitColour(surface, light); return BloxdLight(bloxdApplyFog(lit + surface.emission * 2.0, light)); }

Night blue shift (skyLight-driven)

fn bloxdTerrainLight(surface: BloxdSurface, light: BloxdLightIn) -> BloxdLight { if (!bloxdLit()) { return bloxdDefaultLight(surface, light); } var out = bloxdDefaultLight(surface, light); let night = 1.0 - light.skyLight; out.colour = mix(out.colour, out.colour * vec3f(0.75, 0.82, 1.15), night * 0.6); return out; }