sindicate 0.1.0 → 0.4.0

package/src/world/flora.js

@@ -0,0 +1,87 @@
+// Countryside placement fields — CPU port of braffolk/fable5-world-demo's
+// Scatter.ts placement RULES. His pipeline is a boot-time GPU compute pass, but
+// every rule in it is a pure deterministic function of hashed (x,z) + smooth
+// field samples, so it ports straight onto our manifest placementFields:
+//
+//   clumpField : parent-clump thickets (clustered Poisson / light competition) —
+//                trees gather in copses with real gaps, not uniform speckle
+//   moistureAt : analytic moisture — desert-low; the creek corridor reads lusher,
+//                everything else parched (species density keys off it)
+//   forestness : always 0 — no forest on the Dustwater plain (name/signature kept
+//                for the field consumers)
+//
+// All gates hash SPACE (pcg2d over quantized x,z), never the rng stream, so the
+// mulberry32(1337) placement determinism is untouched.
+// Terrain queries are GAME data — register before building placements:
+//   setFloraTerrain({ heightAt, riverInfo, fbm, LAKES })
+let TERRAIN = { heightAt: () => 0, riverInfo: () => null, fbm: () => 0, LAKES: [] };
+export function setFloraTerrain(t) { TERRAIN = { ...TERRAIN, ...t }; }
+import { dist2D } from '../core/utils.js';
+
+const sstep = (a, b, x) => { const t = Math.min(1, Math.max(0, (x - a) / (b - a))); return t * t * (3 - 2 * t); };
+
+// integer 2D hash (braffolk's pcg2d) — stable at any cell magnitude, unlike
+// sin-based hashes which band at 4-digit coordinates
+function pcg2d(ix, iz, salt) {
+  const M = 1664525, C = 1013904223;
+  let a = (ix + 40000 + (salt & 0x3fff)) >>> 0;
+  let b = (iz + 40000 + ((salt >> 14) & 0x3fff)) >>> 0;
+  a = (Math.imul(a, M) + C) >>> 0;
+  b = (Math.imul(b, M) + C) >>> 0;
+  a = (a + Math.imul(b, M)) >>> 0;
+  b = (b + Math.imul(a, M)) >>> 0;
+  a = (a ^ (a >>> 16)) >>> 0;
+  b = (b ^ (b >>> 16)) >>> 0;
+  a = (a + Math.imul(b, M)) >>> 0;
+  b = (b + Math.imul(a, M)) >>> 0;
+  a = (a ^ (a >>> 16)) >>> 0;
+  b = (b ^ (b >>> 16)) >>> 0;
+  return [(a & 0xffffff) / 16777216, (b & 0xffffff) / 16777216];
+}
+
+/** spatial probability gate: 0..1, deterministic per ~0.5 m cell */
+export const hashXZ = (x, z, salt) => pcg2d(Math.floor(x * 2), Math.floor(z * 2), salt)[0];
+
+// Parent clump field: hashed parent points on a coarse grid, weight = max kernel
+// over the 3×3 neighbourhood — ~1 at clump hearts, 0 in the gaps between. The
+// SAME salt is shared by trees and understory so ferns gather under the same
+// thickets whose trees they shade beneath (braffolk's canopy proxy).
+const PARENT_CELL = 26;
+const PARENT_PROB = 0.62;
+export const TREE_SALT = 0x51f3;
+
+export function clumpField(x, z, salt = TREE_SALT) {
+  const bx = Math.floor(x / PARENT_CELL), bz = Math.floor(z / PARENT_CELL);
+  let w = 0;
+  for (let dz = -1; dz <= 1; dz++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      const cx = bx + dx + 8192, cz = bz + dz + 8192;
+      if (pcg2d(cx, cz, salt ^ 0x9e3779)[0] >= PARENT_PROB) continue;
+      const [h0, h1] = pcg2d(cx, cz, salt);
+      const px = (cx - 8192 + 0.15 + h0 * 0.7) * PARENT_CELL;
+      const pz = (cz - 8192 + 0.15 + h1 * 0.7) * PARENT_CELL;
+      const r = PARENT_CELL * (h0 * 0.55 + 0.5);
+      const k = 1 - sstep(r * 0.22, r, Math.hypot(x - px, z - pz));
+      if (k > w) w = k;
+    }
+  }
+  return w;
+}
+
+/** analytic moisture 0..1 — desert-low: faint drift, a lusher corridor along the creek */
+export function moistureAt(x, z) {
+  let m = 0.12 + TERRAIN.fbm(x + 191, z - 87, 3, 2, 0.5, 0.012) * 0.1;
+  const ri = TERRAIN.riverInfo(x, z);
+  if (ri.dist < ri.w + 30) m += 0.35 * (1 - Math.max(0, ri.dist - ri.w) / 30);
+  for (const L of TERRAIN.LAKES) {
+    const d = dist2D(x, z, L.x, L.z) - L.r;
+    if (d < 22) m += 0.35 * (1 - Math.max(0, d) / 22);
+  }
+  m -= Math.max(0, (TERRAIN.heightAt(x, z) - 12) * 0.012);
+  return Math.min(1, Math.max(0, m));
+}
+
+/** no forest on the desert plain — always 0 (signature kept for the field consumers) */
+export function forestness(x, z) {
+  return 0;
+}

