sindicate 0.1.0

package/src/world/water.js

@@ -0,0 +1,227 @@
+// Low-poly water with SEE-THROUGH depth: techniques ported from Braffolk's
+// fable5-world-demo WaterMaterial (same three.js/TSL stack), restyled for our faceted
+// Synty look. The surface refracts the actual scene behind it (viewportSharedTexture)
+// with per-channel Beer–Lambert absorption by water-column thickness, and reflects the
+// sky-phase colours by fresnel — so riverbeds and wading legs show through the shallows,
+// deep water goes murky, and the water tracks dawn/dusk/night/moor-dread for free.
+// Kept from ours: the gentle faceted swell, per-vertex aDepth (foam + inside-gating),
+// the pond's rClip sprawl guard, the dive-under-terrain shoreline geometry.
+// Their hard-won lessons honoured: fresnel weights use a FLATTENED normal (a tilted
+// per-facet normal saturates (1−cosθ)^5 into a white sheet); refraction uv is
+// depth-VALIDATED so foreground geometry never smears into the water.
+import * as THREE from 'three/webgpu';
+import {
+  Fn, attribute, positionLocal, positionWorld, positionView, time, sin, vec2, vec3, float,
+  normalize, cross, dot, clamp, mix, max, smoothstep, dFdx, dFdy, uv, exp, reflect,
+  cameraPosition, cameraNear, cameraFar, screenUV, viewportSharedTexture, viewportDepthTexture,
+  perspectiveDepthToViewZ, fract, abs, texture,
+} from 'three/tsl';
+import { uSkyCol, uHorizonCol } from './weatherUniforms.js';
+import { waterNoiseTexture } from './waterNoise.js';
+
+const C = (hex) => { const c = new THREE.Color(hex); return vec3(c.r, c.g, c.b); };
+
+// UK water absorption per metre (r dies first → cool green-blue depths, murky by ~2.5m)
+const SIGMA = vec3(0.55, 0.24, 0.17);
+
+// Scene-behind-the-water, refracted and absorbed. n = the faceted surface normal;
+// murk = in-scatter density (rivers run denser — their plain beds give refraction
+// little to show until the riverbed-texturing pass lands).
+// Returns { col, vDepth }: the transmitted colour and the vertical water column (for foam).
+const refraction = (n, murk = vec3(0.10, 0.16, 0.17)) => {
+  const toCam = cameraPosition.sub(positionWorld);
+  const dist = toCam.length();
+  const viewDirY = toCam.y.div(dist.max(1e-4));
+  const fragZ = positionView.z; // negative
+  // ripple/facet-driven refraction offset, shrinking with distance
+  const refrK = clamp(float(9).div(dist.max(1)), 0.04, 1).mul(0.05);
+  const ruv = screenUV.add(n.xz.mul(refrK));
+  const zR = perspectiveDepthToViewZ(viewportDepthTexture(ruv).x, cameraNear, cameraFar);
+  // refracted sample landing on geometry IN FRONT of the water (a wader, a bridge post)
+  // must fall back to the straight uv, or the foreground smears into the surface
+  const leaked = zR.greaterThan(fragZ.add(0.02));
+  const uvF = mix(ruv, screenUV, leaked.select(float(1), float(0)));
+  const zS = mix(zR, perspectiveDepthToViewZ(viewportDepthTexture(screenUV).x, cameraNear, cameraFar), leaked.select(float(1), float(0)));
+  const thick = fragZ.sub(zS).max(0);            // metres of water along the view ray
+  const sceneCol = viewportSharedTexture(uvF).rgb;
+  const absorb = thick.mul(1.3);
+  const T = vec3(exp(absorb.mul(-0.55)), exp(absorb.mul(-0.24)), exp(absorb.mul(-0.17)));
+  // turbidity in-scatter follows the sky phase → murk brightens by day, dims at night
+  const inscat = uSkyCol.mul(murk);
+  const col = sceneCol.mul(T).add(inscat.mul(vec3(1, 1, 1).sub(T)));
+  const vDepth = thick.mul(viewDirY.abs().max(0.06)); // vertical column (shore feather/foam)
+  return { col, vDepth, viewDir: toCam.div(dist.max(1e-4)) };
+};
+
+// Sky-phase reflection along the reflected ray, reproducing the dome's horizon→sky ramp.
+// Darkened ×0.78: real water reflects darker than the sky (micro-roughness), and a full-
+// brightness midday sky whites out narrow streams seen at grazing angles.
+const skyReflection = (viewDir, n) => {
+  const rdir = reflect(viewDir.negate(), n);
+  return mix(uHorizonCol, uSkyCol, smoothstep(0.0, 0.55, rdir.y.max(0.035))).mul(0.78);
+};
+
+// Fresnel on a HARD-flattened normal (braffolk's lesson: reflectance must follow the
+// MEAN surface or big low-poly facet tilts saturate (1−cosθ)^5 into an ice sheet) and
+// capped so the refracted bed always survives underneath. The facets still sparkle —
+// the FULL normal shapes the reflected sky colour + shimmer, just not the mix weight.
+const fresnel = (viewDir, n) => {
+  const nF = normalize(vec3(n.x.mul(0.25), n.y, n.z.mul(0.25)));
+  const cosT = clamp(dot(viewDir, nF), 0.0, 1.0);
+  return float(0.02).add(cosT.oneMinus().pow(5).mul(0.98)).mul(0.5);
+};
+
+export function waterMaterial({
+  foam = 0xeef8f6, shallow = 0x3f96a8, deep = 0x114f78, maxDepth = 2.0,
+  foamDepth = 0.18, rClip = 21, waveHeight = 0.16, waveLen = 9, waveSpeed = 0.7,
+  refract = true, // false = the cheap baked-depth ramp (the SEA: too big to pay viewport copies for water you can't see into)
+} = {}) {
+  const mat = new THREE.MeshBasicNodeMaterial({ transparent: true, depthWrite: true });
+  const FM = C(foam), SH = C(shallow), DP = C(deep);
+
+  // rClip may be a number (one body per material — the sea) or 'attribute': lakes bake their
+  // radius per-vertex (aRClip) so EVERY lake shares ONE material. Each distinct refracting
+  // material compiles its own viewportSharedTexture sampling, and each ViewportTexture node
+  // pays its own copyFramebufferToTexture per frame — N lakes on one material is 1 copy, not N.
+  const rc = rClip === 'attribute' ? attribute('aRClip', 'float') : float(rClip);
+
+  const waveAt = Fn(([p]) => {
+    const t = time.mul(waveSpeed), k = 6.2832 / waveLen;
+    return sin(p.x.mul(k).add(p.y.mul(k * 0.6)).add(t))
+      .add(sin(p.y.mul(k * 0.9).sub(p.x.mul(k * 0.3)).sub(t.mul(0.85))).mul(0.7))
+      .mul(waveHeight);
+  });
+
+  // foam wherever the water ends — shallow waterline (depth→0) OR the clip radius — both wavy.
+  const foamFull = Fn(([d, pondD]) => {
+    const t = time.mul(waveSpeed);
+    const wav = sin(positionWorld.x.mul(0.5).add(t)).add(sin(positionWorld.z.mul(0.6).sub(t.mul(0.7)))).mul(0.5);
+    const edge = float(foamDepth).add(wav.mul(foamDepth * 0.4));
+    const depthFoam = smoothstep(edge, edge.mul(0.15), d);
+    const radiusFoam = smoothstep(rc.sub(2.0), rc.sub(0.8), pondD.add(wav.mul(0.5)));
+    return max(depthFoam, radiusFoam);
+  });
+
+  mat.positionNode = Fn(() => {
+    const p = positionLocal;
+    // ADD the wave to the baked local Z (shore verts are baked BELOW the terrain so the
+    // sheet dives under dry ground — the waterline is the natural surface intersection)
+    return vec3(p.x, p.y, p.z.add(waveAt(p.xy)));
+  })();
+
+  // Build the expensive nodes ONCE and reference them from both color and opacity —
+  // separate calls would duplicate the viewport-texture sampling in the compiled shader.
+  const nShared = normalize(cross(dFdx(positionWorld), dFdy(positionWorld))); // flat per-facet normal
+  const viewShared = cameraPosition.sub(positionWorld);
+  const viewDirShared = viewShared.div(viewShared.length().max(1e-4));
+  const R = refract ? refraction(nShared) : null;
+  const skyShared = skyReflection(viewDirShared, nShared);
+  const fresShared = fresnel(viewDirShared, nShared);
+
+  mat.colorNode = Fn(() => {
+    const wp = positionWorld;
+    const t = time.mul(waveSpeed);
+    const shimmer = sin(wp.x.mul(0.7).add(t)).mul(sin(wp.z.mul(0.8).sub(t))).mul(0.05).add(1);
+    const d = attribute('aDepth', 'float');
+    const base = refract ? R.col : mix(SH, DP, smoothstep(0, maxDepth, d)); // sea: baked ramp
+    const water = mix(base, skyShared, fresShared).mul(shimmer);
+    const col = mix(water, FM, foamFull(d, positionLocal.xy.length()));  // foam at every edge
+    // darken the WHOLE surface (base + foam, not just the sky reflection) with the sky's brightness,
+    // so water doesn't glow white at dusk/night. uSkyCol goes near-black at night → lit floors at 0.22.
+    const lit = clamp(uSkyCol.r.add(uSkyCol.g).add(uSkyCol.b).mul(0.55), 0.22, 1.0);
+    return col.mul(lit);
+  })();
+
+  mat.opacityNode = Fn(() => {
+    const d = attribute('aDepth', 'float'), pondD = positionLocal.xy.length();
+    // per-pixel shoreline feather (mm-deep water fades over the bed) gated by the baked
+    // inside test + the pond's sprawl clip
+    const inside = smoothstep(0.0, 0.05, d).mul(smoothstep(rc, rc.sub(0.5), pondD));
+    const feather = refract ? smoothstep(0.004, 0.06, R.vDepth) : smoothstep(0.0, 0.4, d).mul(0.92);
+    return clamp(mix(feather.mul(0.94), float(1), foamFull(d, pondD)).mul(inside), 0, 1);
+  })();
+  return mat;
+}
+
+// Flowing river water: a ribbon mesh (built in zones.js) at world Y, with baked per-vertex
+// aDepth + downstream UVs. Same see-through refraction + sky fresnel as the lakes; the
+// downstream streak modulates the surface so the current still reads.
+export function riverMaterial({
+  foam = 0xeef8f6, shallow = 0x4494a4, deep = 0x11557a, maxDepth = 1.3,
+  foamDepth = 0.2, flowSpeed = 0.5,
+  refract = true,
+} = {}) {
+  const mat = new THREE.MeshBasicNodeMaterial({ transparent: true, depthWrite: true, side: THREE.DoubleSide });
+  const FM = C(foam), SH = C(shallow), DP = C(deep);
+
+  mat.positionNode = Fn(() => {
+    const p = positionLocal;
+    const sw = sin(p.x.mul(0.6).add(time.mul(0.8))).add(sin(p.z.mul(0.7).sub(time.mul(0.6)))).mul(0.05);
+    return vec3(p.x, p.y.add(sw), p.z); // gentle swell on the world-space ribbon
+  })();
+
+  const RIVER_MURK = vec3(0.22, 0.30, 0.32); // denser than lakes — gives the stream a visible body
+
+  // ---- flowmap ripples (braffolk WaterMaterial 132-151, faithful port) ----------------
+  // Two phases half a cycle apart, crossfaded by w2 so each phase's snap-back is hidden
+  // (the classic no-sliding-texture flowmap). Gradients come pre-derived from the baked
+  // noise texture, so a ripple layer costs ONE fetch. Flow = per-vertex downstream aFlow.
+  const noiseTex = waterNoiseTexture();
+  const PERIOD = 24; // world metres per noise tile
+  const flowV = attribute('aFlow', 'vec2');
+  const spd = flowV.length();
+  const CYC = 0.45;
+  const ph1 = fract(time.mul(CYC));
+  const ph2 = fract(time.mul(CYC).add(0.5));
+  const w2 = abs(ph1.sub(0.5)).mul(2);
+  const vel = flowV.mul(1.9).add(vec2(0.045, 0.03));          // rivers stream; the constant is the breeze fallback
+  const gradAt = (s, off) => texture(noiseTex, positionWorld.xz.sub(off).div(s * PERIOD)).zw.sub(0.5).div(0.02 * s);
+  const offA = vel.mul(ph1.div(CYC));
+  const offB = vel.mul(ph2.div(CYC)).add(vec2(3.71, 1.13));
+  const rippleLayer = (off) => gradAt(0.9, off).add(gradAt(3.4, off.mul(0.62)).mul(0.5));
+  const grad = mix(rippleLayer(offA), rippleLayer(offB), w2);
+  const rippleAmp = float(0.007).add(spd.mul(0.028));          // their tuned amp — bigger saturates fresnel ("white sheet")
+  const slope = grad.mul(rippleAmp);
+  const facetN = normalize(cross(dFdx(positionWorld), dFdy(positionWorld)));
+  const nShared = normalize(facetN.add(vec3(slope.x.negate(), 0, slope.y.negate()))); // ripples UNDER the facet silhouette
+
+  const viewShared = cameraPosition.sub(positionWorld);
+  const viewDirShared = viewShared.div(viewShared.length().max(1e-4));
+  const R = refract ? refraction(nShared, RIVER_MURK) : null;  // ripple normal wobbles the refraction downstream
+  const skyShared = skyReflection(viewDirShared, nShared);
+  const fresShared = fresnel(viewDirShared, nShared);
+
+  // ---- foam (braffolk 283-308): two decorrelated advected scales MULTIPLY into clumpy
+  // patches (a single thresholded fbm slides as coherent stripes); variance-renormalised
+  // crossfade so coverage doesn't pulse at blend midpoints. Shore foam keys on the water
+  // column; RAPIDS foam keys on the baked downstream DROP (the stepped monotonic profile
+  // gives real rapids exactly where the water level steps down).
+  const dAttr = attribute('aDepth', 'float');
+  const foamUv = (off, s) => positionWorld.xz.sub(off).div(s * PERIOD);
+  const fA = texture(noiseTex, foamUv(offA, 0.55)).y;
+  const fB = texture(noiseTex, foamUv(offB.mul(1.13), 0.55)).y;
+  const dA = texture(noiseTex, foamUv(offA.mul(0.6), 0.21)).y;
+  const dB = texture(noiseTex, foamUv(offB.mul(0.71), 0.21)).y;
+  const varNorm = w2.mul(w2).add(w2.oneMinus().mul(w2.oneMinus())).sqrt();
+  const fblend = mix(fA, fB, w2).sub(0.5).div(varNorm).add(0.5);
+  const fDetail = mix(dA, dB, w2).sub(0.5).div(varNorm).add(0.5);
+  const foamPat = smoothstep(0.42, 0.85, fblend.mul(0.62).add(fDetail.mul(0.38)));
+  const shoreCol = refract ? R.vDepth : dAttr;                 // per-pixel column on high, baked depth on the ramp path
+  const shoreFoam = smoothstep(0.16, 0.03, shoreCol).mul(0.42).mul(smoothstep(0.6, 0.25, dAttr));
+  const rapidFoam = smoothstep(0.025, 0.09, attribute('aDrop', 'float')).mul(0.8);
+  const foamAmt = clamp(shoreFoam.add(rapidFoam), 0, 1).mul(foamPat).clamp(0, 0.68);
+
+  mat.colorNode = Fn(() => {
+    const base = refract ? R.col : mix(SH, DP, smoothstep(0, maxDepth, dAttr));
+    const water = mix(base, skyShared, fresShared);
+    return mix(water, FM, foamAmt);
+  })();
+
+  mat.opacityNode = Fn(() => {
+    const inside = smoothstep(0.0, 0.05, dAttr);           // dry dive-skirt verts stay clipped
+    const feather = refract ? smoothstep(0.004, 0.06, R.vDepth) : smoothstep(0.0, 0.25, dAttr).mul(0.9);
+    const body = smoothstep(0.1, 0.7, dAttr).mul(0.55);    // the channel core always reads as WATER, not damp ground
+    return clamp(max(feather.mul(0.94), body).add(foamAmt.mul(0.6)).mul(inside), 0, 1);
+  })();
+  return mat;
+}

