@3driseai/3drise-viewer 0.1.27 → 0.1.29

package/dist/shaders/glsl/terrainCore.glsl.d.ts

@@ -27,7 +27,7 @@
  *    billions of transcendentals per frame.
  */
 /** Every uniform the height field and the shading read. */
-export declare const terrainUniforms = "\nuniform int   u_terrainType;\n\nuniform float u_elevation;\nuniform float u_seaLevel;\nuniform float u_baseScale;      // 1 / featureSize\nuniform int   u_octaves;\nuniform float u_lacunarity;\nuniform float u_gain;\nuniform float u_ridge;\nuniform float u_warpStrength;\nuniform float u_warpScale;\nuniform float u_erosion;\nuniform float u_terraces;\nuniform float u_terraceSharp;\nuniform vec2  u_bearingDir;\nuniform float u_duneFreq;       // 2pi / duneWavelength\nuniform float u_duneAsym;\nuniform float u_plateau;\nuniform float u_valleyDepth;\nuniform float u_valleyWidth;\n\nuniform float u_cellSize;\nuniform float u_curvature;\n\n// surface\nuniform vec3  u_lowColor, u_midColor, u_rockColor, u_peakColor;\nuniform float u_slopeRockStart, u_slopeRockEnd;\nuniform float u_peakLevel, u_peakBlend, u_peakSlopeFalloff;\nuniform float u_macroVariation, u_macroScale;\nuniform float u_detailStrength, u_detailScale, u_detailFade;\nuniform float u_roughness, u_specular;\n\n// lighting. u_skyAmbient and u_groundAmbient come from useCloudSun through\n// applySunUniforms - the same objects that light the clouds. They are constant\n// across the frame, so computing them on the CPU rather than calling skyRadiance\n// per pixel removes an acos, a pow and three exps from every fragment.\nuniform vec3  u_skyAmbient;\nuniform vec3  u_groundAmbient;\nuniform float u_ambient, u_bounce, u_sunShadow, u_shadowSoftness;\nuniform float u_shadowDistance;\nuniform float u_fogDensity, u_exposure;\nuniform int   u_shadowSteps;\n";
+export declare const terrainUniforms = "\nuniform int   u_terrainType;\n\nuniform float u_elevation;\nuniform float u_seaLevel;\nuniform float u_baseScale;      // 1 / featureSize\nuniform int   u_octaves;\nuniform float u_lacunarity;\nuniform float u_gain;\nuniform float u_ridge;\nuniform float u_warpStrength;\nuniform float u_warpScale;\nuniform float u_erosion;\nuniform float u_terraces;\nuniform float u_terraceSharp;\nuniform vec2  u_bearingDir;\nuniform float u_duneFreq;       // 2pi / duneWavelength\nuniform float u_duneAsym;\nuniform float u_plateau;\nuniform float u_valleyDepth;\nuniform float u_valleyWidth;\n\nuniform float u_cellSize;\nuniform float u_curvature;\n\n// surface\nuniform vec3  u_lowColor, u_midColor, u_rockColor, u_peakColor;\nuniform float u_slopeRockStart, u_slopeRockEnd;\nuniform float u_peakLevel, u_peakBlend, u_peakSlopeFalloff;\nuniform float u_macroVariation, u_macroScale;\nuniform float u_detailStrength, u_detailScale, u_detailFade;\nuniform float u_roughness, u_specular;\n\n// lighting. u_skyAmbient and u_groundAmbient come from useCloudSun through\n// applySunUniforms - the same objects that light the clouds. They are constant\n// across the frame, so computing them on the CPU rather than calling skyRadiance\n// per pixel removes an acos, a pow and three exps from every fragment.\nuniform vec3  u_skyAmbient;\nuniform vec3  u_groundAmbient;\nuniform float u_ambient, u_bounce, u_sunShadow, u_shadowSoftness;\nuniform float u_shadowDistance;\nuniform float u_fogDensity, u_exposure;\nuniform int   u_shadowSteps;\n\n// Ground textures. The far colour per layer is always set: the flat colour for an\n// untextured layer, the texture's own mean x tint for a textured one, so the\n// near-to-far fade has no colour jump.\nuniform vec3  u_tFar[4];\n#ifdef TERRAIN_TEXTURED\nuniform sampler2DArray u_tColor;    // albedo, sRGB\nuniform sampler2DArray u_tNormal;   // rgb tangent normal (GL), a surface height\nuniform sampler2DArray u_tOrm;      // r ambient occlusion, g roughness\nuniform vec4  u_tLayer[4];          // 1/tileSize, normalStrength, textured 0|1, -\nuniform vec3  u_tTint[4];           // layer colour / texture mean: the texture averages to the layer colour\nuniform vec4  u_tMeanC[4];          // per-array layer means, for the stochastic blend\nuniform vec4  u_tMeanN[4];\nuniform vec4  u_tMeanO[4];\nuniform float u_tDistance;\nuniform float u_tHeightBlend;\n#endif\n\n// A land object: a bounded patch of this field, placed by its object's transform.\n// Its \"terrain space\" is metres from the object's origin, unrotated, plus a seed\n// offset; height is above the object's base. See TerrainMaterial's patch vertex.\n#ifdef TERRAIN_PATCH\nuniform vec2  u_patchSize;      // footprint in metres (object scale x / z)\nuniform vec2  u_patchOffset;    // terrain-space centre: the seed's offset into the field\nuniform float u_edgeWidth;      // metres over which the land eases down to its base\nuniform vec3  u_camTerrain;     // the camera, in terrain space\nuniform float u_scaleY;         // object scale y: terrain metres = local y x this\nuniform float u_patchCell;      // metres per grid cell\n#define TERRAIN_CAM u_camTerrain\n#else\n#define TERRAIN_CAM cameraPosition\n#endif\n";
 /**
  * Gradient noise with an analytic derivative.
  *
@@ -53,7 +53,7 @@ export declare const terrainNoise = "\nvec2 tHash(vec2 p){\n  vec3 p3 = fract(ve
  * terrain crawl), and it is most of the cost saving, because the outer rings —
  * which carry three quarters of the vertices — run four octaves instead of nine.
  */
