Three.js Scroll Hourglass — Volume-True Sand Timer

<section class="hgl-stage" id="hglStage">
  <div class="hgl-intro"><p>Scroll ↓ to let the sand run</p></div>
  <canvas id="hglCanvas"></canvas>
  <div class="hgl-hud"><span id="hglPct">0</span>% ELAPSED</div>
</section>
<section class="hgl-bottom"><p>Time’s up.</p></section>

*{box-sizing:border-box;margin:0;padding:0}
html,body{background:#141210;color:#fff;font-family:system-ui,-apple-system,sans-serif}
.hgl-bottom{min-height:70vh;display:flex;justify-content:center;align-items:center;color:#a89d8a;font-size:15px;letter-spacing:.08em;text-transform:uppercase}
.hgl-stage{height:100vh;position:relative;overflow:hidden;background:#141210}
.hgl-intro{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;text-align:center;padding:24px;pointer-events:none;z-index:5;color:#a89d8a;font-size:15px;letter-spacing:.08em;text-transform:uppercase;transition:opacity .4s ease}
#hglCanvas{display:block;width:100%;height:100%}
.hgl-hud{position:absolute;left:24px;bottom:24px;font-variant-numeric:tabular-nums;font-size:13px;letter-spacing:.14em;color:#eab308;text-transform:uppercase;opacity:.85}

const canvas = document.getElementById('hglCanvas');
const pctEl = document.getElementById('hglPct');
const introEl = document.querySelector('.hgl-intro');
const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x141210);
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 200);

scene.add(new THREE.AmbientLight(0xfff2dc, 0.6));
const key = new THREE.DirectionalLight(0xffe9c0, 1.0);
key.position.set(10, 16, 12);
scene.add(key);

// The whole hourglass lives in one group so the end-of-scroll flip
// rotates glass, sand piles, and stream together.
const rig = new THREE.Group();
scene.add(rig);

// Glass: two cones meeting at a narrow neck, semi-transparent.
const glassMat = new THREE.MeshPhysicalMaterial({
  color: 0xcfe6e8, transparent: true, opacity: 0.16, roughness: 0.05,
  metalness: 0, side: THREE.DoubleSide, depthWrite: false,
});
const topGlass = new THREE.Mesh(new THREE.ConeGeometry(5, 8, 48, 1, true), glassMat);
topGlass.position.y = 4.2;
rig.add(topGlass);
const botGlass = new THREE.Mesh(new THREE.ConeGeometry(5, 8, 48, 1, true), glassMat);
botGlass.rotation.x = Math.PI;
botGlass.position.y = -4.2;
rig.add(botGlass);

// Wood frame: two discs and three pillars.
const wood = new THREE.MeshStandardMaterial({ color: 0x5b4226, roughness: 0.65 });
[8.6, -8.6].forEach((y) => {
  const disc = new THREE.Mesh(new THREE.CylinderGeometry(6.4, 6.4, 0.9, 48), wood);
  disc.position.y = y;
  rig.add(disc);
});
for (let i = 0; i < 3; i++) {
  const a = (i / 3) * Math.PI * 2;
  const pillar = new THREE.Mesh(new THREE.CylinderGeometry(0.32, 0.32, 17.2, 12), wood);
  pillar.position.set(Math.cos(a) * 5.9, 0, Math.sin(a) * 5.9);
  rig.add(pillar);
}

// Sand piles: cones whose scale is driven analytically from progress.
// Volume conserved: top pile shrinks as bottom grows by the same cube law.
const sandMat = new THREE.MeshStandardMaterial({ color: 0xd9a441, roughness: 0.9 });
const topSand = new THREE.Mesh(new THREE.ConeGeometry(4.6, 6.6, 40), sandMat);
// Top sand is an inverted cone sitting in the upper bulb, tip down at the neck.
topSand.rotation.x = Math.PI;
rig.add(topSand);
const botSand = new THREE.Mesh(new THREE.ConeGeometry(4.6, 5.2, 40), sandMat.clone());
rig.add(botSand);

// The falling stream: a thin column of recycled particles through the neck.
const GRAINS = 220;
const grainGeo = new THREE.BufferGeometry();
const grainPos = new Float32Array(GRAINS * 3);
const grainSeed = new Float32Array(GRAINS);
for (let i = 0; i < GRAINS; i++) {
  grainSeed[i] = Math.random();
  grainPos[i * 3 + 1] = -9999;
}
grainGeo.setAttribute('position', new THREE.BufferAttribute(grainPos, 3));
const grains = new THREE.Points(grainGeo, new THREE.PointsMaterial({
  color: 0xe8b95a, size: 0.16, transparent: true, opacity: 0.95, sizeAttenuation: true,
}));
rig.add(grains);

gsap.registerPlugin(ScrollTrigger);
const timer = { p: 0 };
gsap.to(timer, {
  p: 1,
  ease: 'none',
  scrollTrigger: { trigger: '#hglStage', start: 'top top', end: '+=450%', scrub: 0.5, pin: true },
});

function resize() {
  const w = canvas.clientWidth, h = canvas.clientHeight;
  renderer.setSize(w, h, false);
  camera.aspect = w / h;
  camera.updateProjectionMatrix();
}

const clock = new THREE.Clock();
function animate() {
  requestAnimationFrame(animate);
  const t = clock.getElapsedTime();
  const p = timer.p;
  if (introEl) introEl.style.opacity = p > 0.02 ? '0' : '1';

  // Sand runs across the first 88% of scroll; the flip takes the rest.
  const run = Math.min(1, p / 0.88);
  const flip = Math.max(0, (p - 0.88) / 0.12);

  // Volume conservation: pile volume ∝ scale³, so scale = cbrt(fraction).
  const topFrac = Math.max(0.0001, 1 - run);
  const botFrac = Math.max(0.0001, run);
  const ts = Math.cbrt(topFrac), bs = Math.cbrt(botFrac);
  topSand.scale.set(ts, ts, ts);
  // Keep the top pile's tip pinned at the neck (y=0): the inverted cone's
  // tip sits half its scaled height below its center.
  topSand.position.y = 0.4 + (6.6 * ts) / 2;
  botSand.scale.set(bs, bs, bs);
  botSand.position.y = -8.2 + (5.2 * bs) / 2;

  // Stream particles: visible only while sand is running (0 < run < 1).
  const flowing = run > 0.005 && run < 0.995;
  for (let i = 0; i < GRAINS; i++) {
    grainSeed[i] += 0.03 + (i % 5) * 0.005;
    if (grainSeed[i] > 1) {
      grainSeed[i] = 0;
      grainPos[i * 3] = (Math.random() - 0.5) * 0.22;
      grainPos[i * 3 + 1] = flowing ? 0.3 : -9999;
      grainPos[i * 3 + 2] = (Math.random() - 0.5) * 0.22;
    } else if (grainPos[i * 3 + 1] > -999) {
      // Accelerate downward — sand in free fall, not linear drip.
      grainPos[i * 3 + 1] -= 0.18 + grainSeed[i] * 0.55;
      if (grainPos[i * 3 + 1] < botSand.position.y + 2.6 * bs) grainPos[i * 3 + 1] = -9999;
    }
  }
  grainGeo.attributes.position.needsUpdate = true;

  // The flip: once the sand has run out, the last 12% of scroll rotates
  // the whole rig upside down, resetting the timer for a loop.
  const fe = flip * flip * (3 - 2 * flip);
  rig.rotation.z = fe * Math.PI;

  const ang = 0.5 + p * 1.2 + t * 0.05;
  camera.position.set(Math.sin(ang) * 26, 3 + Math.sin(t * 0.3) * 0.8, Math.cos(ang) * 26);
  camera.lookAt(0, 0, 0);

  pctEl.textContent = Math.round(run * 100);
  renderer.render(scene, camera);
}

resize();
window.addEventListener('resize', resize);
animate();