three-base 2.0.142 → 2.0.145

package/WaterFlow/ReservoirSystem.ts

@@ -1,754 +1,754 @@
-import * as THREE from 'three';
-import { ShallowWaterSurface } from './ShallowWaterSurface';
-import type { BasinConfig } from './types';
-
-/**
- * 构造选项：几何口径（length/width/壁高）+ 平面位置（centerX/centerZ）+ 尾流水面网格分辨率。
- * flowTexture 是溢出水花着色器采样的噪声图，缺省时 uniforms.uFlowMap 为 undefined。
- */
-export interface ReservoirOptions {
-    flowTexture?: THREE.Texture;
-    length?: number;
-    width?: number;
-    bottomY?: number;
-    rimY?: number;
-    centerX?: number;
-    centerZ?: number;
-    waveWidth?: number;
-    waveHeight?: number;
-}
-
-/** update 的入参：入口水流量 + 撞击点/能量 + 是否正在喷射。 */
-export interface ReservoirUpdateOptions {
-    flowRate: number;
-    captureFraction?: number;
-    impactX: number;
-    impactZ?: number;
-    impactEnergy?: number;
-    emitting?: boolean;
-}
-
-/** update 的出参：本次入流/溢流的口径，供调用方做音效或统计。 */
-export interface ReservoirUpdateResult {
-    captured: boolean;
-    captureFraction: number;
-    incomingRate: number;
-    missedRate: number;
-    overflowRate: number;
-}
-
-export class ReservoirSystem {
-  /** 几何口径（全部由构造参数推导，构造后不变）。 */
-  private readonly length: number;
-  private readonly width: number;
-  private readonly bottomY: number;
-  private readonly rimY: number;
-  private readonly innerBottomY: number;
-  private readonly maxWaterY: number;
-  private readonly innerLength: number;
-  private readonly innerWidth: number;
-  private readonly surfaceArea: number;
-  private readonly capacity: number;
-
-  /** 水量与溢流状态（每帧变化）。 */
-  private volume: number;
-  private overflowRate: number;
-  private motionOverflowRate: number;
-  private overflowIntensity: number;
-  private active: boolean;
-  private particleFluidMode: boolean;
-
-  /** 容器晃动（xz 两个分量复用 Vector2 的 x/y）。 */
-  private readonly motionPreviousPosition: THREE.Vector2;
-  private readonly motionVelocity: THREE.Vector2;
-  private readonly motionAcceleration: THREE.Vector2;
-  private readonly sloshOffset: THREE.Vector2;
-  private readonly sloshVelocity: THREE.Vector2;
-  private readonly motionWaveImpulse: THREE.Vector2;
-
-  /** 池体节点与拾取体。 */
-  readonly renderer: THREE.WebGLRenderer;
-  readonly group: THREE.Group;
-  readonly hitMeshes: THREE.Mesh[];
-
-  readonly rimFoamMaterial: THREE.MeshBasicMaterial;
-  readonly rimFoamGroup: THREE.Group;
-  readonly waterMaterial: THREE.ShaderMaterial;
-  readonly waterBody: THREE.Mesh;
-  /** 浅水波面；非WebGL2 或缺浮点扩展时为 null（此时只保留水体盒）。 */
-  readonly surface: ShallowWaterSurface | null;
-  readonly overflowMaterial: THREE.ShaderMaterial;
-  readonly overflowGroup: THREE.Group;
-
-  /** 溢流粒子（GPU points）的缓冲与状态。 */
-  readonly dropCount: number;
-  private readonly dropPositions: Float32Array;
-  private readonly dropVelocities: Float32Array;
-  private readonly dropLife: Float32Array;
-  private readonly dropMaxLife: Float32Array;
-  private readonly dropBounces: Uint8Array;
-  private readonly dropSizes: Float32Array;
-  private readonly dropAlpha: Float32Array;
-  private dropCursor: number;
-  private dropAccumulator: number;
-  readonly dropMaterial: THREE.ShaderMaterial;
-  readonly spillPoints: THREE.Points;
-
-  constructor(renderer: THREE.WebGLRenderer, {
-    flowTexture,
-    length = 1.72,
-    width = 1.28,
-    bottomY = -0.13,
-    rimY = 1.14,
-    centerX = 1.82,
-    centerZ = 0,
-    waveWidth = 192,
-    waveHeight = 128,
-  }: ReservoirOptions = {}) {
-    this.renderer = renderer;
-    this.length = length;
-    this.width = width;
-    this.bottomY = bottomY;
-    this.rimY = rimY;
-    this.innerBottomY = bottomY + 0.11;
-    this.maxWaterY = rimY - 0.024;
-    this.innerLength = length - 0.14;
-    this.innerWidth = width - 0.14;
-    this.surfaceArea = this.innerLength * this.innerWidth;
-    this.capacity = this.surfaceArea * (this.maxWaterY - this.innerBottomY);
-    this.volume = 0;
-    this.overflowRate = 0;
-    this.motionOverflowRate = 0;
-    this.overflowIntensity = 0;
-    this.active = false;
-    this.motionPreviousPosition = new THREE.Vector2(centerX, centerZ);
-    this.motionVelocity = new THREE.Vector2();
-    this.motionAcceleration = new THREE.Vector2();
-    this.sloshOffset = new THREE.Vector2();
-    this.sloshVelocity = new THREE.Vector2();
-    this.motionWaveImpulse = new THREE.Vector2();
-    this.particleFluidMode = false;
-
-    this.group = new THREE.Group();
-    this.group.position.set(centerX, 0, centerZ);
-    this.hitMeshes = [];
-
-    const steel = new THREE.MeshStandardMaterial({ color: 0x71878d, roughness: 0.2, metalness: 0.92 });
-    const darkSteel = new THREE.MeshStandardMaterial({ color: 0x172a30, roughness: 0.36, metalness: 0.78 });
-    const glass = new THREE.MeshPhysicalMaterial({
-      color: 0x9edbe2,
-      metalness: 0,
-      roughness: 0.08,
-      transmission: 0.9,
-      transparent: true,
-      opacity: 0.19,
-      thickness: 0.04,
-      ior: 1.48,
-      clearcoat: 1,
-      clearcoatRoughness: 0.04,
-      depthWrite: false,
-      side: THREE.DoubleSide,
-    });
-
-    const wallThickness = 0.035;
-    const tankHeight = rimY - bottomY;
-    const frontBackGeometry = new THREE.BoxGeometry(length, tankHeight, wallThickness);
-    const sideGeometry = new THREE.BoxGeometry(wallThickness, tankHeight, width);
-    [-1, 1].forEach((side) => {
-      const wall = new THREE.Mesh(frontBackGeometry, glass);
-      wall.position.set(0, bottomY + tankHeight * 0.5, side * width * 0.5);
-      wall.renderOrder = 6;
-      this.group.add(wall);
-      this.hitMeshes.push(wall);
-    });
-    [-1, 1].forEach((side) => {
-      const wall = new THREE.Mesh(sideGeometry, glass);
-      wall.position.set(side * length * 0.5, bottomY + tankHeight * 0.5, 0);
-      wall.renderOrder = 6;
-      this.group.add(wall);
-      this.hitMeshes.push(wall);
-    });
-
-    const base = new THREE.Mesh(new THREE.BoxGeometry(length + 0.08, 0.09, width + 0.08), darkSteel);
-    base.position.y = bottomY + 0.025;
-    base.castShadow = true;
-    base.receiveShadow = true;
-    this.group.add(base);
-    this.hitMeshes.push(base);
-
-    const rail = 0.045;
-    const verticalGeometry = new THREE.BoxGeometry(rail, tankHeight + 0.08, rail);
-    for (const x of [-1, 1]) {
-      for (const z of [-1, 1]) {
-        const post = new THREE.Mesh(verticalGeometry, steel);
-        post.position.set(x * length * 0.5, bottomY + tankHeight * 0.5, z * width * 0.5);
-        post.castShadow = true;
-        this.group.add(post);
-      }
-    }
-    const railXGeometry = new THREE.BoxGeometry(length + 0.08, rail, rail);
-    const railZGeometry = new THREE.BoxGeometry(rail, rail, width + 0.08);
-    for (const y of [bottomY + 0.035, rimY]) {
-      for (const z of [-1, 1]) {
-        const edge = new THREE.Mesh(railXGeometry, steel);
-        edge.position.set(0, y, z * width * 0.5);
-        edge.castShadow = true;
-        this.group.add(edge);
-      }
-      for (const x of [-1, 1]) {
-        const edge = new THREE.Mesh(railZGeometry, steel);
-        edge.position.set(x * length * 0.5, y, 0);
-        edge.castShadow = true;
-        this.group.add(edge);
-      }
-    }
-
-    this.rimFoamMaterial = new THREE.MeshBasicMaterial({
-      color: 0xbdeff4,
-      transparent: true,
-      opacity: 0,
-      depthWrite: false,
-      blending: THREE.AdditiveBlending,
-    });
-    this.rimFoamGroup = new THREE.Group();
-    const foamX = new THREE.BoxGeometry(this.innerLength * 0.96, 0.012, 0.025);
-    const foamZ = new THREE.BoxGeometry(0.025, 0.012, this.innerWidth * 0.96);
-    for (const z of [-1, 1]) {
-      const foam = new THREE.Mesh(foamX, this.rimFoamMaterial);
-      foam.position.set(0, this.maxWaterY + 0.014, z * this.innerWidth * 0.5);
-      this.rimFoamGroup.add(foam);
-    }
-    for (const x of [-1, 1]) {
-      const foam = new THREE.Mesh(foamZ, this.rimFoamMaterial);
-      foam.position.set(x * this.innerLength * 0.5, this.maxWaterY + 0.014, 0);
-      this.rimFoamGroup.add(foam);
-    }
-    this.group.add(this.rimFoamGroup);
-
-    this.waterMaterial = new THREE.ShaderMaterial({
-      uniforms: {
-        uTime: { value: 0 },
-        uFlowMap: { value: flowTexture },
-        uOpacity: { value: 0.42 },
-      },
-      vertexShader: /* glsl */`
-        varying vec2 vUv;
-        varying vec3 vWorldPosition;
-        varying vec3 vWorldNormal;
-        void main() {
-          vUv = uv;
-          vec4 world = modelMatrix * vec4(position, 1.0);
-          vWorldPosition = world.xyz;
-          vWorldNormal = normalize(mat3(modelMatrix) * normal);
-          gl_Position = projectionMatrix * viewMatrix * world;
-        }
-      `,
-      fragmentShader: /* glsl */`
-        uniform float uTime;
-        uniform float uOpacity;
-        uniform sampler2D uFlowMap;
-        varying vec2 vUv;
-        varying vec3 vWorldPosition;
-        varying vec3 vWorldNormal;
-        void main() {
-          vec3 viewDir = normalize(cameraPosition - vWorldPosition);
-          float fresnel = 0.02 + 0.98 * pow(1.0 - abs(dot(viewDir, normalize(vWorldNormal))), 5.0);
-          vec3 detail = texture2D(uFlowMap, vUv * vec2(1.6, 2.8) + vec2(0.0, uTime * 0.018)).rgb;
-          float depthTint = smoothstep(-0.2, 1.2, vWorldPosition.y);
-          vec3 color = mix(vec3(0.008, 0.12, 0.16), vec3(0.035, 0.34, 0.4), depthTint);
-          color += detail * 0.035 + vec3(0.2, 0.62, 0.68) * fresnel * 0.42;
-          gl_FragColor = vec4(color, uOpacity + fresnel * 0.18);
-        }
-      `,
-      transparent: true,
-      depthWrite: false,
-      side: THREE.DoubleSide,
-    });
-    this.waterBody = new THREE.Mesh(new THREE.BoxGeometry(this.innerLength, 1, this.innerWidth), this.waterMaterial);
-    this.waterBody.renderOrder = 3;
-    this.group.add(this.waterBody);
-
-    this.surface = renderer.capabilities.isWebGL2 && renderer.extensions.has('EXT_color_buffer_float')
-      ? new ShallowWaterSurface(renderer, {
-        width: waveWidth,
-        height: waveHeight,
-        basinMinX: centerX - this.innerLength * 0.5,
-        basinMaxX: centerX + this.innerLength * 0.5,
-        basinHalfZ: this.innerWidth * 0.5,
-        basinCenterZ: centerZ,
-        waterY: this.innerBottomY,
-        cpuSampling: true,
-      })
-      : null;
-    if (this.surface) this.surface.mesh.renderOrder = 5;
-
-    this.overflowMaterial = new THREE.ShaderMaterial({
-      uniforms: {
-        uTime: { value: 0 },
-        uOverflow: { value: 0 },
-        uFlowMap: { value: flowTexture },
-      },
-      vertexShader: /* glsl */`
-        uniform float uTime;
-        uniform float uOverflow;
-        varying vec2 vUv;
-        void main() {
-          vUv = uv;
-          vec3 p = position;
-          float fall = 1.0 - uv.y;
-          p.x *= mix(0.7, 1.0, uv.y);
-          p.z += sin(uv.x * 29.0 + uTime * 5.0) * 0.012 * fall * uOverflow;
-          p.y -= sin(uv.x * 17.0 + uTime * 3.7) * 0.016 * fall;
-          gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
-        }
-      `,
-      fragmentShader: /* glsl */`
-        uniform float uTime;
-        uniform float uOverflow;
-        uniform sampler2D uFlowMap;
-        varying vec2 vUv;
-        void main() {
-          vec2 flowUvA = vec2(vUv.x * 5.7 + uTime * 0.035, vUv.y * 7.5 + uTime * 0.82);
-          vec2 flowUvB = vec2(vUv.x * 9.3 - uTime * 0.028, vUv.y * 4.2 + uTime * 0.57);
-          float noiseA = dot(texture2D(uFlowMap, flowUvA).rgb, vec3(0.2, 0.58, 0.22));
-          float noiseB = dot(texture2D(uFlowMap, flowUvB).rgb, vec3(0.35, 0.5, 0.15));
-          float noise = mix(noiseA, noiseB, 0.46);
-          float rivuletField = 0.5 + 0.5 * sin(vUv.x * 71.0 + noise * 9.0 + sin(vUv.y * 13.0) * 2.2);
-          float rivulets = smoothstep(0.54 - uOverflow * 0.08, 0.86, rivuletField);
-          float edge = smoothstep(0.0, 0.13, vUv.x) * smoothstep(1.0, 0.87, vUv.x);
-          float verticalFade = smoothstep(0.0, 0.12, vUv.y);
-          float breakup = smoothstep(0.27, 0.76, noise + vUv.y * 0.16);
-          float alpha = edge * verticalFade * rivulets * breakup * (0.2 + uOverflow * 0.62);
-          if (alpha < 0.025 || uOverflow < 0.01) discard;
-          vec3 color = mix(vec3(0.045, 0.32, 0.38), vec3(0.58, 0.92, 0.97), noise * 0.3);
-          gl_FragColor = vec4(color, alpha);
-        }
-      `,
-      transparent: true,
-      depthWrite: false,
-      side: THREE.DoubleSide,
-    });
-
-    this.overflowGroup = new THREE.Group();
-    const sheetHeight = 0.62;
-    const makeSheet = (sheetWidth: number, x: number, z: number, rotationY = 0): void => {
-      const sheet = new THREE.Mesh(new THREE.PlaneGeometry(sheetWidth, sheetHeight, 48, 24), this.overflowMaterial);
-      sheet.position.set(x, rimY - sheetHeight * 0.5 - 0.012, z);
-      sheet.rotation.y = rotationY;
-      sheet.renderOrder = 7;
-      this.overflowGroup.add(sheet);
-    };
-    makeSheet(length * 0.78, 0, -width * 0.5 - 0.026);
-    makeSheet(length * 0.78, 0, width * 0.5 + 0.026);
-    makeSheet(width * 0.72, -length * 0.5 - 0.026, 0, Math.PI * 0.5);
-    makeSheet(width * 0.72, length * 0.5 + 0.026, 0, Math.PI * 0.5);
-    this.group.add(this.overflowGroup);
-
-    this.dropCount = waveWidth <= 112 ? 650 : 1400;
-    this.dropPositions = new Float32Array(this.dropCount * 3);
-    this.dropVelocities = new Float32Array(this.dropCount * 3);
-    this.dropLife = new Float32Array(this.dropCount);
-    this.dropMaxLife = new Float32Array(this.dropCount);
-    this.dropBounces = new Uint8Array(this.dropCount);
-    this.dropSizes = new Float32Array(this.dropCount);
-    this.dropAlpha = new Float32Array(this.dropCount);
-    this.dropCursor = 0;
-    this.dropAccumulator = 0;
-    this.dropPositions.fill(-100);
-
-    const dropGeometry = new THREE.BufferGeometry();
-    const positionAttribute = new THREE.BufferAttribute(this.dropPositions, 3);
-    positionAttribute.setUsage(THREE.DynamicDrawUsage);
-    const alphaAttribute = new THREE.BufferAttribute(this.dropAlpha, 1);
-    alphaAttribute.setUsage(THREE.DynamicDrawUsage);
-    const sizeAttribute = new THREE.BufferAttribute(this.dropSizes, 1);
-    sizeAttribute.setUsage(THREE.DynamicDrawUsage);
-    dropGeometry.setAttribute('position', positionAttribute);
-    dropGeometry.setAttribute('aAlpha', alphaAttribute);
-    dropGeometry.setAttribute('aSize', sizeAttribute);
-    this.dropMaterial = new THREE.ShaderMaterial({
-      uniforms: {
-        uPixelRatio: { value: Math.min(devicePixelRatio, 2) },
-      },
-      vertexShader: /* glsl */`
-        attribute float aAlpha;
-        attribute float aSize;
-        uniform float uPixelRatio;
-        varying float vAlpha;
-        void main() {
-          vec4 mv = modelViewMatrix * vec4(position, 1.0);
-          gl_Position = aAlpha > 0.001 ? projectionMatrix * mv : vec4(2.0, 2.0, 2.0, 1.0);
-          gl_PointSize = min(7.5, aSize * uPixelRatio * (5.0 / max(2.0, -mv.z)));
-          vAlpha = aAlpha;
-        }
-      `,
-      fragmentShader: /* glsl */`
-        varying float vAlpha;
-        void main() {
-          float d = length(gl_PointCoord - 0.5);
-          if (d > 0.5) discard;
-          float core = smoothstep(0.5, 0.08, d);
-          float glint = 1.0 - smoothstep(0.015, 0.13, distance(gl_PointCoord, vec2(0.34, 0.3)));
-          float alpha = core * vAlpha;
-          gl_FragColor = vec4(vec3(0.42, 0.87, 0.96) + glint * 0.45, alpha);
-        }
-      `,
-      transparent: true,
-      depthWrite: false,
-      blending: THREE.AdditiveBlending,
-      toneMapped: false,
-    });
-    this.spillPoints = new THREE.Points(dropGeometry, this.dropMaterial);
-    this.spillPoints.frustumCulled = false;
-    this.spillPoints.renderOrder = 8;
-
-    this.reset();
-    this.setActive(false);
-  }
-
-  setActive(active: boolean): void {
-    this.active = active;
-    this.group.visible = active;
-    if (this.surface) this.surface.mesh.visible = active && this.volume > 0.0005 && !this.particleFluidMode;
-    if (active) this.motionPreviousPosition.set(this.centerX, this.centerZ);
-  }
-
-  setParticleFluidMode(enabled: boolean): void {
-    this.particleFluidMode = Boolean(enabled);
-    this.updateGeometry();
-  }
-
-  moveTo(x: number, z: number): void {
-    this.group.position.x = x;
-    this.group.position.z = z;
-    this.updateGeometry();
-  }
-
-  reset(fillRatio = 0): void {
-    this.volume = this.capacity * THREE.MathUtils.clamp(fillRatio, 0, 1);
-    this.overflowRate = 0;
-    this.motionOverflowRate = 0;
-    this.overflowIntensity = 0;
-    this.clearSpillParticles();
-    this.surface?.clear();
-    this.motionPreviousPosition.set(this.centerX, this.centerZ);
-    this.motionVelocity.set(0, 0);
-    this.motionAcceleration.set(0, 0);
-    this.sloshOffset.set(0, 0);
-    this.sloshVelocity.set(0, 0);
-    this.motionWaveImpulse.set(0, 0);
-    this.surface?.setContainerMotion(0, 0, 0, 0);
-    this.updateGeometry();
-  }
-
-  updateContainerMotion(delta: number): void {
-    const safeDelta = Math.max(delta, 1 / 240);
-    const currentX = this.centerX;
-    const currentZ = this.centerZ;
-    const rawVelocityX = THREE.MathUtils.clamp(
-      (currentX - this.motionPreviousPosition.x) / safeDelta,
-      -3.4,
-      3.4,
-    );
-    const rawVelocityZ = THREE.MathUtils.clamp(
-      (currentZ - this.motionPreviousPosition.y) / safeDelta,
-      -3.4,
-      3.4,
-    );
-    const previousVelocityX = this.motionVelocity.x;
-    const previousVelocityZ = this.motionVelocity.y;
-    const velocityResponse = 1 - Math.exp(-safeDelta * 18);
-    this.motionVelocity.x = THREE.MathUtils.lerp(previousVelocityX, rawVelocityX, velocityResponse);
-    this.motionVelocity.y = THREE.MathUtils.lerp(previousVelocityZ, rawVelocityZ, velocityResponse);
-    this.motionAcceleration.x = THREE.MathUtils.clamp(
-      (this.motionVelocity.x - previousVelocityX) / safeDelta,
-      -22,
-      22,
-    );
-    this.motionAcceleration.y = THREE.MathUtils.clamp(
-      (this.motionVelocity.y - previousVelocityZ) / safeDelta,
-      -22,
-      22,
-    );
-    this.motionPreviousPosition.set(currentX, currentZ);
-
-    const omega = 3.65;
-    const damping = 0.28;
-    const targetX = THREE.MathUtils.clamp(
-      -this.motionAcceleration.x / 9.81 * this.innerLength * 0.5,
-      -0.18,
-      0.18,
-    );
-    const targetZ = THREE.MathUtils.clamp(
-      -this.motionAcceleration.y / 9.81 * this.innerWidth * 0.5,
-      -0.15,
-      0.15,
-    );
-    const dampingForce = 2 * damping * omega;
-    this.sloshVelocity.x += (
-      (targetX - this.sloshOffset.x) * omega * omega - this.sloshVelocity.x * dampingForce
-    ) * safeDelta;
-    this.sloshVelocity.y += (
-      (targetZ - this.sloshOffset.y) * omega * omega - this.sloshVelocity.y * dampingForce
-    ) * safeDelta;
-    this.sloshOffset.addScaledVector(this.sloshVelocity, safeDelta);
-    this.sloshOffset.x = THREE.MathUtils.clamp(this.sloshOffset.x, -0.16, 0.16);
-    this.sloshOffset.y = THREE.MathUtils.clamp(this.sloshOffset.y, -0.13, 0.13);
-
-    this.motionWaveImpulse.set(
-      -this.motionAcceleration.x * safeDelta * 0.00015,
-      -this.motionAcceleration.y * safeDelta * 0.00015,
-    );
-    if (!this.active || this.volume < 0.0005) {
-      this.sloshOffset.multiplyScalar(Math.exp(-safeDelta * 5));
-      this.sloshVelocity.multiplyScalar(Math.exp(-safeDelta * 5));
-      this.motionWaveImpulse.set(0, 0);
-    }
-    this.surface?.setContainerMotion(
-      this.sloshOffset.x,
-      this.sloshOffset.y,
-      this.motionWaveImpulse.x,
-      this.motionWaveImpulse.y,
-    );
-  }
-
-  clearSpillParticles(): void {
-    if (!this.dropLife) return;
-    this.dropLife.fill(0);
-    this.dropAlpha.fill(0);
-    this.dropPositions.fill(-100);
-    this.dropAccumulator = 0;
-    if (this.spillPoints) {
-      this.spillPoints.geometry.attributes.position.needsUpdate = true;
-      this.spillPoints.geometry.attributes.aAlpha.needsUpdate = true;
-    }
-  }
-
-  spawnSpillParticle(): void {
-    let index = -1;
-    for (let attempt = 0; attempt < this.dropCount; attempt++) {
-      const candidate = (this.dropCursor + attempt) % this.dropCount;
-      if (this.dropLife[candidate] <= 0) {
-        index = candidate;
-        this.dropCursor = (candidate + 1) % this.dropCount;
-        break;
-      }
-    }
-    if (index < 0) return;
-
-    let edge = Math.floor(Math.random() * 4);
-    if (this.motionOverflowRate > 0.002) {
-      if (Math.abs(this.sloshOffset.x) > Math.abs(this.sloshOffset.y)) {
-        edge = this.sloshOffset.x >= 0 ? 3 : 2;
-      } else {
-        edge = this.sloshOffset.y >= 0 ? 0 : 1;
-      }
-    }
-    const along = Math.random() - 0.5;
-    const speedOut = 0.1 + Math.random() * 0.24 + this.overflowIntensity * 0.22;
-    const velocityOffset = index * 3;
-    const positionOffset = index * 3;
-    let x = this.centerX;
-    let z = this.centerZ;
-    let vx = (Math.random() - 0.5) * 0.08;
-    let vz = (Math.random() - 0.5) * 0.08;
-
-    if (edge === 0) {
-      x += along * this.innerLength * 0.92;
-      z += this.innerWidth * 0.5 + 0.015;
-      vz += speedOut;
-    } else if (edge === 1) {
-      x += along * this.innerLength * 0.92;
-      z -= this.innerWidth * 0.5 + 0.015;
-      vz -= speedOut;
-    } else if (edge === 2) {
-      x -= this.innerLength * 0.5 + 0.015;
-      z += along * this.innerWidth * 0.9;
-      vx -= speedOut;
-    } else {
-      x += this.innerLength * 0.5 + 0.015;
-      z += along * this.innerWidth * 0.9;
-      vx += speedOut;
-    }
-
-    this.dropPositions[positionOffset] = x;
-    this.dropPositions[positionOffset + 1] = this.maxWaterY + 0.012 + Math.random() * 0.018;
-    this.dropPositions[positionOffset + 2] = z;
-    this.dropVelocities[velocityOffset] = vx;
-    this.dropVelocities[velocityOffset + 1] = 0.03 + Math.random() * 0.19;
-    this.dropVelocities[velocityOffset + 2] = vz;
-    this.dropLife[index] = 1.25 + Math.random() * 0.8;
-    this.dropMaxLife[index] = this.dropLife[index];
-    this.dropBounces[index] = 0;
-    this.dropSizes[index] = 2.2 + Math.random() * 3.3;
-    this.dropAlpha[index] = 0.75 + Math.random() * 0.25;
-  }
-
-  updateSpillParticles(delta: number): void {
-    if (this.active && this.overflowRate > 0.0001) {
-      const spawnRate = Math.min(this.dropCount * 0.86, 140 + this.overflowRate * 2600);
-      this.dropAccumulator += spawnRate * delta;
-      const spawnCount = Math.min(48, Math.floor(this.dropAccumulator));
-      this.dropAccumulator -= spawnCount;
-      for (let i = 0; i < spawnCount; i++) this.spawnSpillParticle();
-    }
-
-    const floorY = -0.17;
-    const drag = Math.exp(-0.18 * delta);
-    for (let i = 0; i < this.dropCount; i++) {
-      if (this.dropLife[i] <= 0) continue;
-      const offset = i * 3;
-      this.dropLife[i] -= delta;
-      this.dropVelocities[offset] *= drag;
-      this.dropVelocities[offset + 1] = this.dropVelocities[offset + 1] * drag - 9.81 * delta;
-      this.dropVelocities[offset + 2] *= drag;
-      this.dropPositions[offset] += this.dropVelocities[offset] * delta;
-      this.dropPositions[offset + 1] += this.dropVelocities[offset + 1] * delta;
-      this.dropPositions[offset + 2] += this.dropVelocities[offset + 2] * delta;
-
-      if (this.dropPositions[offset + 1] <= floorY && this.dropVelocities[offset + 1] < 0) {
-        if (this.dropBounces[i] === 0) {
-          const impact = -this.dropVelocities[offset + 1];
-          const angle = Math.random() * Math.PI * 2;
-          const radial = impact * (0.08 + Math.random() * 0.11);
-          this.dropPositions[offset + 1] = floorY + 0.006;
-          this.dropVelocities[offset] = Math.cos(angle) * radial;
-          this.dropVelocities[offset + 1] = impact * (0.17 + Math.random() * 0.12);
-          this.dropVelocities[offset + 2] = Math.sin(angle) * radial;
-          this.dropBounces[i] = 1;
-          this.dropLife[i] = Math.min(this.dropLife[i], 0.48 + Math.random() * 0.18);
-          this.dropSizes[i] *= 0.72;
-        } else {
-          this.dropLife[i] = 0;
-        }
-      }
-
-      if (this.dropLife[i] <= 0) {
-        this.dropAlpha[i] = 0;
-        this.dropPositions[offset + 1] = -100;
-      } else {
-        const lifeRatio = this.dropLife[i] / Math.max(this.dropMaxLife[i], 0.001);
-        this.dropAlpha[i] = THREE.MathUtils.clamp(lifeRatio * 1.35, 0, 1);
-      }
-    }
-
-    this.spillPoints.geometry.attributes.position.needsUpdate = true;
-    this.spillPoints.geometry.attributes.aAlpha.needsUpdate = true;
-    this.spillPoints.geometry.attributes.aSize.needsUpdate = true;
-  }
-
-  updateGeometry(): void {
-    const waterHeight = Math.max(0.001, this.waterY - this.innerBottomY);
-    this.waterBody.scale.y = waterHeight;
-    this.waterBody.position.y = this.innerBottomY + waterHeight * 0.5;
-    this.waterBody.visible = this.active && this.volume > 0.0005 && !this.particleFluidMode;
-    if (this.surface) {
-      this.surface.setBounds({
-        basinMinX: this.minX,
-        basinMaxX: this.maxX,
-        basinHalfZ: this.innerWidth * 0.5,
-        basinCenterZ: this.centerZ,
-        waterY: this.waterY,
-      });
-      this.surface.mesh.visible = this.active && this.volume > 0.0005 && !this.particleFluidMode;
-    }
-  }
-
-  update(
-    delta: number,
-    elapsed: number,
-    {
-      flowRate,
-      captureFraction = 0,
-      impactX,
-      impactZ = 0,
-      impactEnergy = 0,
-      emitting = false,
-    }: ReservoirUpdateOptions,
-  ): ReservoirUpdateResult {
-    this.updateContainerMotion(delta);
-    const effectiveCapture = this.active && emitting ? THREE.MathUtils.clamp(captureFraction, 0, 1) : 0;
-    const captured = effectiveCapture > 0.001;
-    const incomingRate = flowRate * effectiveCapture;
-    const incomingVolume = incomingRate * delta;
-    const available = Math.max(0, this.capacity - this.volume);
-    const stored = Math.min(available, incomingVolume);
-    const overflowVolume = Math.max(0, incomingVolume - stored);
-    this.volume = Math.min(this.capacity, this.volume + stored);
-    const freeboard = Math.max(0, this.maxWaterY - this.waterY);
-    const crestRise = Math.max(Math.abs(this.sloshOffset.x), Math.abs(this.sloshOffset.y));
-    const overtoppingHead = Math.max(0, crestRise - freeboard);
-    this.motionOverflowRate = this.active
-      ? Math.min(0.38, overtoppingHead * this.surfaceArea * 1.25)
-      : 0;
-    const motionOverflowVolume = Math.min(this.volume, this.motionOverflowRate * delta);
-    this.volume = Math.max(0, this.volume - motionOverflowVolume);
-    this.overflowRate = (delta > 0 ? overflowVolume / delta : 0) + this.motionOverflowRate;
-    const targetOverflow = THREE.MathUtils.clamp(this.overflowRate / 0.16, 0, 1);
-    this.overflowIntensity = THREE.MathUtils.lerp(
-      this.overflowIntensity,
-      targetOverflow,
-      1 - Math.exp(-delta * (targetOverflow > this.overflowIntensity ? 5.5 : 2.2)),
-    );
-    this.updateGeometry();
-
-    this.waterMaterial.uniforms.uTime.value = elapsed;
-    this.overflowMaterial.uniforms.uTime.value = elapsed;
-    this.overflowMaterial.uniforms.uOverflow.value = this.overflowIntensity;
-    this.overflowGroup.visible = this.active && this.overflowIntensity > 0.008;
-    this.rimFoamMaterial.opacity = this.overflowIntensity * 0.38;
-    this.rimFoamGroup.visible = this.active && this.overflowIntensity > 0.025;
-    this.updateSpillParticles(delta);
-
-    if (this.active) {
-      this.surface?.update(delta, elapsed, impactX, impactEnergy, captured && emitting, impactZ);
-    }
-    return {
-      captured,
-      captureFraction: effectiveCapture,
-      incomingRate,
-      missedRate: Math.max(0, flowRate - incomingRate),
-      overflowRate: this.overflowRate,
-    };
-  }
-
-  setPixelRatio(pixelRatio: number): void {
-    this.dropMaterial.uniforms.uPixelRatio.value = Math.min(pixelRatio, 2);
-  }
-
-  get fillRatio(): number {
-    return this.capacity > 0 ? this.volume / this.capacity : 0;
-  }
-
-  get waterY(): number {
-    return THREE.MathUtils.lerp(this.innerBottomY, this.maxWaterY, this.fillRatio);
-  }
-
-  get centerX(): number {
-    return this.group.position.x;
-  }
-
-  get centerZ(): number {
-    return this.group.position.z;
-  }
-
-  get minX(): number {
-    return this.centerX - this.innerLength * 0.5;
-  }
-
-  get maxX(): number {
-    return this.centerX + this.innerLength * 0.5;
-  }
-
-  get collisionBounds(): BasinConfig {
-    return {
-      minX: this.minX,
-      maxX: this.maxX,
-      halfZ: this.innerWidth * 0.5,
-      centerZ: this.centerZ,
-      waterY: this.waterY,
-      wallTop: this.rimY,
-      containerFloorY: this.innerBottomY,
-    };
-  }
-}
+import * as THREE from 'three';
+import { ShallowWaterSurface } from './ShallowWaterSurface';
+import type { BasinConfig } from './types';
+
+/**
+ * 构造选项：几何口径（length/width/壁高）+ 平面位置（centerX/centerZ）+ 尾流水面网格分辨率。
+ * flowTexture 是溢出水花着色器采样的噪声图，缺省时 uniforms.uFlowMap 为 undefined。
+ */
+export interface ReservoirOptions {
+    flowTexture?: THREE.Texture;
+    length?: number;
+    width?: number;
+    bottomY?: number;
+    rimY?: number;
+    centerX?: number;
+    centerZ?: number;
+    waveWidth?: number;
+    waveHeight?: number;
+}
+
+/** update 的入参：入口水流量 + 撞击点/能量 + 是否正在喷射。 */
+export interface ReservoirUpdateOptions {
+    flowRate: number;
+    captureFraction?: number;
+    impactX: number;
+    impactZ?: number;
+    impactEnergy?: number;
+    emitting?: boolean;
+}
+
+/** update 的出参：本次入流/溢流的口径，供调用方做音效或统计。 */
+export interface ReservoirUpdateResult {
+    captured: boolean;
+    captureFraction: number;
+    incomingRate: number;
+    missedRate: number;
+    overflowRate: number;
+}
+
+export class ReservoirSystem {
+  /** 几何口径（全部由构造参数推导，构造后不变）。 */
+  private readonly length: number;
+  private readonly width: number;
+  private readonly bottomY: number;
+  private readonly rimY: number;
+  private readonly innerBottomY: number;
+  private readonly maxWaterY: number;
+  private readonly innerLength: number;
+  private readonly innerWidth: number;
+  private readonly surfaceArea: number;
+  private readonly capacity: number;
+
+  /** 水量与溢流状态（每帧变化）。 */
+  private volume: number;
+  private overflowRate: number;
+  private motionOverflowRate: number;
+  private overflowIntensity: number;
+  private active: boolean;
+  private particleFluidMode: boolean;
+
+  /** 容器晃动（xz 两个分量复用 Vector2 的 x/y）。 */
+  private readonly motionPreviousPosition: THREE.Vector2;
+  private readonly motionVelocity: THREE.Vector2;
+  private readonly motionAcceleration: THREE.Vector2;
+  private readonly sloshOffset: THREE.Vector2;
+  private readonly sloshVelocity: THREE.Vector2;
+  private readonly motionWaveImpulse: THREE.Vector2;
+
+  /** 池体节点与拾取体。 */
+  readonly renderer: THREE.WebGLRenderer;
+  readonly group: THREE.Group;
+  readonly hitMeshes: THREE.Mesh[];
+
+  readonly rimFoamMaterial: THREE.MeshBasicMaterial;
+  readonly rimFoamGroup: THREE.Group;
+  readonly waterMaterial: THREE.ShaderMaterial;
+  readonly waterBody: THREE.Mesh;
+  /** 浅水波面；非WebGL2 或缺浮点扩展时为 null（此时只保留水体盒）。 */
+  readonly surface: ShallowWaterSurface | null;
+  readonly overflowMaterial: THREE.ShaderMaterial;
+  readonly overflowGroup: THREE.Group;
+
+  /** 溢流粒子（GPU points）的缓冲与状态。 */
+  readonly dropCount: number;
+  private readonly dropPositions: Float32Array;
+  private readonly dropVelocities: Float32Array;
+  private readonly dropLife: Float32Array;
+  private readonly dropMaxLife: Float32Array;
+  private readonly dropBounces: Uint8Array;
+  private readonly dropSizes: Float32Array;
+  private readonly dropAlpha: Float32Array;
+  private dropCursor: number;
+  private dropAccumulator: number;
+  readonly dropMaterial: THREE.ShaderMaterial;
+  readonly spillPoints: THREE.Points;
+
+  constructor(renderer: THREE.WebGLRenderer, {
+    flowTexture,
+    length = 1.72,
+    width = 1.28,
+    bottomY = -0.13,
+    rimY = 1.14,
+    centerX = 1.82,
+    centerZ = 0,
+    waveWidth = 192,
+    waveHeight = 128,
+  }: ReservoirOptions = {}) {
+    this.renderer = renderer;
+    this.length = length;
+    this.width = width;
+    this.bottomY = bottomY;
+    this.rimY = rimY;
+    this.innerBottomY = bottomY + 0.11;
+    this.maxWaterY = rimY - 0.024;
+    this.innerLength = length - 0.14;
+    this.innerWidth = width - 0.14;
+    this.surfaceArea = this.innerLength * this.innerWidth;
+    this.capacity = this.surfaceArea * (this.maxWaterY - this.innerBottomY);
+    this.volume = 0;
+    this.overflowRate = 0;
+    this.motionOverflowRate = 0;
+    this.overflowIntensity = 0;
+    this.active = false;
+    this.motionPreviousPosition = new THREE.Vector2(centerX, centerZ);
+    this.motionVelocity = new THREE.Vector2();
+    this.motionAcceleration = new THREE.Vector2();
+    this.sloshOffset = new THREE.Vector2();
+    this.sloshVelocity = new THREE.Vector2();
+    this.motionWaveImpulse = new THREE.Vector2();
+    this.particleFluidMode = false;
+
+    this.group = new THREE.Group();
+    this.group.position.set(centerX, 0, centerZ);
+    this.hitMeshes = [];
+
+    const steel = new THREE.MeshStandardMaterial({ color: 0x71878d, roughness: 0.2, metalness: 0.92 });
+    const darkSteel = new THREE.MeshStandardMaterial({ color: 0x172a30, roughness: 0.36, metalness: 0.78 });
+    const glass = new THREE.MeshPhysicalMaterial({
+      color: 0x9edbe2,
+      metalness: 0,
+      roughness: 0.08,
+      transmission: 0.9,
+      transparent: true,
+      opacity: 0.19,
+      thickness: 0.04,
+      ior: 1.48,
+      clearcoat: 1,
+      clearcoatRoughness: 0.04,
+      depthWrite: false,
+      side: THREE.DoubleSide,
+    });
+
+    const wallThickness = 0.035;
+    const tankHeight = rimY - bottomY;
+    const frontBackGeometry = new THREE.BoxGeometry(length, tankHeight, wallThickness);
+    const sideGeometry = new THREE.BoxGeometry(wallThickness, tankHeight, width);
+    [-1, 1].forEach((side) => {
+      const wall = new THREE.Mesh(frontBackGeometry, glass);
+      wall.position.set(0, bottomY + tankHeight * 0.5, side * width * 0.5);
+      wall.renderOrder = 6;
+      this.group.add(wall);
+      this.hitMeshes.push(wall);
+    });
+    [-1, 1].forEach((side) => {
+      const wall = new THREE.Mesh(sideGeometry, glass);
+      wall.position.set(side * length * 0.5, bottomY + tankHeight * 0.5, 0);
+      wall.renderOrder = 6;
+      this.group.add(wall);
+      this.hitMeshes.push(wall);
+    });
+
+    const base = new THREE.Mesh(new THREE.BoxGeometry(length + 0.08, 0.09, width + 0.08), darkSteel);
+    base.position.y = bottomY + 0.025;
+    base.castShadow = true;
+    base.receiveShadow = true;
+    this.group.add(base);
+    this.hitMeshes.push(base);
+
+    const rail = 0.045;
+    const verticalGeometry = new THREE.BoxGeometry(rail, tankHeight + 0.08, rail);
+    for (const x of [-1, 1]) {
+      for (const z of [-1, 1]) {
+        const post = new THREE.Mesh(verticalGeometry, steel);
+        post.position.set(x * length * 0.5, bottomY + tankHeight * 0.5, z * width * 0.5);
+        post.castShadow = true;
+        this.group.add(post);
+      }
+    }
+    const railXGeometry = new THREE.BoxGeometry(length + 0.08, rail, rail);
+    const railZGeometry = new THREE.BoxGeometry(rail, rail, width + 0.08);
+    for (const y of [bottomY + 0.035, rimY]) {
+      for (const z of [-1, 1]) {
+        const edge = new THREE.Mesh(railXGeometry, steel);
+        edge.position.set(0, y, z * width * 0.5);
+        edge.castShadow = true;
+        this.group.add(edge);
+      }
+      for (const x of [-1, 1]) {
+        const edge = new THREE.Mesh(railZGeometry, steel);
+        edge.position.set(x * length * 0.5, y, 0);
+        edge.castShadow = true;
+        this.group.add(edge);
+      }
+    }
+
+    this.rimFoamMaterial = new THREE.MeshBasicMaterial({
+      color: 0xbdeff4,
+      transparent: true,
+      opacity: 0,
+      depthWrite: false,
+      blending: THREE.AdditiveBlending,
+    });
+    this.rimFoamGroup = new THREE.Group();
+    const foamX = new THREE.BoxGeometry(this.innerLength * 0.96, 0.012, 0.025);
+    const foamZ = new THREE.BoxGeometry(0.025, 0.012, this.innerWidth * 0.96);
+    for (const z of [-1, 1]) {
+      const foam = new THREE.Mesh(foamX, this.rimFoamMaterial);
+      foam.position.set(0, this.maxWaterY + 0.014, z * this.innerWidth * 0.5);
+      this.rimFoamGroup.add(foam);
+    }
+    for (const x of [-1, 1]) {
+      const foam = new THREE.Mesh(foamZ, this.rimFoamMaterial);
+      foam.position.set(x * this.innerLength * 0.5, this.maxWaterY + 0.014, 0);
+      this.rimFoamGroup.add(foam);
+    }
+    this.group.add(this.rimFoamGroup);
+
+    this.waterMaterial = new THREE.ShaderMaterial({
+      uniforms: {
+        uTime: { value: 0 },
+        uFlowMap: { value: flowTexture },
+        uOpacity: { value: 0.42 },
+      },
+      vertexShader: /* glsl */`
+        varying vec2 vUv;
+        varying vec3 vWorldPosition;
+        varying vec3 vWorldNormal;
+        void main() {
+          vUv = uv;
+          vec4 world = modelMatrix * vec4(position, 1.0);
+          vWorldPosition = world.xyz;
+          vWorldNormal = normalize(mat3(modelMatrix) * normal);
+          gl_Position = projectionMatrix * viewMatrix * world;
+        }
+      `,
+      fragmentShader: /* glsl */`
+        uniform float uTime;
+        uniform float uOpacity;
+        uniform sampler2D uFlowMap;
+        varying vec2 vUv;
+        varying vec3 vWorldPosition;
+        varying vec3 vWorldNormal;
+        void main() {
+          vec3 viewDir = normalize(cameraPosition - vWorldPosition);
+          float fresnel = 0.02 + 0.98 * pow(1.0 - abs(dot(viewDir, normalize(vWorldNormal))), 5.0);
+          vec3 detail = texture2D(uFlowMap, vUv * vec2(1.6, 2.8) + vec2(0.0, uTime * 0.018)).rgb;
+          float depthTint = smoothstep(-0.2, 1.2, vWorldPosition.y);
+          vec3 color = mix(vec3(0.008, 0.12, 0.16), vec3(0.035, 0.34, 0.4), depthTint);
+          color += detail * 0.035 + vec3(0.2, 0.62, 0.68) * fresnel * 0.42;
+          gl_FragColor = vec4(color, uOpacity + fresnel * 0.18);
+        }
+      `,
+      transparent: true,
+      depthWrite: false,
+      side: THREE.DoubleSide,
+    });
+    this.waterBody = new THREE.Mesh(new THREE.BoxGeometry(this.innerLength, 1, this.innerWidth), this.waterMaterial);
+    this.waterBody.renderOrder = 3;
+    this.group.add(this.waterBody);
+
+    this.surface = renderer.capabilities.isWebGL2 && renderer.extensions.has('EXT_color_buffer_float')
+      ? new ShallowWaterSurface(renderer, {
+        width: waveWidth,
+        height: waveHeight,
+        basinMinX: centerX - this.innerLength * 0.5,
+        basinMaxX: centerX + this.innerLength * 0.5,
+        basinHalfZ: this.innerWidth * 0.5,
+        basinCenterZ: centerZ,
+        waterY: this.innerBottomY,
+        cpuSampling: true,
+      })
+      : null;
+    if (this.surface) this.surface.mesh.renderOrder = 5;
+
+    this.overflowMaterial = new THREE.ShaderMaterial({
+      uniforms: {
+        uTime: { value: 0 },
+        uOverflow: { value: 0 },
+        uFlowMap: { value: flowTexture },
+      },
+      vertexShader: /* glsl */`
+        uniform float uTime;
+        uniform float uOverflow;
+        varying vec2 vUv;
+        void main() {
+          vUv = uv;
+          vec3 p = position;
+          float fall = 1.0 - uv.y;
+          p.x *= mix(0.7, 1.0, uv.y);
+          p.z += sin(uv.x * 29.0 + uTime * 5.0) * 0.012 * fall * uOverflow;
+          p.y -= sin(uv.x * 17.0 + uTime * 3.7) * 0.016 * fall;
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
+        }
+      `,
+      fragmentShader: /* glsl */`
+        uniform float uTime;
+        uniform float uOverflow;
+        uniform sampler2D uFlowMap;
+        varying vec2 vUv;
+        void main() {
+          vec2 flowUvA = vec2(vUv.x * 5.7 + uTime * 0.035, vUv.y * 7.5 + uTime * 0.82);
+          vec2 flowUvB = vec2(vUv.x * 9.3 - uTime * 0.028, vUv.y * 4.2 + uTime * 0.57);
+          float noiseA = dot(texture2D(uFlowMap, flowUvA).rgb, vec3(0.2, 0.58, 0.22));
+          float noiseB = dot(texture2D(uFlowMap, flowUvB).rgb, vec3(0.35, 0.5, 0.15));
+          float noise = mix(noiseA, noiseB, 0.46);
+          float rivuletField = 0.5 + 0.5 * sin(vUv.x * 71.0 + noise * 9.0 + sin(vUv.y * 13.0) * 2.2);
+          float rivulets = smoothstep(0.54 - uOverflow * 0.08, 0.86, rivuletField);
+          float edge = smoothstep(0.0, 0.13, vUv.x) * smoothstep(1.0, 0.87, vUv.x);
+          float verticalFade = smoothstep(0.0, 0.12, vUv.y);
+          float breakup = smoothstep(0.27, 0.76, noise + vUv.y * 0.16);
+          float alpha = edge * verticalFade * rivulets * breakup * (0.2 + uOverflow * 0.62);
+          if (alpha < 0.025 || uOverflow < 0.01) discard;
+          vec3 color = mix(vec3(0.045, 0.32, 0.38), vec3(0.58, 0.92, 0.97), noise * 0.3);
+          gl_FragColor = vec4(color, alpha);
+        }
+      `,
+      transparent: true,
+      depthWrite: false,
+      side: THREE.DoubleSide,
+    });
+
+    this.overflowGroup = new THREE.Group();
+    const sheetHeight = 0.62;
+    const makeSheet = (sheetWidth: number, x: number, z: number, rotationY = 0): void => {
+      const sheet = new THREE.Mesh(new THREE.PlaneGeometry(sheetWidth, sheetHeight, 48, 24), this.overflowMaterial);
+      sheet.position.set(x, rimY - sheetHeight * 0.5 - 0.012, z);
+      sheet.rotation.y = rotationY;
+      sheet.renderOrder = 7;
+      this.overflowGroup.add(sheet);
+    };
+    makeSheet(length * 0.78, 0, -width * 0.5 - 0.026);
+    makeSheet(length * 0.78, 0, width * 0.5 + 0.026);
+    makeSheet(width * 0.72, -length * 0.5 - 0.026, 0, Math.PI * 0.5);
+    makeSheet(width * 0.72, length * 0.5 + 0.026, 0, Math.PI * 0.5);
+    this.group.add(this.overflowGroup);
+
+    this.dropCount = waveWidth <= 112 ? 650 : 1400;
+    this.dropPositions = new Float32Array(this.dropCount * 3);
+    this.dropVelocities = new Float32Array(this.dropCount * 3);
+    this.dropLife = new Float32Array(this.dropCount);
+    this.dropMaxLife = new Float32Array(this.dropCount);
+    this.dropBounces = new Uint8Array(this.dropCount);
+    this.dropSizes = new Float32Array(this.dropCount);
+    this.dropAlpha = new Float32Array(this.dropCount);
+    this.dropCursor = 0;
+    this.dropAccumulator = 0;
+    this.dropPositions.fill(-100);
+
+    const dropGeometry = new THREE.BufferGeometry();
+    const positionAttribute = new THREE.BufferAttribute(this.dropPositions, 3);
+    positionAttribute.setUsage(THREE.DynamicDrawUsage);
+    const alphaAttribute = new THREE.BufferAttribute(this.dropAlpha, 1);
+    alphaAttribute.setUsage(THREE.DynamicDrawUsage);
+    const sizeAttribute = new THREE.BufferAttribute(this.dropSizes, 1);
+    sizeAttribute.setUsage(THREE.DynamicDrawUsage);
+    dropGeometry.setAttribute('position', positionAttribute);
+    dropGeometry.setAttribute('aAlpha', alphaAttribute);
+    dropGeometry.setAttribute('aSize', sizeAttribute);
+    this.dropMaterial = new THREE.ShaderMaterial({
+      uniforms: {
+        uPixelRatio: { value: Math.min(devicePixelRatio, 2) },
+      },
+      vertexShader: /* glsl */`
+        attribute float aAlpha;
+        attribute float aSize;
+        uniform float uPixelRatio;
+        varying float vAlpha;
+        void main() {
+          vec4 mv = modelViewMatrix * vec4(position, 1.0);
+          gl_Position = aAlpha > 0.001 ? projectionMatrix * mv : vec4(2.0, 2.0, 2.0, 1.0);
+          gl_PointSize = min(7.5, aSize * uPixelRatio * (5.0 / max(2.0, -mv.z)));
+          vAlpha = aAlpha;
+        }
+      `,
+      fragmentShader: /* glsl */`
+        varying float vAlpha;
+        void main() {
+          float d = length(gl_PointCoord - 0.5);
+          if (d > 0.5) discard;
+          float core = smoothstep(0.5, 0.08, d);
+          float glint = 1.0 - smoothstep(0.015, 0.13, distance(gl_PointCoord, vec2(0.34, 0.3)));
+          float alpha = core * vAlpha;
+          gl_FragColor = vec4(vec3(0.42, 0.87, 0.96) + glint * 0.45, alpha);
+        }
+      `,
+      transparent: true,
+      depthWrite: false,
+      blending: THREE.AdditiveBlending,
+      toneMapped: false,
+    });
+    this.spillPoints = new THREE.Points(dropGeometry, this.dropMaterial);
+    this.spillPoints.frustumCulled = false;
+    this.spillPoints.renderOrder = 8;
+
+    this.reset();
+    this.setActive(false);
+  }
+
+  setActive(active: boolean): void {
+    this.active = active;
+    this.group.visible = active;
+    if (this.surface) this.surface.mesh.visible = active && this.volume > 0.0005 && !this.particleFluidMode;
+    if (active) this.motionPreviousPosition.set(this.centerX, this.centerZ);
+  }
+
+  setParticleFluidMode(enabled: boolean): void {
+    this.particleFluidMode = Boolean(enabled);
+    this.updateGeometry();
+  }
+
+  moveTo(x: number, z: number): void {
+    this.group.position.x = x;
+    this.group.position.z = z;
+    this.updateGeometry();
+  }
+
+  reset(fillRatio = 0): void {
+    this.volume = this.capacity * THREE.MathUtils.clamp(fillRatio, 0, 1);
+    this.overflowRate = 0;
+    this.motionOverflowRate = 0;
+    this.overflowIntensity = 0;
+    this.clearSpillParticles();
+    this.surface?.clear();
+    this.motionPreviousPosition.set(this.centerX, this.centerZ);
+    this.motionVelocity.set(0, 0);
+    this.motionAcceleration.set(0, 0);
+    this.sloshOffset.set(0, 0);
+    this.sloshVelocity.set(0, 0);
+    this.motionWaveImpulse.set(0, 0);
+    this.surface?.setContainerMotion(0, 0, 0, 0);
+    this.updateGeometry();
+  }
+
+  updateContainerMotion(delta: number): void {
+    const safeDelta = Math.max(delta, 1 / 240);
+    const currentX = this.centerX;
+    const currentZ = this.centerZ;
+    const rawVelocityX = THREE.MathUtils.clamp(
+      (currentX - this.motionPreviousPosition.x) / safeDelta,
+      -3.4,
+      3.4,
+    );
+    const rawVelocityZ = THREE.MathUtils.clamp(
+      (currentZ - this.motionPreviousPosition.y) / safeDelta,
+      -3.4,
+      3.4,
+    );
+    const previousVelocityX = this.motionVelocity.x;
+    const previousVelocityZ = this.motionVelocity.y;
+    const velocityResponse = 1 - Math.exp(-safeDelta * 18);
+    this.motionVelocity.x = THREE.MathUtils.lerp(previousVelocityX, rawVelocityX, velocityResponse);
+    this.motionVelocity.y = THREE.MathUtils.lerp(previousVelocityZ, rawVelocityZ, velocityResponse);
+    this.motionAcceleration.x = THREE.MathUtils.clamp(
+      (this.motionVelocity.x - previousVelocityX) / safeDelta,
+      -22,
+      22,
+    );
+    this.motionAcceleration.y = THREE.MathUtils.clamp(
+      (this.motionVelocity.y - previousVelocityZ) / safeDelta,
+      -22,
+      22,
+    );
+    this.motionPreviousPosition.set(currentX, currentZ);
+
+    const omega = 3.65;
+    const damping = 0.28;
+    const targetX = THREE.MathUtils.clamp(
+      -this.motionAcceleration.x / 9.81 * this.innerLength * 0.5,
+      -0.18,
+      0.18,
+    );
+    const targetZ = THREE.MathUtils.clamp(
+      -this.motionAcceleration.y / 9.81 * this.innerWidth * 0.5,
+      -0.15,
+      0.15,
+    );
+    const dampingForce = 2 * damping * omega;
+    this.sloshVelocity.x += (
+      (targetX - this.sloshOffset.x) * omega * omega - this.sloshVelocity.x * dampingForce
+    ) * safeDelta;
+    this.sloshVelocity.y += (
+      (targetZ - this.sloshOffset.y) * omega * omega - this.sloshVelocity.y * dampingForce
+    ) * safeDelta;
+    this.sloshOffset.addScaledVector(this.sloshVelocity, safeDelta);
+    this.sloshOffset.x = THREE.MathUtils.clamp(this.sloshOffset.x, -0.16, 0.16);
+    this.sloshOffset.y = THREE.MathUtils.clamp(this.sloshOffset.y, -0.13, 0.13);
+
+    this.motionWaveImpulse.set(
+      -this.motionAcceleration.x * safeDelta * 0.00015,
+      -this.motionAcceleration.y * safeDelta * 0.00015,
+    );
+    if (!this.active || this.volume < 0.0005) {
+      this.sloshOffset.multiplyScalar(Math.exp(-safeDelta * 5));
+      this.sloshVelocity.multiplyScalar(Math.exp(-safeDelta * 5));
+      this.motionWaveImpulse.set(0, 0);
+    }
+    this.surface?.setContainerMotion(
+      this.sloshOffset.x,
+      this.sloshOffset.y,
+      this.motionWaveImpulse.x,
+      this.motionWaveImpulse.y,
+    );
+  }
+
+  clearSpillParticles(): void {
+    if (!this.dropLife) return;
+    this.dropLife.fill(0);
+    this.dropAlpha.fill(0);
+    this.dropPositions.fill(-100);
+    this.dropAccumulator = 0;
+    if (this.spillPoints) {
+      this.spillPoints.geometry.attributes.position.needsUpdate = true;
+      this.spillPoints.geometry.attributes.aAlpha.needsUpdate = true;
+    }
+  }
+
+  spawnSpillParticle(): void {
+    let index = -1;
+    for (let attempt = 0; attempt < this.dropCount; attempt++) {
+      const candidate = (this.dropCursor + attempt) % this.dropCount;
+      if (this.dropLife[candidate] <= 0) {
+        index = candidate;
+        this.dropCursor = (candidate + 1) % this.dropCount;
+        break;
+      }
+    }
+    if (index < 0) return;
+
+    let edge = Math.floor(Math.random() * 4);
+    if (this.motionOverflowRate > 0.002) {
+      if (Math.abs(this.sloshOffset.x) > Math.abs(this.sloshOffset.y)) {
+        edge = this.sloshOffset.x >= 0 ? 3 : 2;
+      } else {
+        edge = this.sloshOffset.y >= 0 ? 0 : 1;
+      }
+    }
+    const along = Math.random() - 0.5;
+    const speedOut = 0.1 + Math.random() * 0.24 + this.overflowIntensity * 0.22;
+    const velocityOffset = index * 3;
+    const positionOffset = index * 3;
+    let x = this.centerX;
+    let z = this.centerZ;
+    let vx = (Math.random() - 0.5) * 0.08;
+    let vz = (Math.random() - 0.5) * 0.08;
+
+    if (edge === 0) {
+      x += along * this.innerLength * 0.92;
+      z += this.innerWidth * 0.5 + 0.015;
+      vz += speedOut;
+    } else if (edge === 1) {
+      x += along * this.innerLength * 0.92;
+      z -= this.innerWidth * 0.5 + 0.015;
+      vz -= speedOut;
+    } else if (edge === 2) {
+      x -= this.innerLength * 0.5 + 0.015;
+      z += along * this.innerWidth * 0.9;
+      vx -= speedOut;
+    } else {
+      x += this.innerLength * 0.5 + 0.015;
+      z += along * this.innerWidth * 0.9;
+      vx += speedOut;
+    }
+
+    this.dropPositions[positionOffset] = x;
+    this.dropPositions[positionOffset + 1] = this.maxWaterY + 0.012 + Math.random() * 0.018;
+    this.dropPositions[positionOffset + 2] = z;
+    this.dropVelocities[velocityOffset] = vx;
+    this.dropVelocities[velocityOffset + 1] = 0.03 + Math.random() * 0.19;
+    this.dropVelocities[velocityOffset + 2] = vz;
+    this.dropLife[index] = 1.25 + Math.random() * 0.8;
+    this.dropMaxLife[index] = this.dropLife[index];
+    this.dropBounces[index] = 0;
+    this.dropSizes[index] = 2.2 + Math.random() * 3.3;
+    this.dropAlpha[index] = 0.75 + Math.random() * 0.25;
+  }
+
+  updateSpillParticles(delta: number): void {
+    if (this.active && this.overflowRate > 0.0001) {
+      const spawnRate = Math.min(this.dropCount * 0.86, 140 + this.overflowRate * 2600);
+      this.dropAccumulator += spawnRate * delta;
+      const spawnCount = Math.min(48, Math.floor(this.dropAccumulator));
+      this.dropAccumulator -= spawnCount;
+      for (let i = 0; i < spawnCount; i++) this.spawnSpillParticle();
+    }
+
+    const floorY = -0.17;
+    const drag = Math.exp(-0.18 * delta);
+    for (let i = 0; i < this.dropCount; i++) {
+      if (this.dropLife[i] <= 0) continue;
+      const offset = i * 3;
+      this.dropLife[i] -= delta;
+      this.dropVelocities[offset] *= drag;
+      this.dropVelocities[offset + 1] = this.dropVelocities[offset + 1] * drag - 9.81 * delta;
+      this.dropVelocities[offset + 2] *= drag;
+      this.dropPositions[offset] += this.dropVelocities[offset] * delta;
+      this.dropPositions[offset + 1] += this.dropVelocities[offset + 1] * delta;
+      this.dropPositions[offset + 2] += this.dropVelocities[offset + 2] * delta;
+
+      if (this.dropPositions[offset + 1] <= floorY && this.dropVelocities[offset + 1] < 0) {
+        if (this.dropBounces[i] === 0) {
+          const impact = -this.dropVelocities[offset + 1];
+          const angle = Math.random() * Math.PI * 2;
+          const radial = impact * (0.08 + Math.random() * 0.11);
+          this.dropPositions[offset + 1] = floorY + 0.006;
+          this.dropVelocities[offset] = Math.cos(angle) * radial;
+          this.dropVelocities[offset + 1] = impact * (0.17 + Math.random() * 0.12);
+          this.dropVelocities[offset + 2] = Math.sin(angle) * radial;
+          this.dropBounces[i] = 1;
+          this.dropLife[i] = Math.min(this.dropLife[i], 0.48 + Math.random() * 0.18);
+          this.dropSizes[i] *= 0.72;
+        } else {
+          this.dropLife[i] = 0;
+        }
+      }
+
+      if (this.dropLife[i] <= 0) {
+        this.dropAlpha[i] = 0;
+        this.dropPositions[offset + 1] = -100;
+      } else {
+        const lifeRatio = this.dropLife[i] / Math.max(this.dropMaxLife[i], 0.001);
+        this.dropAlpha[i] = THREE.MathUtils.clamp(lifeRatio * 1.35, 0, 1);
+      }
+    }
+
+    this.spillPoints.geometry.attributes.position.needsUpdate = true;
+    this.spillPoints.geometry.attributes.aAlpha.needsUpdate = true;
+    this.spillPoints.geometry.attributes.aSize.needsUpdate = true;
+  }
+
+  updateGeometry(): void {
+    const waterHeight = Math.max(0.001, this.waterY - this.innerBottomY);
+    this.waterBody.scale.y = waterHeight;
+    this.waterBody.position.y = this.innerBottomY + waterHeight * 0.5;
+    this.waterBody.visible = this.active && this.volume > 0.0005 && !this.particleFluidMode;
+    if (this.surface) {
+      this.surface.setBounds({
+        basinMinX: this.minX,
+        basinMaxX: this.maxX,
+        basinHalfZ: this.innerWidth * 0.5,
+        basinCenterZ: this.centerZ,
+        waterY: this.waterY,
+      });
+      this.surface.mesh.visible = this.active && this.volume > 0.0005 && !this.particleFluidMode;
+    }
+  }
+
+  update(
+    delta: number,
+    elapsed: number,
+    {
+      flowRate,
+      captureFraction = 0,
+      impactX,
+      impactZ = 0,
+      impactEnergy = 0,
+      emitting = false,
+    }: ReservoirUpdateOptions,
+  ): ReservoirUpdateResult {
+    this.updateContainerMotion(delta);
+    const effectiveCapture = this.active && emitting ? THREE.MathUtils.clamp(captureFraction, 0, 1) : 0;
+    const captured = effectiveCapture > 0.001;
+    const incomingRate = flowRate * effectiveCapture;
+    const incomingVolume = incomingRate * delta;
+    const available = Math.max(0, this.capacity - this.volume);
+    const stored = Math.min(available, incomingVolume);
+    const overflowVolume = Math.max(0, incomingVolume - stored);
+    this.volume = Math.min(this.capacity, this.volume + stored);
+    const freeboard = Math.max(0, this.maxWaterY - this.waterY);
+    const crestRise = Math.max(Math.abs(this.sloshOffset.x), Math.abs(this.sloshOffset.y));
+    const overtoppingHead = Math.max(0, crestRise - freeboard);
+    this.motionOverflowRate = this.active
+      ? Math.min(0.38, overtoppingHead * this.surfaceArea * 1.25)
+      : 0;
+    const motionOverflowVolume = Math.min(this.volume, this.motionOverflowRate * delta);
+    this.volume = Math.max(0, this.volume - motionOverflowVolume);
+    this.overflowRate = (delta > 0 ? overflowVolume / delta : 0) + this.motionOverflowRate;
+    const targetOverflow = THREE.MathUtils.clamp(this.overflowRate / 0.16, 0, 1);
+    this.overflowIntensity = THREE.MathUtils.lerp(
+      this.overflowIntensity,
+      targetOverflow,
+      1 - Math.exp(-delta * (targetOverflow > this.overflowIntensity ? 5.5 : 2.2)),
+    );
+    this.updateGeometry();
+
+    this.waterMaterial.uniforms.uTime.value = elapsed;
+    this.overflowMaterial.uniforms.uTime.value = elapsed;
+    this.overflowMaterial.uniforms.uOverflow.value = this.overflowIntensity;
+    this.overflowGroup.visible = this.active && this.overflowIntensity > 0.008;
+    this.rimFoamMaterial.opacity = this.overflowIntensity * 0.38;
+    this.rimFoamGroup.visible = this.active && this.overflowIntensity > 0.025;
+    this.updateSpillParticles(delta);
+
+    if (this.active) {
+      this.surface?.update(delta, elapsed, impactX, impactEnergy, captured && emitting, impactZ);
+    }
+    return {
+      captured,
+      captureFraction: effectiveCapture,
+      incomingRate,
+      missedRate: Math.max(0, flowRate - incomingRate),
+      overflowRate: this.overflowRate,
+    };
+  }
+
+  setPixelRatio(pixelRatio: number): void {
+    this.dropMaterial.uniforms.uPixelRatio.value = Math.min(pixelRatio, 2);
+  }
+
+  get fillRatio(): number {
+    return this.capacity > 0 ? this.volume / this.capacity : 0;
+  }
+
+  get waterY(): number {
+    return THREE.MathUtils.lerp(this.innerBottomY, this.maxWaterY, this.fillRatio);
+  }
+
+  get centerX(): number {
+    return this.group.position.x;
+  }
+
+  get centerZ(): number {
+    return this.group.position.z;
+  }
+
+  get minX(): number {
+    return this.centerX - this.innerLength * 0.5;
+  }
+
+  get maxX(): number {
+    return this.centerX + this.innerLength * 0.5;
+  }
+
+  get collisionBounds(): BasinConfig {
+    return {
+      minX: this.minX,
+      maxX: this.maxX,
+      halfZ: this.innerWidth * 0.5,
+      centerZ: this.centerZ,
+      waterY: this.waterY,
+      wallTop: this.rimY,
+      containerFloorY: this.innerBottomY,
+    };
+  }
+}