@marble.fun/track-catalog 3.0.0

package/src/pages/lobby/marble-factory.ts

@@ -0,0 +1,931 @@
+import * as THREE from 'three'
+
+import { homepageMarbleGeometry } from '../../three/homepage-marble-geometry'
+import { MarbleSphereGeometry } from '../../three/marble-sphere-geometry'
+
+import { VisualCylinderGeometry, VisualTorusGeometry, VisualLatheGeometry, VisualExtrudeGeometry } from '../../three/visual-geometry'
+
+import type { MarbleSpec } from './lobby-types'
+
+export interface LobbyMarble {
+  root: THREE.Group
+  marble: THREE.Mesh<THREE.SphereGeometry, THREE.Material>
+  ready: Promise<void>
+  setFocused(focused: boolean): void
+  setBacked(backed: boolean): void
+  setRestingY(y: number): void
+  setPodiumVisible(visible: boolean): void
+  setInFrontOfLens(inFront: boolean): void
+  setEntranceReveal(progress: number): void
+  setPerformanceMode(enabled: boolean): void
+  update(elapsedSeconds: number): void
+  dispose(): void
+}
+
+export interface LobbyMarbleOptions {
+  /** Restore original sphere and filament tessellation for the homepage showcase only. */
+  homepageGeometry?: boolean
+  includeLogo?: boolean
+  geometryDetail?: 'default' | 'medium'
+  performanceMaterial?: boolean
+  tokenMaterial?: THREE.Material
+}
+
+export const LOBBY_MARBLE_RADIUS = 0.73
+export const LOBBY_TOKEN_OUTER_RADIUS = 0.738
+
+const sharedMarbleGeometry = new MarbleSphereGeometry(LOBBY_MARBLE_RADIUS, 48, 40)
+sharedMarbleGeometry.userData.shared = true
+const sharedMediumMarbleGeometry = new MarbleSphereGeometry(LOBBY_MARBLE_RADIUS, 32, 24)
+sharedMediumMarbleGeometry.userData.shared = true
+const sharedBubbleRimGeometry = new MarbleSphereGeometry(LOBBY_TOKEN_OUTER_RADIUS, 40, 32)
+sharedBubbleRimGeometry.userData.shared = true
+
+interface SharedVeinTextures {
+  colorTexture: THREE.CanvasTexture
+  roughnessTexture: THREE.CanvasTexture
+  ready: Promise<void>
+  references: number
+}
+
+const veinTextureCache = new Map<string, SharedVeinTextures>()
+const GLOSSY_LOGO_COLOR = '#9aa09e'
+
+function buildVeinTextures(spec: MarbleSpec, includeLogo: boolean): SharedVeinTextures {
+  const canvas = document.createElement('canvas')
+  canvas.width = 768
+  canvas.height = 384
+  const context = canvas.getContext('2d')
+  if (!context) throw new Error('Canvas 2D context is unavailable')
+  const roughnessCanvas = document.createElement('canvas')
+  roughnessCanvas.width = canvas.width
+  roughnessCanvas.height = canvas.height
+  const roughnessContext = roughnessCanvas.getContext('2d')
+  if (!roughnessContext) throw new Error('Canvas 2D context is unavailable')
+  roughnessContext.fillStyle = '#303030'
+  roughnessContext.fillRect(0, 0, roughnessCanvas.width, roughnessCanvas.height)
+  const image = context.createImageData(canvas.width, canvas.height)
+  let seed = [...spec.id].reduce((value, character) => value + character.charCodeAt(0) * 97, 17)
+  const random = () => {
+    seed = (seed * 1664525 + 1013904223) >>> 0
+    return seed / 4294967296
+  }
+  const phase = random() * Math.PI * 2
+
+  for (let y = 0; y < canvas.height; y += 1) {
+    const v = y / canvas.height
+    for (let x = 0; x < canvas.width; x += 1) {
+      const u = x / canvas.width
+      const theta = u * Math.PI * 2
+      const cloud =
+        Math.sin(theta * 2 + v * 5.2 + phase) * 0.52 +
+        Math.sin(theta * 4 - v * 8.5 + phase * 1.8) * 0.28 +
+        Math.sin(theta * 9 + v * 15 - phase * 0.7) * 0.13 +
+        Math.sin(theta * 17 - v * 23 + phase * 2.4) * 0.06
+      const broadCloud =
+        Math.sin(theta * 1.15 + v * 3.1 + phase * 0.55) * 0.62 + Math.sin(theta * 0.58 - v * 5.4 + phase * 1.35) * 0.38
+      const patchField = broadCloud + Math.sin(theta * 2.35 + v * 2.2 - phase * 0.8) * 0.28
+      const darkPatch = THREE.MathUtils.smoothstep(patchField, -0.58, 0.78)
+      const value = Math.max(180, Math.min(246, 236 + cloud * 14 - darkPatch * 40))
+      const pixel = (y * canvas.width + x) * 4
+      image.data[pixel] = value
+      image.data[pixel + 1] = Math.min(255, value + 2)
+      image.data[pixel + 2] = Math.min(255, value + 1)
+      image.data[pixel + 3] = 255
+    }
+  }
+  context.putImageData(image, 0, 0)
+
+  interface VeinPoint {
+    x: number
+    y: number
+  }
+  const traceCrackPath = (points: VeinPoint[], offsetX = 0) => {
+    context.beginPath()
+    context.moveTo(points[0]!.x + offsetX, points[0]!.y)
+    for (let index = 1; index < points.length; index += 1) {
+      const point = points[index]!
+      context.lineTo(point.x + offsetX, point.y)
+    }
+  }
+  const strokeWrappedPath = (points: VeinPoint[], style: string, width: number, blur = 0) => {
+    for (const offsetX of [-canvas.width, 0, canvas.width]) {
+      traceCrackPath(points, offsetX)
+      context.strokeStyle = style
+      context.lineWidth = width
+      context.lineCap = 'round'
+      context.lineJoin = 'miter'
+      context.filter = blur ? `blur(${blur}px)` : 'none'
+      context.stroke()
+    }
+    context.filter = 'none'
+  }
+  const fillWrappedVariablePath = (points: VeinPoint[], style: string, baseWidth: number, phaseOffset: number) => {
+    const edgePoints = points.map((point, index) => {
+      const previous = points[Math.max(0, index - 1)]!
+      const next = points[Math.min(points.length - 1, index + 1)]!
+      const tangentX = next.x - previous.x
+      const tangentY = next.y - previous.y
+      const tangentLength = Math.max(0.001, Math.hypot(tangentX, tangentY))
+      const progress = index / (points.length - 1)
+      const taper = Math.sin(progress * Math.PI) ** 0.42
+      const variation =
+        0.92 +
+        Math.sin(progress * Math.PI * 2.4 + phaseOffset) * 0.24 +
+        Math.sin(progress * Math.PI * 5.2 - phaseOffset * 0.7) * 0.1
+      const halfWidth = baseWidth * Math.max(0.16, taper) * Math.max(0.5, variation) * 0.5
+      const normalX = -tangentY / tangentLength
+      const normalY = tangentX / tangentLength
+      return {
+        left: { x: point.x + normalX * halfWidth, y: point.y + normalY * halfWidth },
+        right: { x: point.x - normalX * halfWidth, y: point.y - normalY * halfWidth },
+      }
+    })
+    context.fillStyle = style
+    for (const offsetX of [-canvas.width, 0, canvas.width]) {
+      context.beginPath()
+      context.moveTo(edgePoints[0]!.left.x + offsetX, edgePoints[0]!.left.y)
+      for (let index = 1; index < edgePoints.length; index += 1) {
+        const edge = edgePoints[index]!
+        context.lineTo(edge.left.x + offsetX, edge.left.y)
+      }
+      for (let index = edgePoints.length - 1; index >= 0; index -= 1) {
+        const edge = edgePoints[index]!
+        context.lineTo(edge.right.x + offsetX, edge.right.y)
+      }
+      context.closePath()
+      context.fill()
+    }
+  }
+
+  const veinCount = 7
+  for (let veinIndex = 0; veinIndex < veinCount; veinIndex += 1) {
+    const points: VeinPoint[] = []
+    const pointCount = 9 + Math.floor(random() * 6)
+    const crackLength = canvas.width * (0.3 + random() * 0.2)
+    const longitudeSlot = (veinIndex / veinCount) * canvas.width
+    const crackStartX = longitudeSlot + (random() - 0.5) * canvas.width * 0.14
+    let veinY = 62 + random() * (canvas.height - 124)
+    let verticalDrift = (random() - 0.5) * 9
+    for (let pointIndex = 0; pointIndex < pointCount; pointIndex += 1) {
+      verticalDrift = THREE.MathUtils.clamp(verticalDrift + (random() - 0.5) * 7, -14, 14)
+      veinY += verticalDrift + (random() - 0.5) * 15
+      veinY = Math.max(44, Math.min(canvas.height - 44, veinY))
+      points.push({
+        x: crackStartX + pointIndex * (crackLength / (pointCount - 1)),
+        y: veinY,
+      })
+    }
+
+    const veinWidth = 1.15 + random() * 1.85
+    strokeWrappedPath(points, 'rgba(30, 39, 37, 0.13)', veinWidth * 6.2, 5)
+    strokeWrappedPath(points, 'rgba(244, 251, 248, 0.16)', veinWidth * 3.4, 1.5)
+    fillWrappedVariablePath(points, 'rgba(45, 56, 53, 0.34)', veinWidth, phase + veinIndex)
+    fillWrappedVariablePath(
+      points,
+      'rgba(255, 255, 255, 0.27)',
+      Math.max(0.4, veinWidth * 0.22),
+      phase + veinIndex + 0.8,
+    )
+
+    for (const branchPointIndex of [Math.floor(pointCount * 0.34), Math.floor(pointCount * 0.64)]) {
+      if (random() < 0.34) continue
+      const origin = points[branchPointIndex]!
+      const branch: VeinPoint[] = [{ ...origin }]
+      let branchX = origin.x
+      let branchY = origin.y
+      const direction = random() > 0.5 ? 1 : -1
+      for (let branchIndex = 0; branchIndex < 4; branchIndex += 1) {
+        branchX += 13 + random() * 18
+        branchY += direction * (7 + random() * 16) + (random() - 0.5) * 8
+        branch.push({ x: branchX, y: branchY })
+      }
+      const branchWidth = 0.6 + random() * 0.9
+      fillWrappedVariablePath(branch, 'rgba(48, 59, 56, 0.25)', branchWidth, phase + branchPointIndex)
+      fillWrappedVariablePath(branch, 'rgba(250, 255, 253, 0.17)', branchWidth * 0.28, phase + branchPointIndex + 0.65)
+    }
+  }
+
+  const colorTexture = new THREE.CanvasTexture(canvas)
+  colorTexture.colorSpace = THREE.SRGBColorSpace
+  colorTexture.wrapS = THREE.RepeatWrapping
+  colorTexture.wrapT = THREE.RepeatWrapping
+  colorTexture.anisotropy = 4
+  const roughnessTexture = new THREE.CanvasTexture(roughnessCanvas)
+  roughnessTexture.wrapS = THREE.RepeatWrapping
+  roughnessTexture.wrapT = THREE.RepeatWrapping
+  roughnessTexture.anisotropy = 4
+  const ready = includeLogo
+    ? new Promise<void>(resolve => {
+        const centerX = canvas.width * 0.25
+        const centerY = canvas.height * 0.5
+        const logo = new Image()
+        logo.onload = () => {
+          const targetSize =
+            spec.logo === 'spacex' ? 170 : spec.logo === 'nvidia' ? 140 : spec.logo === 'microsoft' ? 98 : 130
+          const ratio = logo.naturalWidth / logo.naturalHeight || 1
+          const width = ratio >= 1 ? targetSize : targetSize * ratio
+          const height = ratio >= 1 ? targetSize / ratio : targetSize
+          const logoCanvas = document.createElement('canvas')
+          logoCanvas.width = Math.ceil(width)
+          logoCanvas.height = Math.ceil(height)
+          const logoContext = logoCanvas.getContext('2d')!
+          logoContext.drawImage(logo, 0, 0, width, height)
+          logoContext.globalCompositeOperation = 'source-in'
+          logoContext.fillStyle = GLOSSY_LOGO_COLOR
+          logoContext.fillRect(0, 0, width, height)
+          context.drawImage(logoCanvas, centerX - width / 2, centerY - height / 2)
+          roughnessContext.save()
+          roughnessContext.filter = 'brightness(0)'
+          roughnessContext.drawImage(logo, centerX - width / 2, centerY - height / 2, width, height)
+          roughnessContext.restore()
+          colorTexture.needsUpdate = true
+          roughnessTexture.needsUpdate = true
+          resolve()
+        }
+        logo.onerror = () => resolve()
+        logo.src = `/images/lobby/${spec.logo}.svg`
+      })
+    : Promise.resolve()
+  return { colorTexture, roughnessTexture, ready, references: 0 }
+}
+
+function acquireVeinTextures(spec: MarbleSpec, includeLogo: boolean): SharedVeinTextures & { release(): void } {
+  const key = `${spec.id}:${spec.logo}:${includeLogo ? 'logo' : 'plain'}`
+  const resource = veinTextureCache.get(key) ?? buildVeinTextures(spec, includeLogo)
+  if (!veinTextureCache.has(key)) veinTextureCache.set(key, resource)
+  resource.references += 1
+  let released = false
+  return {
+    ...resource,
+    release: () => {
+      if (released) return
+      released = true
+      resource.references -= 1
+      if (resource.references > 0) return
+      veinTextureCache.delete(key)
+      resource.colorTexture.dispose()
+      resource.roughnessTexture.dispose()
+    },
+  }
+}
+
+function createPodium(color: THREE.Color): {
+  aura: THREE.Mesh
+  glow: THREE.Mesh
+  group: THREE.Group
+  rings: THREE.Mesh[]
+} {
+  const group = new THREE.Group()
+  group.position.y = -1.06
+
+  const base = new THREE.Mesh(
+    new VisualLatheGeometry(
+      [
+        new THREE.Vector2(0, -0.09),
+        new THREE.Vector2(0.79, -0.09),
+        new THREE.Vector2(0.88, -0.078),
+        new THREE.Vector2(0.94, -0.057),
+        new THREE.Vector2(0.985, -0.022),
+        new THREE.Vector2(0.99, 0.004),
+        new THREE.Vector2(0.966, 0.026),
+        new THREE.Vector2(0.91, 0.052),
+        new THREE.Vector2(0.84, 0.062),
+        new THREE.Vector2(0, 0.062),
+      ],
+      128,
+    ),
+    new THREE.MeshPhysicalMaterial({
+      color: new THREE.Color(0x080b0a).lerp(color, 0.025),
+      emissive: color,
+      emissiveIntensity: 0.012,
+      metalness: 0.94,
+      roughness: 0.24,
+      clearcoat: 0.34,
+      clearcoatRoughness: 0.19,
+      anisotropy: 0.42,
+      anisotropyRotation: Math.PI / 2,
+      iridescence: 0.12,
+      iridescenceIOR: 1.45,
+    }),
+  )
+  group.add(base)
+
+  const top = new THREE.Mesh(
+    new VisualCylinderGeometry(0.79, 0.83, 0.022, 128),
+    new THREE.MeshPhysicalMaterial({
+      color: 0x010202,
+      metalness: 0.86,
+      roughness: 0.075,
+      clearcoat: 1,
+      clearcoatRoughness: 0.035,
+      envMapIntensity: 2.2,
+    }),
+  )
+  top.position.y = 0.064
+  group.add(top)
+
+  const edge = new THREE.Mesh(
+    new VisualTorusGeometry(0.925, 0.022, 12, 128),
+    new THREE.MeshPhysicalMaterial({
+      color: new THREE.Color(0x252b29).lerp(color, 0.06),
+      metalness: 1,
+      roughness: 0.14,
+      clearcoat: 0.7,
+      clearcoatRoughness: 0.08,
+    }),
+  )
+  edge.rotation.x = Math.PI / 2
+  edge.position.y = 0.027
+  group.add(edge)
+
+  const seam = new THREE.Mesh(
+    new VisualTorusGeometry(0.805, 0.007, 8, 128),
+    new THREE.MeshStandardMaterial({
+      color,
+      emissive: color,
+      emissiveIntensity: 0.72,
+      metalness: 0.45,
+      roughness: 0.24,
+    }),
+  )
+  seam.rotation.x = Math.PI / 2
+  seam.position.y = 0.078
+  group.add(seam)
+  const undercut = new THREE.Mesh(
+    new VisualTorusGeometry(0.86, 0.018, 10, 128),
+    new THREE.MeshStandardMaterial({
+      color: 0x050706,
+      metalness: 0.96,
+      roughness: 0.2,
+    }),
+  )
+  undercut.rotation.x = Math.PI / 2
+  undercut.position.y = -0.082
+  group.add(undercut)
+
+  const rings = [0.76, 0.94].map((radius, index) => {
+    const ring = new THREE.Mesh(
+      new VisualTorusGeometry(radius, index ? 0.018 : 0.014, 8, 64),
+      new THREE.MeshStandardMaterial({
+        color,
+        emissive: color,
+        emissiveIntensity: 2.1,
+        metalness: 0.08,
+        roughness: 0.22,
+      }),
+    )
+    ring.rotation.x = Math.PI / 2
+    ring.position.y = 0.05 + index * 0.025
+    ring.userData.color = color
+    ring.userData.inactiveColor = new THREE.Color(0x4a504e)
+    ring.userData.inactiveEmissive = new THREE.Color(0x171b1a)
+    group.add(ring)
+    return ring
+  })
+
+  const glow = new THREE.Mesh(
+    new VisualTorusGeometry(0.86, 0.018, 8, 64),
+    new THREE.MeshBasicMaterial({ color, transparent: true, opacity: 0.08 }),
+  )
+  glow.rotation.x = Math.PI / 2
+  glow.position.y = -0.958
+  const aura = new THREE.Mesh(
+    new VisualTorusGeometry(0.91, 0.045, 12, 64),
+    new THREE.MeshBasicMaterial({
+      color,
+      blending: THREE.AdditiveBlending,
+      transparent: true,
+      opacity: 0.022,
+      depthWrite: false,
+    }),
+  )
+  aura.rotation.x = Math.PI / 2
+  aura.position.y = -0.95
+  return { aura, glow, group, rings }
+}
+
+function createFilamentTexture(): THREE.CanvasTexture {
+  const canvas = document.createElement('canvas')
+  canvas.width = 256
+  canvas.height = 256
+  const context = canvas.getContext('2d')
+  if (!context) throw new Error('Canvas 2D context is unavailable')
+
+  context.fillStyle = '#8f8f8f'
+  context.fillRect(0, 0, canvas.width, canvas.height)
+  for (let index = 0; index < 90; index += 1) {
+    const y = Math.random() * canvas.height
+    const alpha = 0.025 + Math.random() * 0.055
+    context.strokeStyle = `rgba(255, 255, 255, ${alpha})`
+    context.lineWidth = 0.35 + Math.random() * 1.1
+    context.beginPath()
+    context.moveTo(-24, y)
+    context.bezierCurveTo(64, y + 4, 184, y - 5, 280, y + 2)
+    context.stroke()
+  }
+
+  const texture = new THREE.CanvasTexture(canvas)
+  texture.wrapS = THREE.RepeatWrapping
+  texture.wrapT = THREE.RepeatWrapping
+  texture.repeat.set(1.3, 5)
+  texture.colorSpace = THREE.NoColorSpace
+  return texture
+}
+
+function createTokenFilament(surfaceTexture?: THREE.Texture, simplified = false, homepageGeometry = false): THREE.Group {
+  const ExtrudeGeometry = homepageGeometry ? THREE.ExtrudeGeometry : VisualExtrudeGeometry
+  const group = new THREE.Group()
+  const scale = 0.00505
+  const x = (value: number) => (value - 128) * scale
+  const y = (value: number) => (128 - value) * scale
+  const point = (pointX: number, pointY: number) => [x(pointX), y(pointY)] as const
+  const moveTo = (shape: THREE.Shape, [pointX, pointY]: readonly [number, number]) => {
+    shape.moveTo(pointX, pointY)
+  }
+  const curveTo = (
+    shape: THREE.Shape,
+    [control1X, control1Y]: readonly [number, number],
+    [control2X, control2Y]: readonly [number, number],
+    [pointX, pointY]: readonly [number, number],
+  ) => {
+    shape.bezierCurveTo(control1X, control1Y, control2X, control2Y, pointX, pointY)
+  }
+
+  const start = point(48.804, 207.196)
+  const end = point(207.196, 48.804)
+  const lower = new THREE.Shape()
+  moveTo(lower, start)
+  curveTo(lower, point(86, 196), point(123, 171), point(147, 144))
+  curveTo(lower, point(171, 117), point(178, 62), end)
+  curveTo(lower, point(180, 66), point(168, 112), point(142, 137))
+  curveTo(lower, point(112, 165), point(83, 190), start)
+  lower.closePath()
+
+  const middle = new THREE.Shape()
+  moveTo(middle, start)
+  curveTo(middle, point(83, 190), point(112, 165), point(142, 137))
+  curveTo(middle, point(168, 112), point(180, 66), end)
+  curveTo(middle, point(181, 62), point(156, 91), point(134, 119))
+  curveTo(middle, point(112, 148), point(89, 183), start)
+  middle.closePath()
+
+  const upper = new THREE.Shape()
+  moveTo(upper, start)
+  curveTo(upper, point(89, 183), point(112, 148), point(134, 119))
+  curveTo(upper, point(156, 91), point(181, 62), end)
+  curveTo(upper, point(171, 48), point(140, 67), point(118, 101))
+  curveTo(upper, point(96, 135), point(77, 190), start)
+  upper.closePath()
+
+  const pieces = [
+    { shape: lower, color: '#dcff72', emissive: '#789b26' },
+    { shape: middle, color: '#c9ff3d', emissive: '#6d941f' },
+    { shape: upper, color: '#9fce32', emissive: '#526f1d' },
+  ] as const
+
+  pieces.forEach(({ shape, color, emissive }) => {
+    const geometry = new ExtrudeGeometry(shape, {
+      depth: 0.04,
+      bevelEnabled: true,
+      bevelSegments: simplified ? 1 : 3,
+      bevelSize: 0.006,
+      bevelThickness: 0.006,
+      curveSegments: simplified ? 24 : 64,
+      steps: 1,
+    })
+    geometry.translate(0, 0, -0.02)
+    const positions = geometry.getAttribute('position')
+    for (let index = 0; index < positions.count; index += 1) {
+      const localX = positions.getX(index)
+      const localY = positions.getY(index)
+      const alongRibbon = localX + localY
+      const acrossRibbon = localY - localX
+      positions.setZ(index, positions.getZ(index) + Math.sin(alongRibbon * 3.2) * 0.026 + acrossRibbon * 0.055)
+    }
+    positions.needsUpdate = true
+    geometry.computeVertexNormals()
+    const material = simplified
+      ? new THREE.MeshStandardMaterial({
+          color: new THREE.Color(color),
+          emissive: new THREE.Color(emissive),
+          emissiveIntensity: 0.08,
+          roughness: 0.38,
+          metalness: 0,
+          side: THREE.DoubleSide,
+          transparent: true,
+          depthWrite: false,
+          toneMapped: false,
+        })
+      : [
+          new THREE.MeshPhysicalMaterial({
+            color: new THREE.Color(color),
+            emissive: new THREE.Color(emissive),
+            emissiveIntensity: 0.05,
+            roughness: 0.3,
+            roughnessMap: surfaceTexture,
+            bumpMap: surfaceTexture,
+            bumpScale: 0.006,
+            metalness: 0,
+            clearcoat: 0.42,
+            clearcoatRoughness: 0.2,
+            sheen: 0.16,
+            sheenColor: new THREE.Color('#eaffaa'),
+            side: THREE.DoubleSide,
+            transparent: true,
+            opacity: 1,
+            depthTest: true,
+            depthWrite: false,
+            toneMapped: false,
+          }),
+          new THREE.MeshBasicMaterial({
+            color: new THREE.Color(color),
+            side: THREE.DoubleSide,
+            transparent: true,
+            opacity: 1,
+            depthTest: true,
+            depthWrite: false,
+            toneMapped: false,
+          }),
+        ]
+    const piece = new THREE.Mesh(geometry, material)
+    piece.renderOrder = 4
+    group.add(piece)
+  })
+  group.rotation.set(-0.08, -0.12, -0.035)
+  group.scale.setScalar(1.28)
+  group.renderOrder = 4
+  return group
+}
+
+let sharedPackedFilament: THREE.Group | undefined
+
+function createPackedTokenFilament(): THREE.Group {
+  if (!sharedPackedFilament) {
+    const surfaceTexture = createFilamentTexture()
+    surfaceTexture.userData.shared = true
+    sharedPackedFilament = createTokenFilament(surfaceTexture)
+    sharedPackedFilament.traverse(object => {
+      if (!(object instanceof THREE.Mesh)) return
+      object.geometry.userData.shared = true
+      const materials = Array.isArray(object.material) ? object.material : [object.material]
+      materials.forEach(material => {
+        material.userData.shared = true
+      })
+    })
+  }
+  return sharedPackedFilament.clone(true)
+}
+
+export function createLobbyMarble(spec: MarbleSpec, options: LobbyMarbleOptions = {}): LobbyMarble {
+  const root = new THREE.Group()
+  root.name = `lobby-marble:${spec.id}`
+  const color = new THREE.Color(spec.color)
+  const isToken = spec.materialStyle === 'marble-token'
+  const isPackedToken = spec.materialStyle === 'packed-token'
+  const isPackedStock = spec.materialStyle === 'packed-stock'
+  const supportsEntranceFade = spec.interactive === true || spec.entranceFade === true
+  const ownedTextures: THREE.Texture[] = []
+  const releaseSharedResources: Array<() => void> = []
+  let ready = Promise.resolve()
+
+  const marbleMaterial = isToken
+    ? (options.tokenMaterial ??
+      new THREE.MeshPhysicalMaterial({
+        color: 0xffffff,
+        emissive: 0xffffff,
+        emissiveIntensity: 0.002,
+        metalness: 0,
+        roughness: 0.08,
+        clearcoat: 1,
+        clearcoatRoughness: 0.04,
+        transparent: true,
+        opacity: 0.14,
+        depthWrite: false,
+      }))
+    : isPackedToken
+      ? new THREE.MeshPhysicalMaterial({
+          color: 0xf4fff0,
+          emissive: 0xd8ffd0,
+          emissiveIntensity: 0.008,
+          metalness: 0,
+          roughness: 0.08,
+          clearcoat: 0.9,
+          clearcoatRoughness: 0.05,
+          envMapIntensity: 0.9,
+          transparent: true,
+          opacity: 0.24,
+          depthWrite: false,
+        })
+      : (() => {
+          const textures = acquireVeinTextures(spec, options.includeLogo !== false)
+          const { colorTexture, roughnessTexture } = textures
+          ready = textures.ready
+          releaseSharedResources.push(textures.release)
+          return new THREE.MeshPhysicalMaterial({
+            color,
+            map: colorTexture,
+            emissive: color,
+            emissiveIntensity: isPackedStock ? 0.002 : 0.018,
+            metalness: 0,
+            roughness: isPackedStock ? 0.08 : 0.42,
+            roughnessMap: roughnessTexture,
+            clearcoat: 1,
+            clearcoatRoughness: isPackedStock ? 0.036 : 0.032,
+            envMapIntensity: 2.25,
+            ior: 1.5,
+            specularIntensity: 0.82,
+            specularColor: new THREE.Color(0xffffff),
+            iridescence: 0.025,
+            iridescenceIOR: 1.32,
+            iridescenceThicknessRange: [90, 145],
+            sheen: 0.035,
+            sheenColor: color.clone().lerp(new THREE.Color(0xffffff), 0.35),
+            sheenRoughness: 0.2,
+            // Reserve marbles switch render paths as they orbit the $MRBL lens:
+            // rear marbles stay in the opaque pass while foreground marbles
+            // become transparent-pass objects and render later.
+            transparent: supportsEntranceFade,
+          })
+        })()
+
+  const performanceMaterial =
+    options.performanceMaterial && marbleMaterial instanceof THREE.MeshPhysicalMaterial && !isToken && !isPackedToken
+      ? new THREE.MeshStandardMaterial({
+          color: marbleMaterial.color.clone(),
+          map: marbleMaterial.map,
+          emissive: marbleMaterial.emissive.clone(),
+          emissiveIntensity: marbleMaterial.emissiveIntensity,
+          metalness: marbleMaterial.metalness,
+          roughness: marbleMaterial.roughness,
+          roughnessMap: marbleMaterial.roughnessMap,
+          transparent: supportsEntranceFade,
+        })
+      : undefined
+  const medium = options.geometryDetail === 'medium'
+  const marbleGeometry = options.homepageGeometry
+    ? homepageMarbleGeometry(LOBBY_MARBLE_RADIUS, medium ? 32 : 48, medium ? 24 : 40)
+    : medium
+      ? sharedMediumMarbleGeometry
+      : sharedMarbleGeometry
+  const marble: THREE.Mesh<THREE.SphereGeometry, THREE.Material> = new THREE.Mesh(marbleGeometry, marbleMaterial)
+  marble.position.set(0, -0.12, -0.18)
+  marble.scale.setScalar(spec.size ?? 1)
+  root.add(marble)
+  let inFrontOfLens = false
+
+  if (isToken) {
+    marble.add(createTokenFilament(undefined, true, options.homepageGeometry))
+    const bubbleRim = new THREE.Mesh(
+      options.homepageGeometry ? homepageMarbleGeometry(LOBBY_TOKEN_OUTER_RADIUS, 40, 32) : sharedBubbleRimGeometry,
+      new THREE.ShaderMaterial({
+        vertexShader: `
+          varying vec3 vViewNormal;
+          varying vec3 vViewDirection;
+          void main() {
+            vec4 viewPosition = modelViewMatrix * vec4(position, 1.0);
+            vViewNormal = normalize(normalMatrix * normal);
+            vViewDirection = normalize(-viewPosition.xyz);
+            gl_Position = projectionMatrix * viewPosition;
+          }
+        `,
+        fragmentShader: `
+          varying vec3 vViewNormal;
+          varying vec3 vViewDirection;
+          void main() {
+            float fresnel = pow(
+              1.0 - max(dot(vViewNormal, vViewDirection), 0.0),
+              3.2
+            );
+            gl_FragColor = vec4(vec3(0.94, 1.0, 0.98), fresnel * 0.17);
+          }
+        `,
+        blending: THREE.AdditiveBlending,
+        transparent: true,
+        depthWrite: false,
+      }),
+    )
+    bubbleRim.renderOrder = 6
+    marble.add(bubbleRim)
+  } else if (isPackedToken) {
+    marble.add(createPackedTokenFilament())
+  }
+
+  const podium = spec.withPodium ? createPodium(color) : undefined
+  if (podium) root.add(podium.group, podium.glow, podium.aura)
+
+  if (isToken) {
+    const glassKey = new THREE.SpotLight(0xf7fffd, 11, 9, 0.28, 0.92, 1.4)
+    glassKey.position.set(-0.65, 3.8, 2.5)
+    glassKey.target = marble
+    root.add(glassKey)
+    const glassEdge = new THREE.PointLight(0xf4f8ff, 1.8, 2.8, 1.7)
+    glassEdge.position.set(0.72, 0.42, 1.15)
+    root.add(glassEdge)
+  }
+
+  const supportsSelection = spec.interactive === true
+  const beamOpacity = { value: 0 }
+  const beamTime = { value: 0 }
+  const beamMaterial = supportsSelection
+    ? new THREE.ShaderMaterial({
+        uniforms: {
+          uColor: { value: color },
+          uOpacity: beamOpacity,
+          uTime: beamTime,
+        },
+        vertexShader: `
+      varying vec2 vUv;
+      void main() {
+        vUv = uv;
+        gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+      }
+    `,
+        fragmentShader: `
+      uniform vec3 uColor;
+      uniform float uOpacity;
+      uniform float uTime;
+      varying vec2 vUv;
+      void main() {
+        float horizontal = smoothstep(0.0, 0.25, vUv.x)
+          * smoothstep(0.0, 0.25, 1.0 - vUv.x);
+        float vertical = smoothstep(0.0, 0.12, vUv.y)
+          * smoothstep(0.0, 0.18, 1.0 - vUv.y);
+        float center = 1.0 - abs(vUv.x - 0.5) * 2.0;
+        float haze = 0.86 + sin(vUv.y * 38.0 + uTime * 0.55) * 0.04;
+        float alpha = uOpacity * horizontal * vertical * (0.48 + center * 0.52) * haze;
+        vec3 neutralLight = mix(vec3(0.75, 1.0, 0.94), uColor, 0.22);
+        gl_FragColor = vec4(neutralLight * 1.25, alpha);
+      }
+    `,
+        blending: THREE.AdditiveBlending,
+        depthWrite: false,
+        side: THREE.DoubleSide,
+        transparent: true,
+      })
+    : undefined
+  const spotlightBeam = beamMaterial
+    ? new THREE.Mesh(new THREE.PlaneGeometry(1.72, 7.5, 1, 16), beamMaterial)
+    : undefined
+  if (spotlightBeam) {
+    spotlightBeam.visible = false
+    spotlightBeam.position.set(0, 2.7, -0.12)
+    root.add(spotlightBeam)
+  }
+  const dustPositions = supportsSelection ? new Float32Array(30 * 3) : undefined
+  for (let index = 0; dustPositions && index < 30; index += 1) {
+    dustPositions[index * 3] = (Math.random() - 0.5) * 1.3
+    dustPositions[index * 3 + 1] = Math.random() * 6.8 - 2.7
+    dustPositions[index * 3 + 2] = (Math.random() - 0.5) * 0.7
+  }
+  const dustGeometry = dustPositions ? new THREE.BufferGeometry() : undefined
+  dustGeometry?.setAttribute('position', new THREE.BufferAttribute(dustPositions!, 3))
+  const dustMaterial = supportsSelection
+    ? new THREE.PointsMaterial({
+        color,
+        size: 0.028,
+        blending: THREE.AdditiveBlending,
+        transparent: true,
+        opacity: 0,
+        depthWrite: false,
+      })
+    : undefined
+  const selectionDust = dustGeometry && dustMaterial ? new THREE.Points(dustGeometry, dustMaterial) : undefined
+  if (selectionDust) {
+    selectionDust.visible = false
+    selectionDust.position.set(0, 2.7, 0.1)
+    root.add(selectionDust)
+  }
+  let focused = false
+  let backed = false
+  let restingY = marble.position.y
+  let entranceReveal = 1
+
+  const applyEntranceReveal = () => {
+    if (isToken || !supportsEntranceFade) return
+    const reveal = THREE.MathUtils.smoothstep(entranceReveal, 0, 1)
+    const fading = reveal < 0.999
+    for (const material of performanceMaterial ? [marbleMaterial, performanceMaterial] : [marbleMaterial]) {
+      material.opacity = reveal
+      material.depthWrite = !fading
+    }
+  }
+
+  return {
+    root,
+    marble,
+    ready,
+    setInFrontOfLens: value => {
+      if (isToken || value === inFrontOfLens) return
+      inFrontOfLens = value
+      const transparent = value || supportsEntranceFade
+      if (marbleMaterial.transparent !== transparent) {
+        marbleMaterial.transparent = transparent
+        marbleMaterial.needsUpdate = true
+      }
+      marbleMaterial.opacity = 1
+      marbleMaterial.depthWrite = true
+      applyEntranceReveal()
+      marble.renderOrder = value ? 8 : 0
+    },
+    setEntranceReveal: progress => {
+      entranceReveal = THREE.MathUtils.clamp(progress, 0, 1)
+      applyEntranceReveal()
+    },
+    setPerformanceMode: enabled => {
+      if (!performanceMaterial) return
+      marble.material = enabled ? performanceMaterial : marbleMaterial
+      applyEntranceReveal()
+    },
+    setPodiumVisible: visible => {
+      if (!podium) return
+      podium.group.visible = visible
+      podium.glow.visible = visible
+      podium.aura.visible = visible
+    },
+    setFocused: value => {
+      focused = value
+      if (value && spotlightBeam && selectionDust) {
+        spotlightBeam.visible = true
+        selectionDust.visible = true
+      }
+    },
+    setBacked: value => {
+      backed = value
+      if (value && spotlightBeam && selectionDust) {
+        spotlightBeam.visible = true
+        selectionDust.visible = true
+      }
+    },
+    setRestingY: value => {
+      restingY = value
+      if (!backed) marble.position.y = value
+    },
+    update: elapsedSeconds => {
+      const active = focused || backed
+      const targetY = restingY + (backed ? 0.58 + Math.sin(elapsedSeconds * 1.65 + root.id) * 0.06 : 0)
+      marble.position.y = THREE.MathUtils.lerp(marble.position.y, targetY, 0.18)
+      const targetScale = (spec.size ?? 1) * (backed ? 1.16 : 1)
+      marble.scale.setScalar(THREE.MathUtils.lerp(marble.scale.x, targetScale, 0.2))
+      if (!isToken) marble.rotation.y = Math.sin(elapsedSeconds * 0.42 + root.id) * 0.22
+      if (dustMaterial && spotlightBeam && selectionDust) {
+        dustMaterial.opacity = THREE.MathUtils.lerp(dustMaterial.opacity, active ? 0.5 : 0, 0.08)
+        spotlightBeam.visible = active || beamOpacity.value > 0.001
+        selectionDust.visible = active || dustMaterial.opacity > 0.001
+        selectionDust.position.y = 2.7 + Math.sin(elapsedSeconds * 0.35 + root.id) * 0.12
+      }
+      const activeMarbleMaterial = marble.material
+      if (activeMarbleMaterial instanceof THREE.MeshStandardMaterial) {
+        activeMarbleMaterial.emissiveIntensity = THREE.MathUtils.lerp(
+          activeMarbleMaterial.emissiveIntensity,
+          active ? 0.12 : isToken ? 0.008 : 0.065,
+          0.09,
+        )
+      }
+      if (beamMaterial) {
+        beamOpacity.value = THREE.MathUtils.lerp(beamOpacity.value, active ? 0.068 : 0, 0.08)
+        beamTime.value = elapsedSeconds
+      }
+      if (podium) {
+        const glowMaterial = podium.glow.material as THREE.MeshBasicMaterial
+        const auraMaterial = podium.aura.material as THREE.MeshBasicMaterial
+        glowMaterial.opacity = THREE.MathUtils.lerp(glowMaterial.opacity, active ? 0.48 : 0.08, 0.08)
+        auraMaterial.opacity = THREE.MathUtils.lerp(
+          auraMaterial.opacity,
+          active ? 0.17 + Math.sin(elapsedSeconds * 2.1) * 0.025 : 0.022,
+          0.08,
+        )
+      }
+      podium?.rings.forEach((ring, index) => {
+        const targetY = active ? 0.235 : 0.05 + index * 0.025
+        const targetX = Math.PI / 2 + (active ? -0.18 + Math.sin(elapsedSeconds * 1.15) * 0.025 : 0)
+        ring.position.y = THREE.MathUtils.lerp(ring.position.y, targetY, 0.17)
+        ring.rotation.x = THREE.MathUtils.lerp(ring.rotation.x, targetX, 0.16)
+        ring.rotation.z = active
+          ? -(elapsedSeconds * (0.34 + index * 0.05)) % (Math.PI * 2)
+          : THREE.MathUtils.lerp(ring.rotation.z, 0, 0.16)
+        const material = ring.material as THREE.MeshStandardMaterial
+        material.color.lerp(active ? color : (ring.userData.inactiveColor as THREE.Color), 0.1)
+        material.emissive.lerp(active ? color : (ring.userData.inactiveEmissive as THREE.Color), 0.1)
+        material.emissiveIntensity = THREE.MathUtils.lerp(material.emissiveIntensity, active ? 2.1 : 0.14, 0.1)
+      })
+    },
+    dispose: () => {
+      const geometries = new Set<THREE.BufferGeometry>()
+      const materials = new Set<THREE.Material>()
+      root.traverse(object => {
+        if (!(object instanceof THREE.Mesh || object instanceof THREE.Points)) return
+        if (object.geometry.userData.shared !== true) geometries.add(object.geometry)
+        const objectMaterials = Array.isArray(object.material) ? object.material : [object.material]
+        objectMaterials.forEach(material => {
+          if (material.userData.shared !== true) materials.add(material)
+        })
+      })
+      if (performanceMaterial && performanceMaterial.userData.shared !== true) materials.add(performanceMaterial)
+      ownedTextures.forEach(texture => texture.dispose())
+      releaseSharedResources.forEach(release => release())
+      materials.forEach(material => material.dispose())
+      geometries.forEach(geometry => geometry.dispose())
+    },
+  }
+}