package/src/world/waterNoise.js

@@ -0,0 +1,47 @@
+// CPU-baked tileable water noise — braffolk's NoiseBake, boot-time edition (~10ms).
+// One 256² RGBA float texture: r = fbm, g = decorrelated fbm (foam), b/a = d(fbm)/du,dv
+// packed as gradient*0.02 + 0.5. Ripple layers and foam patterns each cost ONE fetch.
+import * as THREE from 'three/webgpu';
+
+let tex = null;
+
+export function waterNoiseTexture() {
+  if (tex) return tex;
+  const N = 256;
+  const data = new Float32Array(N * N * 4);
+  // periodic value-noise lattices (deterministic LCG)
+  const lat = (n, seed) => {
+    const g = new Float32Array(n * n);
+    let s = seed >>> 0;
+    for (let i = 0; i < n * n; i++) { s = (s * 1664525 + 1013904223) >>> 0; g[i] = s / 4294967296; }
+    return g;
+  };
+  const L1 = lat(8, 1234567), L2 = lat(16, 424242), L3 = lat(32, 87654321), L4 = lat(8, 5550123);
+  const sample = (L, n, u, v) => { // periodic smooth bilinear
+    u = ((u % 1) + 1) % 1; v = ((v % 1) + 1) % 1;
+    const x = u * n, y = v * n;
+    const x0 = Math.floor(x) % n, y0 = Math.floor(y) % n, x1 = (x0 + 1) % n, y1 = (y0 + 1) % n;
+    let fx = x - Math.floor(x), fy = y - Math.floor(y);
+    fx = fx * fx * (3 - 2 * fx); fy = fy * fy * (3 - 2 * fy);
+    const a = L[y0 * n + x0], b = L[y0 * n + x1], c = L[y1 * n + x0], d = L[y1 * n + x1];
+    return a + (b - a) * fx + (c - a) * fy + (a - b - c + d) * fx * fy;
+  };
+  const fbmAt = (u, v) => sample(L1, 8, u, v) * 0.55 + sample(L2, 16, u, v) * 0.3 + sample(L3, 32, u, v) * 0.15;
+  const fbm2At = (u, v) => sample(L4, 8, u + 0.37, v + 0.61) * 0.6 + sample(L3, 32, u + 0.11, v + 0.83) * 0.4;
+  const e = 1 / N;
+  for (let j = 0; j < N; j++) {
+    for (let i = 0; i < N; i++) {
+      const u = i / N, v = j / N, o = (j * N + i) * 4;
+      data[o] = fbmAt(u, v);
+      data[o + 1] = fbm2At(u, v);
+      data[o + 2] = (fbmAt(u + e, v) - fbmAt(u - e, v)) / (2 * e) * 0.02 + 0.5; // d/du per uv-unit, packed
+      data[o + 3] = (fbmAt(u, v + e) - fbmAt(u, v - e)) / (2 * e) * 0.02 + 0.5;
+    }
+  }
+  tex = new THREE.DataTexture(data, N, N, THREE.RGBAFormat, THREE.FloatType);
+  tex.wrapS = tex.wrapT = THREE.RepeatWrapping;
+  tex.minFilter = THREE.LinearFilter;
+  tex.magFilter = THREE.LinearFilter;
+  tex.needsUpdate = true;
+  return tex;
+}

