# Marble Sorter — `marble-sorter@1.0.0`

A glass marble machine that sorts marbles by colour through three channels, then lifts them back to the top. Loops perfectly.

A machine that sorts marbles by colour, forever. Mixed marbles drop from the top into a glass tube that splits into three channels; brass gates flick open to send each colour down its own lane; the lanes rejoin, a conveyor carries the marbles to the foot of a lift and the lift raises them back to the top. Choose the number of marbles, the colours (primary, candy, forest or mono), the trips round the circuit per loop, glass or brass tubes, the backdrop colour and whether the camera sways.

- Kind: object; status: published; digest sha256:13e4de7339249b861a30eaf288f8ca89f56b05e801a98e6f47a45d3201a68d27
- Role: Object (3D, three.js): a mechanical toy-machine loop, endlessly satisfying, for kids' content, games and tech.
- Implementation: three; entry `src/marble-sorter.js`
- Files: https://aipixelwizard.com/registry/marble-sorter/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/marble-sorter.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/marble-sorter/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/marble-sorter/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 shader materials.; `chrome-material@1.1.0` (demo) — Studio environment light, backdrop and contact shadow.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createMarbleSorter({ marbles?, palette?, trips?, tubes? }) => { group, setProgress(progress), dispose() }` — The board, tubes, gates and marbles, about 13 wide and 8 tall in the xy plane; needs an environment map.
- `PALETTES: { primary, candy, forest, mono }` — The three marble colours.

## Parameters
- `marbles` (integer 6–24, default 12) — Marbles: Marbles in circulation, in threes.
- `palette` (select one of primary | candy | forest | mono, default "primary") — Colours
- `trips` (integer 1–3, default 1) — Trips per loop
- `tubes` (select one of glass | brass, default "glass") — Tubes
- `background` (color, default "#c9ccd4") — Backdrop
- `orbit` (boolean, default true) — Camera sway

## Composition
- Inputs: Time within the loop; the marbles, colours, trips, tubes, backdrop and camera sway.
- Outputs: A full frame rendered in 3D with a studio environment.
- Coordinates: The machine stands in the xy plane (x from −3.5 to 5.5, y from 0 to 6.7) in front of a board at z = −0.7; the camera looks at (2.7, 3.5).
- Lighting: A warm key light with a shadow map and the studio environment.
- Timing: setProgress(progress) places each marble along its lane's curve and sets the gates; frames render in any order.
- Works with: chrome-material, orbit-camera, kinetic-title, number-reveal
- Marble colour decides the lane: left, middle or right; the gates open as the marbles for the side lanes pass the split.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — Every marble makes a whole number of trips round its closed circuit per loop with the marbles spaced evenly in time, each gate's opening is a function of the marbles passing it, and the camera sway 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 a studio environment and a shadow-casting light, add createMarbleSorter().group and call sorter.setProgress(progress) each frame.

Existing project: Copy src/marble-sorter.js; add the group to your scene with an environment map.

Reuse ideas:
- Toy brand: Primary, glass.
- Soft: Candy, many.
- Industrial: Forest, brass tubes.

## Limitations
- Marbles move at a steady speed along their lane rather than accelerating down slopes.
- The gates are decorative: marbles follow their lanes whatever the gates do.

## 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/objects-scenes/marble-sorter (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original studio object: three closed lane curves through glass tubes with marbles sorted by colour, gates opening as the marbles pass and a lift back to the top, on an exact loop.