-export declare const terrainHeight = "\n#define TERRAIN_MOUNTAINS 0\n#define TERRAIN_DUNES     1\n#define TERRAIN_HILLS     2\n#define TERRAIN_CANYON    3\n\n#define TERRAIN_MAX_OCTAVES 12\n\n/** Normalised fBm in [0,1], derivative-damped, with d/d(worldXZ) in grad. */\nfloat terrainFbmD(vec2 p, float lodCell, out vec2 grad){\n  vec2 q = p * u_baseScale;\n\n  // Domain warp. Without it fBm reads as fBm: blobs with no direction and no\n  // drainage. Warping the sample point by a slower copy of the same noise bends\n  // ridge lines into the branching curves erosion actually produces.\n  //\n  // Its Jacobian is carried rather than assumed to be the identity. That shortcut\n  // is the usual one and it shows: at warpStrength 0.3 the normal is wrong by up\n  // to 30% precisely where the warp bends a ridge, which is where the eye goes.\n  vec2 qw = q;\n  mat2 J = mat2(1.0, 0.0, 0.0, 1.0);\n  if (u_warpStrength > 0.0){\n    vec3 w0 = tNoised(q * u_warpScale + vec2(11.3, 5.7));\n    vec3 w1 = tNoised(q * u_warpScale + vec2(-7.1, 19.2));\n    qw = q + vec2(w0.x, w1.x) * u_warpStrength;\n    float k = u_warpStrength * u_warpScale;\n    // Columns, so that (v * J) evaluates transpose(J) * v - which is the chain\n    // rule direction we need, and GLSL ES 1.00 has no transpose().\n    J = mat2(1.0 + k * w0.y, k * w1.y,\n             k * w0.z,       1.0 + k * w1.z);\n  }\n\n  float amp = 1.0;\n  float freq = 1.0;\n  float sum = 0.0;\n  float norm = 0.0;\n  vec2  gradW = vec2(0.0);   // d(sum) / d(qw)\n  vec2  slope = vec2(0.0);   // bounded erosion accumulator, octave-local units\n\n  // Wavelength of the first octave, in world units.\n  float wl = 1.0 / max(u_baseScale, 1e-9);\n\n  for (int i = 0; i < TERRAIN_MAX_OCTAVES; i++){\n    if (i >= u_octaves) break;\n\n    // Fade an octave out as its wavelength approaches the shading cell, then\n    // stop. Popping it off with a hard test leaves a visible ring where the\n    // clipmap level changes; fading is what makes the transition invisible.\n    float limit = 2.0 * lodCell;\n    float fade = clamp(wl / max(limit, 1e-4) - 1.0, 0.0, 1.0);\n    if (fade <= 0.001) break;\n\n    // A constant per-octave offset rather than a rotation matrix: rotating the\n    // domain would need the transpose applied to the derivative as well, and the\n    // offset decorrelates the octaves just as effectively.\n    vec3 n = tNoised(qw * freq + float(i) * vec2(37.13, 61.91));\n    float v = n.x;\n    vec2  g = n.yz;\n\n    // Ridge shaping, with the chain rule carried through so both the erosion term\n    // and the surface normal still see a true slope. 1 - |v| folds the noise about\n    // zero; squaring sharpens the crest.\n    if (u_ridge > 0.0){\n      // Ramp the fold in by octave. 1 - |v| is C1-discontinuous along the whole\n      // v = 0 contour, and on octave 0 that contour is a kilometre-long smooth\n      // arc - so the crease runs right across the terrain and reads as a\n      // modelling seam, not as a ridge. Found by baking presets to heightmaps\n      // and hillshading them, where the arcs are unmistakable; on the lit\n      // terrain they hide as a suspiciously straight shadow edge.\n      //\n      // A crest only reads as a crest at a scale where a crest is plausible, so\n      // the base octave stays smooth, the next is half folded and everything\n      // finer is fully ridged. Sharpness at the scales that matter is unchanged.\n      float ridgeAmt = u_ridge * clamp(float(i) * 0.5, 0.0, 1.0);\n      float s = sign(v);\n      float r = 1.0 - abs(v);\n      float rv = r * r * 2.0 - 1.0;\n      vec2  rg = -4.0 * r * s * g;\n      v = mix(v, rv, ridgeAmt);\n      g = mix(g, rg, ridgeAmt);\n    }\n\n    // The erosion term. Slope accumulated so far suppresses everything finer.\n    // Deliberately fed the OCTAVE-LOCAL derivative, not the frequency-scaled one:\n    // scaled, it grows like lacunarity^i, the damping collapses by the third\n    // octave and every finer octave vanishes - a terrain that is flat however high\n    // its elevation is set. Its own derivative is ignored, which is the standard\n    // approximation and invisible at these amplitudes.\n    float damp = 1.0 / (1.0 + u_erosion * 1.5 * dot(slope, slope));\n    float wgt = amp * damp * fade;\n\n    sum   += wgt * v;\n    norm  += amp * fade;\n    gradW += wgt * g * freq;\n    slope += g * amp * damp;\n\n    amp  *= u_gain;\n    freq *= u_lacunarity;\n    wl   /= u_lacunarity;\n  }\n\n  float inv = 1.0 / max(norm, 1e-4);\n\n  // Contrast, and it is not a taste knob.\n  //\n  // Dividing by the summed amplitude is the textbook normalisation and it is\n  // wrong for terrain: octaves of gradient noise almost never align, so the sum\n  // lands in about a quarter of the range the divisor assumes and the field comes\n  // out spanning 0.45-0.69 instead of 0-1. A 1400 m elevation then renders as a\n  // 320 m swell, and no amount of extra octaves fixes it because they are being\n  // divided away too. Measured against the height field directly: 3.2 recovers\n  // roughly 740 m of the 1400, which is a real range at a real grade.\n  //\n  // The soft clamp rather than a hard one, so a peak that would overshoot rolls\n  // off instead of arriving with a flat top.\n  float t = sum * inv * 3.2;\n  float rs = inversesqrt(1.0 + t * t);\n\n  // d(height)/d(qw) -> d/d(q) via the warp Jacobian -> d/d(world).\n  vec2 dqw = gradW * (0.5 * 3.2 * rs * rs * rs * inv);\n  grad = (dqw * J) * u_baseScale;\n\n  return 0.5 + 0.5 * t * rs;\n}\n\n/**\n * Height above sea level in world units at a world XZ, and the surface gradient\n * d(height)/d(worldXZ). The normal is normalize(vec3(-grad.x, 1, -grad.y)).\n *\n * Curvature is deliberately NOT applied here. It is a view-relative bend applied\n * at the vertex, and folding it in would make the height field depend on where\n * the camera is \u2014 which the shadow march and the normals both sample, and would\n * mean a shadow that moves when you turn your head.\n */\nfloat terrainSample(vec2 p, float lodCell, out vec2 grad){\n  vec2 gh;\n  float h = terrainFbmD(p, lodCell, gh);\n\n  if (u_terrainType == TERRAIN_DUNES){\n    // Dunes are a wave train transverse to the wind, not a noise field. The fBm\n    // bends the crest lines and sets how tall each dune is; the sine is the dune.\n    vec2 d = vec2(u_bearingDir.y, -u_bearingDir.x);\n    float phase  = dot(p, d) * u_duneFreq + 7.0 * h;\n    vec2  dphase = d * u_duneFreq + 7.0 * gh;\n\n    float u  = 0.5 + 0.5 * sin(phase);\n    vec2  du = 0.5 * cos(phase) * dphase;\n\n    // Asymmetry: a real dune is a long windward ramp and a short slip face at the\n    // angle of repose. Raising the crest to a power does that in one instruction.\n    float k  = mix(1.0, 3.2, u_duneAsym);\n    float us = max(u, 1e-4);\n    float s  = pow(us, k);\n    vec2  ds = k * pow(us, k - 1.0) * du;\n\n    // The envelope keeps dune height varying across the field rather than\n    // stamping one ridge repeated to the horizon.\n    float env = 0.45 + 0.55 * h;\n    float a = 0.15 + 0.5 * h;\n    float b = s * env;\n    vec2  da = 0.5 * gh;\n    vec2  db = ds * env + s * 0.55 * gh;\n    h  = mix(a, b, 0.8);\n    gh = mix(da, db, 0.8);\n  }\n  else if (u_terrainType == TERRAIN_CANYON){\n    // Canyon country is a plateau with things taken out of it, not a mountain\n    // range. Flatten the top first, then cut.\n    float om = 1.0 - h;\n    float mesa = mix(h, 1.0 - om * om * om, u_plateau);\n    float dmf  = mix(1.0, 3.0 * om * om, u_plateau);\n\n    // Channel network: ridged noise is near 1 along its zero set, which is a\n    // connected branching line \u2014 a drainage network, for free.\n    vec3  cn  = tNoised(p * (u_baseScale * 1.7) + vec2(4.2, -9.1));\n    float ch  = 1.0 - abs(cn.x);\n    vec2  dch = -sign(cn.x) * cn.yz * (u_baseScale * 1.7);\n\n    float e0 = 1.0 - u_valleyWidth;\n    float ct = clamp((ch - e0) / max(1.0 - e0, 1e-4), 0.0, 1.0);\n    float carve  = ct * ct * (3.0 - 2.0 * ct);\n    float dcarve = 6.0 * ct * (1.0 - ct) / max(1.0 - e0, 1e-4);\n\n    h  = mesa - u_valleyDepth * carve;\n    gh = dmf * gh - (u_valleyDepth * dcarve) * dch;\n  }\n\n  // Sedimentary banding. Applied after shaping, so it bands the finished landform\n  // rather than the raw noise.\n  if (u_terraces >= 0.5){\n    float n = u_terraces;\n\n    // The aliasing bound is HORIZONTAL, not vertical. What aliases is how far\n    // across the ground a riser takes to climb, and that scales with the\n    // landform's own size divided by the number of bands stacked on it. Widening\n    // the riser is not enough on its own either: smoothstep(0, 1, fr) still has a\n    // flat spot at each end, so a \"fully softened\" terrace is still a staircase.\n    // Fade all the way to the identity ramp, which is the un-terraced surface.\n    float featureSize = 1.0 / max(u_baseScale, 1e-9);\n    float soft = clamp(lodCell * n * 8.0 / featureSize, 0.0, 1.0);\n    float w = max(1.0 - 0.95 * u_terraceSharp, 0.02);\n\n    float x  = h * n;\n    float fr = fract(x);\n    float ct = clamp(fr / w, 0.0, 1.0);\n    float k   = mix(ct * ct * (3.0 - 2.0 * ct), fr, soft);\n    float dk  = mix(6.0 * ct * (1.0 - ct) / w, 1.0, soft);\n\n    h  = (floor(x) + k) / n;\n    gh = dk * gh;\n  }\n\n  grad = gh * u_elevation;\n  return u_seaLevel + u_elevation * h;\n}\n\n/**\n * Height only, and a genuinely separate path rather than terrainSample with the\n * gradient thrown away.\n *\n * This is the shadow march's inner loop - fourteen calls per shaded point - and\n * it is the one place where paying for a derivative nobody reads actually shows\n * up. No warp Jacobian, no gradient accumulation, no chain rule through the\n * shaping: about half the work of the full sample.\n */\nfloat terrainHeightAt(vec2 p, float lodCell){\n  vec2 q = p * u_baseScale;\n  if (u_warpStrength > 0.0){\n    q += vec2(\n      tNoise(q * u_warpScale + vec2(11.3, 5.7)),\n      tNoise(q * u_warpScale + vec2(-7.1, 19.2))\n    ) * u_warpStrength;\n  }\n\n  float amp = 1.0, freq = 1.0, sum = 0.0, norm = 0.0;\n  vec2  slope = vec2(0.0);\n  float wl = 1.0 / max(u_baseScale, 1e-9);\n\n  for (int i = 0; i < TERRAIN_MAX_OCTAVES; i++){\n    if (i >= u_octaves) break;\n    float limit = 2.0 * lodCell;\n    float fade = clamp(wl / max(limit, 1e-4) - 1.0, 0.0, 1.0);\n    if (fade <= 0.001) break;\n\n    vec3 n = tNoised(q * freq + float(i) * vec2(37.13, 61.91));\n    float v = n.x;\n    vec2  g = n.yz;\n    if (u_ridge > 0.0){\n      // Same octave ramp as the derivative path above - the two must agree or a\n      // height query and the rendered surface disagree by the fold amount.\n      float ridgeAmt = u_ridge * clamp(float(i) * 0.5, 0.0, 1.0);\n      float sg = sign(v);\n      float r = 1.0 - abs(v);\n      v = mix(v, r * r * 2.0 - 1.0, ridgeAmt);\n      g = mix(g, -4.0 * r * sg * g, ridgeAmt);\n    }\n    float damp = 1.0 / (1.0 + u_erosion * 1.5 * dot(slope, slope));\n    sum   += amp * damp * fade * v;\n    norm  += amp * fade;\n    slope += g * amp * damp;\n\n    amp  *= u_gain;\n    freq *= u_lacunarity;\n    wl   /= u_lacunarity;\n  }\n\n  float t = (sum / max(norm, 1e-4)) * 3.2;\n  float h = 0.5 + 0.5 * t * inversesqrt(1.0 + t * t);\n\n  if (u_terrainType == TERRAIN_DUNES){\n    vec2 d = vec2(u_bearingDir.y, -u_bearingDir.x);\n    float u = 0.5 + 0.5 * sin(dot(p, d) * u_duneFreq + 7.0 * h);\n    float s = pow(max(u, 1e-4), mix(1.0, 3.2, u_duneAsym));\n    h = mix(0.15 + 0.5 * h, s * (0.45 + 0.55 * h), 0.8);\n  }\n  else if (u_terrainType == TERRAIN_CANYON){\n    float om = 1.0 - h;\n    float mesa = mix(h, 1.0 - om * om * om, u_plateau);\n    float ch = 1.0 - abs(tNoise(p * (u_baseScale * 1.7) + vec2(4.2, -9.1)));\n    h = mesa - u_valleyDepth * smoothstep(1.0 - u_valleyWidth, 1.0, ch);\n  }\n\n  if (u_terraces >= 0.5){\n    float n = u_terraces;\n    float featureSize = 1.0 / max(u_baseScale, 1e-9);\n    float soft = clamp(lodCell * n * 8.0 / featureSize, 0.0, 1.0);\n    float w = max(1.0 - 0.95 * u_terraceSharp, 0.02);\n    float x = h * n;\n    float fr = fract(x);\n    h = (floor(x) + mix(smoothstep(0.0, w, fr), fr, soft)) / n;\n  }\n\n  return u_seaLevel + u_elevation * h;\n}\n\nvec3 terrainNormal(vec2 grad){\n  return normalize(vec3(-grad.x, 1.0, -grad.y));\n}\n";
+export declare const terrainHeight = "\n#define TERRAIN_MOUNTAINS 0\n#define TERRAIN_DUNES     1\n#define TERRAIN_HILLS     2\n#define TERRAIN_CANYON    3\n\n#define TERRAIN_MAX_OCTAVES 12\n\n/** Normalised fBm in [0,1], derivative-damped, with d/d(worldXZ) in grad. */\nfloat terrainFbmD(vec2 p, float lodCell, out vec2 grad){\n  vec2 q = p * u_baseScale;\n\n  // Domain warp. Without it fBm reads as fBm: blobs with no direction and no\n  // drainage. Warping the sample point by a slower copy of the same noise bends\n  // ridge lines into the branching curves erosion actually produces.\n  //\n  // Its Jacobian is carried rather than assumed to be the identity. That shortcut\n  // is the usual one and it shows: at warpStrength 0.3 the normal is wrong by up\n  // to 30% precisely where the warp bends a ridge, which is where the eye goes.\n  vec2 qw = q;\n  mat2 J = mat2(1.0, 0.0, 0.0, 1.0);\n  if (u_warpStrength > 0.0){\n    vec3 w0 = tNoised(q * u_warpScale + vec2(11.3, 5.7));\n    vec3 w1 = tNoised(q * u_warpScale + vec2(-7.1, 19.2));\n    qw = q + vec2(w0.x, w1.x) * u_warpStrength;\n    float k = u_warpStrength * u_warpScale;\n    // Columns, so that (v * J) evaluates transpose(J) * v - which is the chain\n    // rule direction we need, and GLSL ES 1.00 has no transpose().\n    J = mat2(1.0 + k * w0.y, k * w1.y,\n             k * w0.z,       1.0 + k * w1.z);\n  }\n\n  float amp = 1.0;\n  float freq = 1.0;\n  float sum = 0.0;\n  float norm = 0.0;\n  vec2  gradW = vec2(0.0);   // d(sum) / d(qw)\n  vec2  slope = vec2(0.0);   // bounded erosion accumulator, octave-local units\n\n  // Wavelength of the first octave, in world units.\n  float wl = 1.0 / max(u_baseScale, 1e-9);\n\n  for (int i = 0; i < TERRAIN_MAX_OCTAVES; i++){\n    if (i >= u_octaves) break;\n\n    // Fade an octave out as its wavelength approaches the shading cell, then\n    // stop. Popping it off with a hard test leaves a visible ring where the\n    // clipmap level changes; fading is what makes the transition invisible.\n    float limit = 2.0 * lodCell;\n    float fade = clamp(wl / max(limit, 1e-4) - 1.0, 0.0, 1.0);\n    if (fade <= 0.001) break;\n\n    // A constant per-octave offset rather than a rotation matrix: rotating the\n    // domain would need the transpose applied to the derivative as well, and the\n    // offset decorrelates the octaves just as effectively.\n    vec3 n = tNoised(qw * freq + float(i) * vec2(37.13, 61.91));\n    float v = n.x;\n    vec2  g = n.yz;\n\n    // Ridge shaping, with the chain rule carried through so both the erosion term\n    // and the surface normal still see a true slope. 1 - |v| folds the noise about\n    // zero; squaring sharpens the crest.\n    if (u_ridge > 0.0){\n      // Ramp the fold in by octave. 1 - |v| is C1-discontinuous along the whole\n      // v = 0 contour, and on octave 0 that contour is a kilometre-long smooth\n      // arc - so the crease runs right across the terrain and reads as a\n      // modelling seam, not as a ridge. Found by baking presets to heightmaps\n      // and hillshading them, where the arcs are unmistakable; on the lit\n      // terrain they hide as a suspiciously straight shadow edge.\n      //\n      // A crest only reads as a crest at a scale where a crest is plausible, so\n      // the base octave stays smooth, the next is half folded and everything\n      // finer is fully ridged. Sharpness at the scales that matter is unchanged.\n      float ridgeAmt = u_ridge * clamp(float(i) * 0.5, 0.0, 1.0);\n      float s = sign(v);\n      float r = 1.0 - abs(v);\n      float rv = r * r * 2.0 - 1.0;\n      vec2  rg = -4.0 * r * s * g;\n      v = mix(v, rv, ridgeAmt);\n      g = mix(g, rg, ridgeAmt);\n    }\n\n    // The erosion term. Slope accumulated so far suppresses everything finer.\n    // Deliberately fed the OCTAVE-LOCAL derivative, not the frequency-scaled one:\n    // scaled, it grows like lacunarity^i, the damping collapses by the third\n    // octave and every finer octave vanishes - a terrain that is flat however high\n    // its elevation is set. Its own derivative is ignored, which is the standard\n    // approximation and invisible at these amplitudes.\n    float damp = 1.0 / (1.0 + u_erosion * 1.5 * dot(slope, slope));\n    float wgt = amp * damp * fade;\n\n    sum   += wgt * v;\n    norm  += amp * fade;\n    gradW += wgt * g * freq;\n    slope += g * amp * damp;\n\n    amp  *= u_gain;\n    freq *= u_lacunarity;\n    wl   /= u_lacunarity;\n  }\n\n  float inv = 1.0 / max(norm, 1e-4);\n\n  // Contrast, and it is not a taste knob.\n  //\n  // Dividing by the summed amplitude is the textbook normalisation and it is\n  // wrong for terrain: octaves of gradient noise almost never align, so the sum\n  // lands in about a quarter of the range the divisor assumes and the field comes\n  // out spanning 0.45-0.69 instead of 0-1. A 1400 m elevation then renders as a\n  // 320 m swell, and no amount of extra octaves fixes it because they are being\n  // divided away too. Measured against the height field directly: 3.2 recovers\n  // roughly 740 m of the 1400, which is a real range at a real grade.\n  //\n  // The soft clamp rather than a hard one, so a peak that would overshoot rolls\n  // off instead of arriving with a flat top.\n  float t = sum * inv * 3.2;\n  float rs = inversesqrt(1.0 + t * t);\n\n  // d(height)/d(qw) -> d/d(q) via the warp Jacobian -> d/d(world).\n  vec2 dqw = gradW * (0.5 * 3.2 * rs * rs * rs * inv);\n  grad = (dqw * J) * u_baseScale;\n\n  return 0.5 + 0.5 * t * rs;\n}\n\n/**\n * Height above sea level in world units at a world XZ, and the surface gradient\n * d(height)/d(worldXZ). The normal is normalize(vec3(-grad.x, 1, -grad.y)).\n *\n * Curvature is deliberately NOT applied here. It is a view-relative bend applied\n * at the vertex, and folding it in would make the height field depend on where\n * the camera is \u2014 which the shadow march and the normals both sample, and would\n * mean a shadow that moves when you turn your head.\n */\nfloat terrainSample(vec2 p, float lodCell, out vec2 grad){\n  vec2 gh;\n  float h = terrainFbmD(p, lodCell, gh);\n\n  if (u_terrainType == TERRAIN_DUNES){\n    // Dunes are a wave train transverse to the wind, not a noise field. The fBm\n    // bends the crest lines and sets how tall each dune is; the sine is the dune.\n    vec2 d = vec2(u_bearingDir.y, -u_bearingDir.x);\n    float phase  = dot(p, d) * u_duneFreq + 7.0 * h;\n    vec2  dphase = d * u_duneFreq + 7.0 * gh;\n\n    float u  = 0.5 + 0.5 * sin(phase);\n    vec2  du = 0.5 * cos(phase) * dphase;\n\n    // Asymmetry: a real dune is a long windward ramp and a short slip face at the\n    // angle of repose. Raising the crest to a power does that in one instruction.\n    float k  = mix(1.0, 3.2, u_duneAsym);\n    float us = max(u, 1e-4);\n    float s  = pow(us, k);\n    vec2  ds = k * pow(us, k - 1.0) * du;\n\n    // The envelope keeps dune height varying across the field rather than\n    // stamping one ridge repeated to the horizon.\n    float env = 0.45 + 0.55 * h;\n    float a = 0.15 + 0.5 * h;\n    float b = s * env;\n    vec2  da = 0.5 * gh;\n    vec2  db = ds * env + s * 0.55 * gh;\n    h  = mix(a, b, 0.8);\n    gh = mix(da, db, 0.8);\n  }\n  else if (u_terrainType == TERRAIN_CANYON){\n    // Canyon country is a plateau with things taken out of it, not a mountain\n    // range. Flatten the top first, then cut.\n    float om = 1.0 - h;\n    float mesa = mix(h, 1.0 - om * om * om, u_plateau);\n    float dmf  = mix(1.0, 3.0 * om * om, u_plateau);\n\n    // Channel network: ridged noise is near 1 along its zero set, which is a\n    // connected branching line \u2014 a drainage network, for free.\n    vec3  cn  = tNoised(p * (u_baseScale * 1.7) + vec2(4.2, -9.1));\n    float ch  = 1.0 - abs(cn.x);\n    vec2  dch = -sign(cn.x) * cn.yz * (u_baseScale * 1.7);\n\n    float e0 = 1.0 - u_valleyWidth;\n    float ct = clamp((ch - e0) / max(1.0 - e0, 1e-4), 0.0, 1.0);\n    float carve  = ct * ct * (3.0 - 2.0 * ct);\n    float dcarve = 6.0 * ct * (1.0 - ct) / max(1.0 - e0, 1e-4);\n\n    h  = mesa - u_valleyDepth * carve;\n    gh = dmf * gh - (u_valleyDepth * dcarve) * dch;\n  }\n\n  // Sedimentary banding. Applied after shaping, so it bands the finished landform\n  // rather than the raw noise.\n  if (u_terraces >= 0.5){\n    float n = u_terraces;\n\n    // The aliasing bound is HORIZONTAL, not vertical. What aliases is how far\n    // across the ground a riser takes to climb, and that scales with the\n    // landform's own size divided by the number of bands stacked on it. Widening\n    // the riser is not enough on its own either: smoothstep(0, 1, fr) still has a\n    // flat spot at each end, so a \"fully softened\" terrace is still a staircase.\n    // Fade all the way to the identity ramp, which is the un-terraced surface.\n    float featureSize = 1.0 / max(u_baseScale, 1e-9);\n    float soft = clamp(lodCell * n * 8.0 / featureSize, 0.0, 1.0);\n    float w = max(1.0 - 0.95 * u_terraceSharp, 0.02);\n\n    float x  = h * n;\n    float fr = fract(x);\n    float ct = clamp(fr / w, 0.0, 1.0);\n    float k   = mix(ct * ct * (3.0 - 2.0 * ct), fr, soft);\n    float dk  = mix(6.0 * ct * (1.0 - ct) / w, 1.0, soft);\n\n    h  = (floor(x) + k) / n;\n    gh = dk * gh;\n  }\n\n  grad = gh * u_elevation;\n  return u_seaLevel + u_elevation * h;\n}\n\n/**\n * Height only, and a genuinely separate path rather than terrainSample with the\n * gradient thrown away.\n *\n * This is the shadow march's inner loop - fourteen calls per shaded point - and\n * it is the one place where paying for a derivative nobody reads actually shows\n * up. No warp Jacobian, no gradient accumulation, no chain rule through the\n * shaping: about half the work of the full sample.\n */\nfloat terrainHeightAt(vec2 p, float lodCell){\n  vec2 q = p * u_baseScale;\n  if (u_warpStrength > 0.0){\n    q += vec2(\n      tNoise(q * u_warpScale + vec2(11.3, 5.7)),\n      tNoise(q * u_warpScale + vec2(-7.1, 19.2))\n    ) * u_warpStrength;\n  }\n\n  float amp = 1.0, freq = 1.0, sum = 0.0, norm = 0.0;\n  vec2  slope = vec2(0.0);\n  float wl = 1.0 / max(u_baseScale, 1e-9);\n\n  for (int i = 0; i < TERRAIN_MAX_OCTAVES; i++){\n    if (i >= u_octaves) break;\n    float limit = 2.0 * lodCell;\n    float fade = clamp(wl / max(limit, 1e-4) - 1.0, 0.0, 1.0);\n    if (fade <= 0.001) break;\n\n    vec3 n = tNoised(q * freq + float(i) * vec2(37.13, 61.91));\n    float v = n.x;\n    vec2  g = n.yz;\n    if (u_ridge > 0.0){\n      // Same octave ramp as the derivative path above - the two must agree or a\n      // height query and the rendered surface disagree by the fold amount.\n      float ridgeAmt = u_ridge * clamp(float(i) * 0.5, 0.0, 1.0);\n      float sg = sign(v);\n      float r = 1.0 - abs(v);\n      v = mix(v, r * r * 2.0 - 1.0, ridgeAmt);\n      g = mix(g, -4.0 * r * sg * g, ridgeAmt);\n    }\n    float damp = 1.0 / (1.0 + u_erosion * 1.5 * dot(slope, slope));\n    sum   += amp * damp * fade * v;\n    norm  += amp * fade;\n    slope += g * amp * damp;\n\n    amp  *= u_gain;\n    freq *= u_lacunarity;\n    wl   /= u_lacunarity;\n  }\n\n  float t = (sum / max(norm, 1e-4)) * 3.2;\n  float h = 0.5 + 0.5 * t * inversesqrt(1.0 + t * t);\n\n  if (u_terrainType == TERRAIN_DUNES){\n    vec2 d = vec2(u_bearingDir.y, -u_bearingDir.x);\n    float u = 0.5 + 0.5 * sin(dot(p, d) * u_duneFreq + 7.0 * h);\n    float s = pow(max(u, 1e-4), mix(1.0, 3.2, u_duneAsym));\n    h = mix(0.15 + 0.5 * h, s * (0.45 + 0.55 * h), 0.8);\n  }\n  else if (u_terrainType == TERRAIN_CANYON){\n    float om = 1.0 - h;\n    float mesa = mix(h, 1.0 - om * om * om, u_plateau);\n    float ch = 1.0 - abs(tNoise(p * (u_baseScale * 1.7) + vec2(4.2, -9.1)));\n    h = mesa - u_valleyDepth * smoothstep(1.0 - u_valleyWidth, 1.0, ch);\n  }\n\n  if (u_terraces >= 0.5){\n    float n = u_terraces;\n    float featureSize = 1.0 / max(u_baseScale, 1e-9);\n    float soft = clamp(lodCell * n * 8.0 / featureSize, 0.0, 1.0);\n    float w = max(1.0 - 0.95 * u_terraceSharp, 0.02);\n    float x = h * n;\n    float fr = fract(x);\n    h = (floor(x) + mix(smoothstep(0.0, w, fr), fr, soft)) / n;\n  }\n\n  return u_seaLevel + u_elevation * h;\n}\n\nvec3 terrainNormal(vec2 grad){\n  return normalize(vec3(-grad.x, 1.0, -grad.y));\n}\n\n/**\n * The surface as drawn. For the environment terrain it is the field itself; for a\n * land object the field is eased down to the base across the edge band, so the\n * patch meets whatever it stands on instead of ending in a cliff. The mask is\n * applied to the height AND its gradient (product rule), so normals, slope rock\n * and the shadow march all see the same eased surface the vertices do.\n */\n#ifdef TERRAIN_PATCH\nfloat terrainPatchMask(vec2 p, out vec2 dmask){\n  vec2 l = (p - u_patchOffset) / u_patchSize;           // -0.5 .. 0.5 inside\n  vec2 d = (0.5 - abs(l)) * u_patchSize;                // metres to each pair of edges\n  vec2 sgn = vec2(l.x < 0.0 ? 1.0 : -1.0, l.y < 0.0 ? 1.0 : -1.0);\n  float dist = min(d.x, d.y);\n  vec2 ddist = d.x < d.y ? vec2(sgn.x, 0.0) : vec2(0.0, sgn.y);\n  if (dist <= 0.0){ dmask = vec2(0.0); return 0.0; }\n  if (u_edgeWidth <= 1e-3){ dmask = vec2(0.0); return 1.0; }\n  float x = clamp(dist / u_edgeWidth, 0.0, 1.0);\n  dmask = ddist * (6.0 * x * (1.0 - x) / u_edgeWidth);\n  return x * x * (3.0 - 2.0 * x);\n}\nfloat terrainSurfaceAt(vec2 p, float lodCell, out vec2 grad){\n  vec2 g;\n  float h = terrainSample(p, lodCell, g) - u_seaLevel;\n  vec2 dm;\n  float m = terrainPatchMask(p, dm);\n  grad = g * m + h * dm;\n  return u_seaLevel + h * m;\n}\nfloat terrainOccluderAt(vec2 p, float lodCell){\n  vec2 dm;\n  float m = terrainPatchMask(p, dm);\n  if (m <= 0.0) return u_seaLevel;\n  return u_seaLevel + (terrainHeightAt(p, lodCell) - u_seaLevel) * m;\n}\n#else\nfloat terrainSurfaceAt(vec2 p, float lodCell, out vec2 grad){ return terrainSample(p, lodCell, grad); }\nfloat terrainOccluderAt(vec2 p, float lodCell){ return terrainHeightAt(p, lodCell); }\n#endif\n";
 /**
  * Shading: the analytic self-shadow, the splat, and the light.
  *
@@ -70,7 +70,20 @@ export declare const terrainHeight = "\n#define TERRAIN_MOUNTAINS 0\n#define TER
  * The terminator itself stays per-pixel: `terrainLight` takes N·L from the
  * fragment's own normal, so only the CAST shadow is interpolated.
  */