package/src/world/weatherUniforms.js

@@ -0,0 +1,24 @@
+// Shared weather→ground uniforms. Module-level singletons so the terrain, grass, and Weather all
+// reference the SAME nodes regardless of build order (terrain/grass build before/after Weather).
+// Weather sets the values each frame (eased, so the ground soaks/dries and snow builds/melts gradually).
+import * as THREE from 'three/webgpu';
+import { uniform } from 'three/tsl';
+
+export const uWet = uniform(0);   // 0 dry … 1 soaked — rain darkens the ground
+export const uCover = uniform(0); // 0 bare … 1 snow-covered — snow whitens up-facing ground + grass tips
+export const uDayness = uniform(1); // 0 night … 1 day (sky.js writes it) — dims UNLIT baked-albedo materials (impostors) so they stop glowing at night
+export const uSkyCol = uniform(new THREE.Color(0x7fb2e5));     // current sky-phase zenith colour (sky.js writes)
+export const uHorizonCol = uniform(new THREE.Color(0xdfe9d8)); // current horizon colour — water reflections track day/dusk/night for free
+export const uSunDir = uniform(new THREE.Vector3(0.3, 0.8, 0.3)); // current key light direction (sun by day, moon by night) — grass backlight etc.
+export const uRain = uniform(0);   // 0 dry … 1 downpour — the rain FALLING RIGHT NOW.
+                                   // Not the same thing as uWet, and the difference is the whole point:
+                                   // the ground stays dark and slick for a good while after a storm
+                                   // passes, but the moment the rain stops, drops stop landing on it.
+                                   // Splashes read off this; puddles and sheen read off uWet.
+export const uRainT = uniform(0);  // seconds, running while it rains — the ground's clock, so the rings
+                                   // spreading on the puddles beat in time with the rain actually falling.
+                                   // (Weather had a uTime of its own, but it was private to the rain
+                                   // particles; the ground could not see it, so the ground could not move.)
+export const uCloudiness = uniform(0); // 0 fair … 1 storm deck (weather.js writes; LEADS the rain/snow so the sky thickens BEFORE precipitation and clears after)
+export const uWindDir = uniform(new THREE.Vector2(1, 0)); // unit heading the wind blows TOWARD, on the ground plane (XZ). world/wind.js writes it each frame.
+export const uWindStr = uniform(0.4);  // 0 calm … ~1 gusting — the global wind strength. Grass sway + rain slant scale off it; the CPU tumbleweeds read wind.vx/vz directly.

