three-base 2.0.137 → 2.0.145

package/WaterFlow/GPUFluidSimulation.js

@@ -0,0 +1,785 @@
+import * as THREE from 'three';
+import { SPHField } from './SPHField';
+const quadVertex = /* glsl */ `
+  out vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = vec4(position, 1.0);
+  }
+`;
+function createStateTarget(size) {
+    const target = new THREE.WebGLRenderTarget(size, size, {
+        count: 2,
+        format: THREE.RGBAFormat,
+        type: THREE.FloatType,
+        minFilter: THREE.NearestFilter,
+        magFilter: THREE.NearestFilter,
+        wrapS: THREE.ClampToEdgeWrapping,
+        wrapT: THREE.ClampToEdgeWrapping,
+        depthBuffer: false,
+        stencilBuffer: false,
+    });
+    target.textures[0].name = 'FluidPositionLife';
+    target.textures[1].name = 'FluidVelocityImpact';
+    return target;
+}
+function makeDataTexture(data, size) {
+    const texture = new THREE.DataTexture(data, size, size, THREE.RGBAFormat, THREE.FloatType);
+    texture.minFilter = THREE.NearestFilter;
+    texture.magFilter = THREE.NearestFilter;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.needsUpdate = true;
+    return texture;
+}
+/**
+ * GPUFluidSimulation —— GPGPU 粒子流体模拟（ping-pong 状态纹理 + 网格辅助 SPH）。
+ *
+ * ⚠️ 不支持时（非 WebGL2 或缺 EXT_color_buffer_float）构造器**提前 return**，
+ *    下列标记 `| null` 的资源字段在空壳实例上不会被赋值；所有读它们的入口
+ *    （reset / update / 各 setXxx / dispose / positionTexture）都先过 `if (!this.supported) return;` 守卫。
+ */
+export class GPUFluidSimulation {
+    renderer;
+    size;
+    count;
+    nozzle;
+    /** x=minX, y=maxX, z=zHalfExtent, w=waterY（与 shader 的 uBasin 一致）。 */
+    basin;
+    jetDirection;
+    /** 1=开启粒子与 basin/地面碰撞回弹，0=关闭（喂给 shader 的 uCollision，故为 0/1）。 */
+    collision;
+    supported;
+    /** ping-pong 状态目标；update() 每帧整体交换 read/write，故非 readonly。 */
+    read;
+    /** ping-pong 状态目标；update() 每帧整体交换 read/write，故非 readonly。 */
+    write;
+    sphField;
+    sphDomainMinimum;
+    sphDomainMaximum;
+    scene;
+    camera;
+    /** 材质在 reset/update 间切换（initMaterial ↔ updateMaterial），故类型含 null。 */
+    mesh;
+    initialPosition;
+    initialVelocity;
+    initMaterial;
+    updateMaterial;
+    constructor(renderer, { size = 200, nozzle = new THREE.Vector3(0.58, 1.55, 0), basin = new THREE.Vector4(0.25, 3.85, 0.82, 0.2), speed = 2.4, aperture = 0.78, jetDirection = new THREE.Vector3(1, 0, 0), collision = true, } = {}) {
+        this.renderer = renderer;
+        this.size = size;
+        this.count = size * size;
+        this.nozzle = nozzle.clone();
+        this.basin = basin.clone();
+        this.jetDirection = jetDirection.clone().normalize();
+        this.collision = collision ? 1 : 0;
+        this.supported = renderer.capabilities.isWebGL2 && renderer.extensions.has('EXT_color_buffer_float');
+        if (!this.supported)
+            return;
+        this.read = createStateTarget(size);
+        this.write = createStateTarget(size);
+        this.sphField = new SPHField(renderer, size, { mobile: size <= 128 });
+        this.sphDomainMinimum = new THREE.Vector3();
+        this.sphDomainMaximum = new THREE.Vector3();
+        this.scene = new THREE.Scene();
+        this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+        this.mesh = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), null);
+        this.mesh.frustumCulled = false;
+        this.scene.add(this.mesh);
+        const positionData = new Float32Array(this.count * 4);
+        const velocityData = new Float32Array(this.count * 4);
+        for (let i = 0; i < this.count; i++) {
+            const seed = this.hash(i + 1);
+            positionData[i * 4] = this.nozzle.x;
+            positionData[i * 4 + 1] = this.nozzle.y;
+            positionData[i * 4 + 2] = this.nozzle.z;
+            positionData[i * 4 + 3] = -seed * 2.35;
+            velocityData[i * 4] = 0;
+            velocityData[i * 4 + 1] = 0;
+            velocityData[i * 4 + 2] = 0;
+            velocityData[i * 4 + 3] = 0;
+        }
+        this.initialPosition = makeDataTexture(positionData, size);
+        this.initialVelocity = makeDataTexture(velocityData, size);
+        this.initMaterial = new THREE.ShaderMaterial({
+            glslVersion: THREE.GLSL3,
+            uniforms: {
+                uInitialPosition: { value: this.initialPosition },
+                uInitialVelocity: { value: this.initialVelocity },
+            },
+            vertexShader: quadVertex,
+            fragmentShader: /* glsl */ `
+        precision highp float;
+        uniform sampler2D uInitialPosition;
+        uniform sampler2D uInitialVelocity;
+        in vec2 vUv;
+        layout(location = 0) out vec4 outPosition;
+        layout(location = 1) out vec4 outVelocity;
+        void main() {
+          outPosition = texture(uInitialPosition, vUv);
+          outVelocity = texture(uInitialVelocity, vUv);
+        }
+      `,
+            depthTest: false,
+            depthWrite: false,
+            toneMapped: false,
+        });
+        this.updateMaterial = new THREE.ShaderMaterial({
+            glslVersion: THREE.GLSL3,
+            uniforms: {
+                uPosition: { value: null },
+                uVelocity: { value: null },
+                uDelta: { value: 1 / 90 },
+                uTime: { value: 0 },
+                uSpeed: { value: speed },
+                uAperture: { value: aperture },
+                uFillRatio: { value: 1 },
+                uEmission: { value: 1 },
+                uReservoirActive: { value: 0 },
+                uReservoirFill: { value: 0 },
+                uNozzle: { value: this.nozzle },
+                uBasin: { value: this.basin },
+                uBasinCenterZ: { value: 0 },
+                uWallTop: { value: this.basin.w + 0.22 },
+                uFloorY: { value: -0.17 },
+                uContainerFloorY: { value: 0.06 },
+                uContainerAcceleration: { value: new THREE.Vector2() },
+                uRimWidth: { value: 0.055 },
+                uTurbulence: { value: 0.36 },
+                uSPHDensity: { value: this.sphField.densityTexture },
+                uSPHMomentum: { value: this.sphField.momentumTexture },
+                uSPHDomainMin: { value: this.sphField.domainMin },
+                uSPHDomainMax: { value: this.sphField.domainMax },
+                uSPHGrid: { value: this.sphField.grid },
+                uSPHAtlasTiles: { value: this.sphField.tiles },
+                uSPHCell: { value: this.sphField.cellSize },
+                uSPHKernel: { value: this.sphField.kernelRadius },
+                uSPHRestDensity: { value: size <= 128 ? 1.45 : 2.2 },
+                uSPHPressure: { value: size <= 128 ? 7.2 : 9.4 },
+                uSPHViscosity: { value: 1.15 },
+                uSPHSurfaceTension: { value: 0.72 },
+                uJetDir: { value: this.jetDirection },
+                uCollision: { value: this.collision },
+            },
+            vertexShader: quadVertex,
+            fragmentShader: /* glsl */ `
+        precision highp float;
+        uniform sampler2D uPosition;
+        uniform sampler2D uVelocity;
+        uniform float uDelta;
+        uniform float uTime;
+        uniform float uSpeed;
+        uniform float uAperture;
+        uniform float uFillRatio;
+        uniform float uEmission;
+        uniform float uReservoirActive;
+        uniform float uReservoirFill;
+        uniform float uTurbulence;
+        uniform float uBasinCenterZ;
+        uniform float uWallTop;
+        uniform float uFloorY;
+        uniform float uContainerFloorY;
+        uniform vec2 uContainerAcceleration;
+        uniform float uRimWidth;
+        uniform float uSPHKernel;
+        uniform float uSPHRestDensity;
+        uniform float uSPHPressure;
+        uniform float uSPHViscosity;
+        uniform float uSPHSurfaceTension;
+        uniform vec3 uNozzle;
+        uniform vec4 uBasin; // minX, maxX, zHalfExtent, waterY
+        uniform vec3 uJetDir; // 喷流轴向（已归一化）
+        uniform float uCollision; // 1=开启粒子与 basin/地面碰撞回弹，0=关闭（粒子自由飞行）
+        uniform sampler2D uSPHDensity;
+        uniform sampler2D uSPHMomentum;
+        uniform vec3 uSPHDomainMin;
+        uniform vec3 uSPHDomainMax;
+        uniform vec3 uSPHGrid;
+        uniform vec2 uSPHAtlasTiles;
+        uniform vec3 uSPHCell;
+        in vec2 vUv;
+        layout(location = 0) out vec4 outPosition;
+        layout(location = 1) out vec4 outVelocity;
+
+        float hash12(vec2 p) {
+          vec3 p3 = fract(vec3(p.xyx) * 0.1031);
+          p3 += dot(p3, p3.yzx + 33.33);
+          return fract((p3.x + p3.y) * p3.z);
+        }
+
+        vec2 hash22(vec2 p) {
+          float n = hash12(p);
+          return vec2(n, hash12(p + n + 19.19));
+        }
+
+        bool insideSPHDomain(vec3 position) {
+          return all(greaterThanEqual(position, uSPHDomainMin))
+              && all(lessThanEqual(position, uSPHDomainMax));
+        }
+
+        vec2 sphAtlasUv(vec2 normalizedXY, float slice) {
+          vec2 tile = vec2(mod(slice, uSPHAtlasTiles.x), floor(slice / uSPHAtlasTiles.x));
+          vec2 localCell = normalizedXY * (uSPHGrid.xy - 1.0) + vec2(0.5);
+          return (tile * uSPHGrid.xy + localCell) / (uSPHGrid.xy * uSPHAtlasTiles);
+        }
+
+        vec4 sampleSPHField(sampler2D field, vec3 position) {
+          if (!insideSPHDomain(position)) return vec4(0.0);
+          vec3 normalizedPosition = clamp(
+            (position - uSPHDomainMin) / (uSPHDomainMax - uSPHDomainMin),
+            vec3(0.0), vec3(1.0)
+          );
+          float sliceCoordinate = normalizedPosition.z * (uSPHGrid.z - 1.0);
+          float sliceA = floor(sliceCoordinate);
+          float sliceB = min(sliceA + 1.0, uSPHGrid.z - 1.0);
+          float blendZ = fract(sliceCoordinate);
+          vec4 sampleA = texture(field, sphAtlasUv(normalizedPosition.xy, sliceA));
+          vec4 sampleB = texture(field, sphAtlasUv(normalizedPosition.xy, sliceB));
+          return mix(sampleA, sampleB, blendZ);
+        }
+
+        float particleDensity(vec3 position) {
+          return sampleSPHField(uSPHDensity, position).r;
+        }
+
+        vec3 neighborVelocity(vec3 position) {
+          vec4 momentum = sampleSPHField(uSPHMomentum, position);
+          return momentum.rgb / max(momentum.a, 0.08);
+        }
+
+        float boundaryKernel(float distanceToWall) {
+          float q = max(0.0, 1.0 - abs(distanceToWall) / max(uSPHKernel, 0.001));
+          return q * q * uSPHRestDensity * 2.35;
+        }
+
+        float boundaryDensity(vec3 position) {
+          float density = 0.0;
+          bool withinX = position.x > uBasin.x - uSPHKernel
+                      && position.x < uBasin.y + uSPHKernel;
+          bool withinZ = abs(position.z - uBasinCenterZ) < uBasin.z + uSPHKernel;
+          bool withinWallHeight = position.y < uWallTop + uSPHKernel
+                               && position.y > uFloorY - uSPHKernel;
+
+          if (withinWallHeight && withinZ) {
+            density += boundaryKernel(position.x - uBasin.x);
+            density += boundaryKernel(position.x - uBasin.y);
+          }
+          if (withinWallHeight && withinX) {
+            density += boundaryKernel(position.z - (uBasinCenterZ - uBasin.z));
+            density += boundaryKernel(position.z - (uBasinCenterZ + uBasin.z));
+          }
+          if (withinX && withinZ) {
+            density += boundaryKernel(position.y - uContainerFloorY);
+            bool outsideOpening = position.x <= uBasin.x || position.x >= uBasin.y
+                               || abs(position.z - uBasinCenterZ) >= uBasin.z;
+            if (outsideOpening) density += boundaryKernel(position.y - uWallTop);
+          }
+          return density;
+        }
+
+        float totalDensity(vec3 position) {
+          return particleDensity(position) + boundaryDensity(position);
+        }
+
+        float wettedFraction(float fillRatio) {
+          float axis = clamp(1.0 - 2.0 * fillRatio, -1.0, 1.0);
+          return (acos(axis) - axis * sqrt(max(0.0, 1.0 - axis * axis))) / 3.14159265359;
+        }
+
+        float reservoirParticleFraction() {
+          float fill = clamp(uReservoirFill, 0.0, 1.0);
+          // Keep particle density approximately constant as the retained volume
+          // rises, so screen-space reconstruction has a stable physical scale.
+          float volumeFraction = fill * 0.78;
+          return uReservoirActive * smoothstep(0.002, 0.018, fill) * volumeFraction;
+        }
+
+        void spawnStoredWater(inout vec4 positionLife, inout vec4 velocityImpact, float seed) {
+          vec2 randomXZ = hash22(vUv * 1257.3 + seed * 47.1);
+          float layerJitter = hash12(vUv * 2089.7 + seed * 83.4) - 0.5;
+          float inset = max(0.026, uSPHKernel * 0.32);
+          float bottom = uContainerFloorY + inset;
+          float top = max(bottom + 0.012, uBasin.w - inset * 0.55);
+          float fill = max(clamp(uReservoirFill, 0.0, 1.0), 0.002);
+          float fullColumnHeight = max((uBasin.w - bottom) / fill, 0.012);
+          // The seed also determines when a retained particle becomes active.
+          // Mapping that activation order to vertical layers keeps particle mass
+          // proportional to visible height while the reservoir fills or drains.
+          float layer = clamp(seed / 0.78, 0.0, 1.0);
+          float layerY = bottom + layer * fullColumnHeight
+            + layerJitter * min(uSPHKernel * 0.38, fullColumnHeight * 0.018);
+          positionLife = vec4(
+            mix(uBasin.x + inset, uBasin.y - inset, randomXZ.x),
+            clamp(layerY, bottom, top),
+            mix(uBasinCenterZ - uBasin.z + inset, uBasinCenterZ + uBasin.z - inset, randomXZ.y),
+            0.2 + seed * 0.25
+          );
+          vec2 drift = hash22(vUv * 733.1 + uTime * 0.017) * 2.0 - 1.0;
+          velocityImpact = vec4(drift.x * 0.025, 0.0, drift.y * 0.025, -1.0);
+        }
+
+        void respawn(inout vec4 positionLife, inout vec4 velocityImpact, float seed) {
+          float outletRadius = 0.24 * uAperture;
+          float surfaceY = -outletRadius + 2.0 * outletRadius * clamp(uFillRatio, 0.0, 1.0);
+          vec2 disk = vec2(0.0, -outletRadius * 0.82);
+          bool accepted = false;
+          for (int i = 0; i < 10; i++) {
+            vec2 randomPair = hash22(vUv * 911.7 + seed * 31.3 + float(i) * 17.71);
+            vec2 candidate = (randomPair * 2.0 - 1.0) * outletRadius * 0.96;
+            if (!accepted && dot(candidate, candidate) < outletRadius * outletRadius * 0.92 && candidate.x <= surfaceY) {
+              disk = candidate;
+              accepted = true;
+            }
+          }
+          float radius01 = clamp(length(disk) / max(outletRadius, 0.001), 0.0, 1.0);
+          float profile = pow(max(0.02, 1.0 - radius01), 1.0 / 7.0);
+          vec3 jetAxis = normalize(uJetDir);
+          float axial = uSpeed * mix(0.88, 1.09, profile);
+          float wobble = (hash12(vUv * 173.1 + uTime) - 0.5) * uTurbulence;
+
+          positionLife = vec4(uNozzle + vec3(0.0, disk.x, disk.y), 0.0);
+          vec3 jetJitter = vec3(-disk.x * axial * 0.055 + wobble * 0.045, 0.0, -disk.y * axial * 0.055 + wobble * 0.055);
+          velocityImpact = vec4(jetAxis * axial + jetJitter, 0.0);
+        }
+
+        void main() {
+          vec4 positionLife = texture(uPosition, vUv);
+          vec4 velocityImpact = texture(uVelocity, vUv);
+          float seed = hash12(vUv * 1459.3 + 0.17);
+          vec3 jetAxis = normalize(uJetDir);
+          float maxLife = 2.65 + seed * 1.2;
+          float storedFraction = reservoirParticleFraction();
+
+          if (positionLife.w < 0.0) {
+            positionLife.xyz = uNozzle;
+            velocityImpact = vec4(0.0);
+            if (seed < storedFraction) {
+              spawnStoredWater(positionLife, velocityImpact, seed);
+            } else if (uEmission > 0.5) {
+              float activeFraction = mix(0.08, 1.0, wettedFraction(uFillRatio));
+              float emissionSeed = (seed - storedFraction) / max(1.0 - storedFraction, 0.001);
+              if (emissionSeed <= activeFraction) {
+                positionLife.w += uDelta;
+                if (positionLife.w >= 0.0) respawn(positionLife, velocityImpact, seed);
+              } else {
+                positionLife.w = -0.25 - seed * 0.2;
+              }
+            }
+            outPosition = positionLife;
+            outVelocity = velocityImpact;
+            return;
+          }
+
+          bool storedParticle = velocityImpact.w < -0.5;
+          if (storedParticle && (uReservoirActive < 0.5 || seed >= storedFraction)) {
+            positionLife = vec4(uNozzle, uEmission > 0.5 ? -0.05 - seed * 0.35 : -10.0 - seed);
+            velocityImpact = vec4(0.0);
+            outPosition = positionLife;
+            outVelocity = velocityImpact;
+            return;
+          }
+
+          positionLife.w = storedParticle ? min(positionLife.w + uDelta, 0.8) : positionLife.w + uDelta;
+          if (!storedParticle) velocityImpact.w = max(0.0, velocityImpact.w - uDelta * 0.5);
+
+          vec3 previousPosition = positionLife.xyz;
+          vec3 velocity = velocityImpact.xyz;
+
+          // Grid-assisted SPH: Poly6 density splats are sampled around each particle.
+          // Analytic boundary density acts like stationary ghost particles at solid walls.
+          float densityCenter = totalDensity(positionLife.xyz);
+          float densityPX = totalDensity(positionLife.xyz + vec3(uSPHCell.x, 0.0, 0.0));
+          float densityMX = totalDensity(positionLife.xyz - vec3(uSPHCell.x, 0.0, 0.0));
+          float densityPY = totalDensity(positionLife.xyz + vec3(0.0, uSPHCell.y, 0.0));
+          float densityMY = totalDensity(positionLife.xyz - vec3(0.0, uSPHCell.y, 0.0));
+          float densityPZ = totalDensity(positionLife.xyz + vec3(0.0, 0.0, uSPHCell.z));
+          float densityMZ = totalDensity(positionLife.xyz - vec3(0.0, 0.0, uSPHCell.z));
+          vec3 normalizedPressureGradient = vec3(
+            (densityPX - densityMX) / max(densityPX + densityMX + uSPHRestDensity, 0.001),
+            (densityPY - densityMY) / max(densityPY + densityMY + uSPHRestDensity, 0.001),
+            (densityPZ - densityMZ) / max(densityPZ + densityMZ + uSPHRestDensity, 0.001)
+          );
+          float compression = smoothstep(
+            uSPHRestDensity * 0.72,
+            uSPHRestDensity * 3.4,
+            densityCenter
+          );
+          vec3 pressureAcceleration = -normalizedPressureGradient * uSPHPressure * compression;
+          if (storedParticle) pressureAcceleration *= 0.9;
+          float pressureMagnitude = length(pressureAcceleration);
+          float pressureLimit = storedParticle ? 18.0 : 18.0;
+          if (pressureMagnitude > pressureLimit) pressureAcceleration *= pressureLimit / pressureMagnitude;
+          velocity += pressureAcceleration * uDelta;
+
+          float particleDensityCenter = particleDensity(positionLife.xyz);
+          vec4 localMomentum = sampleSPHField(uSPHMomentum, positionLife.xyz);
+          float neighborCoupling = smoothstep(0.18, uSPHRestDensity * 1.25, particleDensityCenter)
+                                 * smoothstep(0.06, 0.42, localMomentum.a);
+          vec3 smoothedVelocity = localMomentum.rgb / max(localMomentum.a, 0.08);
+          // Water should exchange momentum without moving as one viscous blob.
+          float viscosityMultiplier = storedParticle ? 0.32 : 1.0;
+          velocity += (smoothedVelocity - velocity)
+            * uSPHViscosity * viscosityMultiplier * neighborCoupling * uDelta;
+
+          vec3 surfaceGradient = vec3(
+            particleDensity(positionLife.xyz + vec3(uSPHCell.x, 0.0, 0.0))
+              - particleDensity(positionLife.xyz - vec3(uSPHCell.x, 0.0, 0.0)),
+            particleDensity(positionLife.xyz + vec3(0.0, uSPHCell.y, 0.0))
+              - particleDensity(positionLife.xyz - vec3(0.0, uSPHCell.y, 0.0)),
+            particleDensity(positionLife.xyz + vec3(0.0, 0.0, uSPHCell.z))
+              - particleDensity(positionLife.xyz - vec3(0.0, 0.0, uSPHCell.z))
+          );
+          float surfaceGradientLength = length(surfaceGradient);
+          float freeSurface = smoothstep(0.22, uSPHRestDensity, particleDensityCenter)
+                            * (1.0 - smoothstep(uSPHRestDensity * 1.8, uSPHRestDensity * 4.2, particleDensityCenter));
+          if (surfaceGradientLength > 0.0001) {
+            velocity += surfaceGradient / surfaceGradientLength
+              * uSPHSurfaceTension * (storedParticle ? 0.42 : 1.0) * freeSurface * uDelta;
+          }
+
+          // A clean free jet conserves axial momentum along its own direction until it touches water or a wall.
+          if (!storedParticle && velocityImpact.w < 0.045 && positionLife.y > uBasin.w + 0.045) {
+            velocity += jetAxis * max(0.0, uSpeed * 0.96 - dot(velocity, jetAxis));
+          }
+
+          // Grid pressure is deliberately coarse, so deep retained particles need
+          // hydrostatic support to preserve volume. The free-surface band keeps
+          // substantially more gravity for natural wave falloff and overtopping.
+          if (storedParticle) {
+            float columnHeight = max(uBasin.w - uContainerFloorY, 0.04);
+            float normalizedDepth = clamp(
+              (uBasin.w - positionLife.y) / columnHeight,
+              0.0,
+              1.0
+            );
+            float hydrostaticSupport = mix(
+              0.72,
+              0.995,
+              smoothstep(0.045, 0.27, normalizedDepth)
+            );
+            float belowTargetSurface = 1.0 - smoothstep(
+              0.0,
+              uSPHKernel * 0.8,
+              positionLife.y - uBasin.w
+            );
+            velocity.y += 9.81 * hydrostaticSupport * belowTargetSurface * uDelta;
+            velocity.x -= uContainerAcceleration.x * uDelta;
+            velocity.z -= uContainerAcceleration.y * uDelta;
+          }
+          velocity.y -= 9.81 * uDelta;
+          velocity *= exp(-(storedParticle ? 0.055 : 0.028) * uDelta);
+
+          if (!storedParticle) {
+            float diameter = 0.48 * uAperture;
+            float breakup = smoothstep(uNozzle.x + diameter * 4.0, uNozzle.x + diameter * 11.0, positionLife.x);
+            float swirlPhase = positionLife.x * 8.1 + uTime * 3.0 + seed * 28.0;
+            vec3 curlForce = vec3(0.0, sin(swirlPhase), cos(swirlPhase * 0.87 + 1.4));
+            velocity += curlForce * uTurbulence * breakup * uDelta;
+          }
+          positionLife.xyz += velocity * uDelta;
+
+          bool insideTray = positionLife.x > uBasin.x && positionLife.x < uBasin.y && abs(positionLife.z - uBasinCenterZ) < uBasin.z;
+          bool crossedWater = insideTray && previousPosition.y > uBasin.w && positionLife.y <= uBasin.w && velocity.y < 0.0;
+
+          if (uCollision > 0.5) {
+          if (crossedWater && !storedParticle) {
+            float impact = -velocity.y;
+            vec2 scatter = hash22(vUv * 817.0 + floor(uTime * 37.0)) * 2.0 - 1.0;
+            float splashChance = hash12(vUv * 331.0 + floor(uTime * 19.0));
+            if (splashChance < 0.31 + clamp(impact * 0.035, 0.0, 0.16)) {
+              positionLife.y = uBasin.w + 0.012;
+              velocity.x = velocity.x * (0.16 + seed * 0.12) + scatter.x * impact * 0.28;
+              velocity.y = impact * (0.18 + hash12(vUv * 97.0) * 0.25);
+              velocity.z = velocity.z * 0.2 + scatter.y * impact * 0.34;
+              velocityImpact.w = clamp(impact / 6.0, 0.25, 1.0);
+            } else {
+              positionLife.w = maxLife + 1.0;
+            }
+          }
+
+          bool insideZSpan = abs(positionLife.z - uBasinCenterZ) < uBasin.z + uRimWidth;
+          bool insideXSpan = positionLife.x > uBasin.x - uRimWidth && positionLife.x < uBasin.y + uRimWidth;
+          bool crossedMinWall = (previousPosition.x < uBasin.x && positionLife.x >= uBasin.x)
+                             || (previousPosition.x > uBasin.x && positionLife.x <= uBasin.x);
+          bool crossedMaxWall = (previousPosition.x < uBasin.y && positionLife.x >= uBasin.y)
+                             || (previousPosition.x > uBasin.y && positionLife.x <= uBasin.y);
+          bool crossedNearZ = (previousPosition.z < uBasinCenterZ - uBasin.z && positionLife.z >= uBasinCenterZ - uBasin.z)
+                           || (previousPosition.z > uBasinCenterZ - uBasin.z && positionLife.z <= uBasinCenterZ - uBasin.z);
+          bool crossedFarZ = (previousPosition.z < uBasinCenterZ + uBasin.z && positionLife.z >= uBasinCenterZ + uBasin.z)
+                          || (previousPosition.z > uBasinCenterZ + uBasin.z && positionLife.z <= uBasinCenterZ + uBasin.z);
+          bool wallHit = positionLife.y < uWallTop && (
+            (insideZSpan && (crossedMinWall || crossedMaxWall))
+            || (insideXSpan && (crossedNearZ || crossedFarZ))
+          );
+
+          bool outsideOpening = positionLife.x <= uBasin.x || positionLife.x >= uBasin.y
+                             || abs(positionLife.z - uBasinCenterZ) >= uBasin.z;
+          bool crossedRimTop = previousPosition.y > uWallTop && positionLife.y <= uWallTop
+                            && outsideOpening && insideXSpan && insideZSpan;
+
+          if ((wallHit || crossedRimTop) && !crossedWater) {
+            vec3 collisionNormal = vec3(0.0, 1.0, 0.0);
+            vec2 scatter = hash22(vUv * 527.0 + floor(uTime * 43.0)) * 2.0 - 1.0;
+            if (crossedRimTop) {
+              positionLife.y = uWallTop + 0.008;
+            } else if (crossedMinWall || crossedMaxWall) {
+              float wallPlane = crossedMinWall ? uBasin.x : uBasin.y;
+              float wallSign = crossedMinWall
+                ? (previousPosition.x < uBasin.x ? -1.0 : 1.0)
+                : (previousPosition.x > uBasin.y ? 1.0 : -1.0);
+              collisionNormal = vec3(wallSign, 0.0, 0.0);
+              positionLife.x = wallPlane + wallSign * uRimWidth;
+            } else {
+              float wallPlane = crossedNearZ ? uBasinCenterZ - uBasin.z : uBasinCenterZ + uBasin.z;
+              float wallSign = crossedNearZ
+                ? (previousPosition.z < wallPlane ? -1.0 : 1.0)
+                : (previousPosition.z > wallPlane ? 1.0 : -1.0);
+              collisionNormal = vec3(0.0, 0.0, wallSign);
+              positionLife.z = wallPlane + wallSign * uRimWidth;
+            }
+
+            float normalVelocity = dot(velocity, collisionNormal);
+            float impact = max(0.0, -normalVelocity);
+            float restitution = mix(0.12, 0.23, seed);
+            if (normalVelocity < 0.0) {
+              velocity -= (1.0 + restitution) * normalVelocity * collisionNormal;
+            }
+            vec3 tangentVelocity = velocity - dot(velocity, collisionNormal) * collisionNormal;
+            float collisionFriction = storedParticle
+              ? mix(0.015, 0.04, compression)
+              : mix(0.16, 0.28, compression);
+            velocity -= tangentVelocity * collisionFriction;
+            float roughSplash = smoothstep(1.2, 5.5, impact);
+            velocity += vec3(scatter.x, 0.18 + seed * 0.18, scatter.y)
+              * impact * roughSplash * 0.11;
+            velocityImpact.w = storedParticle
+              ? -1.0
+              : clamp(max(impact, pressureMagnitude * 0.16) / 6.5, 0.18, 1.0);
+          }
+
+          bool crossedFloor = previousPosition.y > uFloorY && positionLife.y <= uFloorY && velocity.y < 0.0;
+          if (crossedFloor && !crossedWater) {
+            if (storedParticle) {
+              positionLife.y = uFloorY + max(0.018, uSPHKernel * 0.24);
+              float impact = -velocity.y;
+              velocity.y = impact * 0.12;
+              velocity.x *= 0.97;
+              velocity.z *= 0.97;
+              velocityImpact.w = -1.0;
+            } else if (velocityImpact.w > 0.12) {
+              positionLife.w = maxLife + 1.0;
+            } else {
+              float impact = -velocity.y;
+              vec2 scatter = hash22(vUv * 691.0 + floor(uTime * 31.0)) * 2.0 - 1.0;
+              positionLife.y = uFloorY + 0.009;
+              velocity.x = velocity.x * 0.12 + scatter.x * impact * 0.38;
+              velocity.y = impact * (0.18 + hash12(vUv * 229.0) * 0.22);
+              velocity.z = velocity.z * 0.12 + scatter.y * impact * 0.42;
+              velocityImpact.w = clamp(impact / 5.8, 0.35, 1.0);
+            }
+          }
+
+          if (storedParticle) {
+            float containmentInset = max(0.018, uSPHKernel * 0.24);
+            float minX = uBasin.x + containmentInset;
+            float maxX = uBasin.y - containmentInset;
+            float minZ = uBasinCenterZ - uBasin.z + containmentInset;
+            float maxZ = uBasinCenterZ + uBasin.z - containmentInset;
+            float bottom = uContainerFloorY + containmentInset;
+
+            bool retainedBelowOverflow = uReservoirFill < 0.985;
+            if (retainedBelowOverflow || positionLife.y < uWallTop + 0.075) {
+              if (positionLife.x < minX) {
+                positionLife.x = minX;
+                velocity.x = abs(velocity.x) * 0.28;
+                velocity.z *= 0.97;
+              } else if (positionLife.x > maxX) {
+                positionLife.x = maxX;
+                velocity.x = -abs(velocity.x) * 0.28;
+                velocity.z *= 0.97;
+              }
+              if (positionLife.z < minZ) {
+                positionLife.z = minZ;
+                velocity.z = abs(velocity.z) * 0.28;
+                velocity.x *= 0.97;
+              } else if (positionLife.z > maxZ) {
+                positionLife.z = maxZ;
+                velocity.z = -abs(velocity.z) * 0.28;
+                velocity.x *= 0.97;
+              }
+            }
+            if (positionLife.y < bottom) {
+              positionLife.y = bottom;
+              velocity.y = abs(velocity.y) * 0.06;
+              velocity.xz *= 0.97;
+            }
+
+            // Retained water may only leave through the rim after the vessel is physically full.
+            // At lower levels, pressure impulses become internal slosh instead of phantom overflow.
+            float retainedCeiling = mix(
+              uBasin.w + 0.065,
+              uWallTop + 0.085,
+              smoothstep(0.96, 1.0, uReservoirFill)
+            );
+            if (uReservoirFill > 0.985
+                && positionLife.y > uWallTop + 0.12
+                && velocity.y > 1.35
+                && length(velocity) > 1.75) {
+              storedParticle = false;
+              positionLife.w = maxLife - 0.72;
+              velocityImpact.w = clamp(length(velocity) / 5.5, 0.18, 0.72);
+            } else {
+              if (positionLife.y > retainedCeiling) {
+                positionLife.y = retainedCeiling;
+                velocity.y = min(velocity.y, -0.08);
+                velocity.xz *= 0.97;
+              }
+              velocityImpact.w = -1.0;
+            }
+          }
+          }
+
+          velocityImpact.xyz = velocity;
+          bool expired = !storedParticle && positionLife.w > maxLife;
+          bool escaped = !storedParticle && (positionLife.y < uFloorY - 0.36
+                      || positionLife.x > uBasin.y + 2.8
+                      || positionLife.x < uNozzle.x - 0.8
+                      || abs(positionLife.z - uBasinCenterZ) > uBasin.z + 2.2);
+          if (expired || escaped) {
+            positionLife = vec4(uNozzle, uEmission > 0.5 ? -seed * 0.85 : -10.0 - seed);
+            velocityImpact = vec4(0.0);
+          }
+
+          outPosition = positionLife;
+          outVelocity = velocityImpact;
+        }
+      `,
+            depthTest: false,
+            depthWrite: false,
+            toneMapped: false,
+        });
+        this.updateSPHDomain();
+        this.reset();
+    }
+    hash(value) {
+        const x = Math.sin(value * 12.9898) * 43758.5453;
+        return x - Math.floor(x);
+    }
+    reset() {
+        if (!this.supported)
+            return;
+        const previousTarget = this.renderer.getRenderTarget();
+        this.mesh.material = this.initMaterial;
+        this.renderer.setRenderTarget(this.read);
+        this.renderer.render(this.scene, this.camera);
+        this.renderer.setRenderTarget(this.write);
+        this.renderer.render(this.scene, this.camera);
+        this.renderer.setRenderTarget(previousTarget);
+    }
+    update(delta, elapsed) {
+        if (!this.supported)
+            return;
+        this.sphField.build(this.read.textures[0], this.read.textures[1]);
+        this.updateMaterial.uniforms.uPosition.value = this.read.textures[0];
+        this.updateMaterial.uniforms.uVelocity.value = this.read.textures[1];
+        this.updateMaterial.uniforms.uDelta.value = delta;
+        this.updateMaterial.uniforms.uTime.value = elapsed;
+        this.mesh.material = this.updateMaterial;
+        const previousTarget = this.renderer.getRenderTarget();
+        this.renderer.setRenderTarget(this.write);
+        this.renderer.render(this.scene, this.camera);
+        this.renderer.setRenderTarget(previousTarget);
+        [this.read, this.write] = [this.write, this.read];
+    }
+    setParameters({ speed, aperture, fillRatio, emitting, turbulence }) {
+        if (!this.supported)
+            return;
+        if (speed !== undefined)
+            this.updateMaterial.uniforms.uSpeed.value = speed;
+        if (aperture !== undefined)
+            this.updateMaterial.uniforms.uAperture.value = aperture;
+        if (fillRatio !== undefined)
+            this.updateMaterial.uniforms.uFillRatio.value = fillRatio;
+        if (emitting !== undefined)
+            this.updateMaterial.uniforms.uEmission.value = emitting ? 1 : 0;
+        if (turbulence !== undefined)
+            this.updateMaterial.uniforms.uTurbulence.value = turbulence;
+    }
+    setReservoirState({ active = false, fillRatio = 0 } = {}) {
+        if (!this.supported)
+            return;
+        this.updateMaterial.uniforms.uReservoirActive.value = active ? 1 : 0;
+        this.updateMaterial.uniforms.uReservoirFill.value = THREE.MathUtils.clamp(fillRatio, 0, 1);
+    }
+    setContainerMotion(accelerationX = 0, accelerationZ = 0) {
+        if (!this.supported)
+            return;
+        this.updateMaterial.uniforms.uContainerAcceleration.value.set(THREE.MathUtils.clamp(accelerationX, -22, 22), THREE.MathUtils.clamp(accelerationZ, -22, 22));
+    }
+    setBasin({ minX, maxX, halfZ, centerZ = 0, waterY, wallTop, floorY = -0.17, containerFloorY = 0.06, rimWidth = 0.055, }) {
+        if (!this.supported)
+            return;
+        this.basin.set(minX, maxX, halfZ, waterY);
+        this.updateMaterial.uniforms.uBasinCenterZ.value = centerZ;
+        this.updateMaterial.uniforms.uWallTop.value = wallTop;
+        this.updateMaterial.uniforms.uFloorY.value = floorY;
+        this.updateMaterial.uniforms.uContainerFloorY.value = containerFloorY;
+        this.updateMaterial.uniforms.uRimWidth.value = rimWidth;
+        this.updateSPHDomain();
+    }
+    updateSPHDomain() {
+        if (!this.supported)
+            return;
+        const centerZ = this.updateMaterial.uniforms.uBasinCenterZ.value;
+        const floorY = this.updateMaterial.uniforms.uFloorY.value;
+        const marginZ = this.basin.z + 0.72;
+        this.sphDomainMinimum.set(this.nozzle.x - 0.34, floorY - 0.16, Math.min(-1.45, centerZ - marginZ));
+        this.sphDomainMaximum.set(Math.max(this.nozzle.x + 3.9, this.basin.y + 0.82), this.nozzle.y + 0.38, Math.max(1.45, centerZ + marginZ));
+        this.sphField.setDomain(this.sphDomainMinimum, this.sphDomainMaximum);
+    }
+    /** 运行时改喷流起点（喷嘴）坐标；会重算 SPH 域，已发射粒子在下一次 respawn 时回到新起点 */
+    setNozzle(x, y, z) {
+        if (!this.supported)
+            return;
+        this.nozzle.set(x, y, z);
+        this.updateMaterial.uniforms.uNozzle.value.set(x, y, z);
+        this.updateSPHDomain();
+    }
+    /** 运行时改喷流方向（轴向，会被归一化） */
+    setJetDirection(dx, dy, dz) {
+        if (!this.supported)
+            return;
+        this.jetDirection.set(dx, dy, dz).normalize();
+        this.updateMaterial.uniforms.uJetDir.value.copy(this.jetDirection);
+    }
+    /** 运行时开关粒子与 basin/地面碰撞回弹（默认开启） */
+    setCollision(enabled) {
+        if (!this.supported)
+            return;
+        this.collision = enabled ? 1 : 0;
+        this.updateMaterial.uniforms.uCollision.value = this.collision;
+    }
+    setSPHActiveCount(count) {
+        if (!this.supported)
+            return;
+        this.sphField.setActiveCount(count);
+    }
+    get positionTexture() {
+        return this.supported ? this.read.textures[0] : null;
+    }
+    get velocityTexture() {
+        return this.supported ? this.read.textures[1] : null;
+    }
+    dispose() {
+        if (!this.supported)
+            return;
+        this.read.dispose();
+        this.write.dispose();
+        this.initialPosition.dispose();
+        this.initialVelocity.dispose();
+        this.sphField.dispose();
+        this.initMaterial.dispose();
+        this.updateMaterial.dispose();
+        this.mesh.geometry.dispose();
+    }
+}