three-base 2.0.134 → 2.0.142

package/WaterFlow/GPUFluidSimulation.ts

@@ -0,0 +1,827 @@
+import * as THREE from 'three';
+import { SPHField } from './SPHField';
+import type { BasinConfig, FluidParameters, FluidSimulationOptions, ReservoirState } from './types';
+
+const quadVertex = /* glsl */`
+  out vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = vec4(position, 1.0);
+  }
+`;
+
+function createStateTarget(size: number): THREE.WebGLRenderTarget {
+  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: Float32Array, size: number): THREE.DataTexture {
+  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 {
+  readonly renderer: THREE.WebGLRenderer;
+  readonly size: number;
+  readonly count: number;
+  readonly nozzle: THREE.Vector3;
+  /** x=minX, y=maxX, z=zHalfExtent, w=waterY（与 shader 的 uBasin 一致）。 */
+  readonly basin: THREE.Vector4;
+  readonly jetDirection: THREE.Vector3;
+  /** 1=开启粒子与 basin/地面碰撞回弹，0=关闭（喂给 shader 的 uCollision，故为 0/1）。 */
+  collision: number;
+  readonly supported: boolean;
+
+  /** ping-pong 状态目标；update() 每帧整体交换 read/write，故非 readonly。 */
+  read: THREE.WebGLRenderTarget | null;
+  /** ping-pong 状态目标；update() 每帧整体交换 read/write，故非 readonly。 */
+  write: THREE.WebGLRenderTarget | null;
+  readonly sphField: SPHField | null;
+  readonly sphDomainMinimum: THREE.Vector3;
+  readonly sphDomainMaximum: THREE.Vector3;
+  readonly scene: THREE.Scene;
+  readonly camera: THREE.OrthographicCamera;
+  /** 材质在 reset/update 间切换（initMaterial ↔ updateMaterial），故类型含 null。 */
+  readonly mesh: THREE.Mesh<THREE.PlaneGeometry, THREE.ShaderMaterial | null>;
+
+  readonly initialPosition: THREE.DataTexture | null;
+  readonly initialVelocity: THREE.DataTexture | null;
+  readonly initMaterial: THREE.ShaderMaterial | null;
+  readonly updateMaterial: THREE.ShaderMaterial | null;
+
+  constructor(renderer: THREE.WebGLRenderer, {
+    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,
+  }: FluidSimulationOptions = {}) {
+    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: number): number {
+    const x = Math.sin(value * 12.9898) * 43758.5453;
+    return x - Math.floor(x);
+  }
+
+  reset(): void {
+    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: number, elapsed: number): void {
+    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 }: FluidParameters): void {
+    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 }: ReservoirState = {}): void {
+    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): void {
+    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,
+  }: BasinConfig): void {
+    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(): void {
+    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: number, y: number, z: number): void {
+    if (!this.supported) return;
+    this.nozzle.set(x, y, z);
+    this.updateMaterial.uniforms.uNozzle.value.set(x, y, z);
+    this.updateSPHDomain();
+  }
+
+  /** 运行时改喷流方向（轴向，会被归一化） */
+  setJetDirection(dx: number, dy: number, dz: number): void {
+    if (!this.supported) return;
+    this.jetDirection.set(dx, dy, dz).normalize();
+    this.updateMaterial.uniforms.uJetDir.value.copy(this.jetDirection);
+  }
+
+  /** 运行时开关粒子与 basin/地面碰撞回弹（默认开启） */
+  setCollision(enabled: boolean): void {
+    if (!this.supported) return;
+    this.collision = enabled ? 1 : 0;
+    this.updateMaterial.uniforms.uCollision.value = this.collision;
+  }
+
+  setSPHActiveCount(count: number): void {
+    if (!this.supported) return;
+    this.sphField.setActiveCount(count);
+  }
+
+  get positionTexture(): THREE.Texture | null {
+    return this.supported ? this.read.textures[0] : null;
+  }
+
+  get velocityTexture(): THREE.Texture | null {
+    return this.supported ? this.read.textures[1] : null;
+  }
+
+  dispose(): void {
+    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();
+  }
+}