@3driseai/3drise-viewer 0.1.28 → 0.1.29

package/dist/components/environment/Snow.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { AnimationOptions, MouseMoveDomain, SnowEnvironmentConfig } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export interface SnowProps extends ObjectReadyProps {
+    config: SnowEnvironmentConfig;
+    /** Scene object id: the live-edit handle is found by it. */
+    id?: string;
+    /** Keyframes on the config knobs (animations.environment.animations). */
+    keyframes?: AnimationOptions[];
+    /** Pointer bindings on the config knobs (mouseMove.environment). */
+    mouseMove?: MouseMoveDomain;
+}
+/**
+ * Snowfall with physical flakes: size-dependent terminal fall, helical flutter and tumbling dendrite crystals that glint in the sun, swept by travelling gusts and snow bands. The cursor is a gust, a shelter or a warm hand. Use for winter and weather scenes.
+ *
+ * The volume is the parent's transform: x / z span its scale, y rises from its origin to scale.y.
+ */
+declare const Snow: React.FC<SnowProps>;
+export default Snow;
+//# sourceMappingURL=Snow.d.ts.map

package/dist/components/environment/Snow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Snow.d.ts","sourceRoot":"","sources":["../../../src/components/environment/Snow.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAMtG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAgjBhE,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IAC/C,MAAM,EAAE,qBAAqB,CAAC;IAC9B,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,oEAAoE;IACpE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;GAIG;AACH,QAAA,MAAM,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,SAAS,CAmC7B,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/dist/components/environment/Snow.js