package/src/world/wind.js

@@ -0,0 +1,40 @@
+// GLOBAL WIND — one slowly-wandering heading and a gusting strength, ticked once a frame. Everything
+// that should lean on the weather reads from HERE instead of rolling its own: the tumbleweeds roll on it
+// (CPU: wind.vx/vz), and the grass sway + rain slant read it in their shaders (via uWindDir / uWindStr).
+// `angle` is the heading the wind blows TOWARD (radians on the ground plane, atan2(z, x)). Deterministic
+// layered sines drive the drift + gusts — smooth, no per-frame RNG jerks, and identical after a reload.
+import { uWindDir, uWindStr } from './weatherUniforms.js';
+
+export class Wind {
+  constructor() {
+    this.t = 0;
+    this.baseAngle = 0.7;      // the PREVAILING heading (fixed ~SE-ish); the wind only veers gently around it
+    this.angle = this.baseAngle;
+    this.base = 1.6;           // mean speed (m/s) for the CPU consumers (tumbleweeds) — a light breeze, not a gale (Nick: they rolled too fast)
+    this.gust = 0.5;           // 0..1 current gust factor
+    this.speed = this.base;
+    this.x = Math.cos(this.angle); this.z = Math.sin(this.angle);   // unit heading
+    this.vx = this.x * this.speed; this.vz = this.z * this.speed;   // velocity, m/s
+    this._publish();
+  }
+
+  update(dt) {
+    this.t += dt;
+    // VEER, don't circle. Set the heading DIRECTLY as prevailing ± a bounded oscillation (~±27°); the old
+    // code INTEGRATED sines (angle += …·dt), whose low-frequency term summed to several radians and swept
+    // the wind the whole way round the compass over time (Nick: "pushed things in a 360, weird").
+    this.angle = this.baseAngle + Math.sin(this.t * 0.021) * 0.33 + Math.sin(this.t * 0.057 + 1.3) * 0.14;
+    // gusts swell and lull between ~0.12 and ~1.05
+    this.gust = Math.max(0.12, 0.55 + 0.5 * Math.sin(this.t * 0.21) * Math.sin(this.t * 0.083 + 1.0));
+    this.speed = this.base * (0.5 + 0.85 * this.gust);
+    this.x = Math.cos(this.angle); this.z = Math.sin(this.angle);
+    this.vx = this.x * this.speed; this.vz = this.z * this.speed;
+    this._publish();
+  }
+
+  // hand the current wind to the shared shader uniforms (grass sway, rain slant, and whatever else opts in)
+  _publish() {
+    uWindDir.value.set(this.x, this.z);
+    uWindStr.value = this.gust;
+  }
+}