three-base 2.0.142 → 2.0.166

package/WaterFlow/FloatingDuck.ts

@@ -1,445 +1,445 @@
-import * as THREE from 'three';
-
-/** 鸭子可活动的水域边界（x 范围 + z 半宽 + 中心）。 */
-interface DuckBounds {
-    basinMinX: number;
-    basinMaxX: number;
-    basinHalfZ: number;
-    centerZ: number;
-}
-
-/** 水面采样结果（由 ShallowWaterSurface.sampleSurface 回填，供浮力/倾斜计算读高度与坡度）。 */
-interface DuckSurfaceSample {
-    height?: number;
-    velocityY?: number;
-    slopeX?: number;
-    slopeZ?: number;
-    flowX?: number;
-    flowZ?: number;
-    impact?: number;
-}
-
-/** 构造选项。 */
-export interface FloatingDuckOptions {
-    basinMinX: number;
-    basinMaxX: number;
-    basinHalfZ: number;
-    waterY: number;
-    startX?: number;
-    startZ?: number;
-}
-
-/** setEnvironment / clampToBounds 用的环境口径。 */
-export interface DuckEnvironment {
-    minX: number;
-    maxX: number;
-    halfZ: number;
-    centerZ?: number;
-    waterY: number;
-}
-
-/** update 的可调项。 */
-export interface DuckUpdateOptions {
-    surface?: DuckSurfaceSampler | null;
-    impactX?: number;
-    impactZ?: number;
-    impactEnergy?: number;
-    emitting?: boolean;
-}
-
-/** 只取 update 真正用到的水面能力（避免与 ShallowWaterSurface 形成类型环）。 */
-interface DuckSurfaceSampler {
-    sampleSurface(
-        worldX: number,
-        worldZ: number,
-        target?: DuckSurfaceSample,
-    ): DuckSurfaceSample;
-}
-
-/** 三元组（球体用：位置 / 缩放 / 旋转）。 */
-type Vec3Tuple = [number, number, number];
-
-function addScaledSphere(
-    group: THREE.Group,
-    geometry: THREE.BufferGeometry,
-    material: THREE.Material,
-    position: Vec3Tuple,
-    scale: Vec3Tuple,
-    rotation: Vec3Tuple | null = null,
-): THREE.Mesh {
-    const mesh = new THREE.Mesh(geometry, material);
-    mesh.position.set(...position);
-    mesh.scale.set(...scale);
-    if (rotation) mesh.rotation.set(...rotation);
-    mesh.castShadow = true;
-    mesh.receiveShadow = true;
-    group.add(mesh);
-    return mesh;
-}
-
-/** 漂浮的橡皮鸭：跟随水面高度/坡度做浮沉与倾斜，可被鼠标拖拽。 */
-export class FloatingDuck {
-    private readonly bounds: DuckBounds;
-    /** 静水面高度；setEnvironment 会随容器变化更新（故非 readonly）。 */
-    private waterY: number;
-    private readonly start: THREE.Vector3;
-    private readonly velocity: THREE.Vector3;
-    private readonly surfaceSample: DuckSurfaceSample;
-    private yaw: number;
-    private yawVelocity: number;
-    private pitch: number;
-    private roll: number;
-    private readonly radiusX: number;
-    private readonly radiusZ: number;
-    private active: boolean;
-    private dragging: boolean;
-    private readonly dragOffset: THREE.Vector2;
-    private readonly dragVelocity: THREE.Vector2;
-    private readonly lastDragPosition: THREE.Vector2;
-
-    private readonly group: THREE.Group;
-    private readonly model: THREE.Group;
-    private readonly pickGeometry: THREE.SphereGeometry;
-    private readonly pickMaterial: THREE.MeshBasicMaterial;
-    private readonly pickMesh: THREE.Mesh;
-
-    private readonly yellowMaterial: THREE.MeshPhysicalMaterial;
-    private readonly wingMaterial: THREE.MeshPhysicalMaterial;
-    private readonly beakMaterial: THREE.MeshPhysicalMaterial;
-    private readonly eyeMaterial: THREE.MeshStandardMaterial;
-    private readonly highlightMaterial: THREE.MeshBasicMaterial;
-
-    private readonly sphereGeometry: THREE.SphereGeometry;
-    private readonly body: THREE.Mesh;
-    private readonly head: THREE.Mesh;
-    private readonly beak: THREE.Mesh;
-    private readonly tailGeometry: THREE.ConeGeometry;
-    private readonly tail: THREE.Mesh;
-
-    constructor({
-        basinMinX,
-        basinMaxX,
-        basinHalfZ,
-        waterY,
-        startX = 1.2,
-        startZ = 0.24,
-    }: FloatingDuckOptions) {
-    this.bounds = { basinMinX, basinMaxX, basinHalfZ, centerZ: 0 };
-    this.waterY = waterY;
-    this.start = new THREE.Vector3(startX, waterY - 0.016, startZ);
-    this.velocity = new THREE.Vector3();
-    this.surfaceSample = {};
-    this.yaw = Math.PI;
-    this.yawVelocity = 0;
-    this.pitch = 0;
-    this.roll = 0;
-    this.radiusX = 0.19;
-    this.radiusZ = 0.145;
-    this.active = true;
-    this.dragging = false;
-    this.dragOffset = new THREE.Vector2();
-    this.dragVelocity = new THREE.Vector2();
-    this.lastDragPosition = new THREE.Vector2();
-
-    this.group = new THREE.Group();
-    this.group.name = 'floating-rubber-duck';
-    this.model = new THREE.Group();
-    this.group.add(this.model);
-
-    this.pickGeometry = new THREE.SphereGeometry(0.29, 12, 8);
-    this.pickMaterial = new THREE.MeshBasicMaterial({
-      transparent: true,
-      opacity: 0,
-      depthWrite: false,
-      colorWrite: false,
-    });
-    this.pickMesh = new THREE.Mesh(this.pickGeometry, this.pickMaterial);
-    this.pickMesh.name = 'rubber-duck-pick-volume';
-    this.pickMesh.position.y = 0.13;
-    this.pickMesh.layers.set(2);
-    this.group.add(this.pickMesh);
-
-    this.yellowMaterial = new THREE.MeshPhysicalMaterial({
-      color: 0xf2b705,
-      roughness: 0.46,
-      metalness: 0,
-      clearcoat: 0.32,
-      clearcoatRoughness: 0.28,
-    });
-    this.wingMaterial = new THREE.MeshPhysicalMaterial({
-      color: 0xd99b03,
-      roughness: 0.48,
-      metalness: 0,
-      clearcoat: 0.24,
-    });
-    this.beakMaterial = new THREE.MeshPhysicalMaterial({
-      color: 0xe85e06,
-      roughness: 0.42,
-      metalness: 0,
-      clearcoat: 0.25,
-    });
-    this.eyeMaterial = new THREE.MeshStandardMaterial({ color: 0x101518, roughness: 0.2 });
-    this.highlightMaterial = new THREE.MeshBasicMaterial({ color: 0xffffff });
-
-    this.sphereGeometry = new THREE.SphereGeometry(1, 32, 20);
-    this.body = addScaledSphere(
-      this.model,
-      this.sphereGeometry,
-      this.yellowMaterial,
-      [0, 0.072, 0],
-      [0.19, 0.12, 0.132],
-    );
-    this.head = addScaledSphere(
-      this.model,
-      this.sphereGeometry,
-      this.yellowMaterial,
-      [0.115, 0.205, 0],
-      [0.098, 0.102, 0.096],
-    );
-    this.beak = addScaledSphere(
-      this.model,
-      this.sphereGeometry,
-      this.beakMaterial,
-      [0.203, 0.191, 0],
-      [0.071, 0.026, 0.047],
-    );
-
-    for (const side of [-1, 1]) {
-      addScaledSphere(
-        this.model,
-        this.sphereGeometry,
-        this.wingMaterial,
-        [-0.02, 0.092, side * 0.115],
-        [0.105, 0.048, 0.052],
-        [side * 0.18, 0, side * 0.08],
-      );
-      addScaledSphere(
-        this.model,
-        this.sphereGeometry,
-        this.eyeMaterial,
-        [0.176, 0.237, side * 0.069],
-        [0.014, 0.017, 0.011],
-      );
-      addScaledSphere(
-        this.model,
-        this.sphereGeometry,
-        this.highlightMaterial,
-        [0.184, 0.244, side * 0.077],
-        [0.0045, 0.005, 0.0035],
-      );
-    }
-
-    this.tailGeometry = new THREE.ConeGeometry(0.052, 0.105, 20);
-    this.tail = new THREE.Mesh(this.tailGeometry, this.yellowMaterial);
-    this.tail.position.set(-0.177, 0.132, 0);
-    this.tail.rotation.z = -Math.PI * 0.5;
-    this.tail.castShadow = true;
-    this.model.add(this.tail);
-
-    this.reset();
-  }
-
-  setActive(active: boolean): void {
-    this.active = active;
-    this.group.visible = active;
-  }
-
-  setEnvironment({ minX, maxX, halfZ, centerZ = 0, waterY }: DuckEnvironment, reposition = false): void {
-    this.bounds.basinMinX = minX;
-    this.bounds.basinMaxX = maxX;
-    this.bounds.basinHalfZ = halfZ;
-    this.bounds.centerZ = centerZ;
-    this.waterY = waterY;
-    if (reposition) {
-      const receiverWidth = maxX - minX;
-      this.place(minX + Math.min(0.75, receiverWidth * 0.35), centerZ + Math.min(0.2, halfZ * 0.3));
-    } else {
-      this.clampToBounds();
-    }
-  }
-
-  place(x: number, z: number): void {
-    this.group.position.set(x, this.waterY - 0.016, z);
-    this.velocity.set(0, 0, 0);
-    this.clampToBounds();
-  }
-
-  translateContainer(deltaX: number, deltaZ: number): void {
-    this.group.position.x += deltaX;
-    this.group.position.z += deltaZ;
-    this.clampToBounds();
-  }
-
-  beginDrag(worldX: number, worldZ: number): void {
-    this.dragging = true;
-    this.dragOffset.set(this.group.position.x - worldX, this.group.position.z - worldZ);
-    this.lastDragPosition.set(this.group.position.x, this.group.position.z);
-    this.dragVelocity.set(0, 0);
-    this.velocity.x = 0;
-    this.velocity.z = 0;
-  }
-
-  dragTo(worldX: number, worldZ: number, deltaSeconds: number): void {
-    if (!this.dragging) return;
-    const previousX = this.group.position.x;
-    const previousZ = this.group.position.z;
-    this.group.position.x = worldX + this.dragOffset.x;
-    this.group.position.z = worldZ + this.dragOffset.y;
-    this.clampToBounds();
-    const inverseDelta = 1 / Math.max(deltaSeconds, 1 / 120);
-    const measuredX = (this.group.position.x - previousX) * inverseDelta;
-    const measuredZ = (this.group.position.z - previousZ) * inverseDelta;
-    this.dragVelocity.x = THREE.MathUtils.lerp(this.dragVelocity.x, measuredX, 0.42);
-    this.dragVelocity.y = THREE.MathUtils.lerp(this.dragVelocity.y, measuredZ, 0.42);
-    this.velocity.x = this.dragVelocity.x;
-    this.velocity.z = this.dragVelocity.y;
-    this.lastDragPosition.set(this.group.position.x, this.group.position.z);
-  }
-
-  endDrag(): void {
-    if (!this.dragging) return;
-    this.dragging = false;
-    const releaseSpeed = Math.hypot(this.dragVelocity.x, this.dragVelocity.y);
-    const releaseScale = releaseSpeed > 1.5 ? 1.5 / releaseSpeed : 1;
-    this.velocity.x = this.dragVelocity.x * releaseScale;
-    this.velocity.z = this.dragVelocity.y * releaseScale;
-    this.yawVelocity += THREE.MathUtils.clamp(this.velocity.z * 0.34, -0.7, 0.7);
-  }
-
-  clampToBounds(): void {
-    const minX = this.bounds.basinMinX + this.radiusX;
-    const maxX = this.bounds.basinMaxX - this.radiusX;
-    const minZ = this.bounds.centerZ - this.bounds.basinHalfZ + this.radiusZ;
-    const maxZ = this.bounds.centerZ + this.bounds.basinHalfZ - this.radiusZ;
-    this.group.position.x = THREE.MathUtils.clamp(this.group.position.x, minX, maxX);
-    this.group.position.z = THREE.MathUtils.clamp(this.group.position.z, minZ, maxZ);
-  }
-
-  reset(): void {
-    this.group.position.copy(this.start);
-    this.velocity.set(0, 0, 0);
-    this.yaw = Math.PI;
-    this.yawVelocity = 0;
-    this.pitch = 0;
-    this.roll = 0;
-    this.dragging = false;
-    this.dragVelocity.set(0, 0);
-    this.group.rotation.set(0, this.yaw, 0);
-    this.model.rotation.set(0, 0, 0);
-  }
-
-  update(delta: number, elapsed: number, {
-    surface = null,
-    impactX = 0,
-    impactZ = 0,
-    impactEnergy = 0,
-    emitting = false,
-  }: DuckUpdateOptions = {}): void {
-    if (!this.active) return;
-    const dt = Math.min(delta, 1 / 30);
-    const position = this.group.position;
-    const sample = surface?.sampleSurface(position.x, position.z, this.surfaceSample) || this.surfaceSample;
-    if (!surface) {
-      sample.height = 0;
-      sample.velocityY = 0;
-      sample.slopeX = 0;
-      sample.slopeZ = 0;
-      sample.flowX = 0;
-      sample.flowZ = 0;
-      const dx = position.x - impactX;
-      const dz = position.z - impactZ;
-      const distanceSq = dx * dx + dz * dz;
-      const strength = emitting ? Math.min(impactEnergy * 0.065, 0.9) * Math.exp(-distanceSq / 0.48) : 0;
-      const inverseDistance = 1 / Math.max(Math.sqrt(distanceSq), 0.06);
-      sample.flowX = strength * (0.42 + dx * inverseDistance * 0.68);
-      sample.flowZ = strength * dz * inverseDistance * 0.92;
-      sample.impact = strength * Math.exp(-distanceSq / 0.095);
-    }
-
-    const equilibriumY = this.waterY + sample.height - 0.016;
-    const buoyancyAcceleration = (equilibriumY - position.y) * 34;
-    const verticalDamping = (sample.velocityY - this.velocity.y) * 5.8;
-    this.velocity.y += (buoyancyAcceleration + verticalDamping - sample.impact * 4.4) * dt;
-
-    if (!this.dragging) {
-      const flowResponse = 2.65;
-      this.velocity.x += ((sample.flowX - this.velocity.x) * flowResponse - sample.slopeX * 1.75) * dt;
-      this.velocity.z += ((sample.flowZ - this.velocity.z) * flowResponse - sample.slopeZ * 1.75) * dt;
-      const horizontalDrag = Math.exp(-0.72 * dt);
-      this.velocity.x *= horizontalDrag;
-      this.velocity.z *= horizontalDrag;
-      const horizontalSpeed = Math.hypot(this.velocity.x, this.velocity.z);
-      if (horizontalSpeed > 1.35) {
-        const scale = 1.35 / horizontalSpeed;
-        this.velocity.x *= scale;
-        this.velocity.z *= scale;
-      }
-      position.x += this.velocity.x * dt;
-      position.z += this.velocity.z * dt;
-    }
-    position.y += this.velocity.y * dt;
-    const minX = this.bounds.basinMinX + this.radiusX;
-    const maxX = this.bounds.basinMaxX - this.radiusX;
-    const minZ = this.bounds.centerZ - this.bounds.basinHalfZ + this.radiusZ;
-    const maxZ = this.bounds.centerZ + this.bounds.basinHalfZ - this.radiusZ;
-    let collisionTorque = 0;
-    if (position.x < minX) {
-      position.x = minX;
-      this.velocity.x = Math.abs(this.velocity.x) * 0.42;
-      collisionTorque += 1.8;
-    } else if (position.x > maxX) {
-      position.x = maxX;
-      this.velocity.x = -Math.abs(this.velocity.x) * 0.42;
-      collisionTorque -= 1.8;
-    }
-    if (position.z < minZ) {
-      position.z = minZ;
-      this.velocity.z = Math.abs(this.velocity.z) * 0.42;
-      collisionTorque -= 1.35;
-    } else if (position.z > maxZ) {
-      position.z = maxZ;
-      this.velocity.z = -Math.abs(this.velocity.z) * 0.42;
-      collisionTorque += 1.35;
-    }
-
-    const speedSq = this.velocity.x * this.velocity.x + this.velocity.z * this.velocity.z;
-    if (speedSq > 0.0012) {
-      const desiredYaw = Math.atan2(-this.velocity.z, this.velocity.x);
-      const yawDifference = Math.atan2(Math.sin(desiredYaw - this.yaw), Math.cos(desiredYaw - this.yaw));
-      this.yawVelocity += yawDifference * 2.7 * dt;
-    }
-    const impactSide = THREE.MathUtils.clamp((position.z - impactZ) * 2.2, -1, 1);
-    this.yawVelocity += (collisionTorque + sample.impact * impactSide * 2.2) * dt;
-    this.yawVelocity *= Math.exp(-2.25 * dt);
-    this.yaw += this.yawVelocity * dt;
-
-    const forwardX = Math.cos(this.yaw);
-    const forwardZ = -Math.sin(this.yaw);
-    const rightX = Math.sin(this.yaw);
-    const rightZ = Math.cos(this.yaw);
-    const forwardSlope = sample.slopeX * forwardX + sample.slopeZ * forwardZ;
-    const rightSlope = sample.slopeX * rightX + sample.slopeZ * rightZ;
-    const desiredPitch = THREE.MathUtils.clamp(Math.atan(forwardSlope) - sample.impact * 0.12, -0.25, 0.25);
-    const desiredRoll = THREE.MathUtils.clamp(-Math.atan(rightSlope) - this.yawVelocity * 0.055, -0.24, 0.24);
-    const tiltBlend = 1 - Math.exp(-5.2 * dt);
-    this.pitch = THREE.MathUtils.lerp(this.pitch, desiredPitch, tiltBlend);
-    this.roll = THREE.MathUtils.lerp(this.roll, desiredRoll, tiltBlend);
-
-    this.group.rotation.y = this.yaw;
-    this.model.rotation.x = this.roll;
-    this.model.rotation.z = this.pitch;
-    this.model.position.y = Math.sin(elapsed * 3.1 + position.x * 1.7) * 0.0025;
-  }
-
-  dispose(): void {
-    this.pickGeometry.dispose();
-    this.pickMaterial.dispose();
-    this.sphereGeometry.dispose();
-    this.tailGeometry.dispose();
-    this.yellowMaterial.dispose();
-    this.wingMaterial.dispose();
-    this.beakMaterial.dispose();
-    this.eyeMaterial.dispose();
-    this.highlightMaterial.dispose();
-  }
-}
+import * as THREE from 'three';
+
+/** 鸭子可活动的水域边界（x 范围 + z 半宽 + 中心）。 */
+interface DuckBounds {
+    basinMinX: number;
+    basinMaxX: number;
+    basinHalfZ: number;
+    centerZ: number;
+}
+
+/** 水面采样结果（由 ShallowWaterSurface.sampleSurface 回填，供浮力/倾斜计算读高度与坡度）。 */
+interface DuckSurfaceSample {
+    height?: number;
+    velocityY?: number;
+    slopeX?: number;
+    slopeZ?: number;
+    flowX?: number;
+    flowZ?: number;
+    impact?: number;
+}
+
+/** 构造选项。 */
+export interface FloatingDuckOptions {
+    basinMinX: number;
+    basinMaxX: number;
+    basinHalfZ: number;
+    waterY: number;
+    startX?: number;
+    startZ?: number;
+}
+
+/** setEnvironment / clampToBounds 用的环境口径。 */
+export interface DuckEnvironment {
+    minX: number;
+    maxX: number;
+    halfZ: number;
+    centerZ?: number;
+    waterY: number;
+}
+
+/** update 的可调项。 */
+export interface DuckUpdateOptions {
+    surface?: DuckSurfaceSampler | null;
+    impactX?: number;
+    impactZ?: number;
+    impactEnergy?: number;
+    emitting?: boolean;
+}
+
+/** 只取 update 真正用到的水面能力（避免与 ShallowWaterSurface 形成类型环）。 */
+interface DuckSurfaceSampler {
+    sampleSurface(
+        worldX: number,
+        worldZ: number,
+        target?: DuckSurfaceSample,
+    ): DuckSurfaceSample;
+}
+
+/** 三元组（球体用：位置 / 缩放 / 旋转）。 */
+type Vec3Tuple = [number, number, number];
+
+function addScaledSphere(
+    group: THREE.Group,
+    geometry: THREE.BufferGeometry,
+    material: THREE.Material,
+    position: Vec3Tuple,
+    scale: Vec3Tuple,
+    rotation: Vec3Tuple | null = null,
+): THREE.Mesh {
+    const mesh = new THREE.Mesh(geometry, material);
+    mesh.position.set(...position);
+    mesh.scale.set(...scale);
+    if (rotation) mesh.rotation.set(...rotation);
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    group.add(mesh);
+    return mesh;
+}
+
+/** 漂浮的橡皮鸭：跟随水面高度/坡度做浮沉与倾斜，可被鼠标拖拽。 */
+export class FloatingDuck {
+    private readonly bounds: DuckBounds;
+    /** 静水面高度；setEnvironment 会随容器变化更新（故非 readonly）。 */
+    private waterY: number;
+    private readonly start: THREE.Vector3;
+    private readonly velocity: THREE.Vector3;
+    private readonly surfaceSample: DuckSurfaceSample;
+    private yaw: number;
+    private yawVelocity: number;
+    private pitch: number;
+    private roll: number;
+    private readonly radiusX: number;
+    private readonly radiusZ: number;
+    private active: boolean;
+    private dragging: boolean;
+    private readonly dragOffset: THREE.Vector2;
+    private readonly dragVelocity: THREE.Vector2;
+    private readonly lastDragPosition: THREE.Vector2;
+
+    private readonly group: THREE.Group;
+    private readonly model: THREE.Group;
+    private readonly pickGeometry: THREE.SphereGeometry;
+    private readonly pickMaterial: THREE.MeshBasicMaterial;
+    private readonly pickMesh: THREE.Mesh;
+
+    private readonly yellowMaterial: THREE.MeshPhysicalMaterial;
+    private readonly wingMaterial: THREE.MeshPhysicalMaterial;
+    private readonly beakMaterial: THREE.MeshPhysicalMaterial;
+    private readonly eyeMaterial: THREE.MeshStandardMaterial;
+    private readonly highlightMaterial: THREE.MeshBasicMaterial;
+
+    private readonly sphereGeometry: THREE.SphereGeometry;
+    private readonly body: THREE.Mesh;
+    private readonly head: THREE.Mesh;
+    private readonly beak: THREE.Mesh;
+    private readonly tailGeometry: THREE.ConeGeometry;
+    private readonly tail: THREE.Mesh;
+
+    constructor({
+        basinMinX,
+        basinMaxX,
+        basinHalfZ,
+        waterY,
+        startX = 1.2,
+        startZ = 0.24,
+    }: FloatingDuckOptions) {
+    this.bounds = { basinMinX, basinMaxX, basinHalfZ, centerZ: 0 };
+    this.waterY = waterY;
+    this.start = new THREE.Vector3(startX, waterY - 0.016, startZ);
+    this.velocity = new THREE.Vector3();
+    this.surfaceSample = {};
+    this.yaw = Math.PI;
+    this.yawVelocity = 0;
+    this.pitch = 0;
+    this.roll = 0;
+    this.radiusX = 0.19;
+    this.radiusZ = 0.145;
+    this.active = true;
+    this.dragging = false;
+    this.dragOffset = new THREE.Vector2();
+    this.dragVelocity = new THREE.Vector2();
+    this.lastDragPosition = new THREE.Vector2();
+
+    this.group = new THREE.Group();
+    this.group.name = 'floating-rubber-duck';
+    this.model = new THREE.Group();
+    this.group.add(this.model);
+
+    this.pickGeometry = new THREE.SphereGeometry(0.29, 12, 8);
+    this.pickMaterial = new THREE.MeshBasicMaterial({
+      transparent: true,
+      opacity: 0,
+      depthWrite: false,
+      colorWrite: false,
+    });
+    this.pickMesh = new THREE.Mesh(this.pickGeometry, this.pickMaterial);
+    this.pickMesh.name = 'rubber-duck-pick-volume';
+    this.pickMesh.position.y = 0.13;
+    this.pickMesh.layers.set(2);
+    this.group.add(this.pickMesh);
+
+    this.yellowMaterial = new THREE.MeshPhysicalMaterial({
+      color: 0xf2b705,
+      roughness: 0.46,
+      metalness: 0,
+      clearcoat: 0.32,
+      clearcoatRoughness: 0.28,
+    });
+    this.wingMaterial = new THREE.MeshPhysicalMaterial({
+      color: 0xd99b03,
+      roughness: 0.48,
+      metalness: 0,
+      clearcoat: 0.24,
+    });
+    this.beakMaterial = new THREE.MeshPhysicalMaterial({
+      color: 0xe85e06,
+      roughness: 0.42,
+      metalness: 0,
+      clearcoat: 0.25,
+    });
+    this.eyeMaterial = new THREE.MeshStandardMaterial({ color: 0x101518, roughness: 0.2 });
+    this.highlightMaterial = new THREE.MeshBasicMaterial({ color: 0xffffff });
+
+    this.sphereGeometry = new THREE.SphereGeometry(1, 32, 20);
+    this.body = addScaledSphere(
+      this.model,
+      this.sphereGeometry,
+      this.yellowMaterial,
+      [0, 0.072, 0],
+      [0.19, 0.12, 0.132],
+    );
+    this.head = addScaledSphere(
+      this.model,
+      this.sphereGeometry,
+      this.yellowMaterial,
+      [0.115, 0.205, 0],
+      [0.098, 0.102, 0.096],
+    );
+    this.beak = addScaledSphere(
+      this.model,
+      this.sphereGeometry,
+      this.beakMaterial,
+      [0.203, 0.191, 0],
+      [0.071, 0.026, 0.047],
+    );
+
+    for (const side of [-1, 1]) {
+      addScaledSphere(
+        this.model,
+        this.sphereGeometry,
+        this.wingMaterial,
+        [-0.02, 0.092, side * 0.115],
+        [0.105, 0.048, 0.052],
+        [side * 0.18, 0, side * 0.08],
+      );
+      addScaledSphere(
+        this.model,
+        this.sphereGeometry,
+        this.eyeMaterial,
+        [0.176, 0.237, side * 0.069],
+        [0.014, 0.017, 0.011],
+      );
+      addScaledSphere(
+        this.model,
+        this.sphereGeometry,
+        this.highlightMaterial,
+        [0.184, 0.244, side * 0.077],
+        [0.0045, 0.005, 0.0035],
+      );
+    }
+
+    this.tailGeometry = new THREE.ConeGeometry(0.052, 0.105, 20);
+    this.tail = new THREE.Mesh(this.tailGeometry, this.yellowMaterial);
+    this.tail.position.set(-0.177, 0.132, 0);
+    this.tail.rotation.z = -Math.PI * 0.5;
+    this.tail.castShadow = true;
+    this.model.add(this.tail);
+
+    this.reset();
+  }
+
+  setActive(active: boolean): void {
+    this.active = active;
+    this.group.visible = active;
+  }
+
+  setEnvironment({ minX, maxX, halfZ, centerZ = 0, waterY }: DuckEnvironment, reposition = false): void {
+    this.bounds.basinMinX = minX;
+    this.bounds.basinMaxX = maxX;
+    this.bounds.basinHalfZ = halfZ;
+    this.bounds.centerZ = centerZ;
+    this.waterY = waterY;
+    if (reposition) {
+      const receiverWidth = maxX - minX;
+      this.place(minX + Math.min(0.75, receiverWidth * 0.35), centerZ + Math.min(0.2, halfZ * 0.3));
+    } else {
+      this.clampToBounds();
+    }
+  }
+
+  place(x: number, z: number): void {
+    this.group.position.set(x, this.waterY - 0.016, z);
+    this.velocity.set(0, 0, 0);
+    this.clampToBounds();
+  }
+
+  translateContainer(deltaX: number, deltaZ: number): void {
+    this.group.position.x += deltaX;
+    this.group.position.z += deltaZ;
+    this.clampToBounds();
+  }
+
+  beginDrag(worldX: number, worldZ: number): void {
+    this.dragging = true;
+    this.dragOffset.set(this.group.position.x - worldX, this.group.position.z - worldZ);
+    this.lastDragPosition.set(this.group.position.x, this.group.position.z);
+    this.dragVelocity.set(0, 0);
+    this.velocity.x = 0;
+    this.velocity.z = 0;
+  }
+
+  dragTo(worldX: number, worldZ: number, deltaSeconds: number): void {
+    if (!this.dragging) return;
+    const previousX = this.group.position.x;
+    const previousZ = this.group.position.z;
+    this.group.position.x = worldX + this.dragOffset.x;
+    this.group.position.z = worldZ + this.dragOffset.y;
+    this.clampToBounds();
+    const inverseDelta = 1 / Math.max(deltaSeconds, 1 / 120);
+    const measuredX = (this.group.position.x - previousX) * inverseDelta;
+    const measuredZ = (this.group.position.z - previousZ) * inverseDelta;
+    this.dragVelocity.x = THREE.MathUtils.lerp(this.dragVelocity.x, measuredX, 0.42);
+    this.dragVelocity.y = THREE.MathUtils.lerp(this.dragVelocity.y, measuredZ, 0.42);
+    this.velocity.x = this.dragVelocity.x;
+    this.velocity.z = this.dragVelocity.y;
+    this.lastDragPosition.set(this.group.position.x, this.group.position.z);
+  }
+
+  endDrag(): void {
+    if (!this.dragging) return;
+    this.dragging = false;
+    const releaseSpeed = Math.hypot(this.dragVelocity.x, this.dragVelocity.y);
+    const releaseScale = releaseSpeed > 1.5 ? 1.5 / releaseSpeed : 1;
+    this.velocity.x = this.dragVelocity.x * releaseScale;
+    this.velocity.z = this.dragVelocity.y * releaseScale;
+    this.yawVelocity += THREE.MathUtils.clamp(this.velocity.z * 0.34, -0.7, 0.7);
+  }
+
+  clampToBounds(): void {
+    const minX = this.bounds.basinMinX + this.radiusX;
+    const maxX = this.bounds.basinMaxX - this.radiusX;
+    const minZ = this.bounds.centerZ - this.bounds.basinHalfZ + this.radiusZ;
+    const maxZ = this.bounds.centerZ + this.bounds.basinHalfZ - this.radiusZ;
+    this.group.position.x = THREE.MathUtils.clamp(this.group.position.x, minX, maxX);
+    this.group.position.z = THREE.MathUtils.clamp(this.group.position.z, minZ, maxZ);
+  }
+
+  reset(): void {
+    this.group.position.copy(this.start);
+    this.velocity.set(0, 0, 0);
+    this.yaw = Math.PI;
+    this.yawVelocity = 0;
+    this.pitch = 0;
+    this.roll = 0;
+    this.dragging = false;
+    this.dragVelocity.set(0, 0);
+    this.group.rotation.set(0, this.yaw, 0);
+    this.model.rotation.set(0, 0, 0);
+  }
+
+  update(delta: number, elapsed: number, {
+    surface = null,
+    impactX = 0,
+    impactZ = 0,
+    impactEnergy = 0,
+    emitting = false,
+  }: DuckUpdateOptions = {}): void {
+    if (!this.active) return;
+    const dt = Math.min(delta, 1 / 30);
+    const position = this.group.position;
+    const sample = surface?.sampleSurface(position.x, position.z, this.surfaceSample) || this.surfaceSample;
+    if (!surface) {
+      sample.height = 0;
+      sample.velocityY = 0;
+      sample.slopeX = 0;
+      sample.slopeZ = 0;
+      sample.flowX = 0;
+      sample.flowZ = 0;
+      const dx = position.x - impactX;
+      const dz = position.z - impactZ;
+      const distanceSq = dx * dx + dz * dz;
+      const strength = emitting ? Math.min(impactEnergy * 0.065, 0.9) * Math.exp(-distanceSq / 0.48) : 0;
+      const inverseDistance = 1 / Math.max(Math.sqrt(distanceSq), 0.06);
+      sample.flowX = strength * (0.42 + dx * inverseDistance * 0.68);
+      sample.flowZ = strength * dz * inverseDistance * 0.92;
+      sample.impact = strength * Math.exp(-distanceSq / 0.095);
+    }
+
+    const equilibriumY = this.waterY + sample.height - 0.016;
+    const buoyancyAcceleration = (equilibriumY - position.y) * 34;
+    const verticalDamping = (sample.velocityY - this.velocity.y) * 5.8;
+    this.velocity.y += (buoyancyAcceleration + verticalDamping - sample.impact * 4.4) * dt;
+
+    if (!this.dragging) {
+      const flowResponse = 2.65;
+      this.velocity.x += ((sample.flowX - this.velocity.x) * flowResponse - sample.slopeX * 1.75) * dt;
+      this.velocity.z += ((sample.flowZ - this.velocity.z) * flowResponse - sample.slopeZ * 1.75) * dt;
+      const horizontalDrag = Math.exp(-0.72 * dt);
+      this.velocity.x *= horizontalDrag;
+      this.velocity.z *= horizontalDrag;
+      const horizontalSpeed = Math.hypot(this.velocity.x, this.velocity.z);
+      if (horizontalSpeed > 1.35) {
+        const scale = 1.35 / horizontalSpeed;
+        this.velocity.x *= scale;
+        this.velocity.z *= scale;
+      }
+      position.x += this.velocity.x * dt;
+      position.z += this.velocity.z * dt;
+    }
+    position.y += this.velocity.y * dt;
+    const minX = this.bounds.basinMinX + this.radiusX;
+    const maxX = this.bounds.basinMaxX - this.radiusX;
+    const minZ = this.bounds.centerZ - this.bounds.basinHalfZ + this.radiusZ;
+    const maxZ = this.bounds.centerZ + this.bounds.basinHalfZ - this.radiusZ;
+    let collisionTorque = 0;
+    if (position.x < minX) {
+      position.x = minX;
+      this.velocity.x = Math.abs(this.velocity.x) * 0.42;
+      collisionTorque += 1.8;
+    } else if (position.x > maxX) {
+      position.x = maxX;
+      this.velocity.x = -Math.abs(this.velocity.x) * 0.42;
+      collisionTorque -= 1.8;
+    }
+    if (position.z < minZ) {
+      position.z = minZ;
+      this.velocity.z = Math.abs(this.velocity.z) * 0.42;
+      collisionTorque -= 1.35;
+    } else if (position.z > maxZ) {
+      position.z = maxZ;
+      this.velocity.z = -Math.abs(this.velocity.z) * 0.42;
+      collisionTorque += 1.35;
+    }
+
+    const speedSq = this.velocity.x * this.velocity.x + this.velocity.z * this.velocity.z;
+    if (speedSq > 0.0012) {
+      const desiredYaw = Math.atan2(-this.velocity.z, this.velocity.x);
+      const yawDifference = Math.atan2(Math.sin(desiredYaw - this.yaw), Math.cos(desiredYaw - this.yaw));
+      this.yawVelocity += yawDifference * 2.7 * dt;
+    }
+    const impactSide = THREE.MathUtils.clamp((position.z - impactZ) * 2.2, -1, 1);
+    this.yawVelocity += (collisionTorque + sample.impact * impactSide * 2.2) * dt;
+    this.yawVelocity *= Math.exp(-2.25 * dt);
+    this.yaw += this.yawVelocity * dt;
+
+    const forwardX = Math.cos(this.yaw);
+    const forwardZ = -Math.sin(this.yaw);
+    const rightX = Math.sin(this.yaw);
+    const rightZ = Math.cos(this.yaw);
+    const forwardSlope = sample.slopeX * forwardX + sample.slopeZ * forwardZ;
+    const rightSlope = sample.slopeX * rightX + sample.slopeZ * rightZ;
+    const desiredPitch = THREE.MathUtils.clamp(Math.atan(forwardSlope) - sample.impact * 0.12, -0.25, 0.25);
+    const desiredRoll = THREE.MathUtils.clamp(-Math.atan(rightSlope) - this.yawVelocity * 0.055, -0.24, 0.24);
+    const tiltBlend = 1 - Math.exp(-5.2 * dt);
+    this.pitch = THREE.MathUtils.lerp(this.pitch, desiredPitch, tiltBlend);
+    this.roll = THREE.MathUtils.lerp(this.roll, desiredRoll, tiltBlend);
+
+    this.group.rotation.y = this.yaw;
+    this.model.rotation.x = this.roll;
+    this.model.rotation.z = this.pitch;
+    this.model.position.y = Math.sin(elapsed * 3.1 + position.x * 1.7) * 0.0025;
+  }
+
+  dispose(): void {
+    this.pickGeometry.dispose();
+    this.pickMaterial.dispose();
+    this.sphereGeometry.dispose();
+    this.tailGeometry.dispose();
+    this.yellowMaterial.dispose();
+    this.wingMaterial.dispose();
+    this.beakMaterial.dispose();
+    this.eyeMaterial.dispose();
+    this.highlightMaterial.dispose();
+  }
+}