package/src/world/footprints.js

@@ -0,0 +1,117 @@
+// Footprints in the snow — a resident pool of ground decals stamped on the player's
+// stride and faded out over time in the shader (snow doesn't spring back like grass, so
+// prints LINGER then melt away). Mirrors the grass-trample idea — a timestamped trail —
+// but snow is TERRAIN, not instanced blades, so prints are decal quads laid on the ground.
+//
+// Fixed-size ring buffer of instances → resident-for-life, never added/removed at runtime
+// (the WebGPU skinned/mesh-churn rule): only per-instance matrices + a spawn-time attribute
+// are rewritten as feet land. One InstancedMesh = one draw call for the whole trail.
+import * as THREE from 'three/webgpu';
+import { attribute, uniform, float, uv, smoothstep, oneMinus, step, max, vec3 } from 'three/tsl';
+
+
+const N = 96;             // pool size — must outlast LIFE worth of strides so prints don't self-evict early
+const STRIDE = 0.9;      // metres between footfalls (walk cadence)
+const LATERAL = 0.13;    // left/right offset of each print from the centre line
+const HOLD = 5;          // seconds a print stays at full strength
+const LIFE = 14;         // seconds until fully melted (fade runs HOLD..LIFE)
+const SNOW_MIN = 0.5;    // snowFactor threshold — only leave prints on actual snow
+const STRENGTH = 0.55;   // max decal darkness (a clear cool depression, not a faint smudge)
+
+export class Footprints {
+  constructor(scene, { heightAt = () => 0, snowFactor = () => 0 } = {}) {
+    this._heightAt = heightAt; this._snowFactor = snowFactor;
+    this.scene = scene;
+    this._now = 0; this._head = 0; this._dist = 0; this._foot = 1;
+    this._lastX = null; this._lastZ = null; this._moving = false;
+    this.uNow = uniform(0);
+
+    const geo = new THREE.PlaneGeometry(0.26, 0.44).rotateX(-Math.PI / 2); // lay flat; local +Z = print length
+    const spawn = new Float32Array(N).fill(-1000);                          // all "born" long ago → invisible
+    geo.setAttribute('aSpawn', new THREE.InstancedBufferAttribute(spawn, 1));
+    this._spawnAttr = geo.getAttribute('aSpawn');
+
+    this.mesh = new THREE.InstancedMesh(geo, this._makeMaterial(), N);
+    this.mesh.frustumCulled = false;
+    this.mesh.castShadow = false; this.mesh.receiveShadow = false;
+    this.mesh.renderOrder = 2;                    // draw over the terrain
+    this.mesh.name = 'footprints';
+    const m = new THREE.Matrix4().makeScale(0, 0, 0);
+    for (let i = 0; i < N; i++) this.mesh.setMatrixAt(i, m);
+    this.mesh.instanceMatrix.needsUpdate = true;
+    scene.add(this.mesh);
+
+    this._m = new THREE.Matrix4(); this._q = new THREE.Quaternion();
+    this._p = new THREE.Vector3(); this._sv = new THREE.Vector3(); this._up = new THREE.Vector3(0, 1, 0);
+  }
+
+  _makeMaterial() {
+    const mat = new THREE.MeshBasicNodeMaterial({ transparent: true, depthWrite: false });
+    mat.polygonOffset = true; mat.polygonOffsetFactor = -4; mat.polygonOffsetUnits = -4;
+    const age = this.uNow.sub(attribute('aSpawn', 'float'));
+    const alive = step(float(0), age).mul(oneMinus(step(float(LIFE), age)));  // 1 while 0<=age<=LIFE
+    const fade = oneMinus(smoothstep(float(HOLD), float(LIFE), age));         // 1 → 0 over HOLD..LIFE
+    // procedural two-lobe boot sole (ball + heel) — soft falloff from UV, no texture asset
+    const p = uv();
+    const lobe = (cx, cy, rx, ry) => {
+      const dx = p.x.sub(float(cx)).div(float(rx));
+      const dy = p.y.sub(float(cy)).div(float(ry));
+      const d = dx.mul(dx).add(dy.mul(dy)).sqrt();
+      return oneMinus(smoothstep(float(0.45), float(1.0), d));
+    };
+    const shape = max(lobe(0.5, 0.40, 0.26, 0.34), lobe(0.5, 0.74, 0.17, 0.19));
+    mat.colorNode = vec3(0.10, 0.13, 0.20);                                   // cool pressed-snow shadow (reads grey-blue over white)
+    mat.opacityNode = shape.mul(fade).mul(alive).mul(float(STRENGTH));
+    return mat;
+  }
+
+  // Stamp one print centred at (x,z), long axis along yaw, scaled by `scale`.
+  _stamp(x, z, yaw, scale) {
+    const i = this._head % N;
+    this._q.setFromAxisAngle(this._up, yaw);
+    this._p.set(x, this._heightAt(x, z) + 0.03, z);
+    this._m.compose(this._p, this._q, this._sv.set(scale, scale, scale));
+    this.mesh.setMatrixAt(i, this._m);
+    this._spawnAttr.array[i] = this._now;
+    this.mesh.instanceMatrix.needsUpdate = true;
+    this._spawnAttr.needsUpdate = true;
+    this._head++;
+  }
+
+  // Called each frame with the active ground-walker. `grounded` gates prints (none airborne);
+  // `scale`/`strideMul` let a mounted horse leave bigger, wider-spaced hoof marks.
+  step(dt, x, z, grounded, { scale = 1, strideMul = 1, lateral = LATERAL } = {}) {
+    this._now += dt;
+    this.uNow.value = this._now;
+    if (!grounded) { this._lastX = null; this._moving = false; return; }   // reset stride on takeoff
+    if (this._lastX === null) { this._lastX = x; this._lastZ = z; return; }
+    const dx = x - this._lastX, dz = z - this._lastZ;
+    const moved = Math.hypot(dx, dz);
+    this._lastX = x; this._lastZ = z;
+    const onSnow = this._snowFactor(x, z, this._heightAt(x, z)) >= SNOW_MIN;
+
+    if (moved < 0.004) {                                      // effectively at rest this frame
+      if (this._moving && onSnow) {                          // JUST stopped → plant a standing pair (both feet)
+        const yaw = this._lastYaw ?? 0, nx = Math.sin(yaw), nz = Math.cos(yaw);
+        const sx = -nz, sz = nx;                             // perpendicular
+        this._stamp(x + sx * lateral, z + sz * lateral, yaw, scale);
+        this._stamp(x - sx * lateral, z - sz * lateral, yaw, scale);
+      }
+      this._moving = false;
+      return;
+    }
+    this._moving = true;
+    const nx = dx / moved, nz = dz / moved;                   // unit travel direction
+    const yaw = Math.atan2(nx, nz);                           // align print length to travel
+    this._lastYaw = yaw;
+    const px = -nz, pz = nx;                                  // perpendicular (left/right offset)
+    this._dist += moved;
+    const stride = STRIDE * strideMul;
+    while (this._dist >= stride) {
+      this._dist -= stride;
+      if (!onSnow) { this._foot = -this._foot; continue; }
+      this._stamp(x + px * lateral * this._foot, z + pz * lateral * this._foot, yaw, scale);
+      this._foot = -this._foot;
+    }
+  }
+}

