Clyune Component GalleryHourglass Sand · How it works & code
particle cellular automaton hourglass with flow following Beverloo's law
Runtime logic
Visiting `/physics/hourglass`, DemoHost lazy-loads `demos/kits/kit-physics.js` (registry `mod: 'kit-physics'`) and calls `mount(host, { variant: 'hourglass' })`. mount resolves the variant to family `hourglass`; `withControls` builds the control panel (6 presets + sliders). `createCanvasStage` creates the `<canvas>` (HiDPI ≤ 2×, ResizeObserver) and the info panel. The family’s `build(S)` initialises state and returns the per-frame callback. Every `requestAnimationFrame`: read controls, advance a speed-scaled clock (dt ≤ 50 ms), run the frame callback; returned readouts go to the info panel. Pointer down/drag/move updates the interaction (drag handles, hover readouts); when untouched and auto-demo is on, the pointer follows a Lissajous path. Changing parameters: colour/speed/size apply live; structural ones remount; leaving the page cancels rAF, removes listeners and frees resources.
Environment
Canvas 2D: 2D canvas drawing; requestAnimationFrame: Display-synced animation loop; ResizeObserver: Canvas follows container size; Pointer Events: Unified mouse/touch/pen events; devicePixelRatio: Crisp HiDPI rendering (capped at 2×) · react 18.3.1, react-router-dom 6.30.6, vite 5.4.21
Dependencies
react 18.3.1
Imported APIs
withControls — Wraps the demo in the shared control panel (presets, sliders, reset); hot-updates or remounts on change; paramsFromSpec — Turns the spec (colour/speed/size/count/extras) into control-panel parameter definitions; createCanvasStage — Shared Canvas 2D stage: canvas + info panel, HiDPI, one rAF loop, pointer state, idle auto-pointer; rng — Seeded deterministic PRNG (same seed, same result); hexRgb — Colour string → [r, g, b]; rgba — Builds an rgba() colour string; clamp — Clamps a value to a range; fmt — Number formatting (fixed decimals); F — Formula block HTML; S.onDown — Pointer down; S.onUp — Pointer up; S.onMove — Pointer move; S.clear — Clears with the background colour (translucent = trails); S.get — Reads current control values; S.onFrame — Registers a per-frame callback; its return value feeds the info panel; ctx.save() — Saves the drawing state (transform, styles, clip); ctx.translate() — Translates the coordinate system; ctx.rotate() — Rotates the coordinate system; ctx.fillRect() — Fills a rectangle; ctx.restore() — Restores the saved drawing state
Source code
frontend/src/demos/kits/kit-physics.js: FAM.hourglass (L475-L519)
Code walkthrough
L477-477: Control definitions (colour/speed/size/count/extras): sand color, sand grid, constriction width (cells), sand fill ratio, auto flip on empty. L478-478: Preset buttons: name → parameter overrides (6). L479-487: Info-panel content: live rows(v), formula, notes, params, steps. L488-518: Init function: sets up state and returns the per-frame callback: registers pointer handlers `S.onDown`, `S.onMove`, `S.onUp`; draws with Canvas 2D `save`, `translate`, `rotate`, `fillRect`, `restore`; math via `Math.abs`, `Math.max`, `Math.pow`, `Math.round`, `Math.floor`, `Math.min`; returns readouts `top`, `bot`, `rate`, `eta`, `neck`, `bev`, `flips` … to the info panel.
Principles
Per grain of sand: below → whereabouts;or left down/Down Right → Tilt (twilight first) Beverloo Law: Q = C · ρ · √g · (D − k · d)^(5 / 2) Missing Time ≈ N / Q Sand is neither solid nor liquid. Here It's all about motive Simulation: The image is cut into small cells, and each frame of sand is just three of its own, can fall down, can't just pile up, and is naturally formed The Cape of The sand pile. 沙漏的流量几乎不随沙堆高度变化（不像水），只取决于瓶颈宽度 D，Empirical formula called Beverloo Scientific law : Q ∝ (D − k)^2.5, The bottlenecks are twice as wide and the flow is more than five times larger. The upper half of the void is automatically turned; the click image can also be turned manually, and drag-and-drop can dig sand at the pointer.