Skip to Content
RecipesRealism

Realism

Target API: 5 · Target build: bbb6l5 (2026-11-20, production and preprod) · Status: Verified (ported to the current API — on-device re-check recommended) Physical recipes for “rebuilding vanilla’s look from materials”. Read these premises first:

  1. The light hook is called at the final fragment stage. Its returned colour becomes the final colour as-is. You must re-apply fog yourself (R9.10)
  2. The engine’s default lighting is multiplication only. Specular / fresnel / warm-cool separation / hemisphere ambient can all be built from zero
  3. l.engineColour is the finished color (already fogged). Rebuilding from s.colour (albedo) is the full-fledged approach
  4. Textures are prohibited → all detail must be procedural (hash/noise) (R9.8)

R9.1 Warm torches × cool skylight

fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let blockInt = max(l.blockLight.r, max(l.blockLight.g, l.blockLight.b)); let torch = mix(l.blockLight, blockInt * vec3f(1.00, 0.72, 0.42), 0.55); let sky = mix(l.ambientLightColour, l.skyLightColour, l.skyLight) * vec3f(0.90, 0.95, 1.08); let voxel = max(torch, sky); var col = clamp(s.colour * voxel, vec3f(0.0), vec3f(1.0)); // intermediate clamp col = mix(l.fogColour, col, (1.0 - l.fogAlpha)); // fog redo out.colour = col + s.emission * (1.0 - l.fogAlpha); // emission re-add } return out; }

R9.2 Sun specular (Blinn-Phong)

fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let n = normalize(l.normal); let viewDir = normalize(bloxdEyePosition() - l.position); let sunLen = length(bloxdSunDirection()); if (sunLen > 0.5) { let sunDir = bloxdSunDirection() / sunLen; let h = normalize(viewDir + sunDir); // half vector let ndh = max(dot(n, h), 0.0); let lambert = clamp(dot(n, sunDir), 0.0, 1.0); let spec = pow(ndh, 90.0) * 0.38 * lambert * (0.25 + 0.75 * l.skyLight); out.colour += spec * vec3f(1.0, 0.97, 0.90); } } return out; }

R9.3 Schlick fresnel

fn pack_schlick(cosT: f32, f0: f32) -> f32 { return f0 + (1.0 - f0) * pow(1.0 - clamp(cosT, 0.0, 1.0), 5.0); } fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let n = normalize(l.normal); let viewDir = normalize(bloxdEyePosition() - l.position); let F = pack_schlick(dot(n, viewDir), 0.02); out.colour += F * 0.15 * l.skyLightColour * l.skyLight; // faint edge brightness } return out; }

R9.4 Hemisphere ambient (sky above / ground bounce below)

fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let n = normalize(l.normal); let upness = n.y * 0.5 + 0.5; let ground = l.ambientLightColour * 0.55; // below: bounce let skyH = l.ambientLightColour * 0.30 + l.skyLightColour * 0.45 * l.skyLight; // above: skylight let hemi = vec3f(0.25) + mix(ground, skyH, upness); let voxel = mix(l.ambientLightColour, l.skyLightColour, l.skyLight); var col = clamp(s.colour * voxel * hemi, vec3f(0.0), vec3f(1.0)); // intermediate clamp col = mix(l.fogColour, col, (1.0 - l.fogAlpha)); // fog redo out.colour = col + s.emission * (1.0 - l.fogAlpha); // emission re-add } return out; }

R9.5 ACES filmic (Narkowicz approximation)

fn pack_aces(x: vec3f) -> vec3f { return clamp((x * (vec3f(2.51) * x + vec3f(0.03))) / (x * (vec3f(2.43) * x + vec3f(0.59)) + vec3f(0.14)), vec3f(0.0), vec3f(1.0)); } fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); out.colour = pack_aces(out.colour * 1.2); // 1.2 = exposure return out; }

R9.6 Aerial perspective (“atmosphere” via distance desaturation)

Unlike fog (color replacement), layering “distance desaturation” makes distant views much more realistic.
Caution: only reduce saturation — never touch luminance.

fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); let dist = distance(bloxdEyePosition(), l.position); let aerial = 1.0 - exp(-dist * 0.0035); // falloff (~30% at 100blk / ~75% at 400blk) let luma = dot(out.colour, vec3f(0.2126, 0.7152, 0.0722)); let hazy = mix(vec3f(luma), out.colour, 0.5); // reduce saturation only (luminance unchanged) out.colour = mix(out.colour, hazy, aerial * 0.16); return out; }

R9.7 Wave normals + sun glitter (“sun road” on water)