package/src/world/lampField.js

@@ -0,0 +1,58 @@
+// THE LAMP FIELD — one cheap lighting system for the whole open world, inside AND out.
+//
+// The problem it solves: a WebGPU forward renderer shades EVERY resident light on EVERY fragment and
+// recompiles the pipeline whenever a light is added/removed (the multi-second "night freeze"), so real
+// THREE lights are capped at ~3 for the entire world. lampGlow.js sidestepped that with fake additive
+// glow — but that only paints a FLOOR decal; walls, props and faces stay dark. A saloon at night is too
+// dark to read cards.
+//
+// The fix: feed the NEAREST FIXED-N lamps to the player into a fixed-size uniform array each frame
+// (UniformArrayNode.updateType === RENDER repacks it automatically — no needsUpdate, no recompile), and
+// ADD each lamp's real half-lambert N·L with distance falloff into the world/character materials'
+// emissiveNode. Fixed N is baked into the shader graph => ONE pipeline forever, no light cap, constant
+// per-fragment cost no matter how many lamps exist across how many towns. Real light on walls + faces,
+// the SAME term inside and out. Pure forward TSL — works on the WebGL2 fallback too. See src/core/
+// renderer.js, world.js (the lamp sort it feeds off), lampGlow.js (kept as the visible flame bulb).
+import * as THREE from 'three/webgpu';
+import { Fn, vec3, uniform, uniformArray, positionWorld, normalWorld } from 'three/tsl';
+
+export const LAMP_N = 12;                    // nearest lamps shaded per fragment (fixed => one pipeline)
+const WARM = [1.0, 0.62, 0.30];              // lamp colour (warm oil-flame), scaled by each lamp's intensity
+
+// xyz = world position of the flame, w = 1 / range. Parked far below the world until fed.
+const uLampPos = uniformArray(Array.from({ length: LAMP_N }, () => new THREE.Vector4(0, -9999, 0, 1)));
+// rgb = colour * intensity, a unused.
+const uLampCol = uniformArray(Array.from({ length: LAMP_N }, () => new THREE.Vector4(0, 0, 0, 0)));
+export const uLampNight = uniform(0);        // 0 by day … 1 at night (fed = lampGlow.k), fades the whole term
+
+// per-fragment lamp contribution, tinted by the surface albedo `alb` and gated by night. Returns a colour
+// to ADD in emissiveNode (added after the sun/hemi BRDF = genuine additive fill).
+export const lampLight = /*@__PURE__*/ Fn(([alb]) => {
+  const acc = vec3(0).toVar();
+  for (let i = 0; i < LAMP_N; i++) {
+    const lp = uLampPos.element(i);
+    const lc = uLampCol.element(i);
+    const toL = lp.xyz.sub(positionWorld);
+    const d = toL.length();
+    const L = toL.div(d.max(0.0001));
+    const atten = d.mul(lp.w).oneMinus().max(0);          // 1 at the flame, 0 at range (w = 1/range)
+    const ndl = normalWorld.dot(L).mul(0.5).add(0.5);     // HALF-lambert: soft fill, faces never go pure black
+    acc.addAssign(lc.xyz.mul(atten.mul(atten)).mul(ndl)); // quadratic falloff → pops in invisibly at the N-set edge
+  }
+  return acc.mul(alb).mul(uLampNight);
+});
+
+// CPU: pack the nearest lamps into the uniform arrays. `sorted` is world.js's _lampSorted:
+// [{ p: { x, y, z, I?, range?, lift? } }, ...] nearest-first. Cheap — mutate in place, auto-repacked.
+export function refreshLampField(sorted) {
+  for (let i = 0; i < LAMP_N; i++) {
+    const s = sorted && sorted[i];
+    if (s && s.p) {
+      const p = s.p, I = p.I ?? 1;
+      uLampPos.array[i].set(p.x, (p.y ?? 0) + (p.lift ?? 0), p.z, 1 / (p.range ?? 10));
+      uLampCol.array[i].set(WARM[0] * I, WARM[1] * I, WARM[2] * I, 0);
+    } else {
+      uLampCol.array[i].set(0, 0, 0, 0);      // empty slot: zero colour = contributes nothing
+    }
+  }
+}

