@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/vortex-water-effect.ts

@@ -0,0 +1,863 @@
+import { geometryDetailSegments } from '../../../three/geometry-detail'
+import * as THREE from 'three'
+
+import { VisualCylinderGeometry, VisualTorusGeometry } from '../../../three/visual-geometry'
+
+import { FLOWING_WATER_APPEARANCE_ID, type FluidSurfaceStyle } from '../../../three/water-appearance'
+import type { TrackThemeDefinition } from '../../../three/track-theme'
+
+// Every water-capable piece raises the rendered sheet by the same small
+// amount above its canonical water plane to avoid z-fighting at connections.
+export const TRACK_WATER_SURFACE_OFFSET = 0.035
+export const WATER_ANIMATION_SPEED_SCALE = 1.4
+
+export interface FlowingWaterSurfaceEffectOptions {
+  pieceId: string
+  geometry: THREE.BufferGeometry
+  waveAmplitude: number
+  startAngle?: number
+  flowDirection?: -1 | 1
+  opacity?: number
+  speed?: number
+  laneMode?: boolean
+  connectionPhase?: number
+  name?: string
+  style?: FluidSurfaceStyle
+  themeId?: string
+}
+
+export interface VortexWaterEffectOptions {
+  pieceId: string
+  center: THREE.Vector3 | readonly [number, number, number]
+  innerRadius: number
+  outerRadius: number
+  surfaceHeightAtRadius: (radius: number) => number
+  startAngle?: number
+  orbitDirection?: -1 | 1
+  dropLength?: number
+  entryTransition?: readonly VortexWaterEntryTransitionColumn[]
+  entryConnected?: boolean
+  centerFunnel?: readonly VortexWaterFunnelRing[]
+  style?: FluidSurfaceStyle
+  themeId?: string
+}
+
+export interface VortexWaterEntryTransitionColumn {
+  start: THREE.Vector3 | readonly [number, number, number]
+  collar: THREE.Vector3 | readonly [number, number, number]
+  boundary: THREE.Vector3 | readonly [number, number, number]
+}
+
+export interface VortexWaterFunnelRing {
+  radius: number
+  height: number
+}
+
+const SURFACE_ANGULAR_SEGMENTS = geometryDetailSegments(24, 8)
+// Six rings retain a row inside the inlet foam transition (>80% radius).
+const SURFACE_RADIAL_SEGMENTS = 6
+
+interface FluidPalette {
+  id: string
+  deep: number
+  shallow: number
+  foam: number
+  accent: number
+  accentStrength: number
+  drop: number
+  mist: number
+}
+
+const NATURAL_WATER_PALETTE: FluidPalette = {
+  id: 'natural-water',
+  deep: 0x0d4541,
+  shallow: 0x347367,
+  foam: 0xf4f7f0,
+  accent: 0x347367,
+  accentStrength: 0,
+  drop: 0x55cfe9,
+  mist: 0xd6faff,
+}
+
+function fluidPaletteForTheme(themeId: string | undefined): FluidPalette {
+  if (themeId === 'intergalactic-space-station') {
+    return {
+      id: 'space-station-pink',
+      deep: 0x5a0a46,
+      shallow: 0xf337b4,
+      foam: 0xffd9f5,
+      accent: 0xff8edb,
+      accentStrength: 0.68,
+      drop: 0xf337b4,
+      mist: 0xffd9f5,
+    }
+  }
+  if (themeId === 'vampire-castle') {
+    return {
+      id: 'vampire-blood-red',
+      deep: 0x260307,
+      shallow: 0x8f101c,
+      foam: 0xffc7c9,
+      accent: 0xd62f3b,
+      accentStrength: 0.42,
+      drop: 0x9d101d,
+      mist: 0xffb5b9,
+    }
+  }
+  return NATURAL_WATER_PALETTE
+}
+
+/**
+ * Adds a cheap, visual-only water overlay to a vortex bowl.
+ *
+ * The returned group owns all effect geometry, materials, and render-time wave
+ * animation. It has no physics body or collider, so removing the call removes
+ * the effect completely.
+ */
+export function addVortexWaterEffect(root: THREE.Object3D, options: VortexWaterEffectOptions): THREE.Group {
+  assertVortexWaterEffectOptions(options)
+
+  const center = options.center instanceof THREE.Vector3 ? options.center.clone() : new THREE.Vector3(...options.center)
+  const palette = fluidPaletteForTheme(options.themeId)
+  const effect = new THREE.Group()
+  effect.name = `${options.pieceId}-spiral-waterfall`
+  effect.position.copy(center)
+  markAsDecoration(effect)
+
+  const surfaceGeometry = createWaterSurfaceGeometry(options, center.y)
+  addFlowingWaterSurfaceEffect(effect, {
+    pieceId: options.pieceId,
+    geometry: surfaceGeometry,
+    waveAmplitude: THREE.MathUtils.clamp(options.outerRadius * 0.006, 0.035, 0.075),
+    flowDirection: options.orbitDirection,
+    startAngle: options.startAngle,
+    opacity: 0.58,
+    speed: 2.4,
+    style: options.style,
+    themeId: options.themeId,
+    name: `${options.pieceId}-water-surface`,
+  })
+
+  const funnelThroat = options.centerFunnel?.[0]
+  const innerSurfaceHeight = funnelThroat?.height ?? options.surfaceHeightAtRadius(options.innerRadius * 1.02)
+  const bowlDrop = Math.abs(
+    options.surfaceHeightAtRadius(options.outerRadius) - options.surfaceHeightAtRadius(options.innerRadius),
+  )
+  const dropLength = options.dropLength ?? THREE.MathUtils.clamp(bowlDrop * 0.34, 1.4, 3.2)
+  const dropTop = innerSurfaceHeight - center.y + 0.03
+  const dropTopRadius = Math.max(0.12, funnelThroat?.radius ?? options.innerRadius * 0.68)
+  const dropBottomRadius = Math.max(0.1, dropTopRadius * 0.72)
+  const dropGeometry = new VisualCylinderGeometry(dropTopRadius, dropBottomRadius, dropLength, 18, 3, true)
+  const dropMaterial = new THREE.MeshBasicMaterial({
+    color: palette.drop,
+    depthFunc: THREE.LessEqualDepth,
+    depthTest: true,
+    depthWrite: false,
+    opacity: 0.42,
+    side: THREE.FrontSide,
+    toneMapped: true,
+    transparent: true,
+  })
+  dropMaterial.name = 'vortex-water-drop-material'
+  const drop = new THREE.Mesh(dropGeometry, dropMaterial)
+  drop.name = `${options.pieceId}-spiral-water-drop`
+  drop.position.y = dropTop - dropLength / 2
+  drop.renderOrder = 5
+  markAsDecoration(drop, true)
+  drop.userData.applySemanticTheme = (theme: TrackThemeDefinition) => {
+    const nextPalette = fluidPaletteForTheme(theme.id)
+    dropMaterial.color.setHex(nextPalette.drop)
+  }
+  effect.add(drop)
+
+  const mistRadius = dropBottomRadius * 1.2
+  const mistGeometry = new VisualTorusGeometry(mistRadius, Math.max(0.045, mistRadius * 0.12), 4, 16)
+  const mistMaterial = new THREE.MeshBasicMaterial({
+    color: palette.mist,
+    depthFunc: THREE.LessEqualDepth,
+    depthTest: true,
+    depthWrite: false,
+    opacity: 0.28,
+    side: THREE.FrontSide,
+    toneMapped: true,
+    transparent: true,
+  })
+  mistMaterial.name = 'vortex-water-mist-material'
+  const mist = new THREE.Mesh(mistGeometry, mistMaterial)
+  mist.name = `${options.pieceId}-spiral-water-mist`
+  mist.position.y = dropTop - dropLength * 0.92
+  mist.rotation.x = Math.PI / 2
+  mist.renderOrder = 6
+  markAsDecoration(mist, true)
+  mist.userData.applySemanticTheme = (theme: TrackThemeDefinition) => {
+    const nextPalette = fluidPaletteForTheme(theme.id)
+    mistMaterial.color.setHex(nextPalette.mist)
+  }
+  effect.add(mist)
+
+  root.add(effect)
+  return effect
+}
+
+export function addFlowingWaterSurfaceEffect(
+  root: THREE.Object3D,
+  options: FlowingWaterSurfaceEffectOptions,
+): THREE.Mesh {
+  const animationStart = nowMilliseconds()
+  const palette = fluidPaletteForTheme(options.themeId)
+  const uniforms = {
+    ...THREE.UniformsUtils.clone(THREE.UniformsLib.fog),
+    uTime: { value: 0 },
+    uWaveAmplitude: { value: options.waveAmplitude },
+    uDeepColor: { value: new THREE.Color(palette.deep) },
+    uShallowColor: { value: new THREE.Color(palette.shallow) },
+    uFoamColor: { value: new THREE.Color(palette.foam) },
+    uAccentColor: { value: new THREE.Color(palette.accent) },
+    uAccentStrength: { value: palette.accentStrength },
+    uOpacity: { value: options.opacity ?? 0.56 },
+    uOrbitDirection: { value: options.flowDirection ?? 1 },
+    uStartAngle: { value: options.startAngle ?? 0 },
+    uLaneMode: { value: options.laneMode ? 1 : 0 },
+  }
+  const material = new THREE.ShaderMaterial({
+    depthFunc: THREE.LessEqualDepth,
+    depthTest: true,
+    depthWrite: false,
+    fog: true,
+    fragmentShader: WATER_SURFACE_FRAGMENT_SHADER,
+    side: THREE.FrontSide,
+    toneMapped: true,
+    transparent: true,
+    uniforms,
+    vertexShader: WATER_SURFACE_VERTEX_SHADER,
+  })
+  const materialWithAttributeDefaults = material as THREE.ShaderMaterial & {
+    defaultAttributeValues?: Record<string, number[]>
+  }
+  materialWithAttributeDefaults.defaultAttributeValues = {
+    ...materialWithAttributeDefaults.defaultAttributeValues,
+    waterFlowDirection: [0, 0, -1],
+    waterFlowPhase: [0],
+    waterTurbulence: [0],
+    waterLaneBlend: [options.laneMode ? 1 : 0],
+    waterLaneLateral: [0.5],
+    waterWallDistance: [1],
+    waterWallFoamStrength: [1],
+  }
+  material.name = 'flowing-water-surface-material'
+  const surface = new THREE.Mesh(options.geometry, material)
+  surface.name = options.name ?? `${options.pieceId}-flowing-water-surface`
+  surface.renderOrder = 4
+  surface.userData.flowSpeed = (options.speed ?? 1) * WATER_ANIMATION_SPEED_SCALE
+  surface.userData.flowDirection = options.flowDirection ?? 1
+  surface.userData.fluidSurfaceStyle = options.style ?? 'water'
+  surface.userData.fluidPalette = palette.id
+  surface.userData.semanticAppearanceId = FLOWING_WATER_APPEARANCE_ID
+  if (options.laneMode) {
+    const flowPhases = options.geometry.getAttribute('waterFlowPhase')
+    if (flowPhases) {
+      const localFlowPhases = Float32Array.from(
+        { length: flowPhases.count },
+        (_unused, index) => flowPhases.getX(index),
+      )
+      const setWaterConnectionPhase = (phase: number): void => {
+        if (!Number.isFinite(phase)) return
+        const phaseOffset = phase / 1.6
+        for (let index = 0; index < flowPhases.count; index += 1) {
+          flowPhases.setX(index, localFlowPhases[index]! + phaseOffset)
+        }
+        flowPhases.needsUpdate = true
+        surface.userData.waterConnectionPhase = phase
+      }
+      surface.userData.setWaterConnectionPhase = setWaterConnectionPhase
+      setWaterConnectionPhase(options.connectionPhase ?? 0)
+    }
+  }
+  surface.userData.applySemanticTheme = (theme: TrackThemeDefinition) => {
+    const nextPalette = fluidPaletteForTheme(theme.id)
+    uniforms.uDeepColor.value.setHex(nextPalette.deep)
+    uniforms.uShallowColor.value.setHex(nextPalette.shallow)
+    uniforms.uFoamColor.value.setHex(nextPalette.foam)
+    uniforms.uAccentColor.value.setHex(nextPalette.accent)
+    uniforms.uAccentStrength.value = nextPalette.accentStrength
+    surface.userData.fluidPalette = nextPalette.id
+  }
+  surface.userData.visualFluidThickness = 0.045
+  surface.onBeforeRender = () => {
+    if (!surface.visible) return
+    uniforms.uTime.value =
+      ((nowMilliseconds() - animationStart) / 1_000) * (options.speed ?? 1) * WATER_ANIMATION_SPEED_SCALE
+  }
+  markAsDecoration(surface, true)
+  root.add(surface)
+  return surface
+}
+
+function createWaterSurfaceGeometry(options: VortexWaterEffectOptions, centerY: number): THREE.BufferGeometry {
+  const positions: number[] = []
+  const uvs: number[] = []
+  const entryFades: number[] = []
+  const laneBlends: number[] = []
+  const flowDirections: number[] = []
+  const flowPhases: number[] = []
+  const laneLaterals: number[] = []
+  const wallDistances: number[] = []
+  const wallFoamStrengths: number[] = []
+  const indices: number[] = []
+  const geometryMetadata: Record<string, number> = {}
+  const entryBoundaryNormalPairs: Array<readonly [number, number]> = []
+  const center = options.center instanceof THREE.Vector3 ? options.center : new THREE.Vector3(...options.center)
+  const entryTransition = options.entryTransition ?? []
+  const normalizeAngle = (angle: number): number => ((angle % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2)
+  const entryBoundaryAngles = entryTransition.map(column => {
+    const boundary = toLocalWaterPoint(column.boundary, center)
+    return normalizeAngle(Math.atan2(boundary.z, boundary.x))
+  })
+  const entryOpeningCenter = entryBoundaryAngles.length >= 2
+    ? normalizeAngle(
+        Math.atan2(
+          entryBoundaryAngles.reduce((sum, angle) => sum + Math.sin(angle), 0),
+          entryBoundaryAngles.reduce((sum, angle) => sum + Math.cos(angle), 0),
+        ),
+      )
+    : undefined
+  const signedAngleDifference = (angle: number, reference: number): number =>
+    Math.atan2(Math.sin(angle - reference), Math.cos(angle - reference))
+  const entryOpeningHalfAngle = entryOpeningCenter === undefined
+    ? 0
+    : Math.max(...entryBoundaryAngles.map(angle => Math.abs(signedAngleDifference(angle, entryOpeningCenter))))
+  const isEntryOpeningAngle = (angle: number): boolean =>
+    entryOpeningCenter !== undefined &&
+    Math.abs(signedAngleDifference(angle, entryOpeningCenter)) <= entryOpeningHalfAngle + 0.000_001
+  const entryTerminalHalfWidth =
+    entryTransition.length >= 2
+      ? toLocalWaterPoint(entryTransition[0]!.start, center).distanceTo(
+          toLocalWaterPoint(entryTransition.at(-1)!.start, center),
+        ) / 2
+      : 1
+  const surfaceAngles = [
+    ...Array.from(
+      { length: SURFACE_ANGULAR_SEGMENTS },
+      (_, segment) => (segment / SURFACE_ANGULAR_SEGMENTS) * Math.PI * 2,
+    ),
+    ...entryBoundaryAngles,
+  ]
+    .sort((left, right) => left - right)
+    .filter((angle, index, angles) => index === 0 || Math.abs(angle - angles[index - 1]!) > 0.000_001)
+  const closedSurfaceAngles = [...surfaceAngles, surfaceAngles[0]! + Math.PI * 2]
+  const rowSize = closedSurfaceAngles.length
+  geometryMetadata.waterBowlRowSize = rowSize
+  geometryMetadata.waterBowlOuterRingVertexOffset = SURFACE_RADIAL_SEGMENTS * rowSize
+
+  for (let ring = 0; ring <= SURFACE_RADIAL_SEGMENTS; ring += 1) {
+    const radialProgress = ring / SURFACE_RADIAL_SEGMENTS
+    const radius = THREE.MathUtils.lerp(options.innerRadius, options.outerRadius, radialProgress)
+    const y = options.surfaceHeightAtRadius(radius) - centerY + TRACK_WATER_SURFACE_OFFSET
+
+    for (const [angleIndex, angle] of closedSurfaceAngles.entries()) {
+      const angularProgress = angleIndex === closedSurfaceAngles.length - 1 ? 1 : normalizeAngle(angle) / (Math.PI * 2)
+      positions.push(Math.cos(angle) * radius, y, Math.sin(angle) * radius)
+      uvs.push(radialProgress, angularProgress)
+      entryFades.push(1)
+      laneBlends.push(0)
+      flowDirections.push(0, 0, -1)
+      flowPhases.push(0)
+      laneLaterals.push(0.5)
+      const insideEntryMouth = isEntryOpeningAngle(angle) && radialProgress > 0.8
+      // The circular bowl rim stops at the inlet mouth. Within that opening,
+      // the bowl owns no wall-contact foam at all. The separate inlet rows
+      // carry the two real side-wall contacts up to this boundary; keeping
+      // them off the bowl vertices prevents a radial white wedge from being
+      // interpolated into the open water-to-water join.
+      wallDistances.push(insideEntryMouth ? 1 : (1 - radialProgress) * 3.2)
+      wallFoamStrengths.push(insideEntryMouth ? 0 : 0.5)
+    }
+  }
+
+  for (let ring = 0; ring < SURFACE_RADIAL_SEGMENTS; ring += 1) {
+    for (let segment = 0; segment < surfaceAngles.length; segment += 1) {
+      const inner = ring * rowSize + segment
+      const outer = inner + rowSize
+      // The water is viewed from above with FrontSide culling. Keep the bowl
+      // skin wound upward so it is not discarded by the renderer.
+      indices.push(inner, inner + 1, outer, outer, inner + 1, outer + 1)
+    }
+  }
+
+  if (entryTransition.length >= 2) {
+    const outerRingOffset = SURFACE_RADIAL_SEGMENTS * rowSize
+    const entryCenterStart = entryTransition
+      .map(column => toLocalWaterPoint(column.start, center))
+      .reduce((sum, point) => sum.add(point), new THREE.Vector3())
+      .multiplyScalar(1 / entryTransition.length)
+    const entryCenterCollar = entryTransition
+      .map(column => toLocalWaterPoint(column.collar, center))
+      .reduce((sum, point) => sum.add(point), new THREE.Vector3())
+      .multiplyScalar(1 / entryTransition.length)
+    const entryCenterBoundary = entryTransition
+      .map(column => toLocalWaterPoint(column.boundary, center))
+      .reduce((sum, point) => sum.add(point), new THREE.Vector3())
+      .multiplyScalar(1 / entryTransition.length)
+    const approachLength = entryCenterCollar.distanceTo(entryCenterStart)
+    const fanLength = entryCenterBoundary.distanceTo(entryCenterCollar)
+    const entryLength = Math.max(0.000_001, approachLength + fanLength)
+    const fallbackFlow = entryCenterBoundary.clone().sub(entryCenterStart).setY(0).normalize()
+    const normalizedHorizontalFlow = (from: THREE.Vector3, to: THREE.Vector3): THREE.Vector3 => {
+      const flow = to.clone().sub(from).setY(0)
+      return flow.lengthSq() > 0.000_001 ? flow.normalize() : fallbackFlow.clone()
+    }
+    const approachFlow = normalizedHorizontalFlow(entryCenterStart, entryCenterCollar)
+    const fanFlow = normalizedHorizontalFlow(entryCenterCollar, entryCenterBoundary)
+    const collarFlow = approachFlow.clone().add(fanFlow)
+    if (collarFlow.lengthSq() > 0.000_001) collarFlow.normalize()
+    else collarFlow.copy(fallbackFlow)
+    const entryStartVertexOffset = positions.length / 3
+    const sections = entryTransition.map((column, columnIndex) => {
+      const start = toLocalWaterPoint(column.start, center)
+      const collar = toLocalWaterPoint(column.collar, center)
+      const boundaryAngle = entryBoundaryAngles[columnIndex]!
+      const boundaryAngleIndex = surfaceAngles.findIndex(
+        angle => Math.abs(Math.atan2(Math.sin(angle - boundaryAngle), Math.cos(angle - boundaryAngle))) < 0.000_001,
+      )
+      if (boundaryAngleIndex < 0) throw new Error('Missing shared water inlet boundary angle.')
+      const boundaryIndex = outerRingOffset + boundaryAngleIndex
+      // The structural entry boundary and circular water ring are generated
+      // through separate paths. Reuse the bowl vertex position verbatim so
+      // tiny analytic/tessellation differences cannot overlap or crack the
+      // water at the mouth.
+      const boundary = new THREE.Vector3(
+        positions[boundaryIndex * 3]!,
+        positions[boundaryIndex * 3 + 1]! - TRACK_WATER_SURFACE_OFFSET,
+        positions[boundaryIndex * 3 + 2]!,
+      )
+      // Keep lane advection on the bowl's coincident mouth vertex, then
+      // interpolate it across the first radial bowl band. The inlet receives
+      // its own same-position boundary vertex below so its side-wall foam can
+      // terminate here without leaking into the bowl.
+      laneBlends[boundaryIndex] = 1
+      flowDirections[boundaryIndex * 3] = fanFlow.x
+      flowDirections[boundaryIndex * 3 + 1] = fanFlow.y
+      flowDirections[boundaryIndex * 3 + 2] = fanFlow.z
+      flowPhases[boundaryIndex] = entryLength / 1.6
+      laneLaterals[boundaryIndex] = columnIndex / (entryTransition.length - 1)
+      const inletWallDistance = 1 - Math.abs((columnIndex / (entryTransition.length - 1)) * 2 - 1)
+      return { boundary, boundaryIndex, collar, inletWallDistance, start }
+    })
+    const appendEntryVertex = (
+      point: THREE.Vector3,
+      longitudinalProgress: number,
+      lateralProgress: number,
+      flow: THREE.Vector3,
+      flowPhase: number,
+      entryFade: number,
+      inletWallDistance: number,
+    ): number => {
+      const index = positions.length / 3
+      positions.push(point.x, point.y + TRACK_WATER_SURFACE_OFFSET, point.z)
+      uvs.push(longitudinalProgress, lateralProgress)
+      entryFades.push(entryFade)
+      laneBlends.push(1)
+      flowDirections.push(flow.x, flow.y, flow.z)
+      flowPhases.push(flowPhase)
+      laneLaterals.push(lateralProgress)
+      wallDistances.push(inletWallDistance)
+      wallFoamStrengths.push(1)
+      return index
+    }
+    const startIndices = sections.map((section, columnIndex) =>
+      appendEntryVertex(
+        section.start,
+        0,
+        columnIndex / (sections.length - 1),
+        approachFlow,
+        0,
+        options.entryConnected ? 1 : 0,
+        section.inletWallDistance,
+      ),
+    )
+    const entryCollarVertexOffset = positions.length / 3
+    const collarProgress = approachLength / entryLength
+    const collarIndices = sections.map((section, columnIndex) =>
+      appendEntryVertex(
+        section.collar,
+        collarProgress,
+        columnIndex / (sections.length - 1),
+        collarFlow,
+        approachLength / 1.6,
+        options.entryConnected ? 1 : collarProgress,
+        section.inletWallDistance,
+      ),
+    )
+    const entryBoundaryVertexOffset = positions.length / 3
+    const boundaryIndices = sections.map((section, columnIndex) =>
+      appendEntryVertex(
+        section.boundary,
+        1,
+        columnIndex / (sections.length - 1),
+        fanFlow,
+        entryLength / 1.6,
+        1,
+        section.inletWallDistance,
+      ),
+    )
+    boundaryIndices.forEach((boundaryIndex, columnIndex) => {
+      entryBoundaryNormalPairs.push([boundaryIndex, sections[columnIndex]!.boundaryIndex])
+    })
+    for (let column = 0; column < sections.length - 1; column += 1) {
+      const start = startIndices[column]!
+      const nextStart = startIndices[column + 1]!
+      const collar = collarIndices[column]!
+      const nextCollar = collarIndices[column + 1]!
+      const boundary = boundaryIndices[column]!
+      const nextBoundary = boundaryIndices[column + 1]!
+      indices.push(start, nextStart, collar, nextStart, nextCollar, collar)
+      indices.push(collar, nextCollar, boundary, nextCollar, nextBoundary, boundary)
+    }
+    geometryMetadata.waterEntryStartVertexOffset = entryStartVertexOffset
+    geometryMetadata.waterEntryCollarVertexOffset = entryCollarVertexOffset
+    geometryMetadata.waterEntryBoundaryVertexOffset = entryBoundaryVertexOffset
+    geometryMetadata.waterEntryColumnCount = sections.length
+    geometryMetadata.waterEntryRowCount = 3
+  }
+
+  const centerFunnel = options.centerFunnel ?? []
+  const funnelOffset = positions.length / 3
+  if (centerFunnel.length >= 2) {
+    for (const [ringIndex, ring] of centerFunnel.entries()) {
+      const funnelProgress = ringIndex / (centerFunnel.length - 1)
+      for (const [angleIndex, angle] of closedSurfaceAngles.entries()) {
+        const angularProgress =
+          angleIndex === closedSurfaceAngles.length - 1 ? 1 : normalizeAngle(angle) / (Math.PI * 2)
+        positions.push(
+          Math.cos(angle) * ring.radius,
+          ring.height - centerY + TRACK_WATER_SURFACE_OFFSET,
+          Math.sin(angle) * ring.radius,
+        )
+        uvs.push((1 - funnelProgress) * 0.18, angularProgress)
+        entryFades.push(1)
+        laneBlends.push(0)
+        flowDirections.push(0, 0, -1)
+        flowPhases.push(0)
+        laneLaterals.push(0.5)
+        wallDistances.push(1)
+        wallFoamStrengths.push(0)
+      }
+    }
+    for (let ring = 0; ring < centerFunnel.length - 1; ring += 1) {
+      for (let segment = 0; segment < surfaceAngles.length; segment += 1) {
+        const inner = funnelOffset + ring * rowSize + segment
+        const outer = inner + rowSize
+        indices.push(inner, inner + 1, outer, outer, inner + 1, outer + 1)
+      }
+    }
+  }
+
+  const geometry = new THREE.BufferGeometry()
+  geometry.name = 'vortex-water-surface-geometry'
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3))
+  geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2))
+  geometry.setAttribute('waterEntryFade', new THREE.Float32BufferAttribute(entryFades, 1))
+  geometry.setAttribute('waterLaneBlend', new THREE.Float32BufferAttribute(laneBlends, 1))
+  geometry.setAttribute('waterFlowDirection', new THREE.Float32BufferAttribute(flowDirections, 3))
+  geometry.setAttribute('waterFlowPhase', new THREE.Float32BufferAttribute(flowPhases, 1))
+  geometry.setAttribute('waterLaneLateral', new THREE.Float32BufferAttribute(laneLaterals, 1))
+  geometry.setAttribute('waterWallDistance', new THREE.Float32BufferAttribute(wallDistances, 1))
+  geometry.setAttribute('waterWallFoamStrength', new THREE.Float32BufferAttribute(wallFoamStrengths, 1))
+  geometry.setIndex(indices)
+  Object.assign(geometry.userData, geometryMetadata)
+  geometry.userData.waterEntryWallDistanceBasis = 'topology-owned-inlet-rows-with-open-bowl-mouth'
+  geometry.userData.waterEntryTerminalHalfWidth = entryTerminalHalfWidth
+  geometry.computeVertexNormals()
+  const normals = geometry.getAttribute('normal')
+  const seamRingOffsets = [
+    ...Array.from({ length: SURFACE_RADIAL_SEGMENTS + 1 }, (_, ring) => ring * rowSize),
+    ...(centerFunnel.length >= 2
+      ? Array.from({ length: centerFunnel.length }, (_, ring) => funnelOffset + ring * rowSize)
+      : []),
+  ]
+  for (const offset of seamRingOffsets) {
+    const first = new THREE.Vector3().fromBufferAttribute(normals, offset)
+    const last = new THREE.Vector3().fromBufferAttribute(normals, offset + rowSize - 1)
+    const shared = first.add(last).normalize()
+    normals.setXYZ(offset, shared.x, shared.y, shared.z)
+    normals.setXYZ(offset + rowSize - 1, shared.x, shared.y, shared.z)
+  }
+  for (const [entryBoundaryIndex, bowlBoundaryIndex] of entryBoundaryNormalPairs) {
+    const shared = new THREE.Vector3()
+      .fromBufferAttribute(normals, entryBoundaryIndex)
+      .add(new THREE.Vector3().fromBufferAttribute(normals, bowlBoundaryIndex))
+      .normalize()
+    normals.setXYZ(entryBoundaryIndex, shared.x, shared.y, shared.z)
+    normals.setXYZ(bowlBoundaryIndex, shared.x, shared.y, shared.z)
+  }
+  normals.needsUpdate = true
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  return geometry
+}
+
+function toLocalWaterPoint(
+  point: THREE.Vector3 | readonly [number, number, number],
+  center: THREE.Vector3,
+): THREE.Vector3 {
+  return (point instanceof THREE.Vector3 ? point.clone() : new THREE.Vector3(...point)).sub(center)
+}
+
+function markAsDecoration(object: THREE.Object3D, ownsMaterial = false): void {
+  object.userData.decorative = true
+  object.userData.visualOnly = true
+  if (ownsMaterial) object.userData.ownsMaterial = true
+}
+
+function assertVortexWaterEffectOptions(options: VortexWaterEffectOptions): void {
+  if (!options.pieceId) throw new Error('Vortex water effect requires a pieceId.')
+  if (!Number.isFinite(options.innerRadius) || options.innerRadius <= 0) {
+    throw new Error('Vortex water effect innerRadius must be positive.')
+  }
+  if (!Number.isFinite(options.outerRadius) || options.outerRadius <= options.innerRadius) {
+    throw new Error('Vortex water effect outerRadius must be greater than innerRadius.')
+  }
+  if (options.dropLength !== undefined && (!Number.isFinite(options.dropLength) || options.dropLength <= 0)) {
+    throw new Error('Vortex water effect dropLength must be positive when provided.')
+  }
+}
+
+function nowMilliseconds(): number {
+  return typeof performance === 'undefined' ? Date.now() : performance.now()
+}
+
+const WATER_SURFACE_VERTEX_SHADER = /* glsl */ `
+  uniform float uTime;
+  uniform float uWaveAmplitude;
+  uniform float uOrbitDirection;
+  uniform float uStartAngle;
+  uniform float uLaneMode;
+  attribute float waterEntryFade;
+  attribute float waterLaneBlend;
+  attribute float waterLaneLateral;
+  attribute vec3 waterFlowDirection;
+  attribute float waterFlowPhase;
+  attribute float waterTurbulence;
+  attribute float waterWallDistance;
+  attribute float waterWallFoamStrength;
+
+  varying float vRadialProgress;
+  varying float vAngularProgress;
+  varying float vEntryFade;
+  varying float vLaneBlend;
+  varying vec3 vWaterWorldPosition;
+  varying vec3 vWaterWorldNormal;
+  varying vec3 vWaterWorldFlow;
+  varying float vWaterFlowPhase;
+  varying float vTurbulence;
+  varying float vWaterWallDistance;
+  varying float vWaterWallFoamStrength;
+
+  #include <fog_pars_vertex>
+
+  void main() {
+    float radialProgress = clamp(uv.x, 0.0, 1.0);
+    float angle = uv.y * 6.28318530718 + uStartAngle;
+    float directedAngle = angle * uOrbitDirection;
+    float laneBlend = max(step(0.5, uLaneMode), waterLaneBlend);
+
+    vec3 vortexFlow = normalize(vec3(-position.z, 0.0, position.x) * uOrbitDirection + vec3(0.000001));
+    vec3 localFlow = normalize(mix(vortexFlow, waterFlowDirection, laneBlend));
+    vec3 worldFlow = normalize(mat3(modelMatrix) * localFlow);
+    vec3 worldNormal = normalize(mat3(modelMatrix) * normal);
+
+    vec3 displaced = position;
+
+    vec3 waterWorldPosition = (modelMatrix * vec4(displaced, 1.0)).xyz;
+    vRadialProgress = radialProgress;
+    vAngularProgress = mix(uv.y, waterLaneLateral, laneBlend);
+    vEntryFade = waterEntryFade;
+    vLaneBlend = laneBlend;
+    vWaterWorldPosition = waterWorldPosition;
+    vWaterWorldNormal = worldNormal;
+    vWaterWorldFlow = worldFlow;
+    vWaterFlowPhase = waterFlowPhase;
+    vTurbulence = waterTurbulence;
+    vWaterWallDistance = waterWallDistance;
+    vWaterWallFoamStrength = waterWallFoamStrength;
+    vec4 mvPosition = modelViewMatrix * vec4(displaced, 1.0);
+    gl_Position = projectionMatrix * mvPosition;
+    #include <fog_vertex>
+  }
+`
+
+const WATER_SURFACE_FRAGMENT_SHADER = /* glsl */ `
+  uniform vec3 uDeepColor;
+  uniform vec3 uShallowColor;
+  uniform vec3 uFoamColor;
+  uniform vec3 uAccentColor;
+  uniform float uOpacity;
+  uniform float uAccentStrength;
+  uniform float uTime;
+  uniform float uOrbitDirection;
+  uniform float uStartAngle;
+  uniform float uLaneMode;
+
+  varying float vRadialProgress;
+  varying float vAngularProgress;
+  varying float vEntryFade;
+  varying float vLaneBlend;
+  varying vec3 vWaterWorldPosition;
+  varying vec3 vWaterWorldNormal;
+  varying vec3 vWaterWorldFlow;
+  varying float vWaterFlowPhase;
+  varying float vTurbulence;
+  varying float vWaterWallDistance;
+  varying float vWaterWallFoamStrength;
+
+  #include <fog_pars_fragment>
+
+  float waterHash(vec2 point) {
+    return fract(sin(dot(point, vec2(127.1, 311.7))) * 43758.5453123);
+  }
+
+  float waterNoise(vec2 point) {
+    vec2 cell = floor(point);
+    vec2 fraction = fract(point);
+    fraction = fraction * fraction * (3.0 - 2.0 * fraction);
+    float a = waterHash(cell);
+    float b = waterHash(cell + vec2(1.0, 0.0));
+    float c = waterHash(cell + vec2(0.0, 1.0));
+    float d = waterHash(cell + vec2(1.0, 1.0));
+    return mix(mix(a, b, fraction.x), mix(c, d, fraction.x), fraction.y);
+  }
+
+  float waterFbm(vec2 point) {
+    float value = 0.0;
+    float amplitude = 0.54;
+    for (int octave = 0; octave < 4; octave += 1) {
+      value += waterNoise(point) * amplitude;
+      point = mat2(1.72, 1.21, -1.21, 1.72) * point + 1.37;
+      amplitude *= 0.48;
+    }
+    return value;
+  }
+
+  void main() {
+    float laneBlend = vLaneBlend;
+    float angle = vAngularProgress * 6.28318530718 + uStartAngle;
+    float directedAngle = angle * uOrbitDirection;
+    vec2 vortexOrbit = vec2(cos(directedAngle), sin(directedAngle));
+
+    float lanePhase = vWaterFlowPhase * 6.28318530718;
+    float vortexPhase = directedAngle * 2.0 - vRadialProgress * 17.0;
+    float flowPhase = mix(vortexPhase, lanePhase, laneBlend);
+    float lateral = vAngularProgress * 2.0 - 1.0;
+    float broadPhase = mix(
+      directedAngle * 2.0 - vRadialProgress * 17.0 - uTime * 1.15 + vortexOrbit.y * 1.8,
+      flowPhase - uTime * 1.15 + lateral * 1.8,
+      laneBlend
+    );
+    float finePhase = mix(
+      directedAngle * 5.0 - vRadialProgress * 39.0 - uTime * 2.18 - vortexOrbit.x * 6.4,
+      flowPhase * 2.35 - uTime * 2.18 - lateral * 6.4,
+      laneBlend
+    );
+    float crossPhase = mix(
+      directedAngle * 3.0 - vRadialProgress * 12.0 - uTime * 0.82 + vortexOrbit.y * 5.8,
+      flowPhase * 0.72 - uTime * 0.82 + lateral * 11.6,
+      laneBlend
+    );
+    float flowSlope = cos(broadPhase) * 0.022 + cos(finePhase) * 0.034 + cos(crossPhase) * 0.018;
+    float sideSlope = cos(broadPhase) * 0.018 - cos(finePhase) * 0.036 + cos(crossPhase) * 0.042;
+
+    vec3 baseNormal = normalize(vWaterWorldNormal);
+    vec3 flowTangent = normalize(vWaterWorldFlow - baseNormal * dot(vWaterWorldFlow, baseNormal));
+    vec3 lateralTangent = normalize(cross(baseNormal, flowTangent));
+    vec3 waterNormal = normalize(baseNormal - flowTangent * flowSlope - lateralTangent * sideSlope);
+    vec3 viewDirection = normalize(cameraPosition - vWaterWorldPosition);
+    float fresnel = pow(1.0 - clamp(dot(waterNormal, viewDirection), 0.0, 1.0), 3.2);
+    vec3 keyDirection = normalize(vec3(-0.34, 0.87, 0.35));
+    float diffuseLight = max(dot(waterNormal, keyDirection), 0.0);
+    vec3 halfDirection = normalize(keyDirection + viewDirection);
+    float specular = pow(max(dot(waterNormal, halfDirection), 0.0), 96.0);
+
+    // Everything below is expressed in accumulated path space. Two differently
+    // advected ripple families create a flowing, broken interference mesh without
+    // resetting or fanning radially when the lane curves.
+    vec2 vortexCurrentCoordinates =
+      vortexOrbit * (2.4 + vRadialProgress * 1.8) + vec2(-uTime * 0.36, uTime * 0.055);
+    vec2 laneCurrentCoordinates = vec2(flowPhase * 0.24 - uTime * 0.36, lateral * 4.8 + uTime * 0.055);
+    vec2 currentCoordinates = mix(vortexCurrentCoordinates, laneCurrentCoordinates, laneBlend);
+    float bodyNoise = waterFbm(currentCoordinates * 0.72);
+    float currentWarp = (bodyNoise - 0.5) * 2.0;
+    float shallowMix = mix(smoothstep(0.04, 1.0, vRadialProgress), 0.48 + bodyNoise * 0.16, laneBlend);
+    vec3 waterColor = mix(uDeepColor, uShallowColor, clamp(shallowMix, 0.0, 1.0));
+    waterColor *= 0.66 + diffuseLight * 0.24;
+    waterColor = mix(waterColor, vec3(0.34, 0.61, 0.58), fresnel * 0.34);
+    waterColor += vec3(1.0, 0.88, 0.7) * specular * 0.12;
+
+    float rippleFamilyA = sin(mix(
+      directedAngle * 7.0 - vRadialProgress * 55.0 - uTime * 2.35 + vortexOrbit.y * 2.8 + currentWarp * 2.8,
+      flowPhase * 3.25 - uTime * 2.35 + lateral * 9.4 + currentWarp * 2.8,
+      laneBlend
+    ));
+    float rippleFamilyB = sin(mix(
+      directedAngle * 5.0 - vRadialProgress * 36.0 - uTime * 1.46 - vortexOrbit.x * 3.6 - currentWarp * 3.6,
+      flowPhase * 2.1 - uTime * 1.46 - lateral * 15.6 - currentWarp * 3.6,
+      laneBlend
+    ));
+    float rippleFamilyC = sin(mix(
+      directedAngle * 9.0 - vRadialProgress * 72.0 - uTime * 2.9 + vortexOrbit.y * 3.1 +
+        sin(directedAngle * 4.0 + uTime * 0.52),
+      flowPhase * 4.6 - uTime * 2.9 + lateral * 3.1 + sin(lateral * 18.0 + uTime * 0.52),
+      laneBlend
+    ));
+    float rippleMesh = max(1.0 - abs(rippleFamilyA), 1.0 - abs(rippleFamilyB));
+    rippleMesh = max(rippleMesh, (1.0 - abs(rippleFamilyC)) * 0.78);
+    vec2 rippleBreakupCoordinates = mix(
+      vortexOrbit * (3.7 + vRadialProgress * 2.1) + vec2(-uTime * 0.14, uTime * 0.09),
+      vec2(flowPhase * 0.42 - uTime * 0.14, lateral * 7.6 + uTime * 0.09),
+      laneBlend
+    );
+    float rippleBreakup = waterFbm(rippleBreakupCoordinates);
+    float rippleHighlight = pow(clamp(rippleMesh, 0.0, 1.0), 2.7) * smoothstep(0.28, 0.82, rippleBreakup);
+    float softCurrent = smoothstep(0.54, 0.96, 0.5 + 0.5 * rippleFamilyA) * (0.35 + bodyNoise * 0.65);
+    float refractiveShimmer =
+      (0.5 + 0.5 * rippleFamilyA) * (0.5 + 0.5 * rippleFamilyB) * (0.55 + bodyNoise * 0.45);
+    waterColor += vec3(0.32, 0.52, 0.48) * rippleHighlight * 0.18;
+    waterColor += vec3(0.2, 0.4, 0.37) * refractiveShimmer * 0.09;
+    waterColor += vec3(0.15, 0.31, 0.29) * softCurrent * 0.035;
+    float accentRibbon = rippleHighlight * (0.72 + 0.28 * smoothstep(0.52, 0.86, rippleBreakup));
+    waterColor = mix(waterColor, uAccentColor, clamp(accentRibbon * uAccentStrength * 0.78, 0.0, 0.78));
+    waterColor += uAccentColor * accentRibbon * uAccentStrength * 0.12;
+
+    vec2 foamCoordinates = mix(
+      vortexOrbit * (4.8 + vRadialProgress * 1.6) + vec2(-uTime * 0.22, 0.0),
+      vec2(vWaterFlowPhase * 4.8 - uTime * 0.22, vAngularProgress * 12.0),
+      laneBlend
+    );
+    float foamNoise = waterFbm(foamCoordinates + bodyNoise * 1.3);
+    float wallDistance = max(0.0, vWaterWallDistance);
+    float edgeBand = exp(-pow((wallDistance - 0.045) * 13.0, 2.0));
+    float edgeBreakup = smoothstep(0.54, 0.82, foamNoise + sin(flowPhase * 0.7) * 0.08);
+    float edgeFoam = edgeBand * (0.48 + edgeBreakup * 0.52);
+    float bendFoam = vTurbulence * edgeBand * (0.42 + smoothstep(0.6, 0.86, foamNoise) * 0.45);
+    float foam = max(edgeFoam, bendFoam) * clamp(vWaterWallFoamStrength, 0.0, 1.0);
+
+    float alpha = clamp(uOpacity + fresnel * 0.15 + foam * 0.18 + rippleHighlight * 0.035, 0.0, 0.77);
+    waterColor = mix(waterColor, uFoamColor, foam * 0.78);
+
+    float entryMask = clamp(vEntryFade, 0.0, 1.0);
+    waterColor = mix(uShallowColor * 1.08, waterColor, 0.32 + entryMask * 0.68);
+    gl_FragColor = vec4(waterColor, alpha * entryMask);
+    #include <tonemapping_fragment>
+    #include <colorspace_fragment>
+
+    #ifdef USE_FOG
+      #ifdef FOG_EXP2
+        float waterFogFactor = 1.0 - exp(-fogDensity * fogDensity * vFogDepth * vFogDepth);
+      #else
+        float waterFogFactor = smoothstep(fogNear, fogFar, vFogDepth);
+      #endif
+      // Water follows scene fog but keeps a faint readable body at maximum
+      // distance instead of becoming indistinguishable from the background.
+      gl_FragColor.rgb = mix(gl_FragColor.rgb, fogColor, waterFogFactor * 0.84);
+    #endif
+  }
+`