-export declare const terrainShading = "\n/** 1 lit, 0 shadowed, soft in between. */\nfloat terrainSunShadow(vec3 p, vec3 n, float lodCell, int steps){\n  if (steps < 1 || u_sunShadow <= 0.0) return 1.0;\n  // Below the horizon there is nothing to shadow; the march would also walk\n  // downhill forever.\n  if (u_sunDir.y <= 0.015) return 1.0;\n  // A surface facing away from the sun is shadowed by definition, and marching\n  // from it only finds the ground it is already part of.\n  if (dot(n, u_sunDir) <= 0.0) return 0.0;\n\n  // Lift off the surface before starting, or every sample on a steep face - a\n  // terrace riser above all - reads its own ground as an occluder and the whole\n  // wall goes black in a grid of triangles. Start ON the offset surface and\n  // compare raw heights; subtracting the bias from the height difference instead\n  // makes the first sample fail on any slope tilted a few degrees from the sun.\n  float bias = max(lodCell, u_elevation * 0.003);\n  vec3 origin = p + n * bias;\n\n  float shadowLod = (1.0 / max(u_baseScale, 1e-9)) * 0.008;\n\n  float res = 1.0;\n  float t = bias * 3.0;\n  float maxT = (u_elevation * 2.5) / max(u_sunDir.y, 0.05);\n\n  for (int i = 0; i < 48; i++){\n    if (i >= steps || t > maxT) break;\n    vec3 sp = origin + u_sunDir * t;\n    // The occluder is sampled at the SHADING lod, coarsening with distance -\n    // never at a fixed coarse lod. Testing a fine surface point against a coarse\n    // height field puts the whole valley floor in shadow, because the coarse\n    // field sits above the fine one wherever the fine one has been cut down.\n    // Sampled MUCH coarser than the surface being shaded. A shadow does not need\n    // nine octaves: what casts a visible shadow is the landform, and marching the\n    // fine field costs the same nine octaves per step for detail that is below a\n    // pixel by the time it lands. Floored against the landform's own size, so the\n    // march runs about five octaves instead of nine wherever it starts.\n    float h = terrainHeightAt(sp.xz, max(max(lodCell * 2.0, t * 0.06), shadowLod));\n    float diff = sp.y - h;\n    res = min(res, u_shadowSoftness * diff / t);\n    if (res <= 0.0) return 0.0;\n    // Geometric growth: near the surface the occluder is metres away, at the end\n    // of the march it is kilometres, and a linear step wastes every sample at one\n    // end or the other. 1.7 rather than 1.42 so twelve steps actually reach maxT -\n    // at 1.42 the march ran out around 700 m and long shadows at low sun simply\n    // did not exist, which is a quality bug that happened to look like a cheap one.\n    t = t * 1.7 + bias;\n  }\n  return saturate(res);\n}\n\n/**\n * The shadow, faded out with distance and given a step budget that falls with it.\n *\n * The march is the most expensive thing left in the renderer, and past a few\n * kilometres it is buying nothing: aerial perspective has already washed most of\n * the contrast out of the ground, and a ridge shadow out there is a couple of\n * pixels wide. Skipping it entirely beyond u_shadowDistance drops the outer\n * clipmap rings - which are two thirds of the vertices - out of the march\n * completely, and the rings in between run four steps instead of fourteen.\n *\n * Faded rather than cut, or the cut-off would draw a visible circle on the ground.\n */\nfloat terrainShadowAt(vec3 p, vec3 n, float lodCell, float dist){\n  float fade = 1.0 - saturate(dist / max(u_shadowDistance, 1.0));\n  if (fade <= 0.002) return 1.0;\n  int steps = int(mix(4.0, float(u_shadowSteps), fade));\n  return mix(1.0, terrainSunShadow(p, n, lodCell, steps), fade);\n}\n\n/**\n * Albedo.\n *\n * Rock is splatted by SLOPE, everything else by height. That ordering is the\n * whole trick: it means a cliff is bare rock whether it is in a valley or on a\n * summit, which is how real ground works and why height-only splatting always\n * reads as a painted contour map.\n */\nvec3 terrainAlbedo(vec3 wp, float h01, float slope){\n  // Large-scale variation. Without it a splat layer is one flat colour across\n  // kilometres, and the eye reads flat colour as untextured rather than as ground.\n  float macro = tNoise(wp.xz * u_macroScale) * 0.5 + 0.5;\n  float tint = 1.0 + u_macroVariation * (macro - 0.5) * 2.0;\n\n  vec3 col = mix(u_lowColor, u_midColor, smoothstep(0.05, 0.55, h01));\n\n  // Peak layer, held back on steep ground: snow does not sit on a vertical face,\n  // and without this the summit looks dipped in paint.\n  float peak = smoothstep(u_peakLevel, u_peakLevel + u_peakBlend, h01 - slope * u_peakSlopeFalloff * 0.6);\n  col = mix(col, u_peakColor, saturate(peak));\n\n  float rock = smoothstep(u_slopeRockStart, u_slopeRockEnd, slope);\n  col = mix(col, u_rockColor, rock);\n\n  return col * tint;\n}\n\n/** High-frequency bump, well below the mesh resolution, faded out with distance\n *  so it never becomes a field of crawling pixels on the horizon. One evaluation:\n *  the noise carries its own derivative, so the three taps a finite difference\n *  would need are not. */\nvec3 terrainDetailNormal(vec3 n, vec3 wp, float dist){\n  float fade = 1.0 - saturate(dist * u_detailFade);\n  float amt = u_detailStrength * fade * fade;\n  if (amt <= 0.001) return n;\n  vec3 d = tNoised(wp.xz * u_detailScale);\n  return normalize(n + vec3(-d.y, 0.0, -d.z) * amt * 0.9);\n}\n\n/**\n * Direct sun, sky fill and ground bounce.\n *\n * Sun irradiance is in the units skyRadiance returns, calibrated against it rather\n * than guessed: a 0.3-albedo surface in full sun lands a little below the sky at\n * the horizon, which is the relationship the eye reads as daylight. Set it to the\n * clouds' SUN_RADIANCE and every ground surface clips to white.\n */\nconst float TERRAIN_SUN = 2.2;\n\nvec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneShadow){\n  float ndl = max(dot(n, u_sunDir), 0.0);\n  // Wrap the terminator slightly: bare ground is not a Lambertian sphere, and a\n  // hard terminator across a whole hillside reads as CG.\n  float wrap = max((dot(n, u_sunDir) + 0.2) / 1.2, 0.0);\n  float diff = mix(ndl, wrap, 0.4);\n\n  vec3 sun = u_sunColor * u_sunIntensity * TERRAIN_SUN * diff * shadow * sceneShadow;\n\n  // Sky fill from the same atmosphere the sky is drawn with, so it darkens and\n  // warms with the sun instead of freezing at a constant blue - but supplied as a\n  // uniform rather than evaluated here, since it is the same for every pixel.\n  // Whitened a little: a single-scattering zenith colour is very saturated, and\n  // at full saturation every shadowed slope - snow above all - comes out cyan.\n  vec3 fill = mix(u_skyAmbient, vec3(dot(u_skyAmbient, vec3(0.3333))), 0.4);\n  vec3 ambient = fill * (0.5 + 0.5 * n.y) * u_ambient * 1.05;\n\n  // Ground bounce, tinted by whatever the ground is. Keeps overhangs and shaded\n  // faces off pure black without flattening them the way raising ambient does.\n  vec3 bounce = u_lowColor * u_groundAmbient * (0.5 - 0.5 * n.y) * u_bounce * 1.3;\n\n  vec3 col = albedo * (sun + ambient + bounce);\n\n  // A single specular lobe. Rock barely needs it; wet sand and snow at low sun\n  // are almost entirely this.\n  if (u_specular > 0.0){\n    vec3 hv = normalize(u_sunDir - viewDir);\n    float a = max(u_roughness * u_roughness, 0.002);\n    float nh = max(dot(n, hv), 0.0);\n    float dd = nh * nh * (a - 1.0) + 1.0;\n    float d = a / max(3.14159265 * dd * dd, 1e-4);\n    col += u_sunColor * u_sunIntensity * TERRAIN_SUN * d * u_specular * shadow * sceneShadow * ndl;\n  }\n\n  return col;\n}\n\n/**\n * Aerial perspective.\n *\n * The single most important line in this shader for the horizon. Ground fades\n * into the exact sky colour it is seen through, at a rate that thins with\n * altitude because the atmosphere does \u2014 so a distant ridge sits behind the haze\n * and a peak above it stands clear of it, which is what tells you the scene is\n * kilometres across rather than metres.\n *\n * The one remaining per-pixel skyRadiance call, and it has to be: the colour is\n * the sky in the view direction, which is different for every fragment.\n */\nvec3 terrainAerial(vec3 col, vec3 rd, float dist, float height){\n  float scaleHeight = exp(-max(height - u_seaLevel, 0.0) / 1400.0);\n  float f = 1.0 - exp(-dist * u_fogDensity * scaleHeight);\n  if (f < 0.002) return col;\n  return mix(col, skyRadiance(rd), saturate(f));\n}\n";
+export declare const terrainShading = "\n/** 1 lit, 0 shadowed, soft in between. */\nfloat terrainSunShadow(vec3 p, vec3 n, float lodCell, int steps){\n  if (steps < 1 || u_sunShadow <= 0.0) return 1.0;\n  // Below the horizon there is nothing to shadow; the march would also walk\n  // downhill forever.\n  if (u_sunDir.y <= 0.015) return 1.0;\n  // A surface facing away from the sun is shadowed by definition, and marching\n  // from it only finds the ground it is already part of.\n  if (dot(n, u_sunDir) <= 0.0) return 0.0;\n\n  // Lift off the surface before starting, or every sample on a steep face - a\n  // terrace riser above all - reads its own ground as an occluder and the whole\n  // wall goes black in a grid of triangles. Start ON the offset surface and\n  // compare raw heights; subtracting the bias from the height difference instead\n  // makes the first sample fail on any slope tilted a few degrees from the sun.\n  float bias = max(lodCell, u_elevation * 0.003);\n  vec3 origin = p + n * bias;\n\n  float shadowLod = (1.0 / max(u_baseScale, 1e-9)) * 0.008;\n\n  float res = 1.0;\n  float t = bias * 3.0;\n  float maxT = (u_elevation * 2.5) / max(u_sunDir.y, 0.05);\n\n  for (int i = 0; i < 48; i++){\n    if (i >= steps || t > maxT) break;\n    vec3 sp = origin + u_sunDir * t;\n    // The occluder is sampled at the SHADING lod, coarsening with distance -\n    // never at a fixed coarse lod. Testing a fine surface point against a coarse\n    // height field puts the whole valley floor in shadow, because the coarse\n    // field sits above the fine one wherever the fine one has been cut down.\n    // Sampled MUCH coarser than the surface being shaded. A shadow does not need\n    // nine octaves: what casts a visible shadow is the landform, and marching the\n    // fine field costs the same nine octaves per step for detail that is below a\n    // pixel by the time it lands. Floored against the landform's own size, so the\n    // march runs about five octaves instead of nine wherever it starts.\n    float h = terrainOccluderAt(sp.xz, max(max(lodCell * 2.0, t * 0.06), shadowLod));\n    float diff = sp.y - h;\n    res = min(res, u_shadowSoftness * diff / t);\n    if (res <= 0.0) return 0.0;\n    // Geometric growth: near the surface the occluder is metres away, at the end\n    // of the march it is kilometres, and a linear step wastes every sample at one\n    // end or the other. 1.7 rather than 1.42 so twelve steps actually reach maxT -\n    // at 1.42 the march ran out around 700 m and long shadows at low sun simply\n    // did not exist, which is a quality bug that happened to look like a cheap one.\n    t = t * 1.7 + bias;\n  }\n  return saturate(res);\n}\n\n/**\n * The shadow, faded out with distance and given a step budget that falls with it.\n *\n * The march is the most expensive thing left in the renderer, and past a few\n * kilometres it is buying nothing: aerial perspective has already washed most of\n * the contrast out of the ground, and a ridge shadow out there is a couple of\n * pixels wide. Skipping it entirely beyond u_shadowDistance drops the outer\n * clipmap rings - which are two thirds of the vertices - out of the march\n * completely, and the rings in between run four steps instead of fourteen.\n *\n * Faded rather than cut, or the cut-off would draw a visible circle on the ground.\n */\nfloat terrainShadowAt(vec3 p, vec3 n, float lodCell, float dist){\n  float fade = 1.0 - saturate(dist / max(u_shadowDistance, 1.0));\n  if (fade <= 0.002) return 1.0;\n  int steps = int(mix(4.0, float(u_shadowSteps), fade));\n  return mix(1.0, terrainSunShadow(p, n, lodCell, steps), fade);\n}\n\n/**\n * Albedo.\n *\n * Rock is splatted by SLOPE, everything else by height. That ordering is the\n * whole trick: it means a cliff is bare rock whether it is in a valley or on a\n * summit, which is how real ground works and why height-only splatting always\n * reads as a painted contour map.\n */\n/**\n * Splat weights for the four layers, in layer order: low, mid, rock, peak.\n * Exactly the old colour mixes written as weights \u2014 low/mid by height, the peak\n * held back on steep ground (snow does not sit on a vertical face), rock by slope\n * and applied last, which is why a cliff reads as a cliff at any altitude.\n */\nvec4 terrainLayerWeights(float h01, float slope){\n  float m = smoothstep(0.05, 0.55, h01);\n  float p = saturate(smoothstep(u_peakLevel, u_peakLevel + u_peakBlend, h01 - slope * u_peakSlopeFalloff * 0.6));\n  float r = smoothstep(u_slopeRockStart, u_slopeRockEnd, slope);\n  return vec4((1.0 - m) * (1.0 - p) * (1.0 - r), m * (1.0 - p) * (1.0 - r), r, p * (1.0 - r));\n}\n\n/** Large-scale variation. Without it a splat layer is one flat colour across\n *  kilometres, and the eye reads flat colour as untextured rather than as ground. */\nfloat terrainMacro(vec3 wp){\n  float macro = tNoise(wp.xz * u_macroScale) * 0.5 + 0.5;\n  return 1.0 + u_macroVariation * (macro - 0.5) * 2.0;\n}\n\n/** The far-field albedo: each layer's far colour by its weight. */\nvec3 terrainAlbedo(vec3 wp, vec4 w){\n  vec3 col = u_tFar[0] * w.x + u_tFar[1] * w.y + u_tFar[2] * w.z + u_tFar[3] * w.w;\n  return col * terrainMacro(wp);\n}\n\n/** High-frequency bump, well below the mesh resolution, faded out with distance\n *  so it never becomes a field of crawling pixels on the horizon. One evaluation:\n *  the noise carries its own derivative, so the three taps a finite difference\n *  would need are not. */\nvec3 terrainDetailNormal(vec3 n, vec3 wp, float dist){\n  float fade = 1.0 - saturate(dist * u_detailFade);\n  float amt = u_detailStrength * fade * fade;\n  if (amt <= 0.001) return n;\n  vec3 d = tNoised(wp.xz * u_detailScale);\n  return normalize(n + vec3(-d.y, 0.0, -d.z) * amt * 0.9);\n}\n\n/**\n * Direct sun, sky fill and ground bounce.\n *\n * Sun irradiance is in the units skyRadiance returns, calibrated against it rather\n * than guessed: a 0.3-albedo surface in full sun lands a little below the sky at\n * the horizon, which is the relationship the eye reads as daylight. Set it to the\n * clouds' SUN_RADIANCE and every ground surface clips to white.\n */\nconst float TERRAIN_SUN = 2.2;\n\nvec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneShadow, float roughness, float ao){\n  float ndl = max(dot(n, u_sunDir), 0.0);\n  // Wrap the terminator slightly: bare ground is not a Lambertian sphere, and a\n  // hard terminator across a whole hillside reads as CG.\n  float wrap = max((dot(n, u_sunDir) + 0.2) / 1.2, 0.0);\n  float diff = mix(ndl, wrap, 0.4);\n\n  vec3 sun = u_sunColor * u_sunIntensity * TERRAIN_SUN * diff * shadow * sceneShadow;\n\n  // Sky fill from the same atmosphere the sky is drawn with, so it darkens and\n  // warms with the sun instead of freezing at a constant blue - but supplied as a\n  // uniform rather than evaluated here, since it is the same for every pixel.\n  // Whitened a little: a single-scattering zenith colour is very saturated, and\n  // at full saturation every shadowed slope - snow above all - comes out cyan.\n  vec3 fill = mix(u_skyAmbient, vec3(dot(u_skyAmbient, vec3(0.3333))), 0.4);\n  vec3 ambient = fill * (0.5 + 0.5 * n.y) * u_ambient * 1.05;\n\n  // Ground bounce, tinted by whatever the ground is. Keeps overhangs and shaded\n  // faces off pure black without flattening them the way raising ambient does.\n  vec3 bounce = u_tFar[0] * u_groundAmbient * (0.5 - 0.5 * n.y) * u_bounce * 1.3;\n\n  // Occlusion is a property of the small-scale surface, so it darkens the light\n  // that arrives from everywhere \u2014 sky fill and bounce \u2014 and leaves the sun alone.\n  vec3 col = albedo * (sun + (ambient + bounce) * ao);\n\n  // A single specular lobe. Rock barely needs it; wet sand and snow at low sun\n  // are almost entirely this.\n  if (u_specular > 0.0){\n    vec3 hv = normalize(u_sunDir - viewDir);\n    float a = max(roughness * roughness, 0.002);\n    float nh = max(dot(n, hv), 0.0);\n    float dd = nh * nh * (a - 1.0) + 1.0;\n    float d = a / max(3.14159265 * dd * dd, 1e-4);\n    col += u_sunColor * u_sunIntensity * TERRAIN_SUN * d * u_specular * shadow * sceneShadow * ndl;\n  }\n\n  return col;\n}\n\n/**\n * Aerial perspective.\n *\n * The single most important line in this shader for the horizon. Ground fades\n * into the exact sky colour it is seen through, at a rate that thins with\n * altitude because the atmosphere does \u2014 so a distant ridge sits behind the haze\n * and a peak above it stands clear of it, which is what tells you the scene is\n * kilometres across rather than metres.\n *\n * The one remaining per-pixel skyRadiance call, and it has to be: the colour is\n * the sky in the view direction, which is different for every fragment.\n */\nvec3 terrainAerial(vec3 col, vec3 rd, float dist, float height){\n  float scaleHeight = exp(-max(height - u_seaLevel, 0.0) / 1400.0);\n  float f = 1.0 - exp(-dist * u_fogDensity * scaleHeight);\n  if (f < 0.002) return col;\n  return mix(col, skyRadiance(rd), saturate(f));\n}\n";
+/**
+ * The textured near field. Needs `surfaceSampling` (surfaceCore.glsl) before it.
+ *
+ * Only the two heaviest layers are sampled per pixel. Two layers overlap almost
+ * everywhere a boundary is; three meet only at triple points, and halving the
+ * fetches is worth a slightly harder edge there. The rock layer is projected
+ * biplanar — it is the only one that ever sits on a steep face — and the other
+ * three straight down.
+ *
+ * Gradients come in from main (see sfSample): which layer a pixel samples is a
+ * per-pixel decision, so nothing in here may call dFdx.
+ */
+export declare const terrainTextured = "\n#ifdef TERRAIN_TEXTURED\nstruct TerrainGrads { vec2 topX; vec2 topY; vec2 sideXX; vec2 sideXY; vec2 sideZX; vec2 sideZY; };\n\n// The large-scale sample is the same texture, T_MACRO times bigger.\n#define T_MACRO 8.0\n\n/**\n * One layer's three arrays at one projection, at two scales.\n *\n * A ground scan is millimetres per texel: a gravel tile shows its pebbles for a\n * few metres and is a flat average colour from fifty. So past the point where a\n * pixel covers a fifth of a tile, the same texture is sampled again T_MACRO times\n * larger, and its pebbles become patches, its cracks become streaks \u2014 the set's\n * character survives out to hundreds of metres instead of dissolving into a flat\n * colour, and picking a different set is visible from where people actually look\n * at terrain. The switch is by pixel footprint, so it is the same at any tile\n * size and any camera height. Each scale is skipped when its weight is zero.\n */\nvoid terrainTap(int L, vec2 uv, vec2 dx, vec2 dy, out vec4 c, out vec4 nh, out vec4 o){\n  float layer = float(L);\n  float fp = max(length(dx), length(dy));\n  float m = smoothstep(0.04, 0.25, fp);\n  vec4 cd = vec4(0.0);\n  vec4 nd = vec4(0.0);\n  vec4 od = vec4(0.0);\n  vec4 cm = vec4(0.0);\n  vec4 nm = vec4(0.0);\n  vec4 om = vec4(0.0);\n  if (m < 0.999){\n    cd = sfSample(u_tColor,  uv, dx, dy, layer, u_tMeanC[L]);\n    nd = sfSample(u_tNormal, uv, dx, dy, layer, u_tMeanN[L]);\n    od = sfSample(u_tOrm,    uv, dx, dy, layer, u_tMeanO[L]);\n  }\n  if (m > 0.001){\n    vec2 mu = uv / T_MACRO;\n    vec2 mdx = dx / T_MACRO;\n    vec2 mdy = dy / T_MACRO;\n    cm = sfSample(u_tColor,  mu, mdx, mdy, layer, u_tMeanC[L]);\n    nm = sfSample(u_tNormal, mu, mdx, mdy, layer, u_tMeanN[L]);\n    om = sfSample(u_tOrm,    mu, mdx, mdy, layer, u_tMeanO[L]);\n    // No height blending at the large scale. A height map blown up 8x has\n    // tens-of-metres blobs, and blending layers along those contours paints\n    // the ground in camouflage. Mid height = an ordinary cross-fade.\n    nm.a = 0.5;\n  }\n  c  = mix(cd, cm, m);\n  nh = mix(nd, nm, m);\n  o  = mix(od, om, m);\n}\n\n/** One layer: albedo (tinted), an unnormalised world normal, surface height,\n *  roughness and occlusion. An untextured layer returns its flat colour. */\nvoid terrainLayerSample(int L, vec3 wp, vec3 n, TerrainGrads g,\n                        out vec3 col, out vec3 wn, out float h, out float rough, out float ao){\n  col = u_tFar[L];\n  wn = n;\n  h = 0.5;\n  rough = u_roughness;\n  ao = 1.0;\n  if (u_tLayer[L].z > 0.5){\n    float inv = u_tLayer[L].x;\n    float ns = u_tLayer[L].y;\n    vec4 c = vec4(0.0);\n    vec4 nh = vec4(0.0);\n    vec4 o = vec4(0.0);\n    vec3 acc = vec3(0.0);\n    if (L == 2){\n      // Biplanar: the two strongest axes. The third adds a fraction of a percent\n      // anywhere that is not an exact corner and costs a third of the fetches.\n      vec3 an = abs(n);\n      an = an * an * an;\n      an /= max(an.x + an.y + an.z, 1e-4);\n      float lo = min(an.x, min(an.y, an.z));\n      vec3 bw = max(an - lo, 0.0);\n      bw /= max(bw.x + bw.y + bw.z, 1e-4);\n      vec4 c1, n1, o1;\n      if (bw.y > 0.002){\n        terrainTap(L, wp.xz * inv, g.topX * inv, g.topY * inv, c1, n1, o1);\n        c += c1 * bw.y; nh += n1 * bw.y; o += o1 * bw.y;\n        acc += sfWhiteoutTop(n, sfUnpackNormal(n1.rgb, ns)) * bw.y;\n      }\n      if (bw.x > 0.002){\n        terrainTap(L, wp.zy * inv, g.sideXX * inv, g.sideXY * inv, c1, n1, o1);\n        c += c1 * bw.x; nh += n1 * bw.x; o += o1 * bw.x;\n        acc += sfWhiteoutX(n, sfUnpackNormal(n1.rgb, ns)) * bw.x;\n      }\n      if (bw.z > 0.002){\n        terrainTap(L, wp.xy * inv, g.sideZX * inv, g.sideZY * inv, c1, n1, o1);\n        c += c1 * bw.z; nh += n1 * bw.z; o += o1 * bw.z;\n        acc += sfWhiteoutZ(n, sfUnpackNormal(n1.rgb, ns)) * bw.z;\n      }\n    } else {\n      terrainTap(L, wp.xz * inv, g.topX * inv, g.topY * inv, c, nh, o);\n      acc = sfWhiteoutTop(n, sfUnpackNormal(nh.rgb, ns));\n    }\n    col = c.rgb * u_tTint[L];\n    wn = acc;\n    h = nh.a;\n    rough = o.g;\n    ao = o.r;\n  }\n}\n\n/** Near-field surface for weights w. Outputs albedo (no macro), normal,\n *  roughness and occlusion. */\nvoid terrainSurfaceNear(vec3 wp, vec3 n, vec4 w, TerrainGrads g,\n                        out vec3 albedo, out vec3 nrm, out float rough, out float ao){\n  float ws[4];\n  ws[0] = w.x; ws[1] = w.y; ws[2] = w.z; ws[3] = w.w;\n  int i0 = 0;\n  float b0 = -1.0;\n  for (int i = 0; i < 4; i++){ if (ws[i] > b0){ b0 = ws[i]; i0 = i; } }\n  ws[i0] = -1.0;\n  int i1 = 0;\n  float b1 = -1.0;\n  for (int i = 0; i < 4; i++){ if (ws[i] > b1){ b1 = ws[i]; i1 = i; } }\n  b0 = max(b0, 0.0);\n  b1 = max(b1, 0.0);\n  float bs = max(b0 + b1, 1e-4);\n  b0 /= bs;\n  b1 /= bs;\n\n  vec3 c0, n0, c1, n1;\n  float h0, r0, a0, h1, r1, a1;\n  terrainLayerSample(i0, wp, n, g, c0, n0, h0, r0, a0);\n  if (b1 > 0.001){\n    terrainLayerSample(i1, wp, n, g, c1, n1, h1, r1, a1);\n  } else {\n    c1 = c0; n1 = n0; h1 = h0; r1 = r0; a1 = a0;\n  }\n\n  // Height blend: the layer whose own surface is higher at this texel wins, so\n  // gravel comes through grass along the gravel's grain and rock emerges from\n  // soil along its cracks, instead of the two cross-fading into mud.\n  float hb = u_tHeightBlend;\n  float range = mix(1.0, 0.04, hb);\n  float v0 = b0 + h0 * hb;\n  float v1 = b1 + h1 * hb;\n  float peak = max(v0, v1);\n  float w0 = max(v0 - (peak - range), 0.0);\n  float w1 = max(v1 - (peak - range), 0.0);\n  if (b1 <= 0.001) w1 = 0.0;\n  float ws2 = max(w0 + w1, 1e-4);\n  w0 /= ws2;\n  w1 /= ws2;\n\n  albedo = c0 * w0 + c1 * w1;\n  nrm = normalize(n0 * w0 + n1 * w1);\n  rough = r0 * w0 + r1 * w1;\n  ao = a0 * w0 + a1 * w1;\n}\n#endif\n";
 /** Everything a surface material needs, in include order. Requires three's
  *  `<common>` and `skyLib` from cloudCore before it. */
 export declare const terrainField: string;

package/dist/shaders/glsl/terrainCore.glsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terrainCore.glsl.d.ts","sourceRoot":"","sources":["../../../src/shaders/glsl/terrainCore.glsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,eAAe,6/CA2C3B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,uiCAiCxB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,i+XA0SzB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,+tQA8K1B,CAAA;AAED;wDACwD;AACxD,eAAO,MAAM,YAAY,QAA4D,CAAA;AAErF,eAAO,MAAM,WAAW,QAA4C,CAAA"}
+{"version":3,"file":"terrainCore.glsl.d.ts","sourceRoot":"","sources":["../../../src/shaders/glsl/terrainCore.glsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,eAAe,wpGA2E3B,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,uiCAiCxB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,mqbAiVzB,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,s0RAuL1B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,4pLAyJ3B,CAAA;AAED;wDACwD;AACxD,eAAO,MAAM,YAAY,QAA4D,CAAA;AAErF,eAAO,MAAM,WAAW,QAA4C,CAAA"}

package/dist/shaders/glsl/terrainCore.glsl.js

@@ -70,6 +70,38 @@ uniform float u_ambient, u_bounce, u_sunShadow, u_shadowSoftness;
 uniform float u_shadowDistance;
 uniform float u_fogDensity, u_exposure;
 uniform int   u_shadowSteps;
+
+// Ground textures. The far colour per layer is always set: the flat colour for an
+// untextured layer, the texture's own mean x tint for a textured one, so the
+// near-to-far fade has no colour jump.
+uniform vec3  u_tFar[4];
+#ifdef TERRAIN_TEXTURED
+uniform sampler2DArray u_tColor;    // albedo, sRGB
+uniform sampler2DArray u_tNormal;   // rgb tangent normal (GL), a surface height
+uniform sampler2DArray u_tOrm;      // r ambient occlusion, g roughness
+uniform vec4  u_tLayer[4];          // 1/tileSize, normalStrength, textured 0|1, -
+uniform vec3  u_tTint[4];           // layer colour / texture mean: the texture averages to the layer colour
+uniform vec4  u_tMeanC[4];          // per-array layer means, for the stochastic blend
+uniform vec4  u_tMeanN[4];
+uniform vec4  u_tMeanO[4];
+uniform float u_tDistance;
+uniform float u_tHeightBlend;
+#endif
+
+// A land object: a bounded patch of this field, placed by its object's transform.
+// Its "terrain space" is metres from the object's origin, unrotated, plus a seed
+// offset; height is above the object's base. See TerrainMaterial's patch vertex.
+#ifdef TERRAIN_PATCH
+uniform vec2  u_patchSize;      // footprint in metres (object scale x / z)
+uniform vec2  u_patchOffset;    // terrain-space centre: the seed's offset into the field
+uniform float u_edgeWidth;      // metres over which the land eases down to its base
+uniform vec3  u_camTerrain;     // the camera, in terrain space
+uniform float u_scaleY;         // object scale y: terrain metres = local y x this
+uniform float u_patchCell;      // metres per grid cell
+#define TERRAIN_CAM u_camTerrain
+#else
+#define TERRAIN_CAM cameraPosition
+#endif
 `;
 /**
  * Gradient noise with an analytic derivative.
@@ -427,6 +459,45 @@ float terrainHeightAt(vec2 p, float lodCell){
 vec3 terrainNormal(vec2 grad){
   return normalize(vec3(-grad.x, 1.0, -grad.y));
 }
+
+/**
+ * The surface as drawn. For the environment terrain it is the field itself; for a
+ * land object the field is eased down to the base across the edge band, so the
+ * patch meets whatever it stands on instead of ending in a cliff. The mask is
+ * applied to the height AND its gradient (product rule), so normals, slope rock
+ * and the shadow march all see the same eased surface the vertices do.
+ */
+#ifdef TERRAIN_PATCH
+float terrainPatchMask(vec2 p, out vec2 dmask){
+  vec2 l = (p - u_patchOffset) / u_patchSize;           // -0.5 .. 0.5 inside
+  vec2 d = (0.5 - abs(l)) * u_patchSize;                // metres to each pair of edges
+  vec2 sgn = vec2(l.x < 0.0 ? 1.0 : -1.0, l.y < 0.0 ? 1.0 : -1.0);
+  float dist = min(d.x, d.y);
+  vec2 ddist = d.x < d.y ? vec2(sgn.x, 0.0) : vec2(0.0, sgn.y);
+  if (dist <= 0.0){ dmask = vec2(0.0); return 0.0; }
+  if (u_edgeWidth <= 1e-3){ dmask = vec2(0.0); return 1.0; }
+  float x = clamp(dist / u_edgeWidth, 0.0, 1.0);
+  dmask = ddist * (6.0 * x * (1.0 - x) / u_edgeWidth);
+  return x * x * (3.0 - 2.0 * x);
+}
+float terrainSurfaceAt(vec2 p, float lodCell, out vec2 grad){
+  vec2 g;
+  float h = terrainSample(p, lodCell, g) - u_seaLevel;
+  vec2 dm;
+  float m = terrainPatchMask(p, dm);
+  grad = g * m + h * dm;
+  return u_seaLevel + h * m;
+}
+float terrainOccluderAt(vec2 p, float lodCell){
+  vec2 dm;
+  float m = terrainPatchMask(p, dm);
+  if (m <= 0.0) return u_seaLevel;
+  return u_seaLevel + (terrainHeightAt(p, lodCell) - u_seaLevel) * m;
+}
+#else
+float terrainSurfaceAt(vec2 p, float lodCell, out vec2 grad){ return terrainSample(p, lodCell, grad); }
+float terrainOccluderAt(vec2 p, float lodCell){ return terrainHeightAt(p, lodCell); }
+#endif
 `;
 /**
  * Shading: the analytic self-shadow, the splat, and the light.
@@ -481,7 +552,7 @@ float terrainSunShadow(vec3 p, vec3 n, float lodCell, int steps){
     // fine field costs the same nine octaves per step for detail that is below a
     // pixel by the time it lands. Floored against the landform's own size, so the
     // march runs about five octaves instead of nine wherever it starts.
-    float h = terrainHeightAt(sp.xz, max(max(lodCell * 2.0, t * 0.06), shadowLod));
+    float h = terrainOccluderAt(sp.xz, max(max(lodCell * 2.0, t * 0.06), shadowLod));
     float diff = sp.y - h;
     res = min(res, u_shadowSoftness * diff / t);
     if (res <= 0.0) return 0.0;
@@ -522,23 +593,30 @@ float terrainShadowAt(vec3 p, vec3 n, float lodCell, float dist){
  * summit, which is how real ground works and why height-only splatting always
  * reads as a painted contour map.
  */
-vec3 terrainAlbedo(vec3 wp, float h01, float slope){
-  // Large-scale variation. Without it a splat layer is one flat colour across
-  // kilometres, and the eye reads flat colour as untextured rather than as ground.
-  float macro = tNoise(wp.xz * u_macroScale) * 0.5 + 0.5;
-  float tint = 1.0 + u_macroVariation * (macro - 0.5) * 2.0;
-
-  vec3 col = mix(u_lowColor, u_midColor, smoothstep(0.05, 0.55, h01));
-
-  // Peak layer, held back on steep ground: snow does not sit on a vertical face,
-  // and without this the summit looks dipped in paint.
-  float peak = smoothstep(u_peakLevel, u_peakLevel + u_peakBlend, h01 - slope * u_peakSlopeFalloff * 0.6);
-  col = mix(col, u_peakColor, saturate(peak));
+/**
+ * Splat weights for the four layers, in layer order: low, mid, rock, peak.
+ * Exactly the old colour mixes written as weights — low/mid by height, the peak
+ * held back on steep ground (snow does not sit on a vertical face), rock by slope
+ * and applied last, which is why a cliff reads as a cliff at any altitude.
+ */
+vec4 terrainLayerWeights(float h01, float slope){
+  float m = smoothstep(0.05, 0.55, h01);
+  float p = saturate(smoothstep(u_peakLevel, u_peakLevel + u_peakBlend, h01 - slope * u_peakSlopeFalloff * 0.6));
+  float r = smoothstep(u_slopeRockStart, u_slopeRockEnd, slope);
+  return vec4((1.0 - m) * (1.0 - p) * (1.0 - r), m * (1.0 - p) * (1.0 - r), r, p * (1.0 - r));
+}
 
-  float rock = smoothstep(u_slopeRockStart, u_slopeRockEnd, slope);
-  col = mix(col, u_rockColor, rock);
+/** Large-scale variation. Without it a splat layer is one flat colour across
+ *  kilometres, and the eye reads flat colour as untextured rather than as ground. */
+float terrainMacro(vec3 wp){
+  float macro = tNoise(wp.xz * u_macroScale) * 0.5 + 0.5;
+  return 1.0 + u_macroVariation * (macro - 0.5) * 2.0;
+}
 
-  return col * tint;
+/** The far-field albedo: each layer's far colour by its weight. */
+vec3 terrainAlbedo(vec3 wp, vec4 w){
+  vec3 col = u_tFar[0] * w.x + u_tFar[1] * w.y + u_tFar[2] * w.z + u_tFar[3] * w.w;
+  return col * terrainMacro(wp);
 }
 
 /** High-frequency bump, well below the mesh resolution, faded out with distance
@@ -563,7 +641,7 @@ vec3 terrainDetailNormal(vec3 n, vec3 wp, float dist){
  */
 const float TERRAIN_SUN = 2.2;
 
-vec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneShadow){
+vec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneShadow, float roughness, float ao){
   float ndl = max(dot(n, u_sunDir), 0.0);
   // Wrap the terminator slightly: bare ground is not a Lambertian sphere, and a
   // hard terminator across a whole hillside reads as CG.
@@ -582,15 +660,17 @@ vec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneSh
 
   // Ground bounce, tinted by whatever the ground is. Keeps overhangs and shaded
   // faces off pure black without flattening them the way raising ambient does.
-  vec3 bounce = u_lowColor * u_groundAmbient * (0.5 - 0.5 * n.y) * u_bounce * 1.3;
+  vec3 bounce = u_tFar[0] * u_groundAmbient * (0.5 - 0.5 * n.y) * u_bounce * 1.3;
 
-  vec3 col = albedo * (sun + ambient + bounce);
+  // Occlusion is a property of the small-scale surface, so it darkens the light
+  // that arrives from everywhere — sky fill and bounce — and leaves the sun alone.
+  vec3 col = albedo * (sun + (ambient + bounce) * ao);
 
   // A single specular lobe. Rock barely needs it; wet sand and snow at low sun
   // are almost entirely this.
   if (u_specular > 0.0){
     vec3 hv = normalize(u_sunDir - viewDir);
-    float a = max(u_roughness * u_roughness, 0.002);
+    float a = max(roughness * roughness, 0.002);
     float nh = max(dot(n, hv), 0.0);
     float dd = nh * nh * (a - 1.0) + 1.0;
     float d = a / max(3.14159265 * dd * dd, 1e-4);
@@ -619,6 +699,172 @@ vec3 terrainAerial(vec3 col, vec3 rd, float dist, float height){
   return mix(col, skyRadiance(rd), saturate(f));
 }
 `;
+/**
+ * The textured near field. Needs `surfaceSampling` (surfaceCore.glsl) before it.
+ *
+ * Only the two heaviest layers are sampled per pixel. Two layers overlap almost
+ * everywhere a boundary is; three meet only at triple points, and halving the
+ * fetches is worth a slightly harder edge there. The rock layer is projected
+ * biplanar — it is the only one that ever sits on a steep face — and the other
+ * three straight down.
+ *
+ * Gradients come in from main (see sfSample): which layer a pixel samples is a
+ * per-pixel decision, so nothing in here may call dFdx.
+ */
+export const terrainTextured = /* glsl */ `
+#ifdef TERRAIN_TEXTURED
+struct TerrainGrads { vec2 topX; vec2 topY; vec2 sideXX; vec2 sideXY; vec2 sideZX; vec2 sideZY; };
+
+// The large-scale sample is the same texture, T_MACRO times bigger.
+#define T_MACRO 8.0
+
+/**
+ * One layer's three arrays at one projection, at two scales.
+ *
+ * A ground scan is millimetres per texel: a gravel tile shows its pebbles for a
+ * few metres and is a flat average colour from fifty. So past the point where a
+ * pixel covers a fifth of a tile, the same texture is sampled again T_MACRO times
+ * larger, and its pebbles become patches, its cracks become streaks — the set's
+ * character survives out to hundreds of metres instead of dissolving into a flat
+ * colour, and picking a different set is visible from where people actually look
+ * at terrain. The switch is by pixel footprint, so it is the same at any tile
+ * size and any camera height. Each scale is skipped when its weight is zero.
+ */
+void terrainTap(int L, vec2 uv, vec2 dx, vec2 dy, out vec4 c, out vec4 nh, out vec4 o){
+  float layer = float(L);
+  float fp = max(length(dx), length(dy));
+  float m = smoothstep(0.04, 0.25, fp);
+  vec4 cd = vec4(0.0);
+  vec4 nd = vec4(0.0);
+  vec4 od = vec4(0.0);
+  vec4 cm = vec4(0.0);
+  vec4 nm = vec4(0.0);
+  vec4 om = vec4(0.0);
+  if (m < 0.999){
+    cd = sfSample(u_tColor,  uv, dx, dy, layer, u_tMeanC[L]);
+    nd = sfSample(u_tNormal, uv, dx, dy, layer, u_tMeanN[L]);
+    od = sfSample(u_tOrm,    uv, dx, dy, layer, u_tMeanO[L]);
+  }
+  if (m > 0.001){
+    vec2 mu = uv / T_MACRO;
+    vec2 mdx = dx / T_MACRO;
+    vec2 mdy = dy / T_MACRO;
+    cm = sfSample(u_tColor,  mu, mdx, mdy, layer, u_tMeanC[L]);
+    nm = sfSample(u_tNormal, mu, mdx, mdy, layer, u_tMeanN[L]);
+    om = sfSample(u_tOrm,    mu, mdx, mdy, layer, u_tMeanO[L]);
+    // No height blending at the large scale. A height map blown up 8x has
+    // tens-of-metres blobs, and blending layers along those contours paints
+    // the ground in camouflage. Mid height = an ordinary cross-fade.
+    nm.a = 0.5;
+  }
+  c  = mix(cd, cm, m);
+  nh = mix(nd, nm, m);
+  o  = mix(od, om, m);
+}
+
+/** One layer: albedo (tinted), an unnormalised world normal, surface height,
+ *  roughness and occlusion. An untextured layer returns its flat colour. */
+void terrainLayerSample(int L, vec3 wp, vec3 n, TerrainGrads g,
+                        out vec3 col, out vec3 wn, out float h, out float rough, out float ao){
+  col = u_tFar[L];
+  wn = n;
+  h = 0.5;
+  rough = u_roughness;
+  ao = 1.0;
+  if (u_tLayer[L].z > 0.5){
+    float inv = u_tLayer[L].x;
+    float ns = u_tLayer[L].y;
+    vec4 c = vec4(0.0);
+    vec4 nh = vec4(0.0);
+    vec4 o = vec4(0.0);
+    vec3 acc = vec3(0.0);
+    if (L == 2){
+      // Biplanar: the two strongest axes. The third adds a fraction of a percent
+      // anywhere that is not an exact corner and costs a third of the fetches.
+      vec3 an = abs(n);
+      an = an * an * an;
+      an /= max(an.x + an.y + an.z, 1e-4);
+      float lo = min(an.x, min(an.y, an.z));
+      vec3 bw = max(an - lo, 0.0);
+      bw /= max(bw.x + bw.y + bw.z, 1e-4);
+      vec4 c1, n1, o1;
+      if (bw.y > 0.002){
+        terrainTap(L, wp.xz * inv, g.topX * inv, g.topY * inv, c1, n1, o1);
+        c += c1 * bw.y; nh += n1 * bw.y; o += o1 * bw.y;
+        acc += sfWhiteoutTop(n, sfUnpackNormal(n1.rgb, ns)) * bw.y;
+      }
+      if (bw.x > 0.002){
+        terrainTap(L, wp.zy * inv, g.sideXX * inv, g.sideXY * inv, c1, n1, o1);
+        c += c1 * bw.x; nh += n1 * bw.x; o += o1 * bw.x;
+        acc += sfWhiteoutX(n, sfUnpackNormal(n1.rgb, ns)) * bw.x;
+      }
+      if (bw.z > 0.002){
+        terrainTap(L, wp.xy * inv, g.sideZX * inv, g.sideZY * inv, c1, n1, o1);
+        c += c1 * bw.z; nh += n1 * bw.z; o += o1 * bw.z;
+        acc += sfWhiteoutZ(n, sfUnpackNormal(n1.rgb, ns)) * bw.z;
+      }
+    } else {
+      terrainTap(L, wp.xz * inv, g.topX * inv, g.topY * inv, c, nh, o);
+      acc = sfWhiteoutTop(n, sfUnpackNormal(nh.rgb, ns));
+    }
+    col = c.rgb * u_tTint[L];
+    wn = acc;
+    h = nh.a;
+    rough = o.g;
+    ao = o.r;
+  }
+}
+
+/** Near-field surface for weights w. Outputs albedo (no macro), normal,
+ *  roughness and occlusion. */
+void terrainSurfaceNear(vec3 wp, vec3 n, vec4 w, TerrainGrads g,
+                        out vec3 albedo, out vec3 nrm, out float rough, out float ao){
+  float ws[4];
+  ws[0] = w.x; ws[1] = w.y; ws[2] = w.z; ws[3] = w.w;
+  int i0 = 0;
+  float b0 = -1.0;
+  for (int i = 0; i < 4; i++){ if (ws[i] > b0){ b0 = ws[i]; i0 = i; } }
+  ws[i0] = -1.0;
+  int i1 = 0;
+  float b1 = -1.0;
+  for (int i = 0; i < 4; i++){ if (ws[i] > b1){ b1 = ws[i]; i1 = i; } }
+  b0 = max(b0, 0.0);
+  b1 = max(b1, 0.0);
+  float bs = max(b0 + b1, 1e-4);
+  b0 /= bs;
+  b1 /= bs;
+
+  vec3 c0, n0, c1, n1;
+  float h0, r0, a0, h1, r1, a1;
+  terrainLayerSample(i0, wp, n, g, c0, n0, h0, r0, a0);
+  if (b1 > 0.001){
+    terrainLayerSample(i1, wp, n, g, c1, n1, h1, r1, a1);
+  } else {
+    c1 = c0; n1 = n0; h1 = h0; r1 = r0; a1 = a0;
+  }
+
+  // Height blend: the layer whose own surface is higher at this texel wins, so
+  // gravel comes through grass along the gravel's grain and rock emerges from
+  // soil along its cracks, instead of the two cross-fading into mud.
+  float hb = u_tHeightBlend;
+  float range = mix(1.0, 0.04, hb);
+  float v0 = b0 + h0 * hb;
+  float v1 = b1 + h1 * hb;
+  float peak = max(v0, v1);
+  float w0 = max(v0 - (peak - range), 0.0);
+  float w1 = max(v1 - (peak - range), 0.0);
+  if (b1 <= 0.001) w1 = 0.0;
+  float ws2 = max(w0 + w1, 1e-4);
+  w0 /= ws2;
+  w1 /= ws2;
+
+  albedo = c0 * w0 + c1 * w1;
+  nrm = normalize(n0 * w0 + n1 * w1);
+  rough = r0 * w0 + r1 * w1;
+  ao = a0 * w0 + a1 * w1;
+}
+#endif
+`;
 /** Everything a surface material needs, in include order. Requires three's
  *  `<common>` and `skyLib` from cloudCore before it. */
 export const terrainField = [terrainUniforms, terrainNoise, terrainHeight].join('\n');

package/dist/shaders/ocean/OceanSurfaceMaterial.d.ts

@@ -41,6 +41,8 @@ export declare const oceanMaterialDefaults: {
     u_skyAmbient: THREE.Color;
     u_groundAmbient: THREE.Color;
     u_sunIntensity: number;
+    u_moonDir: THREE.Vector3;
+    u_moonColor: THREE.Color;
     u_turbidity: number;
     u_rayleigh: number;
     u_mieCoefficient: number;

package/dist/shaders/ocean/OceanSurfaceMaterial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OceanSurfaceMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/ocean/OceanSurfaceMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAmM9D,MAAM,WAAW,qBAAqB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAMD;yEACyE;AACzE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CjC,CAAA;AAgBD,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,cAAc;;CAa7D;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,oBAAoB,EAAE,YAAY,CAAC,OAAO,oBAAoB,CAAC,CAAA;KAClE;CACJ"}
+{"version":3,"file":"OceanSurfaceMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/ocean/OceanSurfaceMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAmM9D,MAAM,WAAW,qBAAqB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAMD;yEACyE;AACzE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDjC,CAAA;AAgBD,qBAAa,oBAAqB,SAAQ,KAAK,CAAC,cAAc;;CAa7D;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,oBAAoB,EAAE,YAAY,CAAC,OAAO,oBAAoB,CAAC,CAAA;KAClE;CACJ"}

package/dist/shaders/ocean/OceanSurfaceMaterial.js

@@ -233,6 +233,9 @@ export const oceanMaterialDefaults = {
     u_skyAmbient: new THREE.Color(0.6, 0.9, 1.6),
     u_groundAmbient: new THREE.Color(0.45, 0.42, 0.37),
     u_sunIntensity: 1,
+    // Moonlight, set by useOceanMaterial; black = no moon.
+    u_moonDir: new THREE.Vector3(0, 1, 0),
+    u_moonColor: new THREE.Color(0, 0, 0),
     u_turbidity: 2,
     u_rayleigh: 1,
     u_mieCoefficient: 0.005,

package/dist/shaders/terrain/TerrainMaterial.d.ts

@@ -27,6 +27,12 @@ export declare const terrainMaterialDefaults: {
     u_valleyWidth: number;
     u_cellSize: number;
     u_curvature: number;
+    u_patchSize: THREE.Vector2;
+    u_patchOffset: THREE.Vector2;
+    u_edgeWidth: number;
+    u_camTerrain: THREE.Vector3;
+    u_scaleY: number;
+    u_patchCell: number;
     u_lowColor: THREE.Color;
     u_midColor: THREE.Color;
     u_rockColor: THREE.Color;
@@ -43,6 +49,17 @@ export declare const terrainMaterialDefaults: {
     u_detailFade: number;
     u_roughness: number;
     u_specular: number;
+    u_tFar: THREE.Color[];
+    u_tColor: THREE.DataArrayTexture | null;
+    u_tNormal: THREE.DataArrayTexture | null;
+    u_tOrm: THREE.DataArrayTexture | null;
+    u_tLayer: THREE.Vector4[];
+    u_tTint: THREE.Color[];
+    u_tMeanC: THREE.Vector4[];
+    u_tMeanN: THREE.Vector4[];
+    u_tMeanO: THREE.Vector4[];
+    u_tDistance: number;
+    u_tHeightBlend: number;
     u_ambient: number;
     u_bounce: number;
     u_sunShadow: number;

package/dist/shaders/terrain/TerrainMaterial.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/terrain/TerrainMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAyM9D,MAAM,WAAW,uBAAuB;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAED;yEACyE;AACzE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgEnC,CAAA;AAcD;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK,CAAC,cAAc;;CAWxD;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,eAAe,EAAE,YAAY,CAAC,OAAO,eAAe,CAAC,CAAA;KACxD;CACJ"}
+{"version":3,"file":"TerrainMaterial.d.ts","sourceRoot":"","sources":["../../../src/shaders/terrain/TerrainMaterial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAiR9D,MAAM,WAAW,uBAAuB;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAA;CAChC;AAED;yEACyE;AACzE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAqDd,KAAK,CAAC,gBAAgB,GAAG,IAAI;eAC5B,KAAK,CAAC,gBAAgB,GAAG,IAAI;YAChC,KAAK,CAAC,gBAAgB,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BhD,CAAA;AAqBD;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK,CAAC,cAAc;;CAWxD;AAID,OAAO,QAAQ,oBAAoB,CAAC;IAChC,UAAU,aAAa;QACnB,eAAe,EAAE,YAAY,CAAC,OAAO,eAAe,CAAC,CAAA;KACxD;CACJ"}