package/src/world/lampGlow.js

@@ -0,0 +1,92 @@
+// FAKE LIGHT, SO WE CAN AFFORD A LIT TOWN.
+//
+// Real lights are the scarcest thing in this renderer: WebGPU's forward loop evaluates EVERY
+// resident light on EVERY fragment, even one sitting at intensity 0 — which is why world.js
+// keeps a FIXED pool of 2–6 point lights and slides them to whichever posts are nearest, and
+// why the count may never change at runtime (a new light = a shader recompile = the multi-second
+// night freeze this codebase keeps warning about). Six lights over a whole town is a lit lamp
+// here and there and a dark street everywhere else.
+//
+// So light the street WITHOUT lights. Two pieces of geometry per lamp, both unlit, additive and
+// depth-write-off, so they cost a draw call each for the WHOLE TOWN and no shading at all:
+//
+//   FLAME  a small additive ball at the wick. It reads as the lamp being ON from any angle —
+//          no billboarding shader needed, because a sphere looks the same from everywhere.
+//   POOL   a flat disc of light on the dirt beneath, with a soft radial falloff painted into a
+//          texture. This is the bit that actually makes a street look lit: light ON something.
+//
+// Both fade in with the night (opacity is one shared uniform per material — free to animate),
+// so they cost nothing by day. The real light pool still rides along for the nearest few posts,
+// which is what gives genuine shading on the player and the boardwalk; this fills in the other
+// forty. Unlimited lamps, zero recompiles.
+import * as THREE from 'three/webgpu';
+
+// A radial falloff, painted once into a 128² canvas. Smooth, warm at the centre, gone at the rim.
+function glowTexture() {
+  const c = document.createElement('canvas');
+  c.width = c.height = 128;
+  const g = c.getContext('2d');
+  const grad = g.createRadialGradient(64, 64, 0, 64, 64, 64);
+  grad.addColorStop(0.0, 'rgba(255, 216, 150, 1.0)');
+  grad.addColorStop(0.35, 'rgba(255, 190, 110, 0.55)');
+  grad.addColorStop(0.7, 'rgba(255, 170, 90, 0.16)');
+  grad.addColorStop(1.0, 'rgba(255, 160, 80, 0.0)');
+  g.fillStyle = grad;
+  g.fillRect(0, 0, 128, 128);
+  const t = new THREE.CanvasTexture(c);
+  t.colorSpace = THREE.SRGBColorSpace;
+  return t;
+}
+
+export class LampGlow {
+  // lamps: [{ x, y, z, ground }] — y is the flame, ground is the dirt under it
+  constructor(scene, lamps, { poolR = 5.6, flameR = 0.18 } = {}) {
+    this.lamps = lamps;
+    this.k = 0;                     // 0 by day … 1 at night (eased)
+    if (!lamps.length) return;
+
+    const tex = glowTexture();
+    // THE POOL on the ground. One InstancedMesh for every lamp in the world = ONE draw call.
+    this.poolMat = new THREE.MeshBasicMaterial({
+      map: tex, transparent: true, opacity: 0, depthWrite: false,
+      blending: THREE.AdditiveBlending, side: THREE.DoubleSide, fog: false, toneMapped: false,
+    });
+    const poolGeo = new THREE.PlaneGeometry(poolR * 2, poolR * 2).rotateX(-Math.PI / 2);
+    this.pool = new THREE.InstancedMesh(poolGeo, this.poolMat, lamps.length);
+    // THE FLAME at the wick — a ball, so it needs no billboarding to face you.
+    this.flameMat = new THREE.MeshBasicMaterial({
+      color: 0xffcf8a, transparent: true, opacity: 0, depthWrite: false,
+      blending: THREE.AdditiveBlending, fog: false, toneMapped: false,
+    });
+    this.flame = new THREE.InstancedMesh(new THREE.SphereGeometry(flameR, 8, 6), this.flameMat, lamps.length);
+
+    const m = new THREE.Matrix4();
+    const q = new THREE.Quaternion();
+    const s = new THREE.Vector3(1, 1, 1);
+    lamps.forEach((l, i) => {
+      // the pool sits a whisker above the dirt, or it z-fights the ground it is painted on
+      this.pool.setMatrixAt(i, m.compose(new THREE.Vector3(l.x, (l.ground ?? l.y - 2) + 0.03, l.z), q, s));
+      this.flame.setMatrixAt(i, m.compose(new THREE.Vector3(l.x, l.y, l.z), q, s));
+    });
+    for (const im of [this.pool, this.flame]) {
+      im.instanceMatrix.needsUpdate = true;
+      im.frustumCulled = false;       // the town is one instanced mesh; culling it all-or-nothing is worse
+      im.castShadow = im.receiveShadow = false;
+      im.matrixAutoUpdate = false;
+      im.renderOrder = 3;             // after the world, so the additive pass lands on top of it
+      scene.add(im);
+    }
+    console.log(`[lamps] ${lamps.length} glow lamps (2 draw calls, no lights)`);
+  }
+
+  // hour → lit. Lamps strike at 19.25 (~7:15pm, Nick — 18 lit them while it was still full daylight),
+  // out by 6.5 — the same window world.js lights its real pool on.
+  update(dt, hour) {
+    if (!this.pool) return;
+    const night = (hour >= 19.25 || hour < 6.5) ? 1 : 0;
+    this.k += (night - this.k) * Math.min(1, dt * 1.5);
+    if (this.k < 0.002 && this.poolMat.opacity === 0) return;
+    this.poolMat.opacity = this.k * 0.95;
+    this.flameMat.opacity = this.k;
+  }
+}