fn pack_waveNormal(p: vec3f, t: f32) -> vec3f { // height h = 0.50 sin(px+1.6t) + 0.35 sin(1.35pz+1.28t) + 0.15 sin(0.7(px+pz)-1.76t) let c1 = cos(p.x * 1.00 + t * 1.60); let c2 = cos(p.z * 1.35 + t * 1.28); let c3 = cos((p.x + p.z) * 0.70 - t * 1.76); let dhdx = 0.50 * c1 + 0.15 * 0.70 * c3; // dh/dx let dhdz = 0.35 * 1.35 * c2 + 0.15 * 0.70 * c3; // dh/dz return normalize(vec3f(-dhdx * 0.55, 1.0, -dhdz * 0.55)); } fn bloxdLiquidLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let baseN = normalize(l.normal); let worldPos = bloxdWorldPosition(l.position); let n = normalize(mix(baseN, pack_waveNormal(worldPos, bloxdSeconds()), clamp(baseN.y * 2.0, 0.0, 1.0))); let viewDir = normalize(bloxdEyePosition() - l.position); let sunLen = length(bloxdSunDirection()); if (sunLen > 0.5) { let sunDir = bloxdSunDirection() / sunLen; let h = normalize(viewDir + sunDir); let glint = pow(max(dot(n, h), 0.0), 240.0) * 1.1 * (0.25 + 0.75 * l.skyLight); out.colour += glint * vec3f(1.0); } } return out; }

R9.8 Procedural micro-bump (texture-ban workaround)

fn pack_hash(p: vec3f) -> f32 { return fract(sin(dot(p, vec3f(12.9898, 78.233, 37.719))) * 43758.5453); } fn pack_bumpNormal(p: vec3f, n: vec3f, strength: f32) -> vec3f { let e = 0.15; let h0 = pack_hash(p); let hx = pack_hash(p + vec3f(e, 0.0, 0.0)); let hz = pack_hash(p + vec3f(0.0, 0.0, e)); let tangentX = normalize(cross(vec3f(0.0, 1.0, 0.0), n) + vec3f(0.0001, 0.0, 0.0)); let tangentZ = normalize(cross(n, tangentX)); return normalize(n + tangentX * (hx - h0) * strength + tangentZ * (hz - h0) * strength); } fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let local = fract(l.position - l.normal * 0.5); // in-block local coords let n = pack_bumpNormal(local * 16.0, normalize(l.normal), 0.35); let sunLen = length(bloxdSunDirection()); if (sunLen > 0.5) { let sunDir = bloxdSunDirection() / sunLen; let lam = clamp(dot(n, sunDir), 0.0, 1.0); let lamFlat = clamp(dot(normalize(l.normal), sunDir), 0.0, 1.0); out.colour *= mix(1.0, 0.85 + 0.15 * (lam / max(lamFlat, 0.001)), 0.5); } } return out; }

R9.9 Nonlinear cave darkening + lamp protection

fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let sky = clamp(l.skyLight, 0.0, 1.0); let underground = 1.0 - sky; let blockInt = max(l.blockLight.r, max(l.blockLight.g, l.blockLight.b)); let keep = 0.12 + 0.88 * blockInt; // lift lamp-lit spots out.colour *= mix(keep, 1.0, sky * sky); // nonlinear (squared) darkening } return out; }

R9.10 Re-applying fog (required when discarding engineColour)

Setting a floor like min(l.fogAlpha, 0.75) caps “no denser than this” (0.0 = engine-accurate / 0.3–0.5 = clearer distance). Note the engine fog is a horizon-only linear fog (near render distance only); mid-distance haze must be built pack-side. Real fog settings (implementation-verified): linear fixed / fogStart = chunk render distance / fogEnd = +1 chunk / effectively disabled at 100–101 chunks when fog is off / default color RGB(183, 191, 195).

fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let voxel = mix(l.ambientLightColour, l.skyLightColour, l.skyLight); var col = s.colour * (voxel * 1.1 + vec3f(0.05)); col = clamp(col, vec3f(0.0), vec3f(1.0)); col = mix(l.fogColour, col, min(l.fogAlpha, 0.85)); // fog redo (0.15 = light floor) col += s.emission * (1.0 - l.fogAlpha); // emission also fogged out.colour = col; } return out; }

R9.11 Cinema grade (cool shadows / warm highlights / night desaturation)

fn pack_luma(c: vec3f) -> f32 { return dot(c, vec3f(0.2126, 0.7152, 0.0722)); } fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { let lum = pack_luma(out.colour); out.colour *= mix(vec3f(0.93, 1.00, 1.06), vec3f(1.06, 1.00, 0.93), lum); let sunPresent = smoothstep(0.0, 0.5, length(bloxdSunDirection())); let night = 1.0 - sunPresent; // night only when sun direction is zero; no dusk gradient out.colour = mix(out.colour, vec3f(pack_luma(out.colour)), night * 0.28); } return out; }

R9.12 Projected shadows — lift inversion + threshold cut (definitive)

On bbb6l5+ builds you can skip the threshold cut: bloxdShadow() gives the engine’s real sun-following shadow factor (0–1, entity shadows included) directly — see Shadows. The recipe below remains the one-route-for-all-builds classic and the stylized half-tone look.

Premise recheck (section 10): l.skyLight is not the raw voxel value (n/15) but the value after the engine’s “lift curve”
y = 1-(1-x/(3-2x))³ (an S-curve lifting dark areas).

Placeraw voxellifted (= l.skyLight)pow(·, 5.0)
open sky1.001.001.00
under tree (radius 2)0.870.970.86 ← nearly untouched
radius 30.800.920.66
radius 50.670.780.29

This is the proven root cause of “shadows won’t deepen no matter the gamma”. But the curve is monotonic, so it can be inverted algebraically:
c=(1-y)^(1/3); x=3(1-c)/(3-2c). After restoring raw values, just binarize with a threshold cut (smoothstep).
LightEngine’s BFS lateral spread is “1 block = -1”, so the threshold th = 1 - r/15 directly dials
”occlusion of radius r or more counts as shadow”. Breaking blocks moves shadows instantly (LightEngine recalculates in real time).
Limitation: shadows are “upward sky” based, so they don’t rotate with the sun (section 15, “The truth about shadows”).

// Invert the engine lift exactly to restore raw voxel skyLight (n/15) fn sh_unlift(y: f32) -> f32 { let t = clamp(1.0 - clamp(y, 0.0, 1.0), 0.0, 1.0); let c = pow(t, 1.0 / 3.0); // no cbrt in WGSL, use pow return clamp(3.0 * (1.0 - c) / (3.0 - 2.0 * c), 0.0, 1.0); } const shTh = 0.87; // shadow radius dial: th = 1 - r/15 (0.87 = radius 2+ is shadow) const shSoft = 0.04; // edge softness (0.02 = hard / 0.08 = soft) fn bloxdTerrainLight(s: BloxdSurface, l: BloxdLightIn) -> BloxdLight { var out = bloxdDefaultLight(s, l); if (bloxdLit()) { // 1. restore raw values (skipping this never yields shadows) let skyRaw = sh_unlift(l.skyLight); // 2. threshold cut — cleanly separates sunlit=1 / shadow=0 let sky = smoothstep(shTh - shSoft, shTh + shSoft, skyRaw); // sun Lambert (fall back to l.directional when there is no sun) let sunLen = length(bloxdSunDirection()); let sunL = select(clamp(l.directional, 0.0, 1.0), clamp(dot(normalize(l.normal), bloxdSunDirection() / sunLen), 0.0, 1.0), sunLen > 0.5); // the essence of projection: direct sun only reaches where sky is visible let lit = sunL * sky; // shadow side: tinted sky blue, not black + minimum ambient let shade = 0.09 + 0.16 * sky * vec3f(0.72, 0.82, 1.05); var col = s.colour * (shade + lit * vec3f(1.00, 0.90, 0.72) * 1.18); // torch light pierces shadows (blockLight is also lifted, restore together) let blockRaw = vec3f(sh_unlift(l.blockLight.r), sh_unlift(l.blockLight.g), sh_unlift(l.blockLight.b)); let blockInt = max(blockRaw.r, max(blockRaw.g, blockRaw.b)); col = max(col, s.colour * mix(blockRaw, blockInt * vec3f(1.0, 0.7, 0.4), 0.6) * 1.40); // re-apply fog (discarded engineColour's share) col = mix(l.fogColour, col, min(l.fogAlpha, 0.85)); out.colour = clamp(col + s.emission * (1.0 - l.fogAlpha), vec3f(0.0), vec3f(1.0)); // don't forget emission (fogged) } return out; }

Tuning guide: shadow area is set by shTh alone — 0.93 = radius 1.5+ / 0.87 = radius 2 / 0.80 = radius 3 / 0.67 = radius 5.
Edge hardness is shSoft (0.02 = hard / 0.08 = soft). Shadow core darkness is the two-point shift of 0.09 (minimum ambient) and 0.16 (sky scatter).
To widen shadows at dusk, add thEff = shTh + 0.10 * (1.0 - clamp(sunDir.y, 0.0, 1.0)) (long-dusk-shadow approximation.
sunDir is bloxdSunDirection() / length(bloxdSunDirection())). For bluer shadows raise the B of vec3f(0.72, 0.82, 1.05).