/** * sail.js — shade sail cloth simulation, corner loads, hardware failure. [Lane B] * * A 3D verlet cloth on a bilinear patch between 4 anchors. Wind pressure is * applied per FACE, not per node, which is the whole point: a twisted (hypar) * sail turns most of its faces edge-on to the wind and sheds load, while a flat * one presents every face square-on and catches everything. That difference is * the game's thesis and it is asserted in sail.selftest.js. * * Units are SI throughout: metres, kilograms, seconds, newtons. Corner loads * come out in real newtons and hardware ratings are real working load limits, * so a 5x5 m sail in a 34 m/s storm genuinely puts ~1-4 kN on a corner — which * is genuinely why real shade sails use 3 kN+ shackles. * * The sim core holds no THREE types: nodes are plain Float64Arrays, so the hot * loop allocates nothing, replays bit-for-bit, and runs headless under node * (see sail.selftest.js) as well as in Lane A's selftest.html. three.js only * appears in createSailView(), which is imported lazily. */ import * as THREE from '../vendor/three.module.js'; import { Emitter, FIXED_DT, HARDWARE } from './contracts.js'; import { RAIN_TIME_COMPRESSION } from './weather.core.js'; export { HARDWARE }; /** * What a carried spare re-rigs a corner with. The prep phase sells exactly one * kind ("spare shackle, $15"), so repair() has no hardware argument to take. */ const SPARE_HW = HARDWARE[1]; // ---------- sim tunables ---------- const SIM_DT = FIXED_DT; // sim always steps at a fixed rate; step() accumulates const MAX_SUBSTEPS = 5; // spiral-of-death guard when the frame hitches const RELAX_ITERS = 5; // FABRIC_K is calibrated against this; changing it rescales loads const GRAVITY = -9.81; // ---------- aerodynamics ---------- // 0.5 * air density (1.225) * flat-plate drag coefficient (~1.4). // Newtons per m^2 of face area per (m/s)^2 of normal-on airflow. const PRESSURE_COEFF = 0.86; const TANGENT_COEFF = 0.02; // skin friction dragging along the face const MAX_NORMAL_SPEED = 45; // clamp on the normal-on component, m/s — stability in extreme gusts // ---------- fabric ---------- const FABRIC_DENSITY = 0.32; // kg/m^2, typical knitted shade cloth // Axial stiffness of one grid spring, N/m — roughly E*t*width/length for // knitted HDPE mesh. Fed to the solver as a compliance (1/k), not used to // convert stretch into force: see _measureLoads for why that distinction is // the whole ballgame. const FABRIC_K = 100000; const K_COMPRESS = 0.08; // cloth resists stretch hard, compression barely (from prototype) const K_BEND = 0.04; const COMP_STRETCH = 1 / FABRIC_K; const COMP_COMPRESS = 1 / (FABRIC_K * K_COMPRESS); const COMP_BEND = 1 / (FABRIC_K * K_BEND); const VEL_DAMP = 0.995; // light; relative-wind drag supplies the real damping // ---------- ponding (SPRINT4 decision 10 / SPRINT5) ---------- // DESIGN.md §"Rain → ponding": "Flat sails collect water; water is heavy; the // belly collects more (positive feedback) until sudden dump, tear, or corner // failure." Lane C owns how hard it rains (rainMmPerHour + RAIN_TIME_COMPRESSION); // this owns how much of it a sail holds. // // The model is FLOW, not a drain coefficient. Water leaves a sail because it has // somewhere to GO, not because the fabric is tilted: each node pushes water down // its steepest neighbour, rim nodes pour it over the edge. The neighbourhood is // 8-way ON PURPOSE — on a hypar the water runs along the saddle's DIAGONAL ridge // to the two low corners, and a 4-way graph can't follow that, so it traps water // in the shallow gravity belly the cloth sags into between grid lines and a hypar // pools as much as a flat sail (measured: it did, until diagonals). So a flat // sail's belly is a basin water flows INTO and can't climb out of, while a hypar // drains to its low corners and off — which is why ponding cannot pincer §7. // // (My reverted Sprint-3 prototype drained by slope magnitude instead and pooled // 1 kg — it measured the coefficient I'd invented, not the sail.) const POND_FLOW = 6.0; // 1/s per unit of downhill gradient — how fast water finds the low spot const POND_SPILL = 3.0; // 1/s — a rim node pouring over the edge, when the edge is downhill // Depth cap per node. Water funnels into ~10 belly nodes, not evenly, so this is // the depth AT THE DEEPEST POINT (a torn-sail extreme), not the average — set // too low and the whole sail saturates shallow and never reaches a kill load. const POND_MAX_KG_M2 = 900; // ~90 cm at the single deepest node const BROOM_DRAIN = 2.5; // 1/s at the poke — a ~1.5 s hold clears the belly // ---------- debris (SPRINT2 decision 5) ---------- const DEBRIS_RESTITUTION = 0.1; // a wheelie bin into shade cloth barely bounces const DEBRIS_SKIN = 0.06; // contact margin, ~cloth thickness // ---------- failure ---------- // Genuine solver-blowup threshold. NOT a "loads shouldn't get this high" cap: // investigating Lane D's tn-1.04 report showed a 155 m² flat sail holding // 2100 kg of ponded water really does put ~21 kN on a corner, and it stays // finite and tracks the water — that's correct physics for an absurd rig, not // divergence. Real divergence is 100 kN+ and NaN. So this sits well above any // real load; POND_BELLY_MAX below is what stops a sail bellying to 5 m first. const DIVERGENCE_N = 80000; // 80 kN — past here the solver has actually blown up const POND_BELLY_MAX = 4.0; // metres of sag before the sail tears and dumps (DESIGN.md "sudden dump… tear") const OVERLOAD_SECS = 0.4; // prototype: 0.4 s sustained overload before it lets go const OVERLOAD_RECOVER = 2.0; // prototype: overload timer bleeds off at 2x const LOAD_TAU = 0.11; // load meter smoothing time constant, s export const TENSION_MIN = 0.6; export const TENSION_MAX = 1.4; /** * How much pre-strain the tension dial actually commands, per unit of dial. * Dial 1.0 is neutral (rest length = as-cut), 1.4 is drum tight, 0.6 is loose. * * The prototype used `rest = rest / tension`, which on its 2D arbitrary scale * was harmless. In real newtons it is not: it asks for 17% pre-strain at dial * 1.2 and 29% at 1.4 — i.e. stretching an 18 m sail by three metres — and it * put 68 kN on a corner of the real yard's biggest quad before any wind blew. * * 0.10 puts dial 1.4 at 4% pre-strain. Measured: it swings a 5x5 m rig's peak * load 2.1x from loose to tight, so the dial is a real decision; and it redlines * the yard's 192 m2 quad at 8.3 kN drum-tight, which blows even a rated shackle * — correctly, because you cannot drum-tighten 192 m2 of cloth on $30 of * hardware. The load bars show that during prep, which is where it should be * learned. */ const PRE_STRAIN = 0.10; const TRIM_MIN = 0.85; const TRIM_MAX = 1.15; const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v); /** * Order 4 anchors into a non-self-intersecting ring by angle around their * centroid, projected onto the ground plane. Ported from the prototype's * orderRing; without it, picking corners in a silly order knots the sail. */ export function orderRing(anchors) { const n = anchors.length; let cx = 0, cz = 0; for (const a of anchors) { cx += a.pos.x; cz += a.pos.z; } cx /= n; cz /= n; return [...anchors].sort( (a, b) => Math.atan2(a.pos.z - cz, a.pos.x - cx) - Math.atan2(b.pos.z - cz, b.pos.x - cx) ); } export class SailRig { /** * @param {object} opts * @param {Array} opts.anchors world.anchors — see contracts.js Anchor * @param {number} opts.gridN nodes per side (default 10) * @param {number} opts.porosity 0 = solid membrane, ~0.3 = knitted shade cloth (blows through, less load) */ constructor({ anchors = [], gridN = 10, porosity = 0 } = {}) { this.anchors = anchors; this.N = gridN; this.porosity = porosity; this.corners = []; /** Emits 'break' and 'repair' as {type, corner} — contracts.js SailRig. */ this.events = new Emitter(); this.tension = 1.0; this.t = 0; this.rigged = false; this._acc = 0; // scratch, reused every face to keep the hot loop allocation-free this._probe = { x: 0, y: 0, z: 0 }; // Lane C's wind.sample(pos, t, out) takes an out-vector so we don't allocate // one per face per substep — 162 faces at 60 Hz is ~9.7k throwaway Vector3s // a second otherwise. A stub wind that ignores `out` still works: we read // the RETURN value, not this. this._windOut = new THREE.Vector3(); } /** * Rig the sail across 4 anchors. * @param {string[]} anchorIds 4 anchor ids; reordered into a ring internally * @param {object[]} hwChoices hardware per anchor id, same order as anchorIds * @param {number} tension 0.6 (loose, flogs) .. 1.4 (drum tight, shock-loads) */ attach(anchorIds, hwChoices, tension = 1.0) { if (anchorIds.length !== 4) throw new Error(`sail needs exactly 4 corners, got ${anchorIds.length}`); const picked = anchorIds.map((id) => { const a = this.anchors.find((x) => x.id === id); if (!a) throw new Error(`unknown anchor "${id}"`); return a; }); const hwById = new Map(anchorIds.map((id, i) => [id, hwChoices[i] || HARDWARE[0]])); const ring = orderRing(picked); this.tension = clamp(tension, TENSION_MIN, TENSION_MAX); /** * A new sail is a new clock. [SPRINT13 — D's pool nit, and it wasn't a nit] * * `this.t` is the sim's OWN fixed-step clock: step() burns ragged frame dt * into SIM_DT chunks and samples the wind at this.t, which is the whole * reason a 144 Hz browser and a fast-forwarded selftest produce byte-equal * traces. But it was only ever zeroed in the constructor, and main.js builds * ONE SailRig at boot and re-attach()es it every night — while step() runs * every frame in EVERY phase (storm, aftermath, the forecast card) the * moment `rigged` is true. * * So night 2 opened its storm with the clock wherever night 1's aftermath * left it, and sampled the storm curve from there. Measured on the wild * night, p1..p4 with rated shackles: * * clock reset (as authored) p4 3.65 kN p2 2.78 p3 1.62 p1 0.98 * carried t=110 (night 2) p4 2.60 kN p2 1.92 p3 0.81 p1 0.54 * * Every night after the first flew a storm 30-50% weaker than the one C * authored — past the end of its own baseCurve, so it read the tail breeze * flat, with no build and no peak. Worse, the offset was however long the * player spent reading the invoice, so it wasn't even the same wrong storm * twice: a determinism break in a repo whose whole sim is built on not * having one. * * Zeroed here rather than in main.js because attach() is the one door every * caller comes through (boot, the picking adapter, balance.test, the audit), * and commit → attach → game.advance() → storm all land in a single keypress, * so t=0 at attach IS t=0 at the first storm frame. */ this.t = 0; this._acc = 0; this.corners = ring.map((a) => ({ anchorId: a.id, anchor: a, hw: hwById.get(a.id), load: 0, peakLoad: 0, overload: 0, broken: false, trim: 1.0, loadVec: { x: 0, y: 0, z: 0 }, // reaction direction, not just magnitude — see _measureLoads })); this._build(ring); this.rigged = true; return this; } _build(ring) { const N = this.N; const nodeCount = N * N; this.pos = new Float64Array(nodeCount * 3); this.prev = new Float64Array(nodeCount * 3); this.force = new Float64Array(nodeCount * 3); this.invMass = new Float64Array(nodeCount); // Bilinear patch across the 4 corners. Because the anchors sit at different // heights, this initial surface is already a hypar — the sim just relaxes it. const [c0, c1, c2, c3] = ring.map((a) => a.pos); for (let v = 0; v < N; v++) { for (let u = 0; u < N; u++) { const fu = u / (N - 1), fv = v / (N - 1); const i = (v * N + u) * 3; for (let k = 0; k < 3; k++) { const ax = ['x', 'y', 'z'][k]; const top = (1 - fu) * c0[ax] + fu * c1[ax]; const bot = (1 - fu) * c3[ax] + fu * c2[ax]; this.pos[i + k] = this.prev[i + k] = (1 - fv) * top + fv * bot; } } } const idx = (u, v) => v * N + u; this.cornerIdx = [idx(0, 0), idx(N - 1, 0), idx(N - 1, N - 1), idx(0, N - 1)]; // springs: structural + shear carry load; bend only resists folding this.springs = []; const link = (a, b, kind) => { const ax = a * 3, bx = b * 3; const dx = this.pos[bx] - this.pos[ax]; const dy = this.pos[bx + 1] - this.pos[ax + 1]; const dz = this.pos[bx + 2] - this.pos[ax + 2]; this.springs.push({ a, b, restBase: Math.hypot(dx, dy, dz), rest: 0, kind }); }; for (let v = 0; v < N; v++) { for (let u = 0; u < N; u++) { if (u < N - 1) link(idx(u, v), idx(u + 1, v), 'struct'); if (v < N - 1) link(idx(u, v), idx(u, v + 1), 'struct'); if (u < N - 1 && v < N - 1) { link(idx(u, v), idx(u + 1, v + 1), 'shear'); link(idx(u + 1, v), idx(u, v + 1), 'shear'); } if (u < N - 2) link(idx(u, v), idx(u + 2, v), 'bend'); if (v < N - 2) link(idx(u, v), idx(u, v + 2), 'bend'); } } // XPBD Lagrange multipliers, one per spring, reset every substep this.lambda = new Float64Array(this.springs.length); // ---- ponding state ---- this.water = new Float64Array(nodeCount); // kg on each node this._nodeFlat = new Float64Array(nodeCount); // area-weighted |ny|, refilled by the wind pass this._nodeArea = new Float64Array(nodeCount); this._wFlow = new Float64Array(nodeCount); // per-step transfer buffer // 8-neighbour graph, -1 padded (see the ponding note for why diagonals). this._nbr = new Int32Array(nodeCount * 8).fill(-1); this._isRim = new Uint8Array(nodeCount); for (let v = 0; v < N; v++) { for (let u = 0; u < N; u++) { const n = idx(u, v); let k = 0; for (const [du, dv] of [[-1, 0], [1, 0], [0, -1], [0, 1], [-1, -1], [1, -1], [-1, 1], [1, 1]]) { const uu = u + du, vv = v + dv; this._nbr[n * 8 + k++] = (uu >= 0 && uu < N && vv >= 0 && vv < N) ? idx(uu, vv) : -1; } this._isRim[n] = (u === 0 || u === N - 1 || v === 0 || v === N - 1) ? 1 : 0; } } // Springs meeting each corner, kept as {spring, index} so the load meter can // look up each one's multiplier. Bend springs are included: the hardware // physically carries every element that touches it, and leaving them out // under-reports the reaction and breaks the statics balance. this.cornerSprings = this.cornerIdx.map((ci) => this.springs .map((s, si) => ({ s, si })) .filter(({ s }) => s.a === ci || s.b === ci) ); // triangles: wind acts per face, and coverage raycasts against these this.tris = new Uint16Array((N - 1) * (N - 1) * 6); let ti = 0; for (let v = 0; v < N - 1; v++) { for (let u = 0; u < N - 1; u++) { const a = idx(u, v), b = idx(u + 1, v), c = idx(u + 1, v + 1), d = idx(u, v + 1); this.tris[ti++] = a; this.tris[ti++] = b; this.tris[ti++] = c; this.tris[ti++] = a; this.tris[ti++] = c; this.tris[ti++] = d; } } // grid-space proximity of every node to each corner, for per-corner trim this._cornerWeight = []; for (let k = 0; k < 4; k++) { const cu = [0, N - 1, N - 1, 0][k], cv = [0, 0, N - 1, N - 1][k]; const w = new Float64Array(nodeCount); for (let v = 0; v < N; v++) { for (let u = 0; u < N; u++) { const dist = Math.hypot(u - cu, v - cv) / (N - 1); w[idx(u, v)] = Math.max(0, 1 - dist); } } this._cornerWeight.push(w); } this.area = this._surfaceArea(); const mass = (FABRIC_DENSITY * this.area) / nodeCount; this.nodeMass = mass; this.invMass.fill(1 / mass); this._applyRestLengths(); this._repin(0); } /** Rest lengths shrink as the tension dial rises, modulated per corner by trim. */ _applyRestLengths() { for (const s of this.springs) { let wsum = 0, tsum = 0; for (let k = 0; k < 4; k++) { const w = this._cornerWeight[k][s.a] + this._cornerWeight[k][s.b]; wsum += w; tsum += w * this.corners[k].trim; } const trim = wsum > 1e-9 ? tsum / wsum : 1; s.rest = s.restBase * (1 - PRE_STRAIN * (this.tension * trim - 1)); } } /** Pinned corners are infinite-mass so springs stretch honestly against them. */ _repin(t) { for (let k = 0; k < 4; k++) { const c = this.corners[k]; const ci = this.cornerIdx[k]; if (c.broken) { this.invMass[ci] = 1 / this.nodeMass; // freed node — flogging falls out of this continue; } this.invMass[ci] = 0; const p = this._anchorPos(c.anchor, t); this.pos[ci * 3] = p.x; this.pos[ci * 3 + 1] = p.y; this.pos[ci * 3 + 2] = p.z; this.prev[ci * 3] = p.x; this.prev[ci * 3 + 1] = p.y; this.prev[ci * 3 + 2] = p.z; } } /** * Where a corner is pinned right now. `sway(t)` is the ABSOLUTE world * position, not an offset from `pos` (contracts.js Anchor; Lane A called this * out in THREADS). House and post anchors return a constant; tree anchors * wander, and that wander is dynamic load — the reason a tree is the scary * anchor. The returned vector is shared and reused between calls, so read it * immediately and never store it. */ _anchorPos(a, t) { return a.sway ? a.sway(t) : a.pos; } _surfaceArea() { let total = 0; for (let i = 0; i < this.tris.length; i += 3) { const a = this.tris[i] * 3, b = this.tris[i + 1] * 3, c = this.tris[i + 2] * 3; const e1x = this.pos[b] - this.pos[a], e1y = this.pos[b + 1] - this.pos[a + 1], e1z = this.pos[b + 2] - this.pos[a + 2]; const e2x = this.pos[c] - this.pos[a], e2y = this.pos[c + 1] - this.pos[a + 1], e2z = this.pos[c + 2] - this.pos[a + 2]; const nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x; total += Math.hypot(nx, ny, nz) * 0.5; } return total; } /** * Advance the sim. Accumulates real time and burns it in fixed SIM_DT chunks, * so a variable-rate render loop and a fast-forwarded selftest produce * identical traces. Never reads a clock. * * @param {number} dt seconds elapsed since last call * @param {object} wind { sample(pos, t) -> {x,y,z} } * @param {number} t world time, seconds * @param {object} [debris] Lane C's debris module, or anything with `.pieces`. * Optional — the cloth runs fine without a storm's * worth of crates in it. */ step(dt, wind, t, debris = null) { if (!this.rigged) return; const pieces = debris ? (debris.pieces ?? debris) : null; this._acc += dt; let n = 0; while (this._acc >= SIM_DT && n < MAX_SUBSTEPS) { this._substep(SIM_DT, wind, this.t, pieces); this._acc -= SIM_DT; this.t += SIM_DT; n++; } if (n === MAX_SUBSTEPS) this._acc = 0; // dropped frames: don't try to catch up } _substep(dt, wind, t, pieces) { this._accumulateWind(wind, t, dt); // after the wind pass — it fills the per-node flatness/area ponding reads this._applyPonding(wind.rainMmPerHour ? wind.rainMmPerHour(t) : 0, dt); if (pieces && pieces.length) this._applyDebris(pieces, dt); this._integrate(dt); this.lambda.fill(0); // XPBD multipliers are per-substep for (let i = 0; i < RELAX_ITERS; i++) this._relax(dt * dt); this._pinCorners(t); this._measureLoads(dt); this._checkFailure(dt); if (this.watchDivergence) this._checkDivergence(); } /** * Optional tripwire for Lane D's tn-1.04 report. That spike does NOT reproduce * on current main — with swaying tree anchors, 3xrated+1carabiner, loads climb * smoothly 7.2->8.7 kN across the whole tension range, no discontinuity at * 1.04 (decision 11's downdraft bump and the §7 re-point changed the load * regime under it). So rather than clamp real physics to fix a bug I can't * demonstrate — the displacement clamp I tried moved the thesis 39->34% — this * just WATCHES. Set `rig.watchDivergence = true` and it throws with the corner, * load and time the instant a corner exceeds a physically-impossible load, so * if it ever comes back it comes back with a repro instead of a mystery. */ _checkDivergence() { for (let k = 0; k < 4; k++) { const c = this.corners[k]; if (c.load > DIVERGENCE_N || !Number.isFinite(c.load)) { throw new Error( `sail divergence: corner ${c.anchorId} at ${(c.load / 1000).toFixed(1)} kN, ` + `t=${this.t.toFixed(2)}s, tension=${this.tension.toFixed(3)}. This is the tn-1.04 cliff ` + `(THREADS [D] 2026-07-17) recurring — capture this rig and ping Lane B.`, ); } } } /** Wind force per FACE — the hypar mechanic lives here. */ _accumulateWind(wind, t, dt) { const pos = this.pos, prev = this.prev, F = this.force; F.fill(0); const coeff = PRESSURE_COEFF * (1 - this.porosity); const tanCoeff = TANGENT_COEFF * (1 - this.porosity); const invDt = 1 / dt; const probe = this._probe; for (let i = 0; i < this.tris.length; i += 3) { const ia = this.tris[i] * 3, ib = this.tris[i + 1] * 3, ic = this.tris[i + 2] * 3; const e1x = pos[ib] - pos[ia], e1y = pos[ib + 1] - pos[ia + 1], e1z = pos[ib + 2] - pos[ia + 2]; const e2x = pos[ic] - pos[ia], e2y = pos[ic + 1] - pos[ia + 1], e2z = pos[ic + 2] - pos[ia + 2]; // |cross| is twice the area and its direction is the face normal let nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x; const len = Math.hypot(nx, ny, nz); if (len < 1e-9) continue; const area = len * 0.5; nx /= len; ny /= len; nz /= len; probe.x = (pos[ia] + pos[ib] + pos[ic]) / 3; probe.y = (pos[ia + 1] + pos[ib + 1] + pos[ic + 1]) / 3; probe.z = (pos[ia + 2] + pos[ib + 2] + pos[ic + 2]) / 3; const w = wind.sample(probe, t, this._windOut); // Relative wind, not absolute: as the cloth accelerates downwind the load // bleeds off by itself. This is what stops flogging from exploding. const vx = (pos[ia] - prev[ia] + pos[ib] - prev[ib] + pos[ic] - prev[ic]) / 3 * invDt; const vy = (pos[ia + 1] - prev[ia + 1] + pos[ib + 1] - prev[ib + 1] + pos[ic + 1] - prev[ic + 1]) / 3 * invDt; const vz = (pos[ia + 2] - prev[ia + 2] + pos[ib + 2] - prev[ib + 2] + pos[ic + 2] - prev[ic + 2]) / 3 * invDt; const rx = w.x - vx, ry = w.y - vy, rz = w.z - vz; const d = clamp(rx * nx + ry * ny + rz * nz, -MAX_NORMAL_SPEED, MAX_NORMAL_SPEED); // d*|d| rather than d^2: keeps the v^2 magnitude but points the force the // way the wind is actually blowing. A sail is double-sided. const p = coeff * area * d * Math.abs(d); const tx = (rx - nx * d) * tanCoeff * area; const ty = (ry - ny * d) * tanCoeff * area; const tz = (rz - nz * d) * tanCoeff * area; const fx = (nx * p + tx) / 3, fy = (ny * p + ty) / 3, fz = (nz * p + tz) / 3; F[ia] += fx; F[ia + 1] += fy; F[ia + 2] += fz; F[ib] += fx; F[ib + 1] += fy; F[ib + 2] += fz; F[ic] += fx; F[ic + 1] += fy; F[ic + 2] += fz; // |ny| is how horizontal the face is (1 flat, 0 on edge), which is also // exactly the fraction of its area rain sees from straight up — so the // ponding catch area is free here rather than a second geometry pass. const share = area / 3, flat = Math.abs(ny) * share; const na = this.tris[i], nb = this.tris[i + 1], nc = this.tris[i + 2]; this._nodeFlat[na] += flat; this._nodeFlat[nb] += flat; this._nodeFlat[nc] += flat; this._nodeArea[na] += share; this._nodeArea[nb] += share; this._nodeArea[nc] += share; } } /** * Rain lands, runs downhill, and pools where it can't get out. Called after * the wind pass (which fills _nodeFlat / _nodeArea). * * ⚠ FABRIC-BLIND, on purpose and on the record (SPRINT16, C's finding): * nothing below reads `this.porosity`, so an open weave ponds exactly like a * membrane. Ruled a known simplification — see setFabric's comment for the * ruling and the re-measure bill a real through-weave leak would incur. * @param {number} mmPerHour wind.rainMmPerHour(t) — REAL-world rate, Lane C's data */ _applyPonding(mmPerHour, dt) { const pos = this.pos, F = this.force, w = this.water, flow = this._wFlow; const N2 = w.length; // 1 mm over 1 m² is 1 kg. Lane C owns the rate and the 40× compression // constant; multiplying them here is the whole of "how much a sail holds". const kgPerM2PerSec = (mmPerHour * RAIN_TIME_COMPRESSION) / 3600; for (let n = 0; n < N2; n++) { const a = this._nodeArea[n]; if (a > 1e-9 && kgPerM2PerSec > 0) { w[n] += kgPerM2PerSec * this._nodeFlat[n] * dt; // rain lands on the horizontal projection } flow[n] = 0; } // steepest-descent transfer: water leaves down the biggest GRADIENT, not the // biggest drop — a diagonal is √2 farther, so the same drop across it is a // gentler slope than straight down. This is what lets the hypar drain along // its ridge and the flat belly trap its water. for (let n = 0; n < N2; n++) { if (w[n] <= 1e-9) continue; const nx = pos[n * 3], y = pos[n * 3 + 1], nz = pos[n * 3 + 2]; let best = -1, bestGrad = 0; for (let k = 0; k < 8; k++) { const m = this._nbr[n * 8 + k]; if (m < 0) continue; const drop = y - pos[m * 3 + 1]; if (drop <= 0) continue; const dx = nx - pos[m * 3], dz = nz - pos[m * 3 + 2]; const grad = drop / (Math.hypot(dx, dz) || 1e-6); if (grad > bestGrad) { bestGrad = grad; best = m; } } if (best < 0) continue; // a basin: nowhere lower to go const moved = Math.min(w[n], w[n] * POND_FLOW * bestGrad * dt); flow[n] -= moved; flow[best] += moved; } // The per-node ceiling is enforced AFTER the flow step, not on the rain-add: // the old rain-add clamp only ran while it was raining, so once the rain // stopped, downhill consolidation could quietly stack a basin node past // POND_MAX_KG_M2 with nothing left to trim it (the belly-tear guard below // only bounds the gross runaway). Water over the cap sheets off the cloth — // it leaves the sail, same as the rim spill; it is not conserved. for (let n = 0; n < N2; n++) { w[n] += flow[n]; const a = this._nodeArea[n]; if (a > 1e-9 && w[n] > POND_MAX_KG_M2 * a) w[n] = POND_MAX_KG_M2 * a; } // A rim node spills over the edge ONLY when the edge is downhill — i.e. it // has no lower interior neighbour to send water to. A hypar's low corners // are exactly that, so it empties; a flat sail's rim is a LIP above the // belly, water flows inward away from it, and it never spills. for (let n = 0; n < N2; n++) { if (!this._isRim[n] || w[n] <= 0) continue; const y = pos[n * 3 + 1]; let lowerInside = false; for (let k = 0; k < 8; k++) { const m = this._nbr[n * 8 + k]; if (m >= 0 && pos[m * 3 + 1] < y - 1e-4) { lowerInside = true; break; } } if (!lowerInside) w[n] = Math.max(0, w[n] - w[n] * POND_SPILL * dt); } // the weight. Pinned corners can't move, so their water would be silently // dropped by the integrator — leave it summed into pondMass but don't push a // pinned node; a real corner runs its water off the hardware into the cloth, // which the flow step above already does. let lowestNode = 1e9, lowestCorner = 1e9; for (let n = 0; n < N2; n++) { if (w[n] > 0 && this.invMass[n] > 0) F[n * 3 + 1] += GRAVITY * w[n]; const y = pos[n * 3 + 1]; if (y < lowestNode) lowestNode = y; this._nodeFlat[n] = 0; this._nodeArea[n] = 0; } for (let k = 0; k < 4; k++) { const cy = pos[this.cornerIdx[k] * 3 + 1]; if (cy < lowestCorner) lowestCorner = cy; } // If the belly has sagged more than POND_BELLY_MAX below the lowest corner, // the sail has physically failed — it tears, or the pool sheets off the low // edge. Either way the water goes. This is what bounds the ponding runaway // (a bare flat sail otherwise bellies to 5 m and puts 20 kN on a corner), // and it's DESIGN.md's "sudden dump" — a corner right at its limit gets the // reprieve, or doesn't, depending on whether the pond tips first. if (lowestCorner - lowestNode > POND_BELLY_MAX && this.pondMass() > 1) { this.dumpPond('belly tore'); } } /** Total water on the sail, kg. Lane A's "SAIL PONDING — get the broom" number. */ pondMass() { if (!this.water) return 0; // the HUD may read this before the sail is rigged let m = 0; for (let n = 0; n < this.water.length; n++) m += this.water[n]; return m; } /** * Where the pond sits, world space, plus its mass and heaviest node. Null if * there's nothing worth pointing at. Lane D walks to this; Lane E draws it. * @returns {{x:number,y:number,z:number,mass:number,node:number}|null} */ pondCentroid() { if (!this.water) return null; let m = 0, x = 0, y = 0, z = 0, node = -1, hw = 0; for (let n = 0; n < this.water.length; n++) { const q = this.water[n]; if (q <= 0) continue; m += q; x += this.pos[n * 3] * q; y += this.pos[n * 3 + 1] * q; z += this.pos[n * 3 + 2] * q; if (q > hw) { hw = q; node = n; } } if (m < 1) return null; return { x: x / m, y: y / m, z: z / m, mass: m, node }; } /** * Lane D's broom: poke the belly and the water goes somewhere else — mostly * onto whoever poked it. Call every frame of the ~1.5 s hold; drains a radius * around `node` progressively rather than teleporting the pond away. * @param {number} node grid node index — aim at pondCentroid().node * @returns {number} kg dumped THIS call. Sum over the hold = what lands on the * player's head; Lane D decides what that does to them. */ drainPondAt(node, dt, radius = 2) { if (!this.rigged || node == null || node < 0 || node >= this.water.length) return 0; const N = this.N, cu = node % N, cv = (node / N) | 0; let dumped = 0; for (let v = Math.max(0, cv - radius); v <= Math.min(N - 1, cv + radius); v++) { for (let u = Math.max(0, cu - radius); u <= Math.min(N - 1, cu + radius); u++) { const n = v * N + u; if (this.water[n] <= 0) continue; const fall = 1 - Math.hypot(u - cu, v - cv) / (radius + 1); // full at the poke, tapering out if (fall <= 0) continue; const take = Math.min(this.water[n], this.water[n] * BROOM_DRAIN * fall * dt); this.water[n] -= take; dumped += take; } } if (dumped > 0) this.events.emit('pondDump', { type: 'pondDump', kg: dumped, node, t: this.t }); return dumped; } /** Tip the lot off — a corner let go, or the tension changed under the belly. */ dumpPond(reason = 'dump') { const kg = this.pondMass(); if (kg <= 0) return 0; this.water.fill(0); this.events.emit('pondDump', { type: 'pondDump', kg, reason, t: this.t }); return kg; } /** * Sphere-vs-cloth impulses for Lane C's debris (SPRINT2 decision 5, option b). * * The exchange is symmetric: every newton-second the cloth takes out of a * crate, the crate loses. That's the point of the decision — one integrator * does the momentum bookkeeping, so a crate punching through a sail slows * down by exactly as much as it speeds the cloth up. Asserted in * sail.selftest.js. * * Pinned corners are the deliberate exception: they have invMass 0, so a * crate that hits one bounces off and the momentum goes into the house. That * is correct — the anchor is bolted to a wall — and it's why the momentum * assert uses an interior hit. * * @param {Array} pieces debris.pieces — {x,y,z,vx,vy,vz,r,mass} */ _applyDebris(pieces, dt) { const pos = this.pos, prev = this.prev, im = this.invMass; for (const p of pieces) { if (p.alive === false || !Number.isFinite(p.mass) || p.mass <= 0) continue; // Swept: main.js steps the sail BEFORE the debris, so these positions are // a frame stale, and a 0.3 m crate at 25 m/s covers 0.42 m in a frame — // enough to pass clean between cloth nodes. Growing the contact radius by // the piece's travel catches both the lag and the tunnelling. const speed = Math.hypot(p.vx, p.vy, p.vz); const solid = p.r + DEBRIS_SKIN; const reach = solid + speed * dt; const reachSq = reach * reach; const wPiece = 1 / p.mass; let jx = 0, jy = 0, jz = 0, hits = 0; for (let n = 0; n < im.length; n++) { const i = n * 3; const dx = pos[i] - p.x, dy = pos[i + 1] - p.y, dz = pos[i + 2] - p.z; const dsq = dx * dx + dy * dy + dz * dz; if (dsq > reachSq || dsq < 1e-12) continue; const d = Math.sqrt(dsq); const nx = dx / d, ny = dy / d, nz = dz / d; // piece centre -> node // node velocity, read out of verlet const vnx = (pos[i] - prev[i]) / dt; const vny = (pos[i + 1] - prev[i + 1]) / dt; const vnz = (pos[i + 2] - prev[i + 2]) / dt; const vrel = (vnx - p.vx) * nx + (vny - p.vy) * ny + (vnz - p.vz) * nz; if (vrel > 0) continue; // already separating — don't glue them together const wNode = im[n]; const denom = wNode + wPiece; if (denom < 1e-12) continue; const j = (-(1 + DEBRIS_RESTITUTION) * vrel) / denom; hits++; // node takes +j along the contact normal; verlet stores velocity as a // position difference, so the impulse goes in by moving `prev` prev[i] -= nx * j * wNode * dt; prev[i + 1] -= ny * j * wNode * dt; prev[i + 2] -= nz * j * wNode * dt; // ...and the piece takes exactly -j. This is the conservation. jx -= nx * j; jy -= ny * j; jz -= nz * j; // Depenetrate free nodes by moving pos AND prev together, so pushing // the cloth off the crate doesn't secretly inject velocity. if (wNode > 0 && d < solid) { const push = solid - d; pos[i] += nx * push; prev[i] += nx * push; pos[i + 1] += ny * push; prev[i + 1] += ny * push; pos[i + 2] += nz * push; prev[i + 2] += nz * push; } } if (hits) { p.vx += jx * wPiece; p.vy += jy * wPiece; p.vz += jz * wPiece; this.events.emit('debrisHit', { type: 'debrisHit', piece: p, nodes: hits, impulse: Math.hypot(jx, jy, jz), t: this.t, }); } } } _integrate(dt) { const pos = this.pos, prev = this.prev, F = this.force, im = this.invMass; const dt2 = dt * dt; for (let n = 0; n < im.length; n++) { if (im[n] === 0) continue; // pinned const i = n * 3; for (let k = 0; k < 3; k++) { const a = F[i + k] * im[n] + (k === 1 ? GRAVITY : 0); const x = pos[i + k]; const nx = x + (x - prev[i + k]) * VEL_DAMP + a * dt2; prev[i + k] = x; pos[i + k] = nx; } } } /** * XPBD constraint solve. The plain-PBD version of this is simpler, but its * position corrections carry no force information — the leftover stretch * after a fixed iteration count is solver error, not fabric strain, so * reading load off it measures the solver. XPBD's Lagrange multiplier lambda * is the real constraint impulse, so lambda/dt^2 is a genuine newton value * and the corner reactions balance the applied wind by construction. */ _relax(dt2) { const pos = this.pos, im = this.invMass, lam = this.lambda; for (let si = 0; si < this.springs.length; si++) { const s = this.springs[si]; const wa = im[s.a], wb = im[s.b]; const w = wa + wb; if (w === 0) continue; // both ends pinned const ia = s.a * 3, ib = s.b * 3; const dx = pos[ib] - pos[ia], dy = pos[ib + 1] - pos[ia + 1], dz = pos[ib + 2] - pos[ia + 2]; const d = Math.hypot(dx, dy, dz); if (d < 1e-9) continue; const C = d - s.rest; const compliance = s.kind === 'bend' ? COMP_BEND : C > 0 ? COMP_STRETCH : COMP_COMPRESS; const at = compliance / dt2; const dLambda = (-C - at * lam[si]) / (w + at); lam[si] += dLambda; // grad C is -n for node a and +n for node b, with n = (b - a)/d const nx = dx / d, ny = dy / d, nz = dz / d; pos[ia] -= nx * dLambda * wa; pos[ia + 1] -= ny * dLambda * wa; pos[ia + 2] -= nz * dLambda * wa; pos[ib] += nx * dLambda * wb; pos[ib + 1] += ny * dLambda * wb; pos[ib + 2] += nz * dLambda * wb; } } _pinCorners(t) { for (let k = 0; k < 4; k++) { const c = this.corners[k]; if (c.broken) continue; const ci = this.cornerIdx[k] * 3; const p = this._anchorPos(c.anchor, t); this.pos[ci] = p.x; this.pos[ci + 1] = p.y; this.pos[ci + 2] = p.z; } } /** * Corner load = magnitude of the VECTOR sum of the tensions in the springs * meeting that corner, each read off its XPBD multiplier as |lambda|/dt^2. * * Reading tension as FABRIC_K * leftover-stretch instead looks equivalent and * is not: after a fixed 5 iterations the leftover stretch is solver error, so * that number measures the solver rather than the fabric and comes out ~50x * hot. The multiplier is the actual constraint impulse, which is why the * statics assert balances. * * The vector sum (rather than a scalar total) is what * makes DESIGN.md's anchor-angle mechanic fall out for free: edges pulling in * nearly the same direction add up, edges pulling apart partly cancel — so a * pinched corner really does multiply its own load. */ _measureLoads(dt) { const pos = this.pos, lam = this.lambda; const invDt2 = 1 / (dt * dt); const alpha = 1 - Math.exp(-dt / LOAD_TAU); for (let k = 0; k < 4; k++) { const c = this.corners[k]; if (c.broken) { c.load = 0; c.loadVec.x = c.loadVec.y = c.loadVec.z = 0; continue; } const ci = this.cornerIdx[k], cix = ci * 3; let sx = 0, sy = 0, sz = 0; for (const { s, si } of this.cornerSprings[k]) { if (lam[si] >= 0) continue; // slack or compressed fabric pulls on nothing const tension = -lam[si] * invDt2; // the multiplier IS the impulse; /dt^2 makes it newtons const o = (s.a === ci ? s.b : s.a) * 3; const dx = pos[o] - pos[cix], dy = pos[o + 1] - pos[cix + 1], dz = pos[o + 2] - pos[cix + 2]; const d = Math.hypot(dx, dy, dz); if (d < 1e-9) continue; sx += (dx / d) * tension; sy += (dy / d) * tension; sz += (dz / d) * tension; } c.loadVec.x += (sx - c.loadVec.x) * alpha; c.loadVec.y += (sy - c.loadVec.y) * alpha; c.loadVec.z += (sz - c.loadVec.z) * alpha; const raw = Math.hypot(sx, sy, sz); c.load += (raw - c.load) * alpha; if (c.load > c.peakLoad) c.peakLoad = c.load; } } /** * Zero the peak-load watermarks to the CURRENT load. `peakLoad` is otherwise * peak-since-attach, which silently folds the attach transient and any settle * into whatever you meant to measure — call this where measurement starts. * * Written for tools/site_audit, which was reporting a 12 s settle's transient * as a storm peak until it called this. `load` itself is untouched. */ resetPeaks() { for (const c of this.corners) c.peakLoad = c.load; return this; } /** * RMS speed of the cloth's nodes, m/s — read straight out of verlet, since * position IS the state here and velocity is just (pos - prev)/dt. * * This is what "is the sail settled" actually asks. Corner LOAD cannot answer * it: measured on the dressed yard, a load-trend guard reads 17% on a rig with * NO settle and 96% on a properly settled one, because what it really sees is * the rig loading up when the wind changes — the better-settled the cloth, the * sharper that ramp. Motion inverts none of that. Under unchanged conditions: * * 0 s settle 0.19 m/s 12 s settle 0.02 m/s 30 s 0.007 * * an order of magnitude, and in the direction the word "settled" means. Sample * it over a window, not per-step: the cloth breathes and never reaches zero. */ nodeSpeed() { const p = this.pos, q = this.prev; if (!p || !q) return 0; let sum = 0, n = 0; for (let i = 0; i < p.length; i += 3) { const dx = p[i] - q[i], dy = p[i + 1] - q[i + 1], dz = p[i + 2] - q[i + 2]; sum += dx * dx + dy * dy + dz * dz; n++; } return n ? Math.sqrt(sum / n) / SIM_DT : 0; } /** * Ported from the prototype: 0.4 s sustained over the rating and it lets go. * * SPRINT12 — the threshold is the ANCHOR's, not just the hardware's: * `hw.rating * anchor.ratingHint`. A's ruling (THREADS sprint 11, "THE * RATINGS ARE REAL. WIRE THEM."): DESIGN's fascia/carport lie is an ANCHOR * failing, and before this line every anchor was exactly as strong as the * carabiner you hung off it — E's baked 0.22/0.30/0.35 were read by nothing, * and the lever that decided whether the trap fired was tension, not steel. * Read LIVE from c.anchor each check (not captured at attach): dress() adopts * GLB hints by MUTATING the anchor objects in place, and a prep-time rig must * see the dressed number, not whatever was there when attach() ran. * The `?? 1` is belt-and-braces — world.js guarantees a finite hint on every * anchor (DEFAULT_RATING_HINT, a.test pins it), because `load > rating * * undefined` is `load > NaN`: always false, i.e. an UNBREAKABLE anchor. */ _checkFailure(dt) { let diverged = false; for (let k = 0; k < 4; k++) { const c = this.corners[k]; if (c.broken) continue; // A non-finite load can never trip the rating check below — NaN compares // false to everything — so a diverged corner would otherwise hold FOREVER // while NaN spreads node-to-node through the spring network. Divergence // is a failure, not weather: break the corner now, on the production // path, not just under the test-only watchDivergence tripwire. The event // carries reason:'divergence' so a log can tell it from an honest blow. if (!Number.isFinite(c.load)) { c.broken = true; c.overload = 0; c.load = 0; c.loadVec.x = c.loadVec.y = c.loadVec.z = 0; this.invMass[this.cornerIdx[k]] = 1 / this.nodeMass; this.dumpPond('corner blew'); this.events.emit('break', { type: 'break', corner: c, anchorId: c.anchorId, hw: c.hw.name, t: this.t, reason: 'divergence' }); diverged = true; continue; } if (c.load > c.hw.rating * (c.anchor.ratingHint ?? 1)) c.overload += dt; else c.overload = Math.max(0, c.overload - dt * OVERLOAD_RECOVER); if (c.overload > OVERLOAD_SECS) { c.broken = true; c.overload = 0; c.load = 0; // Hand the node its mass back. Everything good about a failure comes // from this one line: the freed corner stops being pinned, so it flies // on the wind and the flogging is emergent rather than animated. // Without it a "blown" corner stays welded in mid-air. this.invMass[this.cornerIdx[k]] = 1 / this.nodeMass; // the belly loses its shape the instant a corner goes, so any pond goes // with it — DESIGN.md's "sudden dump", onto whatever is below. this.dumpPond('corner blew'); this.events.emit('break', { type: 'break', corner: c, anchorId: c.anchorId, hw: c.hw.name, t: this.t }); } } // SPRINT16 gate 2.1 — THE HEAL. The break above made divergence detectable // (the fresh-eyes review's fix); this makes it survivable to LOOK at. The // freed corner otherwise keeps integrating from the NaN the solver left in // the spring network, and the cloth a player sees after the bang is a // shredded z-fighting mess, not a cloth. Heal ONLY on a divergence break — // an honest overload break has finite state and must not be touched. if (diverged) this._healNonFinite(); if (this._dirtyRest) { this._applyRestLengths(); this._dirtyRest = false; } } /** * Reset every non-finite node from its nearest finite neighbour (grid rings, * straight neighbours before diagonals — _nbr's own order), or from the * corners' anchors when the whole cloth is poisoned. `prev` is matched to * `pos` on every healed node so verlet reads zero velocity out of the heal * instead of inventing a launch. Non-finite WATER is zeroed too: a NaN pond * re-poisons the healed positions on the very next substep through the * weight term (F += GRAVITY * w), so healing positions alone heals nothing. * * Deterministic (fixed iteration order, no randomness, no clock), and pure * repair: a rig with fully finite state is untouched byte-for-byte — the * negative control in sail.selftest.js asserts a clean storm never emits * 'heal'. Emits 'heal' {nodes, t} so a log can count what a bang cost. * * @returns {number} nodes healed */ _healNonFinite() { const pos = this.pos, prev = this.prev, w = this.water; const n = this.invMass.length; // A NaN pond is poison whether or not its node's position survived. On // the divergence path today this is a SECOND wire — the break's // dumpPond('corner blew') already fill(0)s the whole pond — but the heal's // own contract must not depend on the dump's side effect: if divergence // ever stops dumping (a "the cloth healed, keep the water" retune), the // NaN pond would corrupt pondMass/centroid/broom forever. Unit-asserted // directly in sail.selftest.js for exactly that reason. for (let i = 0; i < n; i++) if (!Number.isFinite(w[i])) w[i] = 0; const sick = new Uint8Array(n); // 1 = position needs a donor let sickCount = 0, anyFinite = false, healed = 0; for (let i = 0; i < n; i++) { const x = i * 3; if (Number.isFinite(pos[x]) && Number.isFinite(pos[x + 1]) && Number.isFinite(pos[x + 2])) { anyFinite = true; // finite position, poisoned velocity: match prev, keep the position if (!Number.isFinite(prev[x]) || !Number.isFinite(prev[x + 1]) || !Number.isFinite(prev[x + 2])) { prev[x] = pos[x]; prev[x + 1] = pos[x + 1]; prev[x + 2] = pos[x + 2]; healed++; } } else { sick[i] = 1; sickCount++; } } if (sickCount) { // Whole cloth gone: re-seed the corners from their anchors — the one // world position a rig always knows — then flood from there. if (!anyFinite) { for (let k = 0; k < 4; k++) { const ci = this.cornerIdx[k], x = ci * 3; const p = this._anchorPos(this.corners[k].anchor, this.t); pos[x] = prev[x] = p.x; pos[x + 1] = prev[x + 1] = p.y; pos[x + 2] = prev[x + 2] = p.z; if (sick[ci]) { sick[ci] = 0; sickCount--; healed++; } } } // Ring-by-ring flood: each pass, a sick node bordering the finite region // copies that neighbour and joins it, so positions march inward from the // nearest healthy cloth. Terminates: the grid is connected, so every // pass with sick nodes left heals at least one. let changed = true; while (sickCount && changed) { changed = false; for (let i = 0; i < n; i++) { if (!sick[i]) continue; for (let k = 0; k < 8; k++) { const m = this._nbr[i * 8 + k]; if (m < 0 || sick[m]) continue; const x = i * 3, mx = m * 3; pos[x] = prev[x] = pos[mx]; pos[x + 1] = prev[x + 1] = pos[mx + 1]; pos[x + 2] = prev[x + 2] = pos[mx + 2]; sick[i] = 0; sickCount--; healed++; changed = true; break; } } } } if (healed) this.events.emit('heal', { type: 'heal', nodes: healed, t: this.t }); return healed; } // --- Lane D's seam (SPRINT2 decision 4) -------------------------------- // D landed first and duck-typed these against the rig, so B conforms to D's // spelling rather than the other way round. Thin aliases on purpose: the // behaviour lives in repairCorner/trimCorner, these just match the call sites // in interact.js and are what contracts.js promises. /** * Re-rig corner `i` with the spare the player was carrying. The spare is the * "$15 spare shackle" the prep phase sells, so it re-rigs at shackle grade — * which can be an UPGRADE on a corner that blew a carabiner, and a downgrade * on one that blew a rated shackle. That's the prototype's behaviour and it's * a real decision about which corner you run back to. * @param {number} i */ repair(i) { this.repairCorner(i, SPARE_HW); } /** * Per-corner turnbuckle. @param {number} i @param {number} delta ±, clamped 0.85–1.15. */ trim(i, delta) { this.trimCorner(i, delta); } /** * Live world position of corner `i`, as a FRESH vector — a blown corner's node * is flying, so Lane D's prompt has to chase it rather than sit on the anchor. * Fresh (not shared scratch) because interact.js holds the result across the * frame and two corners are read back to back. * @param {number} i * @returns {THREE.Vector3|null} */ cornerPos(i) { if (!this.rigged || !this.corners[i]) return null; const n = this.cornerIdx[i] * 3; return new THREE.Vector3(this.pos[n], this.pos[n + 1], this.pos[n + 2]); } /** Re-rig a blown corner with fresh hardware. Lane D's hold-E repair calls this. */ repairCorner(index, hw = SPARE_HW) { const c = this.corners[index]; if (!c || !c.broken) return false; c.broken = false; c.hw = hw; c.load = 0; c.overload = 0; this._repin(this.t); this.events.emit('repair', { type: 'repair', corner: c, anchorId: c.anchorId, hw: hw.name, t: this.t }); return true; } /** Turnbuckle trim at ONE corner (Lane D, 1.2 s hold). Tightens/eases locally. */ trimCorner(index, delta) { const c = this.corners[index]; if (!c) return false; c.trim = clamp(c.trim + delta, TRIM_MIN, TRIM_MAX); this._dirtyRest = true; return true; } /** * What the sail is made of. Porosity scales the wind pressure term — and, as * of SPRINT16, that is ALL it scales. The previous version of this comment * claimed an open weave "sheds the water it can't hold — so a porous cloth * also ponds far less", and C's gate-3 measurement caught the cheque the sim * doesn't cash: _applyPonding never reads porosity, so cloth and membrane * pond IDENTICALLY (the $75 soaker ring's q2 gap, 3.24 vs 3.32 kN, is wind * term only). RULED a known simplification rather than silently fixed * ([B] THREADS 2026-07-20): every pinned cloth number in the repo — the * backyard separation block, the §7 gates, C's storm_06 pins, the S15 * zero-delta lattice — was measured under fabric-blind ponding, and a pond- * physics change mid-TEETH would move all of them against the sprint's own * one-variable law. The fix (porosity-scaled intake + through-weave leak) * is real, wants its own gate with a full gauntlet re-measure, and C's * soaker is its ready-made test case; rigging.js's membrane-pricing comment * is the same conversation. Set BEFORE attach(); RiggingSession.commit() * does that. * @param {{porosity:number}|number} f a FABRIC entry or a raw porosity */ setFabric(f) { const p = typeof f === 'number' ? f : (f && f.porosity); if (Number.isFinite(p)) this.porosity = clamp(p, 0, 0.9); return this; } setTension(tension) { const was = this.tension; this.tension = clamp(tension, TENSION_MIN, TENSION_MAX); if (!this.rigged) return; this._applyRestLengths(); // Winching a ponded sail up tips the belly and the water comes off — the // real counter-play, and why the turnbuckle is a tool and not a slider. if (this.tension > was + 0.02) this.dumpPond('tensioned up'); } /** * Ground-projected shade over a rect: the fraction of sample points on the * rect that the sail blocks from the sun. This IS the shade mechanic, so it * raycasts toward the real sun rather than projecting straight down — which * is what lets DESIGN.md's moving and seasonal sun change the answer. * * @param {object} rect world.gardenBed shape: CENTRE (x,z), size (w,d), metres * @param {object} sunDir world.sunDir — unit vector from the ground TOWARD * the sun. A hit means shaded. Defaults to overhead. * @param {function} heightAt world.heightAt — rays start at the real ground. * Defaults to a flat y=0, which is only right for tests. */ coverageOver(rect, sunDir = { x: 0, y: 1, z: 0 }, heightAt = null) { if (!this.rigged) return 0; const len = Math.hypot(sunDir.x, sunDir.y, sunDir.z) || 1; const dx = sunDir.x / len, dy = sunDir.y / len, dz = sunDir.z / len; if (dy <= 0.01) return 0; // sun at or below the horizon casts no useful shade const COLS = 6, ROWS = 4; // prototype sampled 6x4 over the garden let hit = 0; for (let i = 0; i < COLS; i++) { for (let j = 0; j < ROWS; j++) { // rect is centre-and-size, so samples straddle (rect.x, rect.z) const ox = rect.x + ((i + 0.5) / COLS - 0.5) * rect.w; const oz = rect.z + ((j + 0.5) / ROWS - 0.5) * rect.d; const oy = heightAt ? heightAt(ox, oz) : 0; if (this._rayHitsSail(ox, oy, oz, dx, dy, dz)) hit++; } } return hit / (COLS * ROWS); } /** Moller-Trumbore against every face; 162 tris, cheap enough to not bother accelerating. */ _rayHitsSail(ox, oy, oz, dx, dy, dz) { const pos = this.pos; for (let i = 0; i < this.tris.length; i += 3) { const a = this.tris[i] * 3, b = this.tris[i + 1] * 3, c = this.tris[i + 2] * 3; const e1x = pos[b] - pos[a], e1y = pos[b + 1] - pos[a + 1], e1z = pos[b + 2] - pos[a + 2]; const e2x = pos[c] - pos[a], e2y = pos[c + 1] - pos[a + 1], e2z = pos[c + 2] - pos[a + 2]; const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x; const det = e1x * px + e1y * py + e1z * pz; if (Math.abs(det) < 1e-9) continue; // ray parallel to the face const inv = 1 / det; const tx = ox - pos[a], ty = oy - pos[a + 1], tz = oz - pos[a + 2]; const u = (tx * px + ty * py + tz * pz) * inv; if (u < 0 || u > 1) continue; const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x; const v = (dx * qx + dy * qy + dz * qz) * inv; if (v < 0 || u + v > 1) continue; const hitT = (e2x * qx + e2y * qy + e2z * qz) * inv; if (hitT > 1e-6) return true; } return false; } /** Sum of the aerodynamic + weight force on the whole sail, N. Used by the statics assert. */ netAppliedForce(wind, t) { this._accumulateWind(wind, t, SIM_DT); let fx = 0, fy = 0, fz = 0; for (let n = 0; n < this.invMass.length; n++) { fx += this.force[n * 3]; fy += this.force[n * 3 + 1] + GRAVITY * this.nodeMass; fz += this.force[n * 3 + 2]; } return { x: fx, y: fy, z: fz }; } maxLoad() { let m = 0; for (const c of this.corners) if (c.load > m) m = c.load; return m; } } /** * three.js view over a rig. Imported lazily so the sim core above stays * headless-runnable; call this only from the browser, after Lane A's vendor/ * exists. Returns a THREE.Group to add to the scene, with update() per frame. */ export async function createSailView(rig, { color = 0xd8c48a } = {}) { const THREE = await import('../vendor/three.module.js'); const geo = new THREE.BufferGeometry(); const verts = new Float32Array(rig.pos.length); geo.setAttribute('position', new THREE.BufferAttribute(verts, 3)); geo.setIndex(new THREE.BufferAttribute(new Uint16Array(rig.tris), 1)); // UVs: the grid IS the UV space, so (i, j) maps straight to (u, v). Without // this three defaults every vertex to (0,0), the map samples one texel, and // the membrane reads as flat colour — which looks like the texture failing // rather than like a bug. (Lane E's recipe, THREADS.) const N = rig.N; const uv = new Float32Array(N * N * 2); for (let j = 0, k = 0; j < N; j++) { for (let i = 0; i < N; i++, k += 2) { uv[k] = i / (N - 1); uv[k + 1] = j / (N - 1); } } geo.setAttribute('uv', new THREE.BufferAttribute(uv, 2)); const mat = new THREE.MeshStandardMaterial({ color, side: THREE.DoubleSide, roughness: 0.92, metalness: 0.0, }); // Resolved against this module rather than the server root: the same reason // weather.js builds STORM_DIR this way, and it's what the integrator's // /world/ -> relative pass was fixing. A missing texture must not take the // sail down — the cloth is the game, the weave is a finish. try { const tex = await new THREE.TextureLoader().loadAsync( new URL('../models/textures/sail_weave.png', import.meta.url).href, ); tex.wrapS = tex.wrapT = THREE.RepeatWrapping; tex.repeat.set(6, 6); // ~6 tiles across a 5 m sail (E's density) tex.colorSpace = THREE.SRGBColorSpace; // r175 spelling — `encoding` is gone tex.anisotropy = 4; // it's viewed at a raking angle from underneath mat.map = tex; // keep mat.color: the weave multiplies it } catch (err) { console.warn('[sail] weave texture missing, falling back to flat colour:', err.message); } const mesh = new THREE.Mesh(geo, mat); mesh.castShadow = true; // the shadow IS the product mesh.receiveShadow = true; mesh.frustumCulled = false; // it flogs well outside its initial bounds const group = new THREE.Group(); group.add(mesh); group.update = () => { verts.set(rig.pos); geo.attributes.position.needsUpdate = true; geo.computeVertexNormals(); geo.computeBoundingSphere(); }; group.update(); return group; }