# Bouncing Marbles in a Box — `bouncing-marbles-box@1.1.0`

Shiny chrome balls pour into a glass box, bounce, roll and settle while the camera glides around.

A complete scene built from four ingredients: real bouncing-ball physics, chrome material with studio lighting, a correctly set-up glass box and a smooth orbit camera. Balls drop in from above, collide, spin and come to rest. Switch to candy-coloured balls or a mix, change the number of balls, the bounciness and how far the camera travels. Use it as-is, or take just the parts you need.

- Kind: example; status: published; digest sha256:2795f54cc2445bbfe1c379558dd244ac1a7f9af2624c81faba3ada4133053694
- Role: Complete example scene.
- Implementation: three; entry `demo.js`
- Files: https://aipixelwizard.com/registry/bouncing-marbles-box/1.1.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/bouncing-marbles-box/versions/1.1.0
- Runnable demo: https://aipixelwizard.com/registry/bouncing-marbles-box/1.1.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — WebGL rendering.; `bouncing-balls@1.0.0` (source) — Physics.; `chrome-material@1.0.0` (source) — Material and environment.; `glass-container@1.1.0` (source) — Glass box, cove backdrop and backlight.; `orbit-camera@1.0.0` (source) — Camera motion.; `apw-runtime@1.0.0` (source) — Harness and export tools.

## Exports
- `createDemo({ canvas, width, height, params, fps, duration }) => { renderFrame(info), dispose() }` — Builds the scene; the harness calls renderFrame for each frame.

## Parameters
- `count` (integer 4–40, default 18) — Number of balls
- `ballStyle` (select one of chrome | mixed | candy, default "chrome") — Ball look
- `bounciness` (number 0.3–0.9, default 0.68) — Bounciness
- `seed` (integer 1–9999, default 4) — Variation
- `turns` (number 0–1, default 0.35) — Camera travel: 0 keeps the camera still; 1 is a full circle with an eased start and stop.
- `cameraDistance` (number 8–18, default 11.5) — Camera distance
- `cameraHeight` (number 1–9, default 5.2) — Camera height
- `glassTint` (color, default "#e8fbff") — Glass tint
- `lightWarmth` (number -1–1, default 0.1) — Light warmth
- `background` (color, default "#0b0b10") — Background

## Composition
- Inputs: Parameters only.
- Outputs: A rendered Three.js scene.
- Coordinates: Y-up. Glass box inner volume 4 × 3 × 4 with floor at y = 0 — identical to the physics box.
- Lighting: Studio environment from chrome-material; tone mapped.
- Timing: Physics baked for the clip's fps/duration; camera driven by progress.
- Works with: —
- Ready to run: all four ingredients are tested together in this example.

## Output and loop
- 1080×1080, 30 fps, 8 s, simulation
- Seamless loop: no — Balls fall and settle once.
- Verified 2026-10-03 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

## Use it
New project: Download the pack, run npm install, then `npm run serve` and open bouncing-marbles-box/1.0.0/index.html. Export a video with `npm run render -- bouncing-marbles-box/1.0.0`.

Existing project: Treat demo.js as a reference for wiring the ingredients together. Copy the ingredient source files into your project and reproduce the assembly in your own scene code; do not replace your project with this demo.

Reuse ideas:
- Swap the balls for other shapes (keep the physics positions) — dice, candies or logos.
- Keep the glass box and physics, drop the orbit and use a fixed hero camera.
- Recolour with ballStyle candy for a playful version.

## Limitations
- Balls do not reflect each other (environment-map reflections only).
- No caustics through the glass.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.
- three.js 0.185.1: MIT (https://github.com/mrdoob/three.js)

Provenance: Original code written for AI Pixel Wizard in October 2026. Demo scene rebuilt in October 2026 to the catalog quality bar (docs/QUALITY.md).