@3driseai/3drise-viewer 0.1.16 → 0.1.18

package/dist/components/effects/MurmurationEffect.js

@@ -0,0 +1,539 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { applyGenerativeAnimations } from '../../utils/handleGenerativeEffectsAnimations.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+/**
+ * A starling murmuration: thousands of boids with topological neighbours swirl around a drifting roost, folding into dense, wave-like sheets. Use for dusk, wildlife, flocking, atmospheric scenes.
+ *
+ * Reynolds boids on the 7 nearest neighbours (spatial hash): separation + alignment + cohesion, Lissajous roost, |v| clamped, bank = atan(a⊥/g)
+ */
+// ---------------------------------------------------------------------------
+// Reynolds boids with a topological neighbourhood (Ballerini et al. showed
+// starlings interact with a fixed number of nearest neighbours, ~7, not with
+// everything inside a fixed radius). Each bird steers by
+//   a = wSep * sum (p_i - p_j) (1 - d^2/dSep^2)/d  +  wAli * (mean v_j - v_i)
+//       + wCoh * (mean p_j - p_i) + roost + flock centring + boundary,
+// with |a| capped (a real bird's turn radius) and |v| held near cruise speed.
+// The nearest seven are found with a uniform spatial hash, so the cost is O(N).
+// A roost point drifts along a Lissajous path and the flock orbits it, which
+// keeps the shape turning over; because alignment is topological, a turn
+// started by a few birds propagates as an agitation wave, and the sheets fold
+// on themselves - the dense, dark folds of a real murmuration. Banking is
+// taken from the lateral acceleration, so birds flash brighter and darker as
+// the wave passes, exactly as a real flock does.
+// ---------------------------------------------------------------------------
+const vert = /* glsl */ `
+  // position holds the chevron template: (along, across, wing-tip flag)
+  attribute vec3 aPos;
+  attribute vec4 aVel;       // velocity xyz, bank angle w
+  attribute float aPhase;
+  uniform float uTime;
+  uniform float uBirdSize;
+  uniform float uBound;
+  uniform float uViewH;
+  uniform float uLead;
+  uniform float uOpacity;
+  varying float vShade;
+  varying float vAlpha;
+  varying float vEdge;
+
+  void main(){
+    vec3 p = aPos + aVel.xyz * uLead;
+    vec3 f = aVel.xyz;
+    float sp = length(f);
+    f = sp > 1e-5 ? f / sp : vec3(0.0, 0.0, 1.0);
+    vec3 side = cross(f, vec3(0.0, 1.0, 0.0));
+    float sl = length(side);
+    side = sl > 1e-4 ? side / sl : vec3(1.0, 0.0, 0.0);
+    vec3 up = cross(side, f);
+    float b = aVel.w;
+    vec3 sb = side * cos(b) + up * sin(b);
+    vec3 ub = up * cos(b) - side * sin(b);
+
+    vec4 mvC = modelViewMatrix * vec4(p, 1.0);
+    float pxPerUnit = projectionMatrix[1][1] * uViewH / max(-mvC.z, 0.05);
+    float L = uBirdSize * 0.075 * uBound;
+    // never let a bird fall under ~2 px: grow it and give back the energy in alpha
+    float grow = max(1.0, 2.2 / max(L * pxPerUnit, 1e-4));
+    L *= grow;
+    vAlpha = uOpacity / grow;
+
+    // wings beat with a per-bird phase, in bursts between short glides
+    float beat = uTime * 7.4 + aPhase * 30.0;
+    float glide = smoothstep(0.25, 0.6, sin(uTime * 0.5 + aPhase * 12.0) * 0.5 + 0.6);
+    float flap = sin(beat) * 0.42 * glide * abs(position.y) * position.z;
+    vec3 world = p + f * (position.x * L) + sb * (position.y * L) + ub * (flap * L);
+
+    // wing plane catches the light from above: banking birds flash, as in a real flock
+    vec3 lightDir = normalize(vec3(0.25, 1.0, 0.4));
+    vShade = 0.42 + 0.58 * pow(abs(dot(ub, lightDir)), 0.7);
+    vEdge = position.z;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(world, 1.0);
+  }
+`;
+const frag = /* glsl */ `
+  uniform vec3 uColor;
+  uniform float uIntensity;
+  varying float vShade;
+  varying float vAlpha;
+  varying float vEdge;
+  void main(){
+    float a = vAlpha * mix(0.85, 1.0, vEdge);
+    if (a < 0.004) discard;
+    vec3 col = uColor * vShade * uIntensity;
+    // premultiplied: birds are small opaque silhouettes, density does the rest
+    gl_FragColor = vec4(col * a, a);
+  }
+`;
+function mulberry32(seed) {
+    return () => {
+        seed |= 0;
+        seed = (seed + 0x6d2b79f5) | 0;
+        let r = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+        r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+        return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function createUniforms() {
+    return {
+        uTime: { value: 0 },
+        uSpeed: { value: 1 },
+        uIntensity: { value: 1 },
+        uOpacity: { value: 0.92 },
+        uColor: { value: new THREE.Color() },
+        uFlockRadius: { value: 2.6 },
+        uCohesion: { value: 1 },
+        uAlignment: { value: 1 },
+        uSeparation: { value: 1 },
+        uBirdSize: { value: 1 },
+        uBound: { value: 1 },
+        uViewH: { value: 800 },
+        uLead: { value: 0 },
+    };
+}
+function applyConfig(u, c, bound, env) {
+    u.uSpeed.value = c.speed;
+    u.uIntensity.value = c.intensity;
+    u.uOpacity.value = c.opacity;
+    u.uColor.value.set(c.color);
+    u.uFlockRadius.value = c.flockRadius;
+    u.uCohesion.value = c.cohesion;
+    u.uAlignment.value = c.alignment;
+    u.uSeparation.value = c.separation;
+    u.uBirdSize.value = c.birdSize;
+    u.uBound.value = bound;
+}
+function build(u, c, bound, env) {
+    const n = Math.round(Math.min(Math.max(c.count, 100), 4000));
+    const hasHost = !!(env && env.hasHost);
+    const b = bound;
+    const K = 7; // topological neighbourhood size
+    const SIM_DT = 1 / 25; // fixed sim rate; the shader extrapolates the rest of the frame
+    const TABLE = 4096; // spatial-hash buckets (power of two)
+    const MASK = TABLE - 1;
+    const rand = mulberry32(5501);
+    const pos = new Float32Array(n * 3);
+    const vel = new Float32Array(n * 4); // vx, vy, vz, bank
+    const phase = new Float32Array(n);
+    const nb = new Int32Array(n * K);
+    const nbCount = new Int32Array(n);
+    const bucketCount = new Int32Array(TABLE + 1);
+    const bucketStart = new Int32Array(TABLE + 1);
+    const cursor = new Int32Array(TABLE);
+    const hashOf = new Int32Array(n);
+    const sorted = new Int32Array(n);
+    const seen = new Int32Array(27);
+    const dBest = new Float32Array(K);
+    const cy = 0.95 * b; // centre of the airspace, above the host
+    for (let i = 0; i < n; i++) {
+        // start in a loose ball, already moving roughly around the roost
+        const uz = rand() * 2 - 1, ph = rand() * Math.PI * 2;
+        const rr = Math.cbrt(rand()) * c.flockRadius * 0.5 * b;
+        const sxy = Math.sqrt(1 - uz * uz);
+        const x = rr * sxy * Math.cos(ph), y = rr * uz * 0.5, z = rr * sxy * Math.sin(ph);
+        pos[i * 3] = x;
+        pos[i * 3 + 1] = y + cy;
+        pos[i * 3 + 2] = z;
+        const sp = 0.8 * b;
+        vel[i * 4] = -z * 0.6 + (rand() - 0.5) * sp;
+        vel[i * 4 + 1] = (rand() - 0.5) * sp * 0.3;
+        vel[i * 4 + 2] = x * 0.6 + (rand() - 0.5) * sp;
+        const m = Math.hypot(vel[i * 4], vel[i * 4 + 1], vel[i * 4 + 2]) + 1e-6;
+        vel[i * 4] *= sp / m;
+        vel[i * 4 + 1] *= sp / m;
+        vel[i * 4 + 2] *= sp / m;
+        vel[i * 4 + 3] = 0;
+        phase[i] = rand();
+    }
+    // one chevron: two triangles, nose forward, wing tips swept back
+    const local = new Float32Array([
+        0.55, 0, 0, -0.3, -0.5, 1, -0.12, 0, 0,
+        0.55, 0, 0, -0.12, 0, 0, -0.3, 0.5, 1,
+    ]);
+    const geo = new THREE.InstancedBufferGeometry();
+    geo.setAttribute('position', new THREE.BufferAttribute(local, 3));
+    const posAttr = new THREE.InstancedBufferAttribute(pos, 3);
+    const velAttr = new THREE.InstancedBufferAttribute(vel, 4);
+    posAttr.setUsage(THREE.DynamicDrawUsage);
+    velAttr.setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute('aPos', posAttr);
+    geo.setAttribute('aVel', velAttr);
+    geo.setAttribute('aPhase', new THREE.InstancedBufferAttribute(phase, 1));
+    geo.instanceCount = n;
+    const mat = new THREE.ShaderMaterial({
+        vertexShader: vert, fragmentShader: frag, uniforms: u,
+        transparent: true, depthWrite: false, blending: THREE.NormalBlending,
+        premultipliedAlpha: true, side: THREE.DoubleSide,
+    });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.frustumCulled = false;
+    const vp = new THREE.Vector2();
+    mesh.onBeforeRender = (renderer) => {
+        renderer.getDrawingBufferSize(vp);
+        u.uViewH.value = vp.y * 0.5;
+    };
+    const group = new THREE.Group();
+    group.add(mesh);
+    let simTime = 0;
+    let acc = 0;
+    let steps = 0;
+    let cell = 0.12 * Math.max(c.flockRadius, 1) * b; // hash cell, self-tuned below
+    function hashCell(ix, iy, iz) {
+        return ((ix * 73856093) ^ (iy * 19349663) ^ (iz * 83492791)) & MASK;
+    }
+    function buildGrid() {
+        for (let h = 0; h <= TABLE; h++)
+            bucketCount[h] = 0;
+        const inv = 1 / cell;
+        for (let i = 0; i < n; i++) {
+            const h = hashCell(Math.floor(pos[i * 3] * inv), Math.floor(pos[i * 3 + 1] * inv), Math.floor(pos[i * 3 + 2] * inv));
+            hashOf[i] = h;
+            bucketCount[h]++;
+        }
+        let s = 0;
+        for (let h = 0; h < TABLE; h++) {
+            bucketStart[h] = s;
+            cursor[h] = s;
+            s += bucketCount[h];
+        }
+        bucketStart[TABLE] = s;
+        for (let i = 0; i < n; i++) {
+            sorted[cursor[hashOf[i]]++] = i;
+        }
+    }
+    /** the K nearest neighbours of every bird, from the 27 cells around it.
+     *  The cell size tunes itself so each bird examines ~26 candidates: the
+     *  flock's density changes by an order of magnitude as it folds. */
+    function findNeighbours() {
+        let cand = 0;
+        let got = 0;
+        const inv = 1 / cell;
+        const rMax = cell * 2;
+        const r2Max = rMax * rMax;
+        for (let i = 0; i < n; i++) {
+            const i3 = i * 3;
+            const x = pos[i3], y = pos[i3 + 1], z = pos[i3 + 2];
+            const cx = Math.floor(x * inv), cyi = Math.floor(y * inv), cz = Math.floor(z * inv);
+            let found = 0;
+            let worst = r2Max;
+            let nSeen = 0;
+            let budget = 96; // hard cap, so a collapsed flock cannot get slow
+            const base = i * K;
+            for (let dx = -1; dx <= 1 && budget > 0; dx++) {
+                for (let dy = -1; dy <= 1 && budget > 0; dy++) {
+                    for (let dz = -1; dz <= 1 && budget > 0; dz++) {
+                        const h = hashCell(cx + dx, cyi + dy, cz + dz);
+                        let dup = 0;
+                        for (let q = 0; q < nSeen; q++)
+                            if (seen[q] === h)
+                                dup = 1;
+                        if (dup === 1)
+                            continue;
+                        seen[nSeen++] = h;
+                        const end = bucketStart[h] + bucketCount[h];
+                        for (let s = bucketStart[h]; s < end; s++) {
+                            if (budget <= 0)
+                                break;
+                            budget--;
+                            const j = sorted[s];
+                            if (j === i)
+                                continue;
+                            const j3 = j * 3;
+                            const ax = pos[j3] - x, ay = pos[j3 + 1] - y, az = pos[j3 + 2] - z;
+                            cand++;
+                            const d2 = ax * ax + ay * ay + az * az;
+                            if (d2 >= worst && found >= K)
+                                continue;
+                            if (d2 >= r2Max)
+                                continue;
+                            // insertion sort into the top-K list
+                            let k = found < K ? found : K - 1;
+                            while (k > 0 && dBest[k - 1] > d2) {
+                                dBest[k] = dBest[k - 1];
+                                nb[base + k] = nb[base + k - 1];
+                                k--;
+                            }
+                            dBest[k] = d2;
+                            nb[base + k] = j;
+                            if (found < K)
+                                found++;
+                            worst = dBest[found - 1];
+                        }
+                    }
+                }
+            }
+            nbCount[i] = found;
+            got += found;
+        }
+        const R = Math.max(u.uFlockRadius.value, 1) * b;
+        let f = Math.cbrt(16 / Math.max(cand / n, 1));
+        if (got < n * 6.4)
+            f = Math.max(f, 1.12);
+        cell = Math.min(Math.max(cell * Math.min(Math.max(f, 0.88), 1.12), 0.02 * R), 0.5 * R);
+    }
+    const roost = new Float32Array(3);
+    const hawk = new Float32Array(3);
+    // A raptor cruising a long, slow path through the airspace. Birds near it
+    // pull away; because alignment is topological, that escape spreads outward
+    // as an agitation wave and tears the dark folds a real murmuration shows.
+    function moveHawk(t) {
+        const R = Math.max(u.uFlockRadius.value, 1) * b;
+        hawk[0] = 1.35 * R * Math.sin(0.038 * t + 0.4);
+        hawk[1] = cy + 0.5 * R * Math.sin(0.107 * t + 1.9);
+        hawk[2] = 1.35 * R * Math.sin(0.0271 * t * 2 + 2.7) * Math.cos(0.019 * t);
+    }
+    function moveRoost(t) {
+        // Lissajous drift: the roost never repeats its path exactly
+        const R = Math.max(u.uFlockRadius.value, 1) * b;
+        roost[0] = 0.22 * R * Math.sin(0.085 * t) + 0.1 * R * Math.sin(0.211 * t + 1.1);
+        roost[1] = cy + 0.12 * R * Math.sin(0.061 * t + 2.3);
+        roost[2] = 0.22 * R * Math.cos(0.073 * t + 0.7) + 0.1 * R * Math.sin(0.187 * t + 3.4);
+    }
+    function step(h) {
+        const R = Math.max(u.uFlockRadius.value, 1) * b;
+        const cruise = 0.32 * R;
+        const maxAcc = 3.2 * cruise;
+        const wSep = 3.6 * Math.max(u.uSeparation.value, 0) * cruise;
+        const wAli = 3.6 * Math.max(u.uAlignment.value, 0);
+        const wCoh = 2.4 * Math.max(u.uCohesion.value, 0);
+        const dSep = 0.055 * R;
+        const dSep2 = dSep * dSep;
+        const hostR = hasHost ? 1.3 * b : 0;
+        // flock centring: every bird keeps a weak bearing on the whole flock, the
+        // term that keeps a murmuration one body even after a raptor splits it
+        let mcx = 0, mcy = 0, mcz = 0;
+        for (let i = 0; i < n; i++) {
+            mcx += pos[i * 3];
+            mcy += pos[i * 3 + 1];
+            mcz += pos[i * 3 + 2];
+        }
+        mcx /= n;
+        mcy /= n;
+        mcz /= n;
+        moveRoost(simTime);
+        moveHawk(simTime);
+        const hx = hawk[0], hy = hawk[1], hz = hawk[2];
+        const rEsc = 0.42 * R;
+        const rEsc2 = rEsc * rEsc;
+        const rx = roost[0], ry = roost[1], rz = roost[2];
+        // the swirl axis leans and turns slowly, so the flock is never a flat disc
+        const sA = 0.95 * Math.sin(0.043 * simTime), sB = 0.95 * Math.cos(0.031 * simTime + 1.2);
+        const sN = 1 / Math.sqrt(1 + sA * sA + sB * sB);
+        const spinX = sA * sN, spinY = sN, spinZ = sB * sN;
+        for (let i = 0; i < n; i++) {
+            const i3 = i * 3, i4 = i * 4;
+            const x = pos[i3], y = pos[i3 + 1], z = pos[i3 + 2];
+            let vx = vel[i4], vy = vel[i4 + 1], vz = vel[i4 + 2];
+            let ax = 0, ay = 0, az = 0;
+            const cnt = nbCount[i];
+            if (cnt > 0) {
+                let mx = 0, my = 0, mz = 0, ux = 0, uy = 0, uz = 0;
+                const base = i * K;
+                for (let k = 0; k < cnt; k++) {
+                    const j = nb[base + k];
+                    const j3 = j * 3, j4 = j * 4;
+                    const dx = pos[j3] - x, dy = pos[j3 + 1] - y, dz = pos[j3 + 2] - z;
+                    mx += dx;
+                    my += dy;
+                    mz += dz;
+                    ux += vel[j4];
+                    uy += vel[j4 + 1];
+                    uz += vel[j4 + 2];
+                    const d2 = dx * dx + dy * dy + dz * dz + 1e-6;
+                    if (d2 < dSep2) {
+                        // soft-core repulsion, strongest right up against a neighbour
+                        const f = wSep * (1 - d2 / dSep2) / Math.sqrt(d2);
+                        ax -= dx * f;
+                        ay -= dy * f;
+                        az -= dz * f;
+                    }
+                }
+                const inv = 1 / cnt;
+                ax += (mx * inv) * wCoh;
+                ay += (my * inv) * wCoh;
+                az += (mz * inv) * wCoh;
+                ax += (ux * inv - vx) * wAli;
+                ay += (uy * inv - vy) * wAli;
+                az += (uz * inv - vz) * wAli;
+            }
+            // roost: a soft spring in, plus a swirl about a slowly tilting axis,
+            // which is why a murmuration keeps circling and folding over its roost
+            const tx = rx - x, ty = ry - y, tz = rz - z;
+            const td = Math.sqrt(tx * tx + ty * ty + tz * tz) + 1e-5;
+            // a loose leash: no roost force at all near it, so the flock is free
+            // to organise itself into sheets instead of filling the airspace
+            const pull = 2.2 * cruise * Math.min(Math.max(td / (0.75 * R) - 0.25, 0), 1.2);
+            ax += (tx / td) * pull;
+            ay += (ty / td) * pull;
+            az += (tz / td) * pull;
+            const swirl = 0.45 * cruise / Math.max(td, 0.35 * R);
+            ax += (spinY * -tz - spinZ * -ty) * swirl;
+            ay += (spinZ * -tx - spinX * -tz) * swirl;
+            az += (spinX * -ty - spinY * -tx) * swirl;
+            // soft, flattened boundary of the airspace
+            const ey = (y - cy) / 0.78;
+            const e = Math.sqrt(x * x + ey * ey + z * z);
+            if (e > R) {
+                const f = -(e - R) * 4 * cruise / (R * e);
+                ax += x * f;
+                ay += ey * f * 0.78;
+                az += z * f;
+            }
+            if (y < -0.55 * b)
+                ay += (-0.55 * b - y) * 6 * cruise;
+            // never fly through the host
+            if (hostR > 0) {
+                const d = Math.sqrt(x * x + y * y + z * z) + 1e-5;
+                if (d < hostR) {
+                    const f = (hostR - d) * 6 * cruise / (hostR * d);
+                    ax += x * f;
+                    ay += y * f;
+                    az += z * f;
+                }
+            }
+            // weak bearing on the flock centre
+            const fx0 = mcx - x, fy0 = mcy - y, fz0 = mcz - z;
+            const fd = Math.sqrt(fx0 * fx0 + fy0 * fy0 + fz0 * fz0) + 1e-5;
+            const fc = 0.75 * cruise * Math.min(fd / (0.5 * R), 1) / fd;
+            ax += fx0 * fc;
+            ay += fy0 * fc;
+            az += fz0 * fc;
+            // escape from the raptor: a strong, short-range push away
+            const gx = x - hx, gy = y - hy, gz = z - hz;
+            const g2 = gx * gx + gy * gy + gz * gz;
+            if (g2 < rEsc2) {
+                const gd = Math.sqrt(g2) + 1e-4;
+                const f = 2.8 * cruise * (1 - gd / rEsc) / gd;
+                ax += gx * f;
+                ay += gy * f * 0.8;
+                az += gz * f;
+            }
+            // cap the turn a bird can pull
+            const am = Math.sqrt(ax * ax + ay * ay + az * az);
+            if (am > maxAcc) {
+                const f = maxAcc / am;
+                ax *= f;
+                ay *= f;
+                az *= f;
+            }
+            vx += ax * h;
+            vy += ay * h;
+            vz += az * h;
+            // hold the airspeed near cruise (birds do not hover or dive away)
+            let sp = Math.sqrt(vx * vx + vy * vy + vz * vz) + 1e-6;
+            const target = sp + (cruise - sp) * Math.min(h * 1.5, 1);
+            const f2 = Math.min(Math.max(target, 0.55 * cruise), 1.5 * cruise) / sp;
+            vx *= f2;
+            vy *= f2;
+            vz *= f2;
+            sp = sp * f2;
+            vel[i4] = vx;
+            vel[i4 + 1] = vy;
+            vel[i4 + 2] = vz;
+            pos[i3] = x + vx * h;
+            pos[i3 + 1] = y + vy * h;
+            pos[i3 + 2] = z + vz * h;
+            // bank: a coordinated turn tilts the wings by atan(lateral accel / g)
+            const fx = vx / sp, fy = vy / sp, fz = vz / sp;
+            let sx = fz, sy = 0, sz = -fx; // cross(f, up)
+            const sl = Math.sqrt(sx * sx + sz * sz) + 1e-5;
+            sx /= sl;
+            sz /= sl;
+            const lat = ax * sx + az * sz;
+            const bankT = Math.atan(lat / (1.6 * cruise));
+            vel[i4 + 3] += (bankT - vel[i4 + 3]) * Math.min(h * 4, 1);
+        }
+    }
+    buildGrid();
+    findNeighbours();
+    return {
+        object: group,
+        materials: [mat],
+        apply(c2) { },
+        update(dt, camera) {
+            const h = Math.min(Math.max(dt, 0), 0.1) * Math.max(u.uSpeed.value, 0);
+            u.uTime.value += h;
+            acc += h;
+            let guard = 0;
+            while (acc >= SIM_DT && guard < 3) {
+                // a bird's nearest seven change slowly: refresh them every 3rd step
+                if (steps % 3 === 0) {
+                    buildGrid();
+                    findNeighbours();
+                }
+                step(SIM_DT);
+                simTime += SIM_DT;
+                acc -= SIM_DT;
+                steps++;
+                guard++;
+            }
+            if (guard >= 3)
+                acc = 0;
+            // the shader carries the birds forward over the part of the frame not stepped
+            u.uLead.value = acc;
+            posAttr.needsUpdate = true;
+            velAttr.needsUpdate = true;
+        },
+        dispose() { geo.dispose(); mat.dispose(); },
+    };
+}
+/** Defaults for every knob, so an older saved config still renders. */
+const DEFAULTS = {
+    intensity: 1,
+    speed: 1,
+    color: '#b9c8dc',
+    opacity: 0.92,
+    count: 2200,
+    flockRadius: 2.6,
+    cohesion: 1,
+    alignment: 1,
+    separation: 1,
+    birdSize: 1,
+};
+const MurmurationEffect = ({ boundingRadius, config, animations, hasHost = false, onObjectReady, onObjectDispose }) => {
+    const rootRef = useRef(null);
+    const animCache = useRef({});
+    useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+    // a standalone effect gets boundingRadius 1
+    const b = boundingRadius > 0 ? boundingRadius : 1;
+    const cfg = useMemo(() => ({ ...DEFAULTS, ...config }), [config]);
+    const env = useMemo(() => ({ hasHost: hasHost }), [hasHost]);
+    // uniforms outlive the objects, so keyframe animations survive a rebuild
+    const uniforms = useMemo(() => createUniforms(), []);
+    // rebuilt only when the host size or a structural knob changes
+    const instance = useMemo(() => build(uniforms, { ...DEFAULTS, ...config }, b, env), [uniforms, b, env, cfg.count]);
+    useEffect(() => () => instance.dispose(), [instance]);
+    useLayoutEffect(() => {
+        applyConfig(uniforms, cfg, b, env);
+        instance.apply(cfg);
+    }, [instance, uniforms, cfg, b, env]);
+    useFrame((state, delta) => {
+        instance.update(Math.min(delta, 0.1), state.camera);
+        if (animations?.length)
+            applyGenerativeAnimations(instance.materials, animations, animCache.current, Date.now(), false);
+    });
+    return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
+};
+export default MurmurationEffect;

package/dist/components/effects/PlanetaryRingsEffect.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { AnimationOptions, PlanetaryRingsConfig } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export interface PlanetaryRingsEffectProps extends ObjectReadyProps {
+    boundingRadius: number;
+    config: PlanetaryRingsConfig;
+    animations?: AnimationOptions[];
+    /** True when the effect is attached to an object, so it can react to the host. */
+    hasHost?: boolean;
+}
+declare const PlanetaryRingsEffect: React.FC<PlanetaryRingsEffectProps>;
+export default PlanetaryRingsEffect;
+//# sourceMappingURL=PlanetaryRingsEffect.d.ts.map

package/dist/components/effects/PlanetaryRingsEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlanetaryRingsEffect.d.ts","sourceRoot":"","sources":["../../../src/components/effects/PlanetaryRingsEffect.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsD,MAAM,OAAO,CAAC;AAG3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAqbD,QAAA,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CA+B7D,CAAC;AAEF,eAAe,oBAAoB,CAAC"}