@@ -0,0 +1,609 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { DEFAULT_ENVIRONMENT_OBJECTS, ENVIRONMENT_OBJECTS_ANIMATABLE } from '@3driseai/3drise-core';
+import { withConfigDefaults } from '../../utils/configAnimations.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigDriver } from '../../hooks/useConfigDriver.js';
+import { useCloudSun } from '../../hooks/useCloudSun.js';
+import { stepPointerField, usePointerField } from '../../utils/pointerField.js';
+// Generated from Claude outputs/environment-lab/snow.mjs (the approved lab module) — edit there and regenerate.
+// Snow — environment object (lab module).
+// Construction: every flake is an analytic trajectory evaluated on the GPU from a per-flake seed.
+//   fall      y = y0 - v(d) * fallPhase        terminal velocity grows with flake size (v ~ 0.8..1.4 m/s)
+//   wind      xz += windOffset * drift          windOffset is integrated on the CPU (rate knobs never jump)
+//   gusts     a value-noise field travelling downwind at wind speed: it shoves flakes ahead and
+//             thickens the snowfall into sweeping curtains (snow bands) — one field, two readings
+//   flutter   helical side-slip of a falling plate (radius ~ 25 cm, 1..2.6 rad/s per flake)
+//   eddies    an ABC (Arnold–Beltrami–Childress) displacement: vx(y,z), vy(z,x), vz(x,y) -> divergence free
+//   tumble    the plate normal oscillates about vertical; the sprite is the plate's projected ellipse
+// Positions wrap with mod() inside their tile, faded at the tile and volume faces: nothing pops.
+// Optics: sky fill tinted by shadeColor + sun (two-sided plate diffuse + Henyey–Greenstein forward
+// lobe, g = 0.6) + specular glints when a tumbling plate's normal crosses the sun half-vector.
+// Two layers: near crystals (instanced dendrite quads in a camera-centred tile) and the far fall
+// (round specks filling the whole volume). Two draw calls.
+// Cost: the fall is fill-bound, not vertex-bound. Each far speck is drawn only out to the radius where
+// it is still above the alpha cut (and not at all when it never is), and is lit once in the vertex
+// stage; the near layer is skipped when the camera is too far from the volume to see a crystal.
+const catalog = {
+    key: 'snow',
+    name: 'Snow',
+    description: 'Snowfall with physical flakes: size-dependent terminal fall, helical flutter and tumbling dendrite crystals that glint in the sun, swept by travelling gusts and snow bands. The cursor is a gust, a shelter or a warm hand. Use for winter and weather scenes.',
+    tags: ['snow', 'weather', 'winter', 'snowfall', 'atmosphere', 'interactive'],
+    structural: ['density', 'quality', 'seed'],
+    pointerModes: ['gust', 'shelter', 'warmth'],
+    pointerLabels: { none: 'Off', gust: 'Gust', shelter: 'Shelter', warmth: 'Warmth' },
+};
+const QUALITY = { low: 0.5, medium: 1, high: 1.6 };
+const NEAR_BASE = 40000;
+const FAR_BASE = 60000;
+const NEAR_MAX = 90000;
+const FAR_MAX = 150000;
+const NEAR_TILE = 16;
+const WIND_MS = 8; // m/s per unit of windStrength (Rain's 0..1 range)
+const DEG = Math.PI / 180;
+function mulberry32(a) {
+    return function () {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function createUniforms() {
+    return {
+        uTime: { value: 0 },
+        uFall: { value: 0 },
+        uWind: { value: new THREE.Vector2() },
+        uWindDir: { value: new THREE.Vector2(0, 1) },
+        uGustPhase: { value: 0 },
+        uTurbPhase: { value: 0 },
+        uVolume: { value: new THREE.Vector3(100, 40, 100) },
+        uCam: { value: new THREE.Vector3() },
+        uTile: { value: NEAR_TILE },
+        uFollow: { value: 0 },
+        uViewH: { value: 800 },
+        uFarGain: { value: 20 },
+        uIntensity: { value: 1 },
+        uOpacity: { value: 0.9 },
+        uColor: { value: new THREE.Color('#f4f8ff') },
+        uShadeColor: { value: new THREE.Color('#a9bddc') },
+        uWindStrength: { value: 0.18 },
+        uTurb: { value: 0.25 },
+        uFlakeSize: { value: 0.045 },
+        uFlutter: { value: 0.6 },
+        uTumble: { value: 0.5 },
+        uGustiness: { value: 0.6 },
+        uBands: { value: 0.75 },
+        uGlint: { value: 0.8 },
+        uSpeed: { value: 1 },
+        uSunDir: { value: new THREE.Vector3(0.35, 0.42, 0.84).normalize() },
+        uSunColor: { value: new THREE.Color(1.0, 0.93, 0.82) },
+        uSkyAmbient: { value: new THREE.Color(0.55, 0.65, 0.85) },
+        uPointer: { value: new THREE.Vector3() },
+        uPointerVel: { value: new THREE.Vector3() },
+        uPointerActive: { value: 0 },
+        uPointerMode: { value: 0 },
+        uPointerStrength: { value: 1 },
+        uPointerRadius: { value: 1 },
+        uPointerColor: { value: new THREE.Color('#ffb070') },
+    };
+}
+function setColor(uniform, v) {
+    if (v === undefined || v === null)
+        return;
+    if (v.isColor)
+        uniform.value.copy(v);
+    else
+        uniform.value.set(v);
+}
+// The one push point: every per-frame knob lands here.
+function applyConfig(u, c) {
+    if (c.intensity !== undefined)
+        u.uIntensity.value = c.intensity;
+    if (c.speed !== undefined)
+        u.uSpeed.value = c.speed;
+    if (c.opacity !== undefined)
+        u.uOpacity.value = c.opacity;
+    setColor(u.uColor, c.color);
+    setColor(u.uShadeColor, c.shadeColor);
+    setColor(u.uPointerColor, c.pointerColor);
+    if (c.windStrength !== undefined)
+        u.uWindStrength.value = c.windStrength;
+    if (c.windDirection !== undefined)
+        u.uWindDir.value.set(Math.sin(c.windDirection * DEG), Math.cos(c.windDirection * DEG));
+    if (c.turbulence !== undefined)
+        u.uTurb.value = c.turbulence;
+    if (c.flakeSize !== undefined)
+        u.uFlakeSize.value = c.flakeSize;
+    if (c.flutter !== undefined)
+        u.uFlutter.value = c.flutter;
+    if (c.tumble !== undefined)
+        u.uTumble.value = c.tumble;
+    if (c.gustiness !== undefined)
+        u.uGustiness.value = c.gustiness;
+    if (c.bands !== undefined)
+        u.uBands.value = c.bands;
+    if (c.glint !== undefined)
+        u.uGlint.value = c.glint;
+    if (c.pointerStrength !== undefined)
+        u.uPointerStrength.value = c.pointerStrength;
+    if (c.pointerRadius !== undefined)
+        u.uPointerRadius.value = c.pointerRadius;
+    if (c.pointerMode !== undefined)
+        u.uPointerMode.value = catalog.pointerModes.indexOf(c.pointerMode);
+    if (c.followCamera !== undefined)
+        u.uFollow.value = c.followCamera ? 1 : 0;
+}
+const COMMON = /* glsl */ `
+uniform float uTime, uFall, uGustPhase, uTurbPhase, uTile, uFollow, uViewH, uFarGain;
+uniform vec2 uWind, uWindDir;
+uniform vec3 uVolume, uCam;
+uniform float uWindStrength, uTurb, uFlakeSize, uFlutter, uTumble, uGustiness, uBands;
+uniform vec3 uPointer, uPointerVel;
+uniform float uPointerActive, uPointerMode, uPointerStrength, uPointerRadius;
+
+float hash21(vec2 p) { p = fract(p * vec2(123.34, 456.21)); p += dot(p, p + 45.32); return fract(p.x * p.y); }
+float vnoise(vec2 p) {
+    vec2 i = floor(p); vec2 f = fract(p); f = f * f * (3.0 - 2.0 * f);
+    float a = hash21(i), b = hash21(i + vec2(1.0, 0.0)), c = hash21(i + vec2(0.0, 1.0)), d = hash21(i + vec2(1.0, 1.0));
+    return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+// Gust field (0..1): long waves across the wind, travelling downwind at the wind's own speed.
+float gustField(vec2 xz) {
+    vec2 pe = vec2(-uWindDir.y, uWindDir.x);
+    float a = dot(xz, uWindDir) / 26.0 - uGustPhase;
+    float b = dot(xz, pe) / 44.0;
+    return vnoise(vec2(a, b)) * 0.65 + vnoise(vec2(a * 2.1 + 3.7, b * 1.7 - 1.3)) * 0.35;
+}
+float bump(float x) { float t = clamp(1.0 - x * x, 0.0, 1.0); return t * t; }
+
+// Where a flake is now (object-local metres) and what it is doing.
+vec3 snowPos(vec3 s, float hs, vec4 sb, vec3 origin, vec3 span,
+             out float d, out float melt, out float shade, out float band) {
+    d = uFlakeSize * mix(0.55, 1.45, hs * hs);
+    float v = 0.8 + 0.45 * sqrt(d / max(uFlakeSize, 1e-4));       // terminal velocity, m/s at speed 1
+    float drift = 0.85 + 0.3 * sb.x;                               // lighter flakes ride the wind more
+    vec3 p = s * span + vec3(uWind.x * drift, -uFall * v, uWind.y * drift);
+    p = origin + mod(p - origin + 0.5 * span, span) - 0.5 * span;
+
+    // helical flutter of a falling plate
+    float om = mix(1.1, 2.6, sb.z);
+    float ph = sb.y * 6.2831853 + om * uTime;
+    p.xz += uFlutter * 0.25 * mix(0.5, 1.5, sb.x) * vec2(cos(ph), sin(ph));
+
+    // ABC eddies: each component independent of its own axis -> divergence free
+    vec3 q = p * 0.09; float t = uTurbPhase;
+    vec3 e = vec3(sin(q.y * 1.7 + t) + cos(q.z * 1.3 - t * 0.7),
+                  sin(q.z * 1.1 + t * 0.8) + cos(q.x * 1.9 + t * 0.5),
+                  sin(q.x * 1.5 - t * 1.1) + cos(q.y * 1.4 + t * 0.6));
+    p += uTurb * 1.6 * e;
+
+    // gusts push flakes downwind and gather them into bands
+    float g = gustField(p.xz);
+    p.xz += uWindDir * uGustiness * (0.4 + 2.0 * uWindStrength) * 6.0 * (g - 0.5);
+    p.y += uGustiness * 0.6 * (g - 0.5);
+    band = mix(1.0, 0.05 + 1.9 * smoothstep(0.38, 0.68, g), uBands);
+
+    melt = 0.0; shade = 1.0;
+    if (uPointerMode > -0.5 && uPointerActive > 0.001) {
+        vec3 P = uPointer * uVolume;
+        vec3 V = uPointerVel * uVolume;
+        float R = max(uPointerRadius * 2.0, 0.1);
+        float S = uPointerStrength * uPointerActive;
+        if (uPointerMode < 0.5) {
+            // gust: the hand's own air puff, along its velocity, relaxing when it stops
+            vec3 dp = p - P;
+            float w = bump(length(dp.xz) / R) * bump(dp.y / (R * 1.5));
+            vec3 push = V * 0.7; float m = length(push); if (m > 8.0) push *= 8.0 / m;
+            // the wake curls: a swirl about the axis across the motion, strongest behind the hand
+            vec3 ax = m > 1e-3 ? normalize(cross(push, vec3(0.0, 1.0, 0.0)) + vec3(0.0, 1e-4, 0.0)) : vec3(0.0);
+            vec3 sw = cross(ax, dp) * smoothstep(0.0, -R, dot(dp, push) / max(m, 1e-3)) * min(m, 4.0) * 0.35;
+            p += S * w * (push + sw + vec3(0.0, 0.08 * m, 0.0));
+        } else if (uPointerMode < 1.5) {
+            // shelter: an invisible canopy over the cursor; flakes slide off its rim, a dry column below
+            vec3 C = P - V * 0.2;
+            vec2 dxz = p.xz - C.xz; float r = length(dxz);
+            float below = smoothstep(C.y + 0.6, C.y - 0.8, p.y);
+            float w = bump(r / (R * 1.15)) * below;
+            p.xz += S * w * R * 0.9 * (r > 1e-3 ? dxz / r : vec2(1.0, 0.0));
+            shade = 1.0 - 0.45 * w * min(S, 1.0);
+        } else {
+            // warmth: a heat source melts flakes into droplets; the plume holds them up and leans with motion
+            vec3 C = P - V * 0.15;
+            float dy = p.y - C.y;
+            float r = length(p.xz - C.xz);
+            float w = bump(r / (R * (1.0 + 0.2 * max(dy, 0.0)))) * smoothstep(-0.7 * R, 0.0, dy) * bump(max(dy, 0.0) / (R * 1.6));
+            melt = smoothstep(0.25, 0.75, w * S);
+            p.y += melt * 0.6;
+        }
+    }
+    return p;
+}
+
+float volumeFade(vec3 p) {
+    float top = min(6.0, 0.15 * uVolume.y);
+    float a = smoothstep(0.0, 0.6, p.y) * (1.0 - smoothstep(uVolume.y - top, uVolume.y, p.y));
+    if (uFollow < 0.5) {
+        vec2 fx = min(vec2(8.0), 0.08 * uVolume.xz);
+        vec2 edge = 0.5 * uVolume.xz - abs(p.xz);
+        a *= smoothstep(0.0, fx.x, edge.x) * smoothstep(0.0, fx.y, edge.y);
+    }
+    return a;
+}
+`;
+const FOG_V = /* glsl */ `
+#ifdef USE_FOG
+varying float vFogDepth;
+#endif
+`;
+const FOG_F = /* glsl */ `
+#ifdef USE_FOG
+uniform vec3 fogColor;
+varying float vFogDepth;
+#ifdef FOG_EXP2
+uniform float fogDensity;
+#else
+uniform float fogNear;
+uniform float fogFar;
+#endif
+#endif
+`;
+const FOG_APPLY = /* glsl */ `
+#ifdef USE_FOG
+#ifdef FOG_EXP2
+    float fogFactor = 1.0 - exp(-fogDensity * fogDensity * vFogDepth * vFogDepth);
+#else
+    float fogFactor = smoothstep(fogNear, fogFar, vFogDepth);
+#endif
+    gl_FragColor.rgb = mix(gl_FragColor.rgb, fogColor * gl_FragColor.a, fogFactor);
+#endif
+`;
+const LIGHT = /* glsl */ `
+uniform vec3 uSunDir;
+uniform vec3 uSunColor, uSkyAmbient, uColor, uShadeColor, uPointerColor;
+uniform float uIntensity, uOpacity, uGlint;
+// sky fill + sun: two-sided plate diffuse and a Henyey–Greenstein forward lobe (g = 0.6)
+vec3 snowLight(vec3 toCam, vec3 n, float shade) {
+    vec3 V = normalize(toCam);
+    float mu = dot(-V, uSunDir);
+    const float g = 0.6;
+    float hg = 0.25 * (1.0 - g * g) / pow(1.0 + g * g - 2.0 * g * mu, 1.5);
+    float sunUp = smoothstep(-0.05, 0.12, uSunDir.y);
+    float diff = 0.45 + 0.55 * abs(dot(n, uSunDir));
+    vec3 lit = uSkyAmbient * uShadeColor * 0.6 + uSunColor * sunUp * (0.5 * diff + 0.3 * hg) * shade;
+    return min(lit * uColor, vec3(1.15));
+}
+`;
+const NEAR_VERT = /* glsl */ `
+${COMMON}
+uniform float uOpacity;
+attribute vec2 aCorner;
+attribute vec4 aSeedA;
+attribute vec4 aSeedB;
+varying vec2 vUv;
+varying float vAlpha, vPx, vMelt, vShade, vRot, vType, vGrow;
+varying vec3 vN, vToCam;
+${FOG_V}
+void main() {
+    float d, melt, shade, band;
+    vec3 p = snowPos(aSeedA.xyz, aSeedA.w, aSeedB, uCam, vec3(uTile), d, melt, shade, band);
+    vec3 toCam = uCam - p;
+    float dist = length(toCam);
+    // bands read at a distance; close up they only thin the fall a little
+    float a = volumeFade(p) * mix(1.0, band, 0.4) * (1.0 - smoothstep(0.3 * uTile, 0.48 * uTile, dist));
+
+    // plate normal: a slow azimuth and a tilt oscillation about vertical
+    float psi = aSeedB.y * 6.2831853 + uTime * 0.35 * (aSeedB.z - 0.5);
+    float th = uTumble * 1.35 * sin(uTime * mix(0.8, 2.2, aSeedB.z) + aSeedB.w * 6.2831853);
+    vec3 n = vec3(sin(th) * cos(psi), cos(th), sin(th) * sin(psi));
+
+    vec4 mv = modelViewMatrix * vec4(p / uVolume, 1.0);
+    vec3 nv = normalize(normalMatrix * n);
+    float fore = abs(dot(nv, normalize(mv.xyz)));
+    vec2 minor = length(nv.xy) > 1e-3 ? normalize(nv.xy) : vec2(0.0, 1.0);
+    vec2 major = vec2(minor.y, -minor.x);   // (major, minor) right-handed: the quad stays front-facing
+
+    float size = d * mix(1.0, 1.25, melt);
+    float px = size * uViewH * projectionMatrix[1][1] * 0.5 / max(-mv.z, 1e-3);
+    float grow = max(1.0, 2.0 / max(px, 1e-3));
+    a /= grow * grow;
+    a *= smoothstep(0.08, 0.45, -mv.z);
+
+    vec2 off = (major * aCorner.x + minor * aCorner.y * max(fore, mix(0.22, 1.0, melt))) * size * 0.5 * grow;
+    mv.xy += off;
+    // the fragment's alpha is at most 3 * a * opacity (a melted droplet's bright point): below the
+    // alpha cut nothing of this crystal survives, so it is clipped away instead of rasterised
+    gl_Position = a * uOpacity * 3.0 < 0.003 ? vec4(2.0, 2.0, 2.0, 1.0) : projectionMatrix * mv;
+
+    vUv = aCorner; vAlpha = a; vPx = px; vMelt = melt; vShade = shade;
+    vRot = aSeedB.y * 6.2831853; vType = aSeedB.x; vGrow = grow;
+    vN = n; vToCam = toCam;
+#ifdef USE_FOG
+    vFogDepth = -mv.z;
+#endif
+}
+`;
+const NEAR_FRAG = /* glsl */ `
+${LIGHT}
+varying vec2 vUv;
+varying float vAlpha, vPx, vMelt, vShade, vRot, vType, vGrow;
+varying vec3 vN, vToCam;
+${FOG_F}
+float lineAA(float dist, float w) { float aa = fwidth(dist) + 1e-4; return 1.0 - smoothstep(w - aa, w + aa, dist); }
+void main() {
+    float r = length(vUv);
+    if (r > 1.0) discard;
+    // six-fold dendrite: fold into one arm, then the arm, its 60-degree side branches and a hex core
+    float ang = atan(vUv.y, vUv.x) + vRot;
+    const float SECT = 1.0471976;
+    float a6 = mod(ang + 0.5 * SECT, SECT) - 0.5 * SECT;
+    vec2 q = r * vec2(cos(a6), abs(sin(a6)));
+    float w = 0.055;
+    float arm = lineAA(q.y, w) * (1.0 - smoothstep(0.86, 0.95, q.x));
+    float n = mix(3.0, 6.0, vType);
+    float s = q.x - q.y * 0.57735;
+    float k = (floor(s * n) + 0.5) / n;
+    float db = abs(s - k) * 0.866;
+    float along = q.y / 0.866;
+    float br = lineAA(db, w * 0.8) * step(along, 0.42 * (1.0 - k)) * step(0.12, k) * step(k, 0.85);
+    br *= step(0.25, vType);                       // the least branched quarter are stellar plates
+    float hexR = r * cos(a6);
+    float core = 1.0 - smoothstep(0.16, 0.16 + fwidth(hexR) + 1e-4, hexR);
+    float crystal = max(max(arm, br), core * 0.85) + 0.18 * exp(-r * r * 6.0);
+    float disc = 0.5 * exp(-r * r * 4.5);
+    float shape = mix(disc, crystal, smoothstep(6.0, 16.0, vPx));
+    // melting: crystals round into a clear droplet with a bright point
+    float drop = 0.8 * exp(-r * r * 3.0) + 0.7 * exp(-dot(vUv - vec2(-0.25, 0.25), vUv - vec2(-0.25, 0.25)) * 30.0);
+    shape = mix(shape, drop, vMelt);
+
+    float alpha = shape * vAlpha * uOpacity * (1.0 + vMelt);
+    if (alpha < 0.003) discard;
+    vec3 lit = snowLight(vToCam, vN, vShade);
+    vec3 H = normalize(uSunDir + normalize(vToCam));
+    float sunUp = smoothstep(-0.05, 0.12, uSunDir.y);
+    // a glint is a point of sun-bright radiance: it survives the sub-pixel dimming that the body does not
+    float gl = pow(abs(dot(vN, H)), 140.0) * uGlint * 3.0 * sunUp * smoothstep(0.4, 0.9, shape) * min(vGrow * vGrow, 16.0);
+    vec3 col = lit + uSunColor * gl;
+    col = mix(col, uPointerColor * (0.9 + 0.6 * gl) + 0.1, vMelt);
+    col *= uIntensity;
+    gl_FragColor = vec4(col * alpha, alpha);
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>
+${FOG_APPLY}
+}
+`;
+const FAR_VERT = /* glsl */ `
+${COMMON}
+${LIGHT}
+attribute vec4 aSeedB;
+varying float vAlpha, vTight;
+varying vec3 vCol;
+${FOG_V}
+void main() {
+    float d, melt, shade, band;
+    vec3 origin = vec3(uFollow > 0.5 ? uCam.x : 0.0, 0.5 * uVolume.y, uFollow > 0.5 ? uCam.z : 0.0);
+    vec3 s = position + vec3(0.5, 0.0, 0.5);
+    vec3 p = snowPos(s, aSeedB.w, aSeedB, origin, uVolume, d, melt, shade, band);
+    vec3 toCam = uCam - p;
+    float dist = length(toCam);
+    float a = volumeFade(p) * band * smoothstep(0.26 * uTile, 0.44 * uTile, dist);
+    vec4 mv = modelViewMatrix * vec4(p / uVolume, 1.0);
+    // far flakes are out of focus: a bokeh disc that converges to a few pixels, energy conserved,
+    // times the share of the real snowfall each far speck stands for
+    float px = d * mix(1.0, 0.5, melt) * 1.3 * uViewH * projectionMatrix[1][1] * 0.5 / max(-mv.z, 1e-3);
+    float coc = (3.0 + 11.0 * smoothstep(6.0, 40.0, -mv.z)) * uViewH / 900.0;
+    float sz = max(px, coc);
+    // close by, the gain is held down so the fall stays calm; far off each speck carries its
+    // full share and the volume reads as a veil of snowfall
+    float gain = mix(min(uFarGain, 5.0), uFarGain, smoothstep(35.0, 110.0, dist));
+    a *= min(1.0, gain * (px * px) / (sz * sz));
+    a *= uOpacity;
+    // Tight sprite. The disc is exp(-3.5 r^2) - 0.03 and the fragment drops alpha < 0.003, so a speck
+    // is visible only out to r^2 = -ln(0.03 + 0.003 / a) / 3.5. A faint speck's bokeh disc is mostly
+    // below the cut: draw the point just that large (same pixels, same values), and when even its
+    // centre is below the cut, do not draw it.
+    float cut = 0.03 + 0.003 / max(a, 1e-6);
+    bool seen = cut < 1.0;
+    // (+0.5 px: a pixel centre sitting exactly on that radius must stay inside the point's square)
+    float ps = seen ? min(sz * sqrt(min(-log(cut) / 3.5, 1.0)) + 0.5, sz) : 0.0;
+    gl_PointSize = ps;
+    gl_Position = seen ? projectionMatrix * mv : vec4(2.0, 2.0, 2.0, 1.0);
+    vAlpha = a;
+    vTight = ps / sz;                       // point coords -> the full disc's coords
+    // a point has one colour: light it here, once, rather than in every pixel it covers
+    vCol = mix(snowLight(toCam, vec3(0.0, 1.0, 0.0), shade), uPointerColor + 0.15, melt * 0.8) * uIntensity;
+#ifdef USE_FOG
+    vFogDepth = -mv.z;
+#endif
+}
+`;
+const FAR_FRAG = /* glsl */ `
+varying float vAlpha, vTight;
+varying vec3 vCol;
+${FOG_F}
+void main() {
+    vec2 uv = (gl_PointCoord * 2.0 - 1.0) * vTight;
+    float r2 = dot(uv, uv);
+    if (r2 > 1.0) discard;
+    float shape = exp(-r2 * 3.5) - 0.03;
+    float alpha = shape * vAlpha;
+    if (alpha < 0.003) discard;
+    gl_FragColor = vec4(vCol * alpha, alpha);
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>
+${FOG_APPLY}
+}
+`;
+function makeMaterial(u, vertexShader, fragmentShader) {
+    return new THREE.ShaderMaterial({
+        // fog uniforms per material, the snow uniforms shared by reference across both layers
+        uniforms: Object.assign({}, THREE.UniformsUtils.clone(THREE.UniformsLib.fog), u),
+        vertexShader, fragmentShader,
+        transparent: true, depthWrite: false, fog: true,
+        blending: THREE.CustomBlending,
+        blendSrc: THREE.OneFactor, blendDst: THREE.OneMinusSrcAlphaFactor,
+        blendSrcAlpha: THREE.OneFactor, blendDstAlpha: THREE.OneMinusSrcAlphaFactor,
+        premultipliedAlpha: true,
+    });
+}
+// Bounds: every layer's `position` spans the unit volume box (x,z in -0.5..0.5, y in 0..1),
+// so Box3.expandByObject centres the gizmo on the volume. Shader seeds live in their own attributes.
+function build(u, c) {
+    const q = QUALITY[c.quality] ?? 1;
+    const dens = Math.max(0.05, c.density ?? 1);
+    const nNear = Math.min(NEAR_MAX, Math.round(NEAR_BASE * dens * q));
+    const nFar = Math.min(FAR_MAX, Math.round(FAR_BASE * dens * q));
+    const rnd = mulberry32((c.seed ?? 7) * 2654435761);
+    const nearGeo = new THREE.InstancedBufferGeometry();
+    // One triangle per crystal, circumscribing the unit disc the fragment keeps (it discards r > 1):
+    // the flake's whole trajectory is evaluated per vertex, so 3 vertices instead of 4 is a quarter less
+    // vertex work. `position` only spans the volume box for the gizmo's bounds.
+    nearGeo.setAttribute('position', new THREE.Float32BufferAttribute([-0.5, 0, -0.5, 0.5, 1, 0.5, 0, 0.5, 0], 3));
+    nearGeo.setAttribute('aCorner', new THREE.Float32BufferAttribute([-1.7320508, -1, 1.7320508, -1, 0, 2], 2));
+    const sa = new Float32Array(nNear * 4), sb = new Float32Array(nNear * 4);
+    for (let i = 0; i < nNear * 4; i++) {
+        sa[i] = rnd();
+        sb[i] = rnd();
+    }
+    nearGeo.setAttribute('aSeedA', new THREE.InstancedBufferAttribute(sa, 4));
+    nearGeo.setAttribute('aSeedB', new THREE.InstancedBufferAttribute(sb, 4));
+    nearGeo.instanceCount = nNear;
+    nearGeo.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0.5, 0), 0.87);
+    const farGeo = new THREE.BufferGeometry();
+    const fp = new Float32Array(nFar * 3), fb = new Float32Array(nFar * 4);
+    for (let i = 0; i < nFar; i++) {
+        fp[i * 3] = rnd() - 0.5;
+        fp[i * 3 + 1] = rnd();
+        fp[i * 3 + 2] = rnd() - 0.5;
+        fb[i * 4] = rnd();
+        fb[i * 4 + 1] = rnd();
+        fb[i * 4 + 2] = rnd();
+        fb[i * 4 + 3] = rnd();
+    }
+    farGeo.setAttribute('position', new THREE.BufferAttribute(fp, 3));
+    farGeo.setAttribute('aSeedB', new THREE.BufferAttribute(fb, 4));
+    farGeo.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0.5, 0), 0.87);
+    const nearMat = makeMaterial(u, NEAR_VERT, NEAR_FRAG);
+    const farMat = makeMaterial(u, FAR_VERT, FAR_FRAG);
+    const near = new THREE.Mesh(nearGeo, nearMat);
+    const far = new THREE.Points(farGeo, farMat);
+    near.frustumCulled = false;
+    far.frustumCulled = false;
+    near.renderOrder = 2;
+    far.renderOrder = 1;
+    // Snow must not swallow clicks meant for the scene behind it.
+    near.raycast = function () { };
+    far.raycast = function () { };
+    const object = new THREE.Group();
+    object.name = 'snow';
+    object.add(far, near);
+    const _s = new THREE.Vector3(), _c = new THREE.Vector3(), _q = new THREE.Quaternion(), _sun = new THREE.Vector3();
+    return {
+        object,
+        materials: [nearMat, farMat],
+        apply: function (cfg) { applyConfig(u, cfg); },
+        // dt clamped by the caller; sunWorld optional (read-only scene sun)
+        update: function (dt, camera, viewH, sunWorld) {
+            object.updateWorldMatrix(true, false);
+            object.getWorldScale(_s);
+            u.uVolume.value.set(Math.max(_s.x, 0.01), Math.max(_s.y, 0.01), Math.max(_s.z, 0.01));
+            const V = u.uVolume.value;
+            const T = Math.min(NEAR_TILE, Math.max(V.x, V.y, V.z));
+            u.uTile.value = T;
+            // each far speck stands for (near density / far density) real flakes
+            u.uFarGain.value = Math.min(20, Math.max(1, (nNear / (T * T * T)) / (nFar / (V.x * V.y * V.z))));
+            object.worldToLocal(_c.copy(camera.position));
+            u.uCam.value.set(_c.x * V.x, _c.y * V.y, _c.z * V.z);
+            // Crystals exist only inside the volume and within 0.48 tile of the eye. When the camera is
+            // farther than that from the volume's box none can be drawn, so the layer (4 vertices per
+            // crystal, all of them every frame) is not submitted at all.
+            const C = u.uCam.value, follow = u.uFollow.value > 0.5;
+            const ox = follow ? 0 : Math.max(Math.abs(C.x) - 0.5 * V.x, 0);
+            const oz = follow ? 0 : Math.max(Math.abs(C.z) - 0.5 * V.z, 0);
+            const oy = Math.max(-C.y, C.y - V.y, 0);
+            near.visible = ox * ox + oy * oy + oz * oz < 0.2304 * T * T;
+            if (viewH)
+                u.uViewH.value = viewH;
+            const sp = u.uSpeed.value, ws = u.uWindStrength.value;
+            u.uTime.value += dt * sp;
+            u.uFall.value += dt * sp;
+            u.uWind.value.addScaledVector(u.uWindDir.value, dt * sp * ws * WIND_MS);
+            u.uGustPhase.value += dt * sp * (0.3 + ws * WIND_MS) / 26;
+            u.uTurbPhase.value += dt * sp * 0.25;
+            if (sunWorld) {
+                object.getWorldQuaternion(_q).invert();
+                u.uSunDir.value.copy(_sun.copy(sunWorld).normalize().applyQuaternion(_q));
+            }
+        },
+        seek: function (t) {
+            u.uTime.value = t;
+            u.uFall.value = t;
+            u.uWind.value.copy(u.uWindDir.value).multiplyScalar(t * u.uWindStrength.value * WIND_MS);
+            u.uGustPhase.value = t * (0.3 + u.uWindStrength.value * WIND_MS) / 26;
+            u.uTurbPhase.value = t * 0.25;
+        },
+        dispose: function () { nearGeo.dispose(); farGeo.dispose(); nearMat.dispose(); farMat.dispose(); },
+    };
+}
+// Where the pointer plane passes (object-local unit coords; the plane faces the camera):
+// 4.5 m ahead of the eye when the camera is inside the volume, else through the volume centre's depth.
+const _pa = new THREE.Vector3(), _pd = new THREE.Vector3(), _pc = new THREE.Vector3();
+function pointerAnchor(object, camera, u, out) {
+    const V = u.uVolume.value, C = u.uCam.value;
+    const inside = Math.abs(C.x) < 0.5 * V.x && Math.abs(C.z) < 0.5 * V.z && C.y > 0 && C.y < V.y;
+    camera.getWorldDirection(_pd);
+    let dist = 4.5;
+    if (!inside) {
+        object.updateWorldMatrix(true, false);
+        object.localToWorld(_pc.set(0, 0.5, 0));
+        dist = Math.max(4.5, _pc.sub(camera.position).dot(_pd));
+    }
+    _pa.copy(camera.position).addScaledVector(_pd, dist);
+    return object.worldToLocal(out.copy(_pa));
+}
+// =============================================================================
+// Component
+// =============================================================================
+const DEFAULTS = DEFAULT_ENVIRONMENT_OBJECTS.snow;
+/** Knobs that rebuild the flakes: never live, they change once, on commit. */
+const STRUCTURAL = ['density', 'quality', 'seed'];
+/** Knobs a keyframe or pointer binding may drive per frame — exactly what applyConfig pushes. */
+const ANIMATABLE = new Set(ENVIRONMENT_OBJECTS_ANIMATABLE.snow.map((p) => p.value));
+/** The scene's sky fill is brighter than the flakes' own ambient term expects. */
+const SKY_FILL = 0.5;
+/**
+ * Snowfall with physical flakes: size-dependent terminal fall, helical flutter and tumbling dendrite crystals that glint in the sun, swept by travelling gusts and snow bands. The cursor is a gust, a shelter or a warm hand. Use for winter and weather scenes.
+ *
+ * The volume is the parent's transform: x / z span its scale, y rises from its origin to scale.y.
+ */
+const Snow = ({ config, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) => {
+    const rootRef = useRef(null);
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    const cfg = useMemo(() => withConfigDefaults(DEFAULTS, config), [config]);
+    // uniforms outlive rebuilds, so phases and keyframes survive a structural change
+    const uniforms = useMemo(() => createUniforms(), []);
+    const instance = useMemo(() => build(uniforms, cfg), [uniforms, cfg.density, cfg.quality, cfg.seed]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => () => instance.dispose(), [instance]);
+    useLayoutEffect(() => { applyConfig(uniforms, cfg); }, [uniforms, cfg]);
+    const push = useCallback((merged) => { applyConfig(uniforms, merged); }, [uniforms]);
+    useConfigDriver({ rootRef, id, family: 'environment', base: cfg, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+    const pointer = usePointerField();
+    // the scene's sun, read-only: the same one the clouds, the water and the key light use
+    const sun = useCloudSun();
+    const anchor = useMemo(() => new THREE.Vector3(), []);
+    const buffer = useMemo(() => new THREE.Vector2(), []);
+    useFrame((state, delta) => {
+        const dt = Math.min(delta, 0.1);
+        const s = sun.update();
+        uniforms.uSunColor.value.copy(s.color);
+        uniforms.uSkyAmbient.value.copy(s.skyAmbient).multiplyScalar(SKY_FILL);
+        state.gl.getDrawingBufferSize(buffer);
+        instance.update(dt, state.camera, buffer.y, s.direction);
+        stepPointerField(uniforms, pointer, state.camera, instance.object, 1, dt, pointerAnchor(instance.object, state.camera, uniforms, anchor));
+    });
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default Snow;

package/dist/components/environment/Thunderstorm.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { AnimationOptions, MouseMoveDomain, ThunderstormEnvironmentConfig } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export interface ThunderstormProps extends ObjectReadyProps {
+    config: ThunderstormEnvironmentConfig;
+    /** Scene object id: the live-edit handle is found by it. */
+    id?: string;
+    /** Keyframes on the config knobs (animations.environment.animations). */
+    keyframes?: AnimationOptions[];
+    /** Pointer bindings on the config knobs (mouseMove.environment). */
+    mouseMove?: MouseMoveDomain;
+}
+/**
+ * A thunderstorm without the rain (rain is its own object): dark storm curtains drifting on the wind, and lightning arriving as a Poisson process of multi-stroke flashes that light the curtains and the whole scene. The cursor calls a strike or clears the murk. Use for storm, noir and dramatic scenes.
+ *
+ * The volume is the parent's transform: x / z span its scale, y rises from its origin to scale.y.
+ */
+declare const Thunderstorm: React.FC<ThunderstormProps>;
+export default Thunderstorm;
+//# sourceMappingURL=Thunderstorm.d.ts.map

package/dist/components/environment/Thunderstorm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Thunderstorm.d.ts","sourceRoot":"","sources":["../../../src/components/environment/Thunderstorm.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAM9G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AA8pBhE,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACvD,MAAM,EAAE,6BAA6B,CAAC;IACtC,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,oEAAoE;IACpE,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;GAIG;AACH,QAAA,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAmC7C,CAAC;AAEF,eAAe,YAAY,CAAC"}