# Abacus Cascade — `abacus-cascade@1.0.0`

A wooden counting frame whose glossy beads slide along their rods in rolling waves. Loops perfectly.

A wooden abacus with brass rods and glossy beads. On every rod the beads leave one end one after another, click across and come back, each rod a little out of step with the one above, so a ripple runs down the frame and back again. Choose the number of rods and beads, the bead colours (rainbow, deep, pastel or bone), the wood, how far each rod lags the last, how many crossings a loop holds, the backdrop and whether the camera drifts.

- Kind: object; status: published; digest sha256:80988871d313db7c38a382431aa74c1714a8fb79b7bdc8f8ba2dceae658cb69a
- Role: Object (3D, three.js): a satisfying mechanical hero object for counting, maths, finance and rhythm content.
- Implementation: three; entry `src/abacus-cascade.js`
- Files: https://aipixelwizard.com/registry/abacus-cascade/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/abacus-cascade.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/abacus-cascade/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/abacus-cascade/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer, geometry and physical materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createAbacus({ rods?, beads?, palette?, wood?, wave?, cycles? }) => { group, setProgress(progress), dispose() }` — The frame, rods and instanced beads as a group; add it to a scene with an environment map and a shadow-casting light.
- `PALETTES: { rainbow, deep, pastel, bone }` — Bead colours (sRGB hex).

## Parameters
- `rods` (integer 3–9, default 6) — Rods
- `beads` (integer 4–10, default 7) — Beads per rod
- `palette` (select one of rainbow | deep | pastel | bone, default "rainbow") — Beads
- `wood` (select one of walnut | oak | ebony, default "walnut") — Wood
- `wave` (number 0–2, default 1) — Wave: How far each rod lags the one above it.
- `cycles` (integer 1–3, default 2) — Crossings: How many times the beads cross the frame in one loop.
- `background` (color, default "#1b2a3a") — Backdrop
- `orbit` (boolean, default true) — Camera drift

## Composition
- Inputs: Time within the loop; the rods, beads, colours, wood, wave, crossings, backdrop and camera drift.
- Outputs: A full frame rendered in 3D with soft shadows and a studio environment.
- Coordinates: The frame is 8 wide and as tall as its rods need, centred on the origin and lifted 3.2 above the floor; beads run along x.
- Lighting: A warm key light with a shadow map and the studio environment for the glossy clear-coated beads.
- Timing: setProgress(progress) sets every bead; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- On each rod bead i crosses when the rod's sine passes a threshold that grows along the rod, so beads never overlap: x(i+1) − x(i) ≥ one bead width.
- Beads are one instanced mesh with per-instance colour.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — Every bead's place is a smoothstep of a sine that goes round a whole number of times per loop, and the camera drift is a sine of the loop, so the last frame meets the first.
- Verified 2026-10-06 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer with shadows and a studio environment (see chrome-material), add createAbacus().group and call abacus.setProgress(progress) each frame.

Existing project: Copy src/abacus-cascade.js; add abacus.group to your scene with an environment map and a shadow-casting light.

Reuse ideas:
- Finance or maths backdrop: Rainbow beads, walnut.
- Calm product loop: Bone beads, ebony.
- Rhythm title: One slow wave.

## Limitations
- The beads slide without friction or collision physics: order is guaranteed by the thresholds, not simulated.
- The beads are plain flattened spheres without a drilled bore.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/mechanical-kinetic/abacus-cascade (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original object: threshold-ordered bead waves on an exact loop, clear-coated instanced beads and a brass-and-wood frame.