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:
- 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)
- The engine’s default lighting is multiplication only. Specular / fresnel / warm-cool separation / hemisphere ambient can all be built from zero
l.engineColouris the finished color (already fogged). Rebuilding froms.colour(albedo) is the full-fledged approach- 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.skyLightis 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).
Place raw voxel lifted (= l.skyLight) pow(·, 5.0) open sky 1.00 1.00 1.00 under tree (radius 2) 0.87 0.97 0.86 ← nearly untouched radius 3 0.80 0.92 0.66 radius 5 0.67 0.78 0.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 thresholdth = 1 - r/15directly 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
shThalone —0.93= radius 1.5+ /0.87= radius 2 /0.80= radius 3 /0.67= radius 5.
Edge hardness isshSoft(0.02 = hard / 0.08 = soft). Shadow core darkness is the two-point shift of0.09(minimum ambient) and0.16(sky scatter).
To widen shadows at dusk, addthEff = shTh + 0.10 * (1.0 - clamp(sunDir.y, 0.0, 1.0))(long-dusk-shadow approximation.
sunDirisbloxdSunDirection() / length(bloxdSunDirection())). For bluer shadows raise the B ofvec3f(0.72, 0.82, 1.05).