mapspinner 0.1.55 → 0.1.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mapspinner",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "description": "WebGL2 Earth-scale terrain rendering SDK for interactive globe applications",
   "main": "src/index.js",
   "exports": {

package/src/gl-render.js

@@ -787,7 +787,7 @@ export async function initMapspinnerRender(gl, opts = {}) {
     // out fall beyond the far plane and vanish. Dropping the horizon reference radius 500m below sea level
     // extends the horizon to tens of km at low altitude so near-shore relief stays in view (negligible
     // depth-precision cost: 500m vs R~6.37e6). Both the cull and the draw use this (single source).
-    const RHORIZON = R - 500.0;
+    const RHORIZON = R - 250.0;   // far brought in 500->250 (user 2026-06-14 'bring far plane in a bit'): deck horizon ~80km->~56km = more z-precision; still clears coastal mountains
     // UNDERWATER FAR-PLANE FIX (user 2026-06-14 'at -214m visible, at -500m it disappears'): when the
     // camera is more than 500m below sea level, camDist < RHORIZON so the sea-level horizon is imaginary
     // (-> 0) and alt is negative; the old max(horizon, alt*8) then collapsed the far plane to ~0 and the
@@ -797,7 +797,7 @@ export async function initMapspinnerRender(gl, opts = {}) {
     // MATCH render()'s near exactly (2026-06-14 jank fix): the cull frustum must use the SAME near
     // as the draw frustum, else behind-limb/screen-AABB culling diverges from what is actually drawn
     // at the deck (cull near was max(*0.1,0.1) while render used the <2m 0.05 branch).
-    const near = altAboveTerrain < 2.0 ? 0.05 : Math.max(altAboveTerrain * 0.1, 0.05);
+    const near = altAboveTerrain < 2.0 ? 0.25 : Math.max(altAboveTerrain * 0.1, 0.25);   // near nudged out 0.05->0.25 (user 2026-06-14 'improve on-ground'): more z-precision on the deck
     // FAR PLANE: horizon distance tracks the visible ground edge; blends toward camDist
     // above 500km for orbital views so the full planet is visible.
     const _fBlend = Math.min(1.0, Math.max(0.0, (alt - 500000.0) / 4500000.0));
@@ -835,14 +835,14 @@ export async function initMapspinnerRender(gl, opts = {}) {
     // out fall beyond the far plane and vanish. Dropping the horizon reference radius 500m below sea level
     // extends the horizon to tens of km at low altitude so near-shore relief stays in view (negligible
     // depth-precision cost: 500m vs R~6.37e6). Both the cull and the draw use this (single source).
-    const RHORIZON = R - 500.0;
+    const RHORIZON = R - 250.0;   // far brought in 500->250 (user 2026-06-14 'bring far plane in a bit'): deck horizon ~80km->~56km = more z-precision; still clears coastal mountains
     // UNDERWATER FAR-PLANE FIX (user 2026-06-14 'at -214m visible, at -500m it disappears'): when the
     // camera is more than 500m below sea level, camDist < RHORIZON so the sea-level horizon is imaginary
     // (-> 0) and alt is negative; the old max(horizon, alt*8) then collapsed the far plane to ~0 and the
     // whole scene vanished past -500m deep (= the 'ocean looks shallow/empty' when exploring). Floor the
     // far reach to 60km when submerged so the seabed + the underwater view stay visible.
     const horizon = (camDist > RHORIZON) ? Math.sqrt(camDist*camDist - RHORIZON*RHORIZON) : 60000.0;
-    const near = altAboveTerrain < 2.0 ? 0.05 : Math.max(altAboveTerrain * 0.1, 0.05);
+    const near = altAboveTerrain < 2.0 ? 0.25 : Math.max(altAboveTerrain * 0.1, 0.25);   // near nudged out 0.05->0.25 (user 2026-06-14 'improve on-ground'): more z-precision on the deck
     const _fBlend = Math.min(1.0, Math.max(0.0, (alt - 500000.0) / 4500000.0));
     const farGround = Math.max(horizon, alt * 8.0);
     const far = farGround * (1.0 - _fBlend) + camDist * _fBlend;

package/src/shaders/terrain.glsl

@@ -631,14 +631,16 @@ highp float composeHeight(vec3 dir0, highp vec2 faceLocal, float tileM){   // W7
       // whole ocean into 'almost-land everywhere', user 2026-06-14) with the flat-at-waterline curve so
       // both sides meet the waterline at slope 0 (no crease); beyond SEABED_EASE the true bathymetry
       // resumes so the ocean goes DEEP.
-      const highp float SEABED_EASE = 120.0;   // metres of depth flattened at the shore (decoupled from the land beach)
+      const highp float SEABED_EASE = 25.0;   // metres of depth flattened at the shore (decoupled from the land beach)
       highp float d0 = -h;
       highp float d = (d0 < SEABED_EASE) ? (d0 * d0 / SEABED_EASE) * (2.0 - d0 / SEABED_EASE) : d0;
-      // STEEPER DROP-OFF (user 2026-06-14 'seabed flat/close to waterline; steeper + more relief'):
-      // narrow shelf 500->150m raw, steeper shelf 0.24->0.6, steeper continental slope 1.19->1.5 so the
+      // NO 'SECOND BEACH' (user 2026-06-14 'shallow ring of water around land / making a second beach'):
+      // the wide flat shelf read as a shallow underwater beach ring. Shelf cut to a tiny 25m-raw lip then
+      // a STEEP 1.9 plunge so the water drops to real depth immediately off the actual beach -- no shelf.
+      // (former: narrow shelf 500->150m raw, steeper shelf 0.24->0.6, steeper continental slope 1.19->1.5 so the
       // seabed plunges to deep water just offshore (less flat shallow shelf) and the deep bathymetry
       // carries 1.5x the bShape relief = more dramatic underwater terrain to explore.
-      h = -(min(d, 150.0) * 0.6 + max(d - 150.0, 0.0) * 1.5);
+      h = -(min(d, 25.0) * 0.4 + max(d - 25.0, 0.0) * 1.9);
       h = max(h, -11000.0);   // cap depth at Mariana Trench (~11km)
   } else {
       // LAND COASTAL SHELF (user 2026-06-14: 'beaches not wide enough'): the underwater shelf above
@@ -869,10 +871,10 @@ void main() {
     // shelf/slope bathymetry remap + underwater displacement -- MUST mirror composeHeight exactly
     // (this is the FS-material running value; composeHeight is the geometry/probe height).
     if (vH < 0.0) {
-        const highp float SEABED_EASE = 120.0;   // mirror composeHeight: narrow waterline ease, deep ocean beyond
+        const highp float SEABED_EASE = 25.0;   // mirror composeHeight: tiny waterline lip, steep plunge (no 'second beach')
         highp float dSea0 = -vH;
         highp float dSea = (dSea0 < SEABED_EASE) ? (dSea0 * dSea0 / SEABED_EASE) * (2.0 - dSea0 / SEABED_EASE) : dSea0;
-        vH = -(min(dSea, 150.0) * 0.6 + max(dSea - 150.0, 0.0) * 1.5);   // steeper drop-off (mirror composeHeight)
+        vH = -(min(dSea, 25.0) * 0.4 + max(dSea - 25.0, 0.0) * 1.9);   // steep drop-off (mirror composeHeight)
         vH = max(vH, -11000.0);   // cap depth at Mariana Trench (~11km)
     } else {
         highp float bShelf = uBeachShelfM > 1.0 ? uBeachShelfM : 600.0;   // LAND COASTAL SHELF -- mirror composeHeight exactly (wide beach, user 2026-06-14); guard stale/unset uniform
@@ -1247,7 +1249,13 @@ vec3 terrainAlbedo(float h, float slope, float rockSlope, highp vec3 worldPos) {
     } else {
         c = mix(bcShore, bcLowland, smoothstep(0.0, bandEdgesLo.x, h));
         c = mix(c, bcGrass, smoothstep(bandEdgesLo.x, bandEdgesLo.y, h));
-        float bandWarp = snoise3(normalize(worldPos) * 400.0) * 500.0;
+        // BIOME-BAND WARP (user 2026-06-14 'hard bands between biomes ... make that more interesting'):
+        // the single-octave warp made smooth wavy contour lines. A 3-octave domain-warped field breaks
+        // the rock/snow boundaries into irregular fingers + patches (height-keyed band wobbles +/-~1.1km
+        // over 1-15km scales), so the biome edge reads natural, not a band. highp dir for the lattice.
+        highp vec3 bwd = normalize(worldPos);
+        highp vec3 bww = bwd + vec3(snoise3(bwd * 130.0)) * 0.004;   // domain warp -> non-parallel fingers
+        float bandWarp = (snoise3(bww * 210.0) * 1.0 + snoise3(bww * 560.0) * 0.5 + snoise3(bww * 1450.0) * 0.25) * 720.0;
         c = mix(c, bcRock, smoothstep(bandEdgesHi.x + bandWarp, bandEdgesHi.y + bandWarp, h));
         c = mix(c, bcSnow, smoothstep(snowEdges.x + bandWarp, snowEdges.y + bandWarp, h));
         c = mix(c, bcRock, smoothstep(slopeRock.x, slopeRock.y, rockSlope) * step(0.0, h));
@@ -1776,10 +1784,19 @@ void main() {
         // beach->land crossover). 2-oct world-dir noise, 1/4 freq (~13km + ~5km waves). Computed once
         // here; the snow/rock bandWarp below reuses warpN. highp dir for the lattice precision.
         highp vec3 bwDir = normalize(vWorld);
-        float warpN = snoise3(bwDir * 3325.0) + 0.5 * snoise3(bwDir * 7750.0);   // ~ +/-1.5
+        // 3-oct (added the ~1km octave, user 2026-06-14 'make biome bands more interesting') -> the
+        // texture-splat rock/snow/beach edges break into finer fingers as you approach, not a hard band.
+        float warpN = snoise3(bwDir * 3325.0) + 0.5 * snoise3(bwDir * 7750.0) + 0.35 * snoise3(bwDir * 17000.0);   // ~ +/-1.8
         // BEACH sand gate tied to uBeachTopM (so the sand TEXTURE scales with the wide beach, not a
         // hardcoded 80m strip) + the shared warp on its LAND edge so the beach->grass line is irregular.
-        float beachW = warpN * uBeachTopM * 0.30;   // warp amplitude scales with the beach band height
+        // FINE BREAK on the grass->sand line (user 2026-06-14 'still a hard straight grass-sand line up
+        // close ... it must gain detail'): warpN breaks it at the km scale; add a high-freq (~80-200m)
+        // octave so the line stays irregular/fingered when you walk right up to it instead of going
+        // straight. Faded in WITH the close-up detail (detailFade-like, via pxWorld) so it never speckles
+        // at distance where the macro band is smooth.
+        float closeBreak = (1.0 - smoothstep(2.0, 40.0, pxWorld));
+        float beachFine = (snoise3(bwDir * 42000.0) + 0.5 * snoise3(bwDir * 95000.0)) * uBeachTopM * 0.45 * closeBreak;
+        float beachW = warpN * uBeachTopM * 0.30 + beachFine;   // warp amplitude scales with the beach band height
         float beach = (1.0 - smoothstep(uBeachTopM * 0.12 + beachW, uBeachTopM + beachW, vH))
                     * (1.0 - smoothstep(0.15, 0.42, slope));
         // SAND BLEED (2026-06-13): patchy sand spills above the main beach line, modulated by VS
@@ -1879,6 +1896,27 @@ void main() {
             texAlb = mix(albB, albA, bSharp);
             texNrm = mix(nrmB, nrmA, bSharp);
         }
+        // FINE DETAIL OCTAVE (user 2026-06-14 'add one octave at 4x smaller -> world better scaled at
+        // 2m'): the base photo tiles at uTexTileM (~2.4km = ~2.3m/texel, smeared at the deck). Sample the
+        // SAME dominant material at 4x frequency (~0.6m/texel) and overlay its luminance + normal so
+        // close-up the ground gains sub-metre structure. Faded out by ~12m px so it never moires far off.
+        // LOW-FREQ = NORMALS ONLY, HIGH-FREQ = TEXTURE + STRONG NORMALS (user 2026-06-14): flatten the
+        // base (2.4km) albedo to its luminance so the MACRO biome color carries the chroma -- the base
+        // octave contributes only its NORMAL (relief), not color blotches. The 4x detail octave then
+        // provides the albedo STRUCTURE + a strong normal.
+        texAlb.rgb = vec3(dot(texAlb.rgb, vec3(0.299, 0.587, 0.114)));   // low-freq: normals only (albedo -> flat luma)
+        float detailFade = (1.0 - smoothstep(1.0, 12.0, pxWorld));
+        if (detailFade > 0.01) {
+            vec4 dA = surfTriTap(uSurfAlb, wt * 4.0, tw, lA);
+            float dl = dot(dA.rgb, vec3(0.299, 0.587, 0.114));
+            float bl = dot(texAlb.rgb, vec3(0.299, 0.587, 0.114));
+            texAlb.rgb *= mix(1.0, clamp(dl / max(bl, 0.04), 0.35, 2.4), detailFade * 1.3);   // HIGH-FREQ albedo structure (heavier)
+            // detail NORMAL: surfTriNrm returns a PERTURBATION vector (texNrm feeds texDn = texNrm*uTexNrmK*k,
+            // NOT a unit normal), so the detail is simply ADDED in the same space -- no normalize (that
+            // scrambled magnitudes = the 'weird highest-octave normals').
+            vec3 dN = surfTriNrm(uSurfNrm, wt * 4.0, tw, lA, n);
+            texNrm = texNrm + dN * detailFade * 1.4;   // BIGGER normal effect for the high-freq octave (user 2026-06-14)
+        }
         float k = uTexMix * texFarFade;
         // macro-tinted detail (user 2026-06-10 'the textured patch must be tinted to the same shade
         // as the spot its replacing'): the texture contributes STRUCTURE + relative chroma only,

package/src/terrain-gen-controls.js

@@ -46,7 +46,7 @@ const DEFAULTS = {
     exposure: 1.0, skyFill: 0.45, biomeSat: 0.72, variationAmt: 0.04, colorVar: 0.5, vertexAO: 1.0,     reliefShade: 2.5,   // variationAmt 0.08->0.04 (user 2026-06-10 'blotchy': the ~50km value mottle painted light/dark patches across the massifs)
     nightFloor: 0.16, termWidth: 0.25, terminatorGlow: 0.30, lookSat: 1.15, lookContrast: 1.08,   // nightFloor 0.05->0.16: no black night terrain (2026-06-09)
     detailOverlay: 6.0, hazeMul: 0.65,   // 2026-06-10 'pale hazy + featureless': perlin-everywhere albedo+elevation fbm (user-tuned 6) + aerial-perspective strength cut
-    ocean: { deep: [0.008,0.025,0.06], shallow: [0.07,0.22,0.26], k: [0.016,0.007,0.0028] },   // k halved (user 2026-06-14 'see the land under the water'): clearer water, bed visible through shallow/medium depth. OVERRIDES the gl-render uOceanK default via window.__uOceanK.
+    ocean: { deep: [0.008,0.025,0.06], shallow: [0.07,0.22,0.26], k: [0.009,0.004,0.0018] },   // k lowered again (user 2026-06-14 'water properly transparent so we see the surface under it'): clearer, the seabed shows through shallow/medium water; deep basins still opaque. OVERRIDES gl-render via window.__uOceanK.
   },
   // HPF band scales (multipliers on the anchor-field band base values; anchor-field.setBandScales).